powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Write-Error



NAME
Write-Error

SYNOPSIS
Writes an object to the error stream.

SYNTAX
Write-Error -ErrorRecord [-CategoryActivity ] [-CategoryReason ] [-CategoryTargetName
] [-CategoryTargetType ] [-RecommendedAction ] []

Write-Error [-Message] [-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}] [-Er
rorId ] [-TargetObject ] [-CategoryActivity ] [-CategoryReason ] [-CategoryTargetNa
me ] [-CategoryTargetType ] [-RecommendedAction ] []

Write-Error -Exception [-Category {NotSpecified | OpenError | CloseError | DeviceError | DeadlockDetect
ed | InvalidArgument | InvalidData | InvalidOperation | InvalidResult | InvalidType | MetadataError | NotImplemente
d | NotInstalled | ObjectNotFound | OperationStopped | OperationTimeout | SyntaxError | ParserError | PermissionDen
ied | ResourceBusy | ResourceExists | ResourceUnavailable | ReadError | WriteError | FromStdErr | SecurityError}] [
-ErrorId ] [-Message ] [-TargetObject ] [-CategoryActivity ] [-CategoryReason ng>] [-CategoryTargetName ] [-CategoryTargetType ] [-RecommendedAction ] [ >]


DESCRIPTION
The Write-Error cmdlet writes an error to the Windows PowerShell error stream. By default, errors are sent to the h
ost 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 t
he other parameters of Write-Error to populate the error record.


PARAMETERS
-Category
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 Ne
twork) 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
Describes the action that caused the error.

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

-CategoryReason
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
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
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
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
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
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
Specifies the message text of the error. If the text includes spaces or special characters, enclose it in quot
ation 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
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
Specifies the object that was being processed when the error occurred. Enter the object (such as a string), a v
ariable 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


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

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.


NOTES





-------------------------- EXAMPLE 1 --------------------------

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 th
e objects in the HKLM: or HKCU drives of the Windows PowerShell Registry provider.





-------------------------- EXAMPLE 2 --------------------------

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 om
its the optional Message parameter name.





-------------------------- EXAMPLE 3 --------------------------

C:\PS>write-error -message "Error: Too many input values." -category InvalidArgument


Description
-----------
This command writes a error and specifies an error category.






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113425
Write-Debug
Write-Verbose
Write-Output
Write-Host
Write-Progress
Write-Warning