Write-Error
Writes an object to the error stream.
Syntax
Write-Error
[-Message] <string>
[-Category <ErrorCategory>]
[-ErrorId <string>]
[-TargetObject <Object>]
[-RecommendedAction <string>]
[-CategoryActivity <string>]
[-CategoryReason <string>]
[-CategoryTargetName <string>]
[-CategoryTargetType <string>]
[<CommonParameters>]
Write-Error
[-Exception] <Exception>
[-Message <string>]
[-Category <ErrorCategory>]
[-ErrorId <string>]
[-TargetObject <Object>]
[-RecommendedAction <string>]
[-CategoryActivity <string>]
[-CategoryReason <string>]
[-CategoryTargetName <string>]
[-CategoryTargetType <string>]
[<CommonParameters>]
Write-Error
[-ErrorRecord] <ErrorRecord>
[-RecommendedAction <string>]
[-CategoryActivity <string>]
[-CategoryReason <string>]
[-CategoryTargetName <string>]
[-CategoryTargetType <string>]
[<CommonParameters>]
Description
The Write-Error
cmdlet declares a non-terminating error. By default, errors are sent in the error
stream to the host program to be displayed, along with output.
To write a non-terminating error, enter an error message string, an ErrorRecord object, or an
Exception object. Use the other parameters of Write-Error
to populate the error record.
Non-terminating errors write an error to the error stream, but they don't stop command processing. If a non-terminating error is declared on one item in a collection of input items, the command continues to process the other items in the collection.
To declare a terminating error, use the Throw
keyword.
For more information, see about_Throw.
Examples
Example 1: Write an error for RegistryKey object
Get-ChildItem | ForEach-Object {
if ($_.GetType().ToString() -eq "Microsoft.Win32.RegistryKey")
{
Write-Error "Invalid object" -ErrorId B1 -TargetObject $_
}
else
{
$_
}
}
This command declares a non-terminating error when the Get-ChildItem
cmdlet returns a
Microsoft.Win32.RegistryKey
object, such as the objects in the HKLM:
or HKCU:
drives of the
PowerShell Registry provider.
Example 2: Write an error message to the console
Write-Error "Access denied."
This command declares a non-terminating error and writes an "Access denied" error. The command uses the Message parameter to specify the message, but omits the optional Message parameter name.
Example 3: Write an error to the console and specify the category
Write-Error -Message "Error: Too many input values." -Category InvalidArgument
This command declares a non-terminating error and specifies an error category.
Example 4: Write an error using an Exception object
$E = [System.Exception]@{Source="Get-ParameterNames.ps1";HelpLink="https://go.microsoft.com/fwlink/?LinkID=113425"}
Write-Error -Exception $E -Message "Files not found. The $Files location doesn't contain any XML files."
This command uses an Exception object to declare a non-terminating error.
The first command uses a hash table to create the System.Exception object. It saves the
exception object in the $E
variable. You can use a hash table to create any object of a type that
has a null constructor.
The second command uses the Write-Error
cmdlet to declare a non-terminating error. The value of
the Exception parameter is the Exception object in the $E
variable.
Parameters
-Category
Specifies the category of the error. The default value is NotSpecified. The acceptable values for this parameter are:
- 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
- ProtocolError
- ConnectionError
- AuthenticationError
- LimitsExceeded
- QuotaExceeded
- NotEnabled
For information about the error categories, see ErrorCategory Enumeration.
Type: | ErrorCategory |
Accepted values: | 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, ProtocolError, ConnectionError, AuthenticationError, LimitsExceeded, QuotaExceeded, NotEnabled |
Position: | Named |
Default value: | NotSpecified |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CategoryActivity
Specifies the action that caused the error.
Type: | String |
Aliases: | Activity |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CategoryReason
Specifies how or why the activity caused the error.
Type: | String |
Aliases: | Reason |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CategoryTargetName
Specifies the name of the object that was being processed when the error occurred.
Type: | String |
Aliases: | TargetName |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CategoryTargetType
Specifies the type of the object that was being processed when the error occurred.
Type: | String |
Aliases: | TargetType |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ErrorId
Specifies an ID string to identify the error. The string should be unique to the error.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ErrorRecord
Specifies an error record object that represents the error. Use the properties of the object to describe the error.
To create an error record object, use the New-Object
cmdlet or get an error record object from the
array in the $Error
automatic variable.
Type: | ErrorRecord |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Exception
Specifies an exception object that represents the error. Use the properties of the object to describe the error.
To create an exception object, use a hash table or use the New-Object
cmdlet.
Type: | Exception |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Message
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
.
Type: | String |
Aliases: | Msg |
Position: | 0 |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-RecommendedAction
Specifies the action that the user should take to resolve or prevent the error.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TargetObject
Specifies the object that was being processed when the error occurred. Enter the object, a variable that contains the object, or a command that gets the object.
Type: | Object |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Inputs
You can pipe a string that contains an error message to this cmdlet.
Outputs
None
This cmdlet returns no output. It only writes to the error message stream.
Notes
Write-Error
doesn't change the value of the $?
automatic variable, therefore it doesn't signal a
terminating error condition. To signal a terminating error, use the
$PSCmdlet.WriteError() method.
Related Links
Σχόλια
https://aka.ms/ContentUserFeedback.
Σύντομα διαθέσιμα: Καθ' όλη τη διάρκεια του 2024 θα καταργήσουμε σταδιακά τα ζητήματα GitHub ως μηχανισμό ανάδρασης για το περιεχόμενο και θα το αντικαταστήσουμε με ένα νέο σύστημα ανάδρασης. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα:Υποβολή και προβολή σχολίων για