From 2faaa52be0c0eea98f2c504f8478c62f80e7ee88 Mon Sep 17 00:00:00 2001 From: Nick Schonning Date: Thu, 14 Mar 2019 12:10:33 -0400 Subject: [PATCH] typo: Automation.Errorrecord -> Automation.ErrorRecord (#3955) - system.String - Fullyqualifiederrorid* - Categoryinfo* - Errordetails* - Invocationinfo* - Targetobject* - Getresourcestring* --- ...minating-error-reporting-to-your-cmdlet.md | 4 ++-- developer/cmdlet/cmdlet-error-reporting.md | 2 +- .../interpreting-errorrecord-objects.md | 18 +++++++------- .../windows-powershell-error-records.md | 24 +++++++++---------- 4 files changed, 24 insertions(+), 24 deletions(-) diff --git a/developer/cmdlet/adding-non-terminating-error-reporting-to-your-cmdlet.md b/developer/cmdlet/adding-non-terminating-error-reporting-to-your-cmdlet.md index 3c4605952429..6cc3997803f9 100644 --- a/developer/cmdlet/adding-non-terminating-error-reporting-to-your-cmdlet.md +++ b/developer/cmdlet/adding-non-terminating-error-reporting-to-your-cmdlet.md @@ -13,7 +13,7 @@ caps.latest.revision: 8 Cmdlets can report nonterminating errors by calling the [System.Management.Automation.Cmdlet.WriteError](/dotnet/api/System.Management.Automation.Cmdlet.WriteError) method and still continue to operate on the current input object or on further incoming pipeline objects. This section explains how to create a cmdlet that reports nonterminating errors from its input processing methods. -For nonterminating errors (as well as terminating errors), the cmdlet must pass an [System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) object identifying the error. Each error record is identified by a unique string called the "error identifier." In addition to the identifier, the category of each error is specified by constants defined by a [System.Management.Automation.Errorcategory](/dotnet/api/System.Management.Automation.ErrorCategory) enumeration. The user can view errors based on their category by setting the `$ErrorView` variable to "CategoryView". +For nonterminating errors (as well as terminating errors), the cmdlet must pass an [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) object identifying the error. Each error record is identified by a unique string called the "error identifier." In addition to the identifier, the category of each error is specified by constants defined by a [System.Management.Automation.Errorcategory](/dotnet/api/System.Management.Automation.ErrorCategory) enumeration. The user can view errors based on their category by setting the `$ErrorView` variable to "CategoryView". For more information about error records, see [Windows PowerShell Error Records](./windows-powershell-error-records.md). @@ -99,7 +99,7 @@ This Get-Proc cmdlet overrides the [System.Management.Automation.Cmdlet.ProcessR #### Things to Remember When Reporting Errors -The [System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) object that the cmdlet passes when writing an error requires an exception at its core. Follow the .NET guidelines when determining the exception to use. Basically, if the error is semantically the same as an existing exception, the cmdlet should use or derive from that exception. Otherwise, it should derive a new exception or exception hierarchy directly from the [System.Exception](/dotnet/api/System.Exception) class. +The [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) object that the cmdlet passes when writing an error requires an exception at its core. Follow the .NET guidelines when determining the exception to use. Basically, if the error is semantically the same as an existing exception, the cmdlet should use or derive from that exception. Otherwise, it should derive a new exception or exception hierarchy directly from the [System.Exception](/dotnet/api/System.Exception) class. When creating error identifiers (accessed through the FullyQualifiedErrorId property of the ErrorRecord class) keep the following in mind. diff --git a/developer/cmdlet/cmdlet-error-reporting.md b/developer/cmdlet/cmdlet-error-reporting.md index f7dcd1dde061..172576c0cd3f 100644 --- a/developer/cmdlet/cmdlet-error-reporting.md +++ b/developer/cmdlet/cmdlet-error-reporting.md @@ -47,7 +47,7 @@ You can also define your own exceptions for issues specific to your situation, o ## Error Records -Windows PowerShell describes a nonterminating error condition through the use of [System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) objects. Each [System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) object provides error category information, an optional target object, and details about the error condition. +Windows PowerShell describes a nonterminating error condition through the use of [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) objects. Each [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) object provides error category information, an optional target object, and details about the error condition. ### Error Identifiers diff --git a/developer/cmdlet/interpreting-errorrecord-objects.md b/developer/cmdlet/interpreting-errorrecord-objects.md index 82ecbf18cdc9..ebe2156d1fdd 100644 --- a/developer/cmdlet/interpreting-errorrecord-objects.md +++ b/developer/cmdlet/interpreting-errorrecord-objects.md @@ -11,9 +11,9 @@ caps.latest.revision: 9 --- # Interpreting ErrorRecord Objects -In most cases, an [System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) object represents a non-terminating error generated by a command or script. Terminating errors can also specify the additional information in an ErrorRecord via the [System.Management.Automation.Icontainserrorrecord](/dotnet/api/System.Management.Automation.IContainsErrorRecord) interface. +In most cases, an [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) object represents a non-terminating error generated by a command or script. Terminating errors can also specify the additional information in an ErrorRecord via the [System.Management.Automation.Icontainserrorrecord](/dotnet/api/System.Management.Automation.IContainsErrorRecord) interface. -If you want to write an error handler in your script or a host to handle specific errors that occur during command or script execution, you must interpret the [System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) object to determine whether it represents the class of error that you want to handle. +If you want to write an error handler in your script or a host to handle specific errors that occur during command or script execution, you must interpret the [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) object to determine whether it represents the class of error that you want to handle. When a cmdlet encounters a terminating or non-terminating error, it should create an error record that describes the error condition. The host application must investigate these error records and perform whatever action will mitigate the error. The host application must also investigate error records for nonterminating errors that failed to process a record but were able to continue, and it must investigate error records for terminating errors that caused the pipeline to stop. @@ -38,13 +38,13 @@ You can review several parts of the error record to identify the error. These pa ### The Error Category -The error category of the error record is one of the predefined constants provided by the [System.Management.Automation.Errorcategory](/dotnet/api/System.Management.Automation.ErrorCategory) enumeration. This information is available through the [System.Management.Automation.Errorrecord.Categoryinfo*](/dotnet/api/System.Management.Automation.ErrorRecord.CategoryInfo) property of the [System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) object. +The error category of the error record is one of the predefined constants provided by the [System.Management.Automation.Errorcategory](/dotnet/api/System.Management.Automation.ErrorCategory) enumeration. This information is available through the [System.Management.Automation.ErrorRecord.CategoryInfo](/dotnet/api/System.Management.Automation.ErrorRecord.CategoryInfo) property of the [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) object. The cmdlet can specify the CloseError, OpenError, InvalidType, ReadError, and WriteError categories, and other error categories. The host application can use the error category to capture groups of errors. ### The Exception -The exception included in the error record is provided by the cmdlet and can be accessed through the [System.Management.Automation.Errorrecord.Exception*](/dotnet/api/System.Management.Automation.ErrorRecord.Exception) property of the [System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) object. +The exception included in the error record is provided by the cmdlet and can be accessed through the [System.Management.Automation.ErrorRecord.Exception*](/dotnet/api/System.Management.Automation.ErrorRecord.Exception) property of the [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) object. Host applications can use the `is` keyword to identify that the exception is of a specific class or of a derived class. It is better to branch on the exception type, as shown in the following example. @@ -64,17 +64,17 @@ In the previous example, the first token is the error identifier, which is follo ### Other Information -The [System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) object might also provide information that describes the environment in which the error occurred. This information includes items such as error details, invocation information, and the target object that was being processed when the error occurred. Although this information might be useful to the host application, it is not typically used to identify the error. This information is available through the following properties: +The [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) object might also provide information that describes the environment in which the error occurred. This information includes items such as error details, invocation information, and the target object that was being processed when the error occurred. Although this information might be useful to the host application, it is not typically used to identify the error. This information is available through the following properties: -[System.Management.Automation.Errorrecord.Errordetails*](/dotnet/api/System.Management.Automation.ErrorRecord.ErrorDetails) +[System.Management.Automation.ErrorRecord.ErrorDetails](/dotnet/api/System.Management.Automation.ErrorRecord.ErrorDetails) -[System.Management.Automation.Errorrecord.Invocationinfo*](/dotnet/api/System.Management.Automation.ErrorRecord.InvocationInfo) +[System.Management.Automation.ErrorRecord.InvocationInfo](/dotnet/api/System.Management.Automation.ErrorRecord.InvocationInfo) -[System.Management.Automation.Errorrecord.Targetobject*](/dotnet/api/System.Management.Automation.ErrorRecord.TargetObject) +[System.Management.Automation.ErrorRecord.TargetObject](/dotnet/api/System.Management.Automation.ErrorRecord.TargetObject) ## See Also -[System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) +[System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) [System.Management.Automation.Errorcategory](/dotnet/api/System.Management.Automation.ErrorCategory) diff --git a/developer/cmdlet/windows-powershell-error-records.md b/developer/cmdlet/windows-powershell-error-records.md index ebd49450b6e5..c2d248d79df8 100644 --- a/developer/cmdlet/windows-powershell-error-records.md +++ b/developer/cmdlet/windows-powershell-error-records.md @@ -16,13 +16,13 @@ caps.latest.revision: 9 --- # Windows PowerShell Error Records -Cmdlets must pass an [System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) object that identifies the error condition for terminating and non-terminating errors. +Cmdlets must pass an [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) object that identifies the error condition for terminating and non-terminating errors. -The [System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) object contains the following information: +The [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) object contains the following information: - The exception that describes the error. Often, this is an exception that the cmdlet caught and converted into an error record. Every error record must contain an exception. -If the cmdlet did not catch an exception, it must create a new exception and choose the exception class that best describes the error condition. However, you do not need to throw the exception because it can be accessed through the [System.Management.Automation.Errorrecord.Exception*](/dotnet/api/System.Management.Automation.ErrorRecord.Exception) property of the [System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) object. +If the cmdlet did not catch an exception, it must create a new exception and choose the exception class that best describes the error condition. However, you do not need to throw the exception because it can be accessed through the [System.Management.Automation.ErrorRecord.Exception](/dotnet/api/System.Management.Automation.ErrorRecord.Exception) property of the [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) object. - An error identifier that provides a targeted designator that can be used for diagnostic purposes and by Windows PowerShell scripts to handle specific error conditions with specific error handlers. Every error record must contain an error identifier (see Error Identifier). @@ -36,7 +36,7 @@ If the cmdlet did not catch an exception, it must create a new exception and cho ## Error Identifier -When you create an error record, specify an identifier that designates the error condition within your cmdlet. Windows PowerShell combines the targeted identifier with the name of your cmdlet to create a fully qualified error identifier. The fully qualified error identifier can be accessed through the [System.Management.Automation.Errorrecord.Fullyqualifiederrorid*](/dotnet/api/System.Management.Automation.ErrorRecord.FullyQualifiedErrorId) property of the [System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) object. The error identifier is not available by itself. It is available only as part of the fully qualified error identifier. +When you create an error record, specify an identifier that designates the error condition within your cmdlet. Windows PowerShell combines the targeted identifier with the name of your cmdlet to create a fully qualified error identifier. The fully qualified error identifier can be accessed through the [System.Management.Automation.ErrorRecord.FullyQualifiedErrorId](/dotnet/api/System.Management.Automation.ErrorRecord.FullyQualifiedErrorId) property of the [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) object. The error identifier is not available by itself. It is available only as part of the fully qualified error identifier. Use the following guidelines to generate error identifiers when you create error records: @@ -58,7 +58,7 @@ When you create an error record, specify the category of the error using one of Avoid using the [System.Management.Automation.Errorcategory.Notspecified](/dotnet/api/System.Management.Automation.ErrorCategory.NotSpecified) constant. If you have any information about the error or about the operation that caused the error, choose the category that best describes the error or the operation, even if the category is not a perfect match. -The information displayed by Windows PowerShell is referred to as the category-view string and is built from the properties of the [System.Management.Automation.Errorcategoryinfo](/dotnet/api/System.Management.Automation.ErrorCategoryInfo) class. (This class is accessed through the error [System.Management.Automation.Errorrecord.Categoryinfo*](/dotnet/api/System.Management.Automation.ErrorRecord.CategoryInfo) property.) +The information displayed by Windows PowerShell is referred to as the category-view string and is built from the properties of the [System.Management.Automation.Errorcategoryinfo](/dotnet/api/System.Management.Automation.ErrorCategoryInfo) class. (This class is accessed through the error [System.Management.Automation.ErrorRecord.CategoryInfo](/dotnet/api/System.Management.Automation.ErrorRecord.CategoryInfo) property.) ``` {Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason} @@ -80,19 +80,19 @@ The following list describes the information displayed: When you develop an error record for a cmdlet, the default error message for the error comes from the default message text in the [System.Exception.Message](/dotnet/api/System.Exception.Message) property. This is a read-only property whose message text is intended only for debugging purposes (according to the .NET Framework guidelines). We recommend that you create an error message that replaces or augments the default message text. Make the message more user-friendly and more specific to the cmdlet. -The replacement message is provided by an [System.Management.Automation.Errordetails](/dotnet/api/System.Management.Automation.ErrorDetails) object. Use one of the following constructors of this object because they provide additional localization information that can be used by Windows PowerShell. +The replacement message is provided by an [System.Management.Automation.ErrorDetails](/dotnet/api/System.Management.Automation.ErrorDetails) object. Use one of the following constructors of this object because they provide additional localization information that can be used by Windows PowerShell. -- [ErrorDetails.ErrorDetails(Cmdlet, String, String, Object\[System.Management.Automation.Errordetails.%23Ctor%28System.Management.Automation.Cmdlet%2Csystem.String%2Csystem.String%2Csystem.Object%5B%5D%29?Displayproperty=Fullname](/dotnet/api/System.Management.Automation.ErrorDetails.%23ctor%28System.Management.Automation.Cmdlet%2CSystem.String%2CSystem.String%2CSystem.Object%5B%5D%29): Use this constructor if your template string is a resource string in the same assembly in which the cmdlet is implemented or if you want to load the template string through an override of the [System.Management.Automation.Cmdlet.Getresourcestring*](/dotnet/api/System.Management.Automation.Cmdlet.GetResourceString) method. +- [ErrorDetails.ErrorDetails(Cmdlet, String, String, Object\[System.Management.Automation.ErrorDetails.%23Ctor%28System.Management.Automation.Cmdlet%2CSystem.String%2CSystem.String%2CSystem.Object%5B%5D%29?Displayproperty=Fullname](/dotnet/api/System.Management.Automation.ErrorDetails.%23ctor%28System.Management.Automation.Cmdlet%2CSystem.String%2CSystem.String%2CSystem.Object%5B%5D%29): Use this constructor if your template string is a resource string in the same assembly in which the cmdlet is implemented or if you want to load the template string through an override of the [System.Management.Automation.Cmdlet.GetResourceString](/dotnet/api/System.Management.Automation.Cmdlet.GetResourceString) method. -- [ErrorDetails.ErrorDetails(Assembly, String, String, Object\[System.Management.Automation.Errordetails.%23Ctor%28System.Reflection.Assembly%2Csystem.String%2Csystem.String%2Csystem.Object%5B%5D%29?Displayproperty=Fullname](/dotnet/api/System.Management.Automation.ErrorDetails.%23ctor%28System.Reflection.Assembly%2CSystem.String%2CSystem.String%2CSystem.Object%5B%5D%29): Use this constructor if the template string is in another assembly and you do not load it through an override of [System.Management.Automation.Cmdlet.Getresourcestring*](/dotnet/api/System.Management.Automation.Cmdlet.GetResourceString). +- [ErrorDetails.ErrorDetails(Assembly, String, String, Object\[System.Management.Automation.ErrorDetails.%23Ctor%28System.Reflection.Assembly%2CSystem.String%2CSystem.String%2CSystem.Object%5B%5D%29?Displayproperty=Fullname](/dotnet/api/System.Management.Automation.ErrorDetails.%23ctor%28System.Reflection.Assembly%2CSystem.String%2CSystem.String%2CSystem.Object%5B%5D%29): Use this constructor if the template string is in another assembly and you do not load it through an override of [System.Management.Automation.Cmdlet.GetResourceString](/dotnet/api/System.Management.Automation.Cmdlet.GetResourceString). The replacement message should conform to the .NET Framework design guidelines for writing exception messages with a small difference. The guidelines state that exception messages should be written for developers. These replacement messages should be written for the cmdlet user. -The replacement error message must be added before the [System.Management.Automation.Cmdlet.WriteError](/dotnet/api/System.Management.Automation.Cmdlet.WriteError) or [System.Management.Automation.Cmdlet.Throwterminatingerror*](/dotnet/api/System.Management.Automation.Cmdlet.ThrowTerminatingError) methods are called. To add a replacement message, set the [System.Management.Automation.Errorrecord.Errordetails*](/dotnet/api/System.Management.Automation.ErrorRecord.ErrorDetails) property of the error record. When this property is set, Windows PowerShell displays the [System.Management.Automation.Errordetails.Message*](/dotnet/api/System.Management.Automation.ErrorDetails.Message) property instead of the default message text. +The replacement error message must be added before the [System.Management.Automation.Cmdlet.WriteError](/dotnet/api/System.Management.Automation.Cmdlet.WriteError) or [System.Management.Automation.Cmdlet.Throwterminatingerror*](/dotnet/api/System.Management.Automation.Cmdlet.ThrowTerminatingError) methods are called. To add a replacement message, set the [System.Management.Automation.ErrorRecord.ErrorDetails](/dotnet/api/System.Management.Automation.ErrorRecord.ErrorDetails) property of the error record. When this property is set, Windows PowerShell displays the [System.Management.Automation.ErrorDetails.Message*](/dotnet/api/System.Management.Automation.ErrorDetails.Message) property instead of the default message text. ## Recommended Action Information -The [System.Management.Automation.Errordetails](/dotnet/api/System.Management.Automation.ErrorDetails) object can also provide information about what actions are recommended when the error occurs. +The [System.Management.Automation.ErrorDetails](/dotnet/api/System.Management.Automation.ErrorDetails) object can also provide information about what actions are recommended when the error occurs. ## Invocation information @@ -108,9 +108,9 @@ When a cmdlet uses [System.Management.Automation.Cmdlet.WriteError](/dotnet/api/ [System.Management.Automation.Errorcategoryinfo](/dotnet/api/System.Management.Automation.ErrorCategoryInfo) -[System.Management.Automation.Errorrecord](/dotnet/api/System.Management.Automation.ErrorRecord) +[System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord) -[System.Management.Automation.Errordetails](/dotnet/api/System.Management.Automation.ErrorDetails) +[System.Management.Automation.ErrorDetails](/dotnet/api/System.Management.Automation.ErrorDetails) [System.Management.Automation.Invocationinfo](/dotnet/api/System.Management.Automation.InvocationInfo)