強烈建議開發準則

2025-04-04

本節說明撰寫 Cmdlet 時應該遵循的指導方針。它們分成設計 Cmdlet 的指導方針，以及撰寫 Cmdlet 程式代碼的指導方針。您可能會發現這些指導方針不適用於每個案例。不過，如果他們確實適用，而且您未遵循這些指導方針，您的使用者在使用 Cmdlet 時可能會有不良的體驗。

設計指導方針

設計 Cmdlet 時，應遵循下列指導方針，以確保使用 Cmdlet 與其他 Cmdlet 之間的一致用戶體驗。當您找到適用於您情況的設計指導方針時，請務必查看類似指導方針的程式代碼指導方針。

針對 Cmdlet 名稱使用特定名詞（SD01）

Cmdlet 命名中使用的名詞必須非常明確，使用者才能探索您的 Cmdlet。將泛型名詞，例如「伺服器」，加在產品名稱的縮略版本前面。例如，如果名詞是指執行 Microsoft SQL Server 實例的伺服器，請使用名詞，例如 “SQLServer”。特定名詞和已核准動詞簡短清單的組合，可讓使用者快速探索和預期功能，同時避免 Cmdlet 名稱之間重複。

為了增強用戶體驗，您為 Cmdlet 名稱選擇的名詞應該是單一的。例如，使用名稱 Get-Process 而不是 Get-Processes。最好針對所有 Cmdlet 名稱遵循此規則，即使 Cmdlet 可能會對多個專案採取行動也一樣。

針對 Cmdlet 名稱使用 Pascal 案例（SD02）

針對參數名稱使用Pascal大小寫。換句話說，將動詞的第一個字母和名詞中使用的所有詞彙大寫。例如，"Clear-ItemProperty"。

參數設計指導方針（SD03）

Cmdlet 需要可接收其必須處理的數據的參數，以及用來決定操作特性的資訊參數。例如，Cmdlet 可能會有一個 Name 從管線接收數據的參數，而 Cmdlet 可能會有參數 Force 來指出 Cmdlet 可以強制執行其作業。 Cmdlet 可以定義的參數數目沒有限制。

使用標準參數名稱

您的 Cmdlet 應該使用標準參數名稱，讓使用者可以快速判斷特定參數的意義。如果需要更特定的名稱，請使用標準參數名稱，然後將更特定的名稱指定為別名。例如，Get-ServiceCmdlet 具有具有泛型名稱（）和更特定別名（NameServiceName）的參數。這兩個詞彙都可以用來指定參數。

如需參數名稱及其數據類型的詳細資訊，請參閱 Cmdlet 參數名稱和功能指導方針。

使用單一參數名稱

請避免針對值為單一元素的參數使用複數名稱。這包括接收陣列或列表的參數，因為使用者可能會提供只有一個元素的陣列或列表。

複數參數名稱應該只在參數的值一律為多重元素值的情況下使用。在這些情況下，Cmdlet 應該確認已提供多個元素，如果未提供多個元素，Cmdlet 應該向用戶顯示警告。

針對參數名稱使用Pascal Case

針對參數名稱使用Pascal大小寫。換句話說，將參數名稱中每個單字的第一個字母大寫，包括名稱的第一個字母。例如，參數名稱 ErrorAction 會使用正確的大寫。下列參數名稱使用不正確的大寫：

errorAction
erroraction

採用選項清單的參數

有兩種方式可以建立參數，其值可以從一組選項中選取。

定義列舉型別（或使用現有的列舉型別），以指定有效值。然後，使用列舉型別來建立該類型的參數。
將 ValidateSet 屬性新增至參數宣告。如需此屬性的詳細資訊，請參閱 ValidateSet 屬性宣告。

針對參數使用標準類型

若要確保與其他 Cmdlet 的一致性，請盡可能對參數使用標準類型。如需應該用於不同參數之類型的詳細資訊，請參閱標準 Cmdlet 參數名稱和類型。本主題提供數個主題的連結，這些主題描述標準參數群組的名稱和 .NET Framework 類型，例如「活動參數」。

使用 Strongly-Typed .NET Framework 類型

參數應定義為 .NET Framework 類型，以提供更佳的參數驗證。例如，限制為一組值的參數應該定義為列舉型別。若要支援統一資源識別碼（URI）值，請將參數定義為 System.Uri 類型。請除自由形式文字屬性外，避免使用基本字串參數。

使用一致的參數類型

