Write-Error

将对象写入错误流。

语法

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:Named
默认值:None
必需:True
接受管道输入:False
接受通配符:False

-Exception

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

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

类型:Exception
Position:Named
默认值: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() 方法。