Come and Check our BETA Alpha version of Powershellcenter.net
Send me your comment to Powershell@powershellcenter.com

Synopsis

Writes an object to the error stream.

Syntax

Write-Error [-Message] <String> [-Category <ErrorCategory>] [-CategoryActivity <String>] [-CategoryReason <String>] [-CategoryTargetName <String>] [-CategoryTargetType <String>] [-ErrorId <String>] [-RecommendedAction <String>] [-TargetObject <Object>] [<CommonParameters>]

Write-Error [-Category <ErrorCategory>] [-CategoryActivity <String>] [-CategoryReason <String>] [-CategoryTargetName <String>] [-CategoryTargetType <String>] [-ErrorId <String>] [-Message <String>] [-RecommendedAction <String>] [-TargetObject <Object>] -Exception <Exception> [<CommonParameters>]

Write-Error [-CategoryActivity <String>] [-CategoryReason <String>] [-CategoryTargetName <String>] [-CategoryTargetType <String>] [-RecommendedAction <String>] -ErrorRecord <ErrorRecord> [<CommonParameters>]

Detailed 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 do not 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 (http://go.microsoft.com/fwlink/?LinkID=145153).

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 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 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.

Required?   true
Position?   named
Default value?   None
Accept pipeline input?   false
Accept wildcard characters?   false

-Exception [<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.

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

Input Type

System.String

You can pipe a string that contains an error message to Write-Error.

Return Type

Error object

Write-Error writes only to the error stream. It does not return any objects.

Notes

Examples

EXAMPLE 1

PS> PS C:\>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 Windows PowerShell Registry provider.

EXAMPLE 2

PS> PS C:\>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

PS> PS C:\>Write-Error -Message "Error: Too many input values." -Category InvalidArgument

This command declares a non-terminating error and specifies an error category.

EXAMPLE 4

PS> PS C:\>$e = [System.Exception]@{$e = [System.Exception]@{Source="Get-ParameterNames.ps1";HelpLink="http://go.microsoft.com/fwlink/?LinkID=113425"}HelpLink="http://go.microsoft.com/fwlink/?LinkID=113425"} PS C:\> Write-Error $e -Message "Files not found. The $Files location does not 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.