Write-Error

参考

模块:: Microsoft.PowerShell.Utility

将对象写入错误流。

语法

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

说明

Write-Error cmdlet 声明非终止错误。默认情况下，将错误随输出一起在错误流中发送到主机程序来显示。

若要编写非终止错误，请输入错误消息字符串、ErrorRecord 对象，或 Exception 对象。请使用 Write-Error 的其他参数来填充错误记录。

非终止错误将错误写入到错误流，但它们不会停止命令处理。如果在输入项的集合中的一个项上声明非终止错误，则该命令会继续处理集合中的其他项。

若要声明终止错误，请使用 Throw 关键字。有关详细信息，请参阅 about_Throw。

示例

示例 1：编写 RegistryKey 对象的错误

Get-ChildItem | ForEach-Object {
    if ($_.GetType().ToString() -eq "Microsoft.Win32.RegistryKey")
    {
        Write-Error "Invalid object" -ErrorId B1 -TargetObject $_
    }
    else
    {
        $_
    }
}

当 Get-ChildItem cmdlet 返回 Microsoft.Win32.RegistryKey 对象（例如 PowerShell 注册表提供程序的 HKLM: 或 HKCU: 驱动器中的对象）时，此命令声明一个非终止错误。

示例 2：将错误消息写入到控制台

Write-Error "Access denied."

此命令声明一个非终止错误，并写入“拒绝访问”错误。此命令使用 Message 参数指定消息，但省略可选的 Message 参数名称。

示例 3：将错误写入到控制台并指定类别

Write-Error -Message "Error: Too many input values." -Category InvalidArgument

此命令声明一个非终止错误，并指定错误类别。

示例 4：使用 Exception 对象编写错误

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

此命令使用 Exception 对象声明一个非终止错误。

第一个命令使用哈希表来创建 System.Exception 对象。它将异常对象保存在 $E 变量中。可以使用哈希表来创建具有空构造函数的类型的任何对象。

第二个命令使用 Write-Error cmdlet 声明一个非终止错误。 Exception 参数的值是 $E 变量中的 Exception 对象。

参数

-Category

指定的错误类别。默认值为 NotSpecified。此参数的可接受值为：

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

有关错误类别的信息，请参阅 ErrorCategory 枚举。

类型:	ErrorCategory
接受的值:	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
默认值:	NotSpecified
必需:	False
接受管道输入:	False
接受通配符:	False

-CategoryActivity

指定导致了此错误的操作。

类型:	String
别名:	Activity
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-CategoryReason

指定该活动如何或为什么导致了此错误。

类型:	String
别名:	Reason
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-CategoryTargetName

指定当发生错误时被处理的对象的名称。

类型:	String
别名:	TargetName
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-CategoryTargetType

指定当发生错误时被处理的对象的类型。

类型:	String
别名:	TargetType
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ErrorId

指定 ID 字符串以标识错误。字符串应该是唯一的错误。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ErrorRecord

指定一个表示错误的错误记录对象。使用对象的属性来描述错误。

要创建错误记录对象，请使用 New-Object cmdlet 或从 $Error 自动变量中的数组获取错误记录对象。

类型:	ErrorRecord
Position:	0
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-Exception

指定一个表示错误的异常对象。使用对象的属性来描述错误。

若要创建异常对象，请使用哈希表，或者使用 New-Object cmdlet。

类型:	Exception
Position:	0
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-Message

指定错误的消息文本。如果文本包含空格或特殊字符，则将其括在引号中。还可通过管道将消息字符串传递给 Write-Error。

类型:	String
别名:	Msg
Position:	0
默认值:	None
必需:	False
接受管道输入:	True
接受通配符:	False

-RecommendedAction

指定用户应当采取的用来解决或防止出现此错误的操作。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-TargetObject

指定当发生错误时被处理的对象。输入该对象，一个包含该对象的变量，或一个获取该对象的命令。

类型:	Object
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

输入

String

可以通过管道将包含错误消息的字符串传递给此 cmdlet。

输出

None

此 cmdlet 不返回任何输出。它只写入错误消息流。

备注

Write-Error 不会更改 $? 自动变量的值，因此它不会发出终止错误条件的信号。要发出终止错误的信号，请使用 $PSCmdlet.WriteError() 方法。

通过