Cmdlet 應根據錯誤是否終止錯誤或非終止錯誤,以不同的方式報告錯誤。 終止錯誤是導致管線立即終止的錯誤,或是沒有理由繼續處理時所發生的錯誤。 非終止錯誤是報告目前錯誤狀況的錯誤,但 Cmdlet 可以繼續處理輸入物件。 非終止錯誤時,使用者通常會收到問題的通知,但 Cmdlet 會繼續處理下一個輸入物件。
終止和非終止錯誤
您可以使用下列指導方針來判斷錯誤狀況是終止錯誤或非終止錯誤。
錯誤狀況是否會讓您的 Cmdlet 無法成功處理任何進一步的輸入物件? 如果是的話,這就是終止錯誤。
與特定輸入物件或輸入物件子集相關的錯誤條件為何? 如果是的話,這就是非終止的錯誤。
指令程式是否接受多個輸入物件,因此處理可能會在另一個輸入物件上成功? 如果是的話,這就是非終止的錯誤。
可以接受多個輸入物件的 Cmdlet 應該決定什麼是終止和非終止的錯誤,即使特定情況只適用于單一輸入物件也是如此。
Cmdlet 可以接收任意數量的輸入物件,並在擲回終止例外狀況之前,傳送任何數目的成功或錯誤物件。 收到的輸入物件數目和傳送的成功與錯誤物件之間沒有任何關聯性。
只能接受0-1 輸入物件並產生0-1 輸出物件的 Cmdlet,應該將錯誤視為終止錯誤並產生終止例外狀況。
報告非終止錯誤
The reporting of a nonterminating error should always be done within the cmdlet's implementation of the System.Management.Automation.Cmdlet.BeginProcessing method, the System.Management.Automation.Cmdlet.ProcessRecord method, or the System.Management.Automation.Cmdlet.EndProcessing method. 這些類型的錯誤是藉由呼叫 WriteError 方法來報告,然後再將錯誤記錄傳送至錯誤資料流程。
報告終止錯誤
終止錯誤是藉由擲回例外狀況或 ThrowTerminatingError 方法來回報。 請注意,Cmdlet 也會攔截並重新擲回例外狀況(例如 OutOfMemory),但它們不需要重新擲回例外狀況,因為 PowerShell 執行時間也會攔截例外狀況。
您也可以針對您的情況特定的問題定義自己的例外狀況,或使用其錯誤記錄將其他資訊新增至現有的例外狀況。
錯誤記錄
PowerShell 會使用 ErrorRecord 物件來描述非終止錯誤狀況。 每個物件都提供錯誤類別資訊、選擇性的目標物件,以及有關錯誤狀況的詳細資料。
錯誤識別碼
錯誤識別碼是用來識別 Cmdlet 內錯誤狀況的簡單字串。 PowerShell 會將此識別碼與 Cmdlet 識別碼結合,以建立完整的錯誤識別碼,以供稍後在篩選錯誤資料流程或記錄錯誤時、回應特定錯誤時使用,或與其他使用者特定的活動搭配使用。
指定錯誤識別碼時,應遵循下列指導方針:
將不同、高度特定的錯誤識別碼指派給不同的程式碼路徑。 每個呼叫 WriteError 或 ThrowTerminatingError 的程式碼路徑,都應該有自己的錯誤識別碼(error identifier)。
對於終止和非終止錯誤而言,錯誤識別碼應該是通用語言執行時間唯一的 (CLR) 例外狀況類型。
請勿變更 Cmdlet 版本與 PowerShell 提供者之間的錯誤識別碼的語法。 在建立錯誤識別碼的語義之後,它應該會在 Cmdlet 的整個生命週期中保持不變。
若為終止錯誤,請針對特定 CLR 例外狀況類型使用唯一的錯誤識別碼。 如果例外狀況類型變更,請使用新的錯誤識別碼。
針對非終止錯誤,請使用特定輸入物件的特定錯誤識別碼。
選擇 tersely 對應至所報告錯誤的識別碼文字。 請勿使用空白字元或標點符號。
不要產生無法重現的錯誤識別碼。 例如,不要產生包含處理序識別碼的識別碼。 只有當錯誤識別碼對應至其他遇到相同問題的使用者所看到的識別碼時,才會很有用。
錯誤類別
錯誤類別用來群組使用者的錯誤。 PowerShell 定義這些類別和 Cmdlet,且 PowerShell 提供者在產生錯誤記錄時,必須在兩者之間進行選擇。
如需可用錯誤類別的描述,請參閱 ErrorCategory 列舉。 一般而言,您應該盡可能避免使用 >aad-userreadusingalternativesecurityid-noerror、 UndefinedError 和 GenericError 。
當使用者設定為 CategoryView 時,可以根據類別來查看錯誤 $ErrorView 。