當多個 Cmdlet 使用相同的參數時，一律使用相同的參數類型。例如，如果 Process 參數是一個 Cmdlet 的 System.Int16 類型，請勿將另一個 Cmdlet 的參數設為 ProcessSystem.Uint16 類型。

採用 True 和 False 的參數

如果您的參數只 true 接受和 false，請將參數定義為 System.Management.Automation.SwitchParameter 類型。當在命令中指定開關參數時，此參數被視為true 。如果參數未包含在命令中，Windows PowerShell 會將參數 false的值視為。請勿定義布爾參數。

如果您的參數需要區分 3 個值：$true、$false 和「未指定」，請定義 Nullable<bool> 類型的參數。第3個「未指定」值的需求通常會在 Cmdlet 可以修改物件的布爾屬性時發生。在此情況下，「未指定」表示不要變更屬性的目前值。

支援參數陣列

使用者通常必須針對多個自變數執行相同的作業。對於這些使用者，Cmdlet 應該接受數位做為參數輸入，讓使用者可以將自變數傳遞至參數做為 Windows PowerShell 變數。例如， Get-Process Cmdlet 會針對識別要擷取之進程名稱的字串使用數位。

支援 PassThru 參數

根據預設，許多修改系統的 Cmdlet，例如 Stop-Process Cmdlet，會作為物件的「接收」，而不會傳回結果。這些 Cmdlet 應該實作 PassThru 參數，來強制 Cmdlet 傳回物件。 PassThru指定參數時，Cmdlet 會使用對 System.Management.Automation.Cmdlet.WriteObject 方法的呼叫傳回物件。例如，下列命令會停止 Calc （CalculatorApp.exe），並將產生的進程傳遞至管線。

Stop-Process -Name CalculatorApp -PassThru

在大部分情況下，Add、Set 和 New Cmdlet 應該支援 PassThru 參數。

支援參數集

Cmdlet 的目的是要完成單一用途。不過，描述作業或作業目標的方法通常不止一種。例如，進程可能依其名稱、標識碼或進程對象來識別。 Cmdlet 應該支援其目標的所有合適表示方式。一般而言，Cmdlet 會藉由指定一組同時運作的參數集（稱為參數集）來滿足這項需求。單一參數可以屬於任意數目的參數集。如需參數集的詳細資訊，請參閱 Cmdlet 參數集。

當您指定參數集時，將集合中只有一個參數設定為 ValueFromPipeline。如需如何宣告 Parameter 屬性的詳細資訊，請參閱 ParameterAttribute 宣告。

使用參數集時，預設參數集是由 Cmdlet 屬性所定義。默認參數集應該包含最有可能用於互動式 Windows PowerShell 作業階段的參數。如需如何宣告 Cmdlet 屬性的詳細資訊，請參閱 CmdletAttribute 宣告。

提供意見反應給使用者（SD04）

使用本節中的指導方針為使用者提供意見反應。此意見反應可讓使用者了解系統中發生什麼情況，並做出更好的系統管理決策。

Windows PowerShell 執行階段可讓用戶藉由設定偏好變數，指定如何處理每次方法 Write 呼叫的輸出。用戶可以設定數個喜好設定變數，包括決定系統是否應該顯示資訊的變數，以及決定系統是否應該在採取進一步動作之前查詢用戶的變數。

支援 WriteWarning、WriteVerbose 和 WriteDebug 方法

當 Cmdlet 即將執行可能有非預期結果的作業時，Cmdlet 應該呼叫 System.Management.Automation.Cmdlet.WriteWarning 方法。例如，如果 Cmdlet 即將覆寫只讀檔案，Cmdlet 應該呼叫這個方法。

當使用者需要 Cmdlet 的一些詳細數據時， Cmdlet 應該呼叫 System.Management.Automation.Cmdlet.WriteVerbose 方法。例如，如果 Cmdlet 作者覺得有些案例可能需要更多 Cmdlet 執行作業的相關信息，Cmdlet 應該呼叫這項資訊。

當開發人員或產品支援工程師必須瞭解 Cmdlet 作業損毀的內容時，Cmdlet 應該呼叫 System.Management.Automation.Cmdlet.WriteDebug 方法。 Cmdlet 不需要在呼叫 System.Management.Automation.Cmdlet.WriteDebug 方法的相同程式代碼中呼叫 System.Management.Automation.Cmdlet.WriteVerbose 方法，因為 Debug 參數會呈現這兩組資訊。

針對需要很長時間的操作支援 WriteProgress 功能

