Write-Error
將物件寫入錯誤資料流。
語法
Write-Error -ErrorRecord <ErrorRecord> [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]
Write-Error [-Message] <string> [-Category {<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>}] [-ErrorId <string>] [-TargetObject <Object>] [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]
Write-Error -Exception <Exception> [-Category {<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>}] [-ErrorId <string>] [-Message <string>] [-TargetObject <Object>] [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]
描述
Write-Error Cmdlet 會將錯誤寫入 Windows PowerShell 錯誤資料流。根據預設，錯誤會連同輸出一起傳送至即將顯示的主機程式。
您可以透過提交錯誤訊息字串、ErrorRecord 物件或 Exception 物件，寫入錯誤。請使用 Write-Error 的其他參數來填入錯誤記錄。
參數
-Category <ErrorCategory>
指定錯誤的類別。預設值為 NotSpecified。
如需錯誤類別的詳細資訊，請參閱 MSDN (Microsoft Developer Network) Library 中的＜ErrorCategory 列舉＞(英文)，網址為：https://go.microsoft.com/fwlink/?LinkId=143600。
必要? |
false |
位置? |
named |
預設值 |
NotSpecified |
接受管線輸入? |
false |
接受萬用字元? |
false |
-CategoryActivity <string>
描述造成錯誤的動作。
必要? |
false |
位置? |
named |
預設值 |
無 |
接受管線輸入? |
false |
接受萬用字元? |
false |
-CategoryReason <string>
說明活動造成錯誤的情況或原因。
必要? |
false |
位置? |
named |
預設值 |
無 |
接受管線輸入? |
false |
接受萬用字元? |
false |
-CategoryTargetName <string>
指定錯誤發生時正在進行處理的物件之名稱。
必要? |
false |
位置? |
named |
預設值 |
無 |
接受管線輸入? |
false |
接受萬用字元? |
false |
-CategoryTargetType <string>
指定錯誤發生時正在進行處理的物件之 .NET 型別。
必要? |
false |
位置? |
named |
預設值 |
無 |
接受管線輸入? |
false |
接受萬用字元? |
false |
-ErrorId <string>
指定要識別錯誤的識別碼字串。此字串對錯誤而言必須是唯一的。
必要? |
false |
位置? |
named |
預設值 |
無 |
接受管線輸入? |
false |
接受萬用字元? |
false |
-ErrorRecord <ErrorRecord>
指定錯誤記錄物件，其中包含描述錯誤的屬性。
若要取得錯誤記錄物件，請使用 New-Object Cmdlet，或從 $Error 自動變數中的陣列取得錯誤記錄物件。
必要? |
true |
位置? |
named |
預設值 |
無 |
接受管線輸入? |
false |
接受萬用字元? |
false |
-Exception <Exception>
指定代表錯誤的例外狀況。
您可以用例外狀況來代替指定訊息文字或例外狀況記錄。
必要? |
true |
位置? |
named |
預設值 |
無 |
接受管線輸入? |
false |
接受萬用字元? |
false |
-Message <string>
指定錯誤的訊息文字。如果文字中包含空格或特殊字元，請將其置於引號內。您也可經由管道將訊息字串輸出至 Write-Error。
必要? |
true |
位置? |
1 |
預設值 |
無 |
接受管線輸入? |
true (ByValue) |
接受萬用字元? |
false |
-RecommendedAction <string>
描述使用者可採取的因應措施，以解決或防止錯誤。
必要? |
false |
位置? |
named |
預設值 |
無 |
接受管線輸入? |
false |
接受萬用字元? |
false |
-TargetObject <Object>
指定錯誤發生時正在進行處理的物件。請輸入物件 (如字串)、含有物件的變數或可取得物件的命令。
必要? |
false |
位置? |
named |
預設值 |
無 |
接受管線輸入? |
false |
接受萬用字元? |
false |
<CommonParameters>
這個 Cmdlet 支援一般參數：-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。如需詳細資訊，請參閱 about_Commonparameters.
輸入和輸出
輸入型別是可經由管道輸出至 Cmdlet 的物件型別。傳回型別則是 Cmdlet 所傳回的物件型別。
輸入 |
System.String 您可經由管道將包含錯誤訊息的字串輸出至 Write-Error。 |
輸出 |
Error object Write-Error 只會寫入錯誤資料流。它不會傳回任何物件。 |
範例 1
C:\PS>get-childitem | foreach-object { if ($_.gettype().tostring() -eq "Microsoft.Win32.RegistryKey") {write-error "Out-of-band object" -errorID B1 -targetobject $_ } else {$_ } }
描述
-----------
當 Get-ChildItem Cmdlet 傳回 Microsoft.Win32.RegistryKey 物件 (例如 Windows PowerShell 登錄提供者之 HKLM: 或 HKCU 磁碟機中的物件) 時，這個命令就會寫入錯誤。
範例 2
C:\PS>write-error "Access denied."
描述
-----------
這個命令會寫入 "Access denied" 錯誤，並使用 Message 參數指定該訊息，但省略選擇性的 Message 參數名稱。
範例 3
C:\PS>write-error -message "Error: Too many input values." -category InvalidArgument
描述
-----------
這個命令會寫入錯誤並指定錯誤類別。
請參閱
概念
Write-Debug
Write-Verbose
Write-Output
Write-Host
Write-Progress
Write-Warning