共用方式為

Write-Error

  • 參考
模組:
Microsoft.PowerShell.Utility

將物件寫入錯誤串流。

Syntax

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

Description

Cmdlet Write-Error 會宣告非終止錯誤。 根據預設，錯誤會透過錯誤串流連同輸出傳送至要顯示的主機程式。

若要寫入非終止錯誤，請輸入錯誤訊息字串、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 傳回 物件時Get-ChildItem宣告非終止錯誤，例如 PowerShell 登錄提供者的 或 HKCU: 磁碟驅動器中的 HKLM:Microsoft.Win32.RegistryKey 物件。

範例 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 。 您可以使用雜湊表建立具有 Null 建構函式類型的任何物件。

第二個命令會 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

指定識別錯誤的識別碼字串。 字串對於每個錯誤必須是唯一的。

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:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Exception

指定表示錯誤的例外狀況物件。 使用物件的屬性可描述錯誤。

若要建立例外狀況物件，請使用哈希表或使用 New-Object Cmdlet。

Type:Exception
Position:0
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

您可以使用管線將包含錯誤訊息的字串傳送至此 Cmdlet。

輸出

None

此 Cmdlet 不會傳回任何輸出。 它只會寫入錯誤訊息數據流。

備註

Write-Error 不會變更自動變數的值 $? ，因此不會發出終止錯誤狀況的訊號。 若要發出終止錯誤的訊號，請使用 $PSCmdlet.WriteError () 方法。