Writes an object to the error stream.
Syntax
 Copy Code |
|
|---|---|
Write-Error -ErrorRecord <ErrorRecord> [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]
Write-Error [-Message] <string> [-Category {<NotSpecified> | <OpenError> | <CloseError> | <DeviceError> | <DeadlockDetected> | <InvalidArgument> | <InvalidData> | <InvalidOperation> | <InvalidResult> | <InvalidType> | <MetadataError> | <NotImplemented> | <NotInstalled> | <ObjectNotFound> | <OperationStopped> | <OperationTimeout> | <SyntaxError> | <ParserError> | <PermissionDenied> | <ResourceBusy> | <ResourceExists> | <ResourceUnavailable> | <ReadError> | <WriteError> | <FromStdErr> | <SecurityError>}] [-ErrorId <string>] [-TargetObject <Object>] [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]
Write-Error -Exception <Exception> [-Category {<NotSpecified> | <OpenError> | <CloseError> | <DeviceError> | <DeadlockDetected> | <InvalidArgument> | <InvalidData> | <InvalidOperation> | <InvalidResult> | <InvalidType> | <MetadataError> | <NotImplemented> | <NotInstalled> | <ObjectNotFound> | <OperationStopped> | <OperationTimeout> | <SyntaxError> | <ParserError> | <PermissionDenied> | <ResourceBusy> | <ResourceExists> | <ResourceUnavailable> | <ReadError> | <WriteError> | <FromStdErr> | <SecurityError>}] [-ErrorId <string>] [-Message <string>] [-TargetObject <Object>] [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]
|
|
Description
The Write-Error cmdlet writes an error to the Windows PowerShell error stream. By default, errors are sent to the host program to be displayed, along with output.
You can write an error by submitting an error message string, an ErrorRecord object, or an Exception object. Use the other parameters of Write-Error to populate the error record.
Parameters
-Category <ErrorCategory>
Specifies the category of the error. The default value is NotSpecified.
For information about the error categories, see "ErrorCategory Enumeration" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143600.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
NotSpecified |
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-CategoryActivity <string>
Describes the action that caused the error.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
None |
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-CategoryReason <string>
Explains how or why the activity caused the error.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
None |
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-CategoryTargetName <string>
Specifies the name of the object that was being processed when the error occurred.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
None |
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-CategoryTargetType <string>
Specifies the .NET type of the object that was being processed when the error occurred.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
None |
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-ErrorId <string>
Specifies an ID string to identify the error. The string should be unique to the error.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
None |
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-ErrorRecord <ErrorRecord>
Specifies an error record object that includes properties that describe the error.
To get an error record object, use the New-Object cmdlet or take an error record object from the array in the $Error automatic variable.
|
Required? |
true |
|
Position? |
named |
|
Default Value |
None |
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-Exception <Exception>
Specifies an exception that represents the error.
You can use an exception instead of specifying message text or an exception record.
|
Required? |
true |
|
Position? |
named |
|
Default Value |
None |
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-Message <string>
Specifies the message text of the error. If the text includes spaces or special characters, enclose it in quotation marks. You can also pipe a message string to Write-Error.
|
Required? |
true |
|
Position? |
1 |
|
Default Value |
None |
|
Accept Pipeline Input? |
true (ByValue) |
|
Accept Wildcard Characters? |
false |
-RecommendedAction <string>
Describes the action that the user should take to resolve or prevent the error.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
None |
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
-TargetObject <Object>
Specifies the object that was being processed when the error occurred. Enter the object (such as a string), a variable that contains the object, or a command that gets the object.
|
Required? |
false |
|
Position? |
named |
|
Default Value |
None |
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
<CommonParameters>
This command supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, and WarningVariable. For more information, see about_CommonParameters.
Inputs and Outputs
The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns.
|
Inputs |
System.String You can pipe a string that contains an error message to Write-Error. |
|
Outputs |
Error object Write-Error writes only to the error stream. It does not return any objects. |
Example 1
| Copy Code |
|
|---|---|
C:\PS>get-childitem | foreach-object { if ($_.gettype().tostring() -eq "Microsoft.Win32.RegistryKey") {write-error "Out-of-band object" -errorID B1 -targetobject $_ } else {$_ } }
|
|
Description
-----------
This command writes an error when the Get-ChildItem cmdlet returns a Microsoft.Win32.RegistryKey object, such as the objects in the HKLM: or HKCU drives of the Windows PowerShell Registry provider.
Example 2
| Copy Code |
|
|---|---|
C:\PS>write-error "Access denied." |
|
Description
-----------
This command writes an "Access denied" error. The command uses the Message parameter to specify the message, but omits the optional Message parameter name.
Example 3
| Copy Code |
|
|---|---|
C:\PS>write-error -message "Error: Too many input values." -category InvalidArgument |
|
Description
-----------
This command writes a error and specifies an error category.