Cmdlet 必須傳遞 ErrorRecord 物件,以識別終止和非終止錯誤的錯誤狀況。
ErrorRecord物件中包含下列資訊:
- 描述錯誤的例外狀況。 這通常是 Cmdlet 攔截並轉換成錯誤記錄的例外狀況。 每個錯誤記錄都必須包含例外狀況。
如果 Cmdlet 未攔截到例外狀況,則必須建立新的例外狀況,並選擇最能描述錯誤狀況的例外狀況類別。 不過,您不需要擲回例外狀況,因為它可以透過 ErrorRecord 物件的ErrorRecord 物件的 exception 屬性來存取。
提供目標指示項的錯誤識別碼,可用於診斷用途,以及藉由 Windows PowerShell 腳本來處理特定錯誤處理常式的特定錯誤狀況。 每個錯誤記錄都必須包含錯誤識別碼 (請參閱錯誤識別碼) 。
提供可用於診斷用途之一般指示項的錯誤類別。 每個錯誤記錄都必須指定錯誤類別 (查看錯誤類別目錄) 。
選用的取代錯誤訊息和建議的動作 (查看取代錯誤訊息) 。
擲回錯誤之 Cmdlet 的選擇性調用資訊。 這項資訊是由 Windows PowerShell (查看調用訊息) 。
發生錯誤時正在處理的目標物件。 這可能是輸入物件,也可能是您的 Cmdlet 正在處理的另一個物件。 例如,針對命令
remove-item -recurse c:\somedirectory,錯誤可能是 "c:\somedirectory\lockedfile" 的 FileInfo 物件實例。 目標物件資訊是選擇性的。
錯誤識別碼
當您建立錯誤記錄時,請指定在您的 Cmdlet 中指定錯誤狀況的識別碼。 Windows PowerShell 將目標識別碼與 Cmdlet 的名稱結合,以建立完整的錯誤識別碼。 您可以透過ErrorRecord物件的ErrorRecord. FullyQualifiedErrorId屬性來存取完整的錯誤識別元(property)。 錯誤識別碼本身不提供。 它只可作為完整錯誤識別碼的一部分。
當您建立錯誤記錄時,請使用下列指導方針來產生錯誤識別碼:
請為錯誤狀況特定的錯誤識別碼。 針對診斷目的,以及使用特定錯誤處理常式處理特定錯誤狀況的腳本,設定目標為錯誤識別碼。 使用者應該能夠使用錯誤識別碼來識別錯誤及其來源。 錯誤識別碼也可讓您從現有的例外狀況報告特定錯誤狀況,如此就不需要新的例外狀況子類別。
一般情況下,請將不同的錯誤識別碼指派給不同的程式碼路徑。 終端使用者從特定識別碼獲益。 通常,每個呼叫 WriteError 的程式碼路徑,或 Throwterminatingerror * 都有它自己的識別元。 當您為錯誤訊息定義新的範本字串時,請定義新的識別碼,反之亦然。 請勿使用錯誤訊息做為識別碼。
當您使用特定的錯誤識別碼發佈程式碼時,您可以為您的完整產品支援週期,使用該識別碼來建立錯誤的語法。 請勿在與原始內容語義不同的內容中重複使用它。 如果此錯誤的語義變更,請建立,然後使用新的識別碼。
一般來說,您應該只針對特定 CLR 型別的例外狀況使用特定的錯誤識別碼。 如果例外狀況的類型或目標物件的類型變更,請建立,然後使用新的識別碼。
針對您要報告的錯誤,選擇與您的錯誤識別碼相關的文字。 使用標準 .NET Framework 命名和大小寫慣例。 請勿使用空白字元或標點符號。 請勿將錯誤識別碼當地語系化。
請勿以無法重現的方式動態產生錯誤識別碼。 例如,請勿併入錯誤資訊,例如處理序識別碼。 如果錯誤識別碼對應至其他遇到相同錯誤狀況的使用者所看到的錯誤識別碼,就很有用。
錯誤類別
當您建立錯誤記錄時,請使用 ErrorCategory 列舉所定義的其中一個常數來指定錯誤的類別。 當使用者將變數設定為時,Windows PowerShell 會使用 [錯誤] 類別來顯示錯誤資訊 $ErrorView "CategoryView" 。
請避免使用ErrorCategory NotSpecified 常數。 如果您有任何關於錯誤或造成錯誤之作業的資訊,請選擇最能描述錯誤或作業的類別,即使類別不是完全相符。
Windows PowerShell 所顯示的資訊稱為類別目錄檢視字串,且是從Errorcategoryinfo類別的屬性所建立。 (這個類別是透過 ErrorRecord CategoryInfo 屬性來存取。 )
{Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason}
下列清單說明顯示的資訊:
Category: Windows PowerShell 定義的ErrorCategory常數。
TargetName:根據預設,當錯誤發生時,此 Cmdlet 所處理的物件名稱。 或另一個 Cmdlet 定義的字串。
TargetType:根據預設,目標物件的類型。 或另一個 Cmdlet 定義的字串。
活動:根據預設,建立錯誤記錄的 Cmdlet 名稱。 或其他 Cmdlet 定義的字串。
原因:根據預設,例外狀況類型。 或另一個 Cmdlet 定義的字串。
取代錯誤訊息
當您開發 Cmdlet 的錯誤記錄時,錯誤的預設錯誤訊息是來自 system.string 屬性中 的預設郵件內文。 這是唯讀屬性,其郵件內文僅供根據 .NET Framework 的指導) 方針 (的偵錯工具用途。 建議您建立取代或增強預設郵件內文的錯誤訊息。 讓訊息更容易使用,而且更明確地指向 Cmdlet。
取代的訊息是由 ErrorDetails 物件提供。 使用這個物件的下列其中一種函式,因為它們提供可供 Windows PowerShell 使用的其他當地語系化資訊。
ErrorDetails (Cmdlet、string、string、Object [] ) :如果您的範本字串是在執行 Cmdlet 之相同元件中的資源字串,或您想要透過 GetResourceString 方法的覆寫載入範本字串,請使用此函式。
ErrorDetails (Assembly、string、string、Object [] ) :如果範本字串是在另一個元件中,而您未透過 GetResourceString的覆寫載入,請使用此函式。
取代訊息應該符合 .NET Framework 的設計指導方針,以使用較小的差異來撰寫例外狀況訊息。 這些指導方針指出應該為開發人員撰寫例外狀況訊息。 應針對 Cmdlet 使用者撰寫這些取代訊息。
您必須在呼叫 WriteError 或 Throwterminatingerror * 方法之前,先新增取代錯誤訊息,然後才會呼叫。 若要加入取代訊息,請設定錯誤記錄的 ErrorRecord. ErrorDetails 屬性。 當設定這個屬性時,Windows PowerShell 會顯示ErrorDetails *屬性,而不是預設的郵件內文。
建議的動作資訊
ErrorDetails物件也可以提供錯誤發生時所建議動作的相關資訊。
調用資訊
當 Cmdlet 使用WriteError或Throwterminatingerror *來報告錯誤記錄時,Windows PowerShell 會自動加入描述錯誤發生時所叫用之命令的資訊,自動新增資訊。 這項資訊是由 Invocationinfo 物件所提供,其中包含命令所叫用的 Cmdlet 名稱、命令本身,以及有關管線或腳本的資訊。 這是唯讀的屬性。