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 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 變數中。您可以使用哈希表來建立具有 Null 建構函式之型別的任何物件。

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

參數

-Category

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

未指定
OpenError
CloseError
DeviceError
DeadlockDetected
InvalidArgument
數據無效
無效操作
無效結果
無效類型
元數據錯誤
尚未實現
未安裝
ObjectNotFound 物件
作已停止
作超時
SyntaxError
解析錯誤
許可權被拒絕
資源繁忙
資源存在
資源不可用
讀取錯誤
WriteError （寫入錯誤）
FromStdErr
SecurityError 安全錯誤
ProtocolError
ConnectionError
AuthenticationError
超出限制
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
別名:	活動

參數集

(All)

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

-CategoryReason

指定活動造成錯誤的方式或原因。

參數屬性

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

參數集

(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

指定要識別錯誤的識別元字串。字串應該對錯誤而言是唯一的。

參數屬性

類型:	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（）方法。

意見反應

此頁面對您有幫助嗎？

共用方式為

Write-Error

語法

NoException (預設值)

WithException

ErrorRecord

Description

範例

範例 1：撰寫 RegistryKey 物件的錯誤

範例 2：將錯誤訊息寫入主控台

範例 3：將錯誤寫入主控台並指定類別

範例 4：使用 Exception 物件寫入錯誤

參數

-Category

參數屬性

參數集

-CategoryActivity

參數屬性

參數集

-CategoryReason

參數屬性

參數集

-CategoryTargetName

參數屬性

參數集

-CategoryTargetType

參數屬性

參數集

-ErrorId

參數屬性

參數集

-ErrorRecord

參數屬性

參數集

-Exception

參數屬性

參數集

-Message

參數屬性

參數集

-RecommendedAction

參數屬性

參數集

-TargetObject

參數屬性

參數集

CommonParameters

輸入

String

輸出

None

備註

相關連結

意見反應