需要很長的時間才能完成且無法在背景中執行的 Cmdlet 作業，應該支援透過定期呼叫 System.Management.Automation.Cmdlet.WriteProgress 方法的進度報告。

使用主機介面

有時候，Cmdlet 必須直接與用戶通訊，而不是使用 System.Management.Automation.Cmdlet 類別支援的各種 Write 或 Should 方法。在此情況下，Cmdlet 應該衍生自 System.Management.Automation.PSCmdlet 類別，並使用 System.Management.Automation.PSCmdlet.Host* 屬性。此屬性支援不同層級的通訊類型，包括 PromptForChoice、Prompt 和 WriteLine/ReadLine 類型。在最特定的層級，它也提供讀取和寫入個別密鑰和處理緩衝區的方法。

除非 Cmdlet 是特別設計來產生圖形使用者介面（GUI），否則不應該使用 System.Management.Automation.PSCmdlet.Host* 屬性略過主機。設計來產生 GUI 的 Cmdlet 範例是 Out-GridView Cmdlet。

備註

Cmdlet 不應該使用 System.Console API。

建立 Cmdlet 說明檔（SD05）

針對每個 Cmdlet 元件，建立包含 Cmdlet 相關信息的 Help.xml 檔案。這項資訊包括 Cmdlet 的描述、Cmdlet 參數的描述、Cmdlet 的使用範例等等。

程式代碼指導方針

撰寫 Cmdlet 的程式代碼時，應遵循下列指導方針，以確保使用 Cmdlet 與其他 Cmdlet 之間的一致用戶體驗。當您找到適用於您情況的編碼指導方針時，請務必查看相似的設計指南。

編碼參數（SC01）

定義 Parameter 參數時，需要宣告 Cmdlet 類別的公用屬性，並使用 Parameter 屬性進行裝飾。參數不一定是 Cmdlet 衍生之 .NET Framework 類別的靜態成員。如需如何宣告 Parameter 屬性的詳細資訊，請參閱參數屬性宣告。

支援 Windows PowerShell 路徑

Windows PowerShell 路徑是將命名空間存取正規化的機制。當您將 Windows PowerShell 路徑指派給 Cmdlet 中的參數時，用戶可以定義自定義的「磁碟驅動器」，做為特定路徑的快捷方式。當使用者指定這類磁碟驅動器時，儲存的數據，例如登錄檔中的數據，可以以一致的方式來使用。

如果您的 Cmdlet 允許使用者指定檔案或數據源，它應該定義 System.String 類型的參數。如果支援多個磁碟，類型應該是陣列。參數的名稱應該是 Path，別名為 PSPath。此外， Path 參數應該支援通配符。如果不需要通配符支援，請定義 LiteralPath 參數。

如果 Cmdlet 讀取或寫入的數據必須是檔案，Cmdlet 應該接受 Windows PowerShell 路徑輸入，而 Cmdlet 應該使用 System.Management.Automation.SessionState.Path 屬性，將 Windows PowerShell 路徑轉譯成文件系統辨識的路徑。特定機制包括下列方法：

如果 Cmdlet 讀取或寫入的數據只是一組字串，而不是檔案，Cmdlet 應該使用提供者內容資訊（Content 成員）來讀取和寫入。此資訊是從 System.Management.Automation.Provider.CmdletProvider.InvokeProvider 屬性取得。這些機制可讓其他數據存放區參與數據的讀取和寫入。

支援通配符字元

如果可能，Cmdlet 應該支援通配符。 Cmdlet 中的許多位置都支援通配符（特別是當參數接受字串來識別一組對象的物件時）。例如，StopProc 教學課程中的範例 Stop-Proc Cmdlet 會定義參數Name來處理代表進程名稱的字串。此參數支援通配符，讓使用者可以輕鬆地指定要停止的進程。

當支援通配符字符時，Cmdlet 作業通常會產生一個陣列。有時候，支持陣列並不合理，因為使用者可能一次只會用到單一項目。例如，Set-Location cmdlet 不需要支援陣列，因為使用者只設定單一位置。在此情況下，cmdlet 仍然支援通配字元，但它強制解析至單一位置。

如需通配符模式的詳細資訊，請參閱支援 Cmdlet 參數中的通配符。

定義物件

本節包含定義 Cmdlet 物件以及擴充現有對象的指導方針。

定義標準成員

定義標準成員，以在自定義 Types.ps1xml 檔案中擴充物件類型（使用 Windows PowerShell Types.ps1xml 檔案作為範本）。標準成員是由名稱為 PSStandardMembers 的節點所定義。這些定義可讓其他 cmdlet 和 Windows PowerShell 運作環境以一致的方式使用您的物件。

