必要的開發指導方針
當您撰寫 Cmdlet 時，必須遵循下列指導方針。 它們分成設計 Cmdlet 的指導方針和撰寫 Cmdlet 程式碼的指導方針。 如果您未遵循這些指導方針，您的 Cmdlet 可能會失敗，而且您的使用者在使用您的 Cmdlet 時可能會有不佳的體驗。
本主題內容
設計方針
程式碼指導方針
設計方針
設計 Cmdlet 時，必須遵循下列指導方針，以確保使用 Cmdlet 和其他 Cmdlet 之間的使用者體驗一致。 當您找到適用于您情況的設計指導方針時，請務必查看類似指導方針的程式碼指導方針。
只使用核准的動詞 (RD01)
Cmdlet 屬性中指定的動詞必須來自 Windows PowerShell 所提供的可辨識動詞集合。 它不得為其中一個禁止的同義字。 使用下列列舉所定義的常數位串來指定 Cmdlet 動詞命令：
如需已核准動詞名稱的詳細資訊，請參閱 Cmdlet 動詞命令。
使用者需要一組可探索和預期的 Cmdlet 名稱。 使用適當的動詞命令，讓使用者可以快速評估 Cmdlet 的功能，以及輕鬆地探索系統的功能。 例如，下列命令列命令會取得系統上名稱開頭為 "start" 的所有命令清單： get-command start-* 。 您可以使用 Cmdlet 中的名詞來區分 Cmdlet 與其他 Cmdlet。 名詞指出將在其上執行作業的資源。 作業本身是以動詞表示。
Cmdlet 名稱：無法使用 (RD02 的字元)
當您命名 Cmdlet 時，請勿使用下列任何特殊字元。
| 字元 | 名稱 |
|---|---|
| # | 數字正負號 |
| , | 逗號 |
| () | 括號 |
| {} | 括弧 |
| [] | 中括弧 |
| & | 符號 |
| - | 連字號 附注： 連字號可以用來分隔動詞和名詞，但不能用在名詞內或動詞內。 |
| / | 斜線 |
| \ | 反斜線 |
| $ | 貨幣符號 |
| ^ | caret |
| ; | 冒號 |
| : | 結腸 |
| " | 雙引號 |
| ' | 單引號 |
| <> | 角括弧 |
| | | 分隔號 |
| ? | 問號 |
| @ | @ 符號 |
| ` | 反向刻度 (抑音符號) |
| * | 星號 |
| % | 百分比符號 |
| + | 加號 |
| = | 等號 |
| ~ | 字型大小 |
無法使用的參數名稱 (RD03)
Windows PowerShell 提供一組通用參數給所有 Cmdlet，加上在特定情況下新增的其他參數。 設計您自己的 Cmdlet 時，您不能使用下列名稱： Confirm、Debug、ErrorAction、ErrorVariable、OutBuffer、OutVariable、WarningAction、WarningVariable、WhatIf、UseTransaction 和 Verbose。 如需這些參數的詳細資訊，請參閱 一般參數名稱。
(RD04) 支援確認要求
針對執行修改系統之作業的 Cmdlet，它們應該呼叫 ShouldProcess * 方法來要求確認，而且在特殊情況下，請呼叫 ShouldContinue * 方法，以進行確認。 (ShouldContinue * 方法應該只在呼叫 ShouldProcess * 方法之後，才呼叫。請將此方法呼叫。 )
為了進行這些呼叫，Cmdlet 必須藉由設定 Cmdlet 屬性的關鍵字，來指定它支援確認要求 SupportsShouldProcess 。 如需設定這個屬性的詳細資訊，請參閱 Cmdlet 屬性聲明。
注意
如果 Cmdlet 類別的 Cmdlet 屬性指出 Cmdlet 支援 ShouldProcess * 方法的呼叫，而此 Cmdlet 無法呼叫 ShouldProcess * 方法，則使用者可能會意外地修改系統（可能為可能為系統修改系統），而無法進行呼叫。
請使用 ShouldProcess * 方法進行任何系統修改。 使用者喜好設定和參數，會 WhatIf 控制 ShouldProcess * 方法。 相反地， ShouldContinue * 呼叫會執行額外的檢查，以進行潛在的危險修改。 這個方法不是由任何使用者喜好設定或參數所控制 WhatIf 。 如果您的 Cmdlet 呼叫 ShouldContinue * 方法，它應該會有一個 Force 參數，該參數會略過這兩個方法的呼叫，並繼續進行作業。 這點很重要，因為它可讓您的 Cmdlet 在非互動式腳本和主機中使用。
如果您的 Cmdlet 支援這些呼叫，使用者可以決定是否要實際執行動作。 例如， 停止進程指令程式 會在停止一組重要的進程（包括系統、Winlogon 和 Spoolsv 程式）之前，先呼叫 ShouldContinue * 方法。
如需有關支援這些方法的詳細資訊，請參閱 要求確認。
(RD05) 的互動式會話支援 Force 參數
如果您的 Cmdlet 以互動方式使用，請一律提供 Force 參數來覆寫互動式動作，例如提示或讀取輸入) 的行。 這點很重要，因為它可讓您的 Cmdlet 在非互動式腳本和主機中使用。 互動式主機可以執行下列方法。
(RD06) 檔輸出物件
Windows PowerShell 會使用寫入管線的物件。 為了讓使用者可以利用每個 Cmdlet 所傳回的物件，您必須記載傳回的物件，而且必須記錄這些傳回物件的成員會使用哪些內容。
程式碼指導方針
撰寫 Cmdlet 程式碼時，必須遵循下列指導方針。 當您找到適用于您的情況的程式碼指導方針時，請務必查看類似指導方針的設計指導方針。
衍生自 Cmdlet 或 PSCmdlet 類別 (RC01)
A cmdlet must derive from either the System.Management.Automation.Cmdlet or System.Management.Automation.PSCmdlet base class. 衍生自system.string 類別的Cmdlet 不會相依于 Windows PowerShell 執行時間。 您可以直接從任何 Microsoft .NET Framework 語言呼叫它們。 衍生自PSCmdlet類別的 Cmdlet 相依于 Windows PowerShell 執行時間。 因此，它們會在運行空間內執行。
您所執行的所有 Cmdlet 類別都必須是公用類別。 如需這些 Cmdlet 類別的詳細資訊，請參閱 Cmdlet 總覽。
指定 Cmdlet 屬性 (RC02)
針對 Windows PowerShell 可辨識的 Cmdlet，其 .NET Framework 類別必須以 Cmdlet 屬性裝飾。 這個屬性會指定 Cmdlet 的下列功能。
識別 Cmdlet 的動詞和名詞配對。
當指定多個參數集時，所使用的預設參數集。 當 Windows PowerShell 沒有足夠的資訊來判斷要使用哪一個參數時，就會使用預設參數集。
指出此 Cmdlet 是否支援對 ShouldProcess * 方法的呼叫。 此方法會在 Cmdlet 變更系統之前，對使用者顯示確認訊息。 如需有關如何提出確認要求的詳細資訊，請參閱 要求確認。
指出與確認訊息相關聯之動作的影響層級 (或嚴重性) 。 在大部分的情況下，應該使用預設值 Medium。 如需影響等級如何影響對使用者顯示之確認要求的詳細資訊，請參閱 要求確認。
如需如何宣告 Cmdlet 屬性的詳細資訊，請參閱 CmdletAttribute宣告。
(RC03 覆寫輸入處理方法)
若要讓 Cmdlet 參與 Windows PowerShell 環境，必須至少覆寫下列其中一個 輸入處理方法。
BeginProcessing 這個方法會呼叫一次，而且它會用來提供前置處理功能。
ProcessRecord 會多次呼叫這個方法，並使用它來提供記錄記錄的功能（record）。
（ EndProcessing ）會呼叫這個方法一次，並使用它來提供後續處理功能。
指定 OutputType 屬性 (RC04)
OutputType 屬性 (在 Windows PowerShell 2.0 中引進) 指定 Cmdlet 傳回給管線的 .NET Framework 類型。 藉由指定 Cmdlet 的輸出類型，您可以讓 Cmdlet 所傳回的物件更容易被其他 Cmdlet 探索。 如需使用這個屬性裝飾 Cmdlet 類別的詳細資訊，請參閱 OutputType 屬性宣告。
請勿保留輸出物件的控制碼 (RC05)
您的 Cmdlet 不應該保留傳遞給 WriteObject * 方法之物件的任何控制碼。 這些物件會傳遞至管線中的下一個 Cmdlet，或由腳本使用。 如果您保留物件的控制碼，兩個實體將擁有每個物件，而這會導致錯誤。
(RC06) ，以穩定的處理錯誤
系統管理環境原本就會偵測並對您所管理的系統進行重要變更。 因此，Cmdlet 很重要地處理錯誤。 如需錯誤記錄的詳細資訊，請參閱Windows PowerShell 錯誤報表。
當錯誤防止 Cmdlet 繼續處理任何其他記錄時，即為終止錯誤。 此 Cmdlet 必須呼叫 ThrowTerminatingError * 方法，該方法會參考 ErrorRecord 物件的.. 管理。 如果 Cmdlet 未攔截到例外狀況，Windows PowerShell 執行時間本身會擲回包含較少資訊的終止錯誤。
針對非終止錯誤，此錯誤不會在來自管線的下一個記錄上停止作業 (例如，由不同進程) 所產生的記錄，此 Cmdlet 必須呼叫 WriteError * 方法，該方法會參考 ErrorRecord 的物件。 非終止錯誤的其中一個範例是，如果特定進程無法停止，就會發生此錯誤。 呼叫 WriteError * 方法可讓使用者以一致的方式執行要求的動作，以及保留特定動作失敗的資訊。 您的 Cmdlet 應該盡可能獨立地處理每一筆記錄。
ErrorRecord所參考的 ThrowTerminatingError * 和 WriteError * 方法，在其核心上需要例外狀況的例外狀況（ * ）。 *方法需要例外狀況。 當您決定要使用的例外狀況時，請遵循 .NET Framework 的設計指導方針。 如果錯誤的語義與現有的例外狀況相同，請使用該例外狀況或衍生自該例外狀況。 否則，請直接從 system.string 類型衍生新的例外 狀況或例外狀況階層。
ErrorRecord物件也需要錯誤分類，以將使用者的錯誤群組在一起。 使用者可以藉由將 shell 變數的值設定為 CategoryView，以根據分類來查看錯誤 $ErrorView 。 可能的類別是由 ErrorCategory 列舉所定義。
如果 Cmdlet 會建立新的執行緒，而且如果在該執行緒中執行的程式碼擲回未處理的例外狀況，Windows PowerShell 將不會攔截到此錯誤，並會終止進程。
如果物件在其偵測器中的程式碼會造成未處理的例外狀況，Windows PowerShell 將不會攔截此錯誤，並將終止進程。 如果物件呼叫會造成未處理例外狀況的 Dispose 方法，也會發生這種情況。
使用 Windows PowerShell 模組，將您的 Cmdlet 部署 (RC07)
建立 Windows PowerShell 模組來封裝和部署您的 Cmdlet。 Windows PowerShell 2.0 中引進模組的支援。 您可以直接將包含 Cmdlet 類別的元件當作二進位模組檔案使用 (當您) 測試 Cmdlet 時，這非常有用，也可以建立參考 Cmdlet 元件的模組資訊清單。 (您也可以在使用模組時新增現有的嵌入式管理單元元件。 ) 如需模組的詳細資訊，請參閱撰寫 Windows PowerShell 模組。
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應