Write-Error

模組:

Microsoft.PowerShell.Utility Module

將物件寫入錯誤串流。

語法

NoException (預設值)

Write-Error
    [-Message] <string>
    [-Category <ErrorCategory>]
    [-ErrorId <string>]
    [-TargetObject <Object>]
    [-RecommendedAction <string>]
    [-CategoryActivity <string>]
    [-CategoryReason <string>]
    [-CategoryTargetName <string>]
    [-CategoryTargetType <string>]
    [<CommonParameters>]

WithException

Write-Error
    [-Exception] <Exception>
    [-Message <string>]
    [-Category <ErrorCategory>]
    [-ErrorId <string>]
    [-TargetObject <Object>]
    [-RecommendedAction <string>]
    [-CategoryActivity <string>]
    [-CategoryReason <string>]
    [-CategoryTargetName <string>]
    [-CategoryTargetType <string>]
    [<CommonParameters>]

ErrorRecord

Write-Error
    [-ErrorRecord] <ErrorRecord>
    [-RecommendedAction <string>]
    [-CategoryActivity <string>]
    [-CategoryReason <string>]
    [-CategoryTargetName <string>]
    [-CategoryTargetType <string>]
    [<CommonParameters>]

Description

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

當 Get-ChildItem 指令檔回傳 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：使用例外物件寫入錯誤

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

此指令使用 例外 物件來宣告非終止錯誤。

第一個指令使用雜湊表來建立 System.Exception 物件。 它會將例外物件儲存在變數中 $E 。 你可以用雜湊表來建立任何帶有空建構子的物件類型。

第二個指令使用 Write-Error cmdlet 來宣告非終止錯誤。 Exception 參數的值是變數中的 $E 物件。

參數

-Category

指定錯誤的類別。 預設值為 NotSpecified。 此參數可接受的值為：

• 未指定
• OpenError
• 關閉錯誤
• 裝置錯誤
• 偵測到死結
• 無效參數
• InvalidData
• 無效操作
• 無效結果
• InvalidType
• 元資料錯誤
• NotImplemented
• 未安裝
• 物件未找到
• 行動停止
• 操作暫停
• 語法錯誤
• 解析錯誤
• 權限已拒絕
• 資源忙碌
• ResourceExists
• 資源不可用
• 讀取錯誤
• WriteError
• 來自StdErr
• 安全錯誤
• 協議錯誤
• 連接錯誤
• 認證錯誤
• 極限超越
• QuotaExceeded
• NotEnabled

關於錯誤類別的資訊，請參見 ErrorCategory 列舉。

參數屬性

類型:	ErrorCategory
預設值:	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
支援萬用字元:	False
不要顯示:	False

參數集

NoException

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

WithException

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-CategoryActivity

指定導致錯誤的動作。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	Activity

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-CategoryReason

說明活動如何或為何導致錯誤。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	Reason

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-CategoryTargetName

指定錯誤發生時正在處理的物件名稱。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	TargetName

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-CategoryTargetType

指定錯誤發生時正在處理的物件類型。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	目標類型

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ErrorId

指定一個 ID 字串來識別錯誤。 字串應該是錯誤唯一的。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

NoException

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

WithException

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ErrorRecord

指定一個代表錯誤的錯誤記錄物件。 利用物件的特性來描述錯誤。

要建立錯誤記錄物件，請使用 New-Object cmdlet 或從自動變數陣 $Error 列取得錯誤記錄物件。

參數屬性

類型:	ErrorRecord
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ErrorRecord

Position:	0
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Exception

指定一個代表錯誤的例外物件。 利用物件的特性來描述錯誤。

要建立例外物件，可以使用雜湊表或 New-Object cmdlet。

參數屬性

類型:	Exception
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

WithException

Position:	0
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Message

指定錯誤訊息的文字內容。 如果文字包含空格或特殊字元，請用引號包圍。 你也可以將訊息串管道接到 Write-Error。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	味精

參數集

NoException

Position:	0
必要:	True
來自管線的值:	True
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

WithException

Position:	0
必要:	False
來自管線的值:	True
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-RecommendedAction

指定使用者應採取的行動來解決或防止錯誤。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-TargetObject

指定錯誤發生時正在處理的物件。 輸入物件、包含該物件的變數，或取得該物件的指令。

參數屬性

類型:	Object
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

NoException

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

WithException

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CommonParameters

此 cmdlet 支援常見參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊，請參閱 about_CommonParameters。

輸入

String

你可以將包含錯誤訊息的字串輸入這個 cmdlet。

輸出

None

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

備註

Write-Error 不會改變自動變數的 $? 值，因此不會表示終止錯誤條件。 要發出終止錯誤訊號，請使用 $PSCmdlet.WriteError（） 方法。

相關連結

• 關於自動變數
• about_Output_Streams
• 關於_重定向
• 寫入-除錯
• Write-Host
• 輸出寫入
• 寫入進度
• Write-Verbose
• Write-Warning