定義作為參數使用的物件成員

如果您要設計供 Cmdlet 使用的物件，請確保其成員能直接對應至使用該物件的 Cmdlet 參數。此映射可讓物件輕鬆地傳送至管線，並從一個 Cmdlet 傳遞至另一個 Cmdlet。

Cmdlet 傳回的預先存在 .NET Framework 對象經常遺漏腳本開發人員或使用者所需的一些重要或便利成員。這些遺漏的成員對於顯示和建立正確的成員名稱特別重要，以便正確地將對象傳遞至管線。建立自定義 Types.ps1xml 檔案以記錄這些必要成員。當您建立此檔案時，建議您遵循下列命名慣例： <Your_Product_Name>。Types.ps1xml。

例如，您可以將腳本屬性新增 Mode 至 System.IO.FileInfo 類型，以便更清楚地顯示檔案的屬性。此外，您可以將別名屬性新增 Count 至 System.Array 類型，以允許使用該屬性名稱（而非 Length）的一致使用。

實作 IComparable 介面

在所有輸出對象上實作 System.IComparable 介面。這可讓輸出對象輕鬆地透過管線傳送至各種排序和分析 Cmdlet。

更新顯示資訊

如果對象的顯示未提供預期的結果，請為該對象建立自定義的 <YourProductName>.Format.ps1xml 檔案。

支援妥善定義的管線輸入（SC02）

實現管線中的中間部分

實作 Cmdlet，假設它會從管線中間呼叫（也就是說，其他 Cmdlet 會產生其輸入或取用其輸出）。例如，您可能會假設 Get-Process Cmdlet 因為會產生數據，所以只會當做管線中的第一個 Cmdlet 使用。不過，由於此 Cmdlet 是針對管線中間所設計，此 Cmdlet 可讓管線中的先前 Cmdlet 或數據指定要擷取的進程。

支援來自輸送管線的輸入

在 Cmdlet 設定的每個參數中，至少包含一個支援管線輸入的參數。支援管線輸入可讓使用者擷取數據或物件、將它們傳送至正確的參數集，並將結果直接傳遞至 Cmdlet。

如果 Parameter 屬性在其宣告中包含 ValueFromPipeline 關鍵字、ValueFromPipelineByPropertyName 關鍵字屬性或同時包含這兩個關鍵字，則參數將接受來自管線的輸入。如果參數集中沒有任何參數支援 ValueFromPipeline 或 ValueFromPipelineByPropertyName 關鍵詞，Cmdlet 就無法有意義地放在另一個 Cmdlet 之後，因為它會忽略任何管線輸入。

支援 ProcessRecord 方法

若要接受管線中上述 Cmdlet 的所有記錄，您的 Cmdlet 必須實作 System.Management.Automation.Cmdlet.ProcessRecord 方法。 Windows PowerShell 會針對傳送至 Cmdlet 的每個記錄呼叫此方法多次。

將單一記錄寫入管線（SC03）

當 Cmdlet 傳回物件時，Cmdlet 應該會在產生物件時立即寫入物件。 Cmdlet 不應該保留它們，以便將它們緩衝到合併的陣列中。那些接收物件作為輸入的 Cmdlet 接著將能夠處理或顯示，或者同時處理和顯示輸出物件，而不會延遲。一次產生一個輸出物件的 Cmdlet 應該呼叫 System.Management.Automation.Cmdlet.WriteObject 方法。批次產生輸出物件的 Cmdlet（例如，因為基礎 API 會傳回輸出物件的陣列），應該呼叫 System.Management.Automation.Cmdlet.WriteObject 方法，並將其第二個參數設定為 true。

建立 Cmdlet Case-Insensitive 和 Case-Preserving （SC04）

根據預設，Windows PowerShell 本身不區分大小寫。不過，因為它處理許多預先存在的系統，所以 Windows PowerShell 會保留方便作和相容性的情況。換句話說，如果字元是以大寫字母提供，Windows PowerShell 會以大寫字母保留它。若要讓系統正常運作，Cmdlet 必須遵循此慣例。可能的話，它應該以不區分大小寫的方式運作。不過，它應該保留稍後在命令或管線中出現的 Cmdlet 的原始大小寫。

另請參閱

必要的開發指導方針

諮詢開發指導方針

撰寫 Windows PowerShell Cmdlet

共用方式為