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
    {
        $_
    }
}

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

示例 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 does not contain any XML files."

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

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

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

参数

-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 枚举。

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

指定导致错误的操作。

Type:	String
Aliases:	Activity
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CategoryReason

指定活动导致错误的方式或原因。

Type:	String
Aliases:	Reason
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CategoryTargetName

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

Type:	String
Aliases:	TargetName
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CategoryTargetType

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

Type:	String
Aliases:	TargetType
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ErrorId

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

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ErrorRecord

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

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

Type:	ErrorRecord
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Exception

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

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

Type:	Exception
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Message

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

Type:	String
Aliases:	Msg
Position:	0
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-RecommendedAction

指定用户应执行的操作来解决或阻止错误。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TargetObject

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

Type:	Object
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

输入

String

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

输出

Error object

Write-Error 仅写入错误流。它不返回任何对象。

备注

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