共用方式為

新增別名、萬用字元擴充與說明到 Cmdlet 參數

  • 發行項

本節描述如何將別名、萬用字元擴充和說明訊息新增至 Stop-Proc Cmdlet 的參數， (建立修改系統) 中所述的 Cmdlet 。

此 Stop-Proc Cmdlet 會嘗試停止使用 Get-Proc 建立您的第一個 Cmdlet) 中所述的 Cmdlet (擷取的進程。

定義 Cmdlet

Cmdlet 建立的第一個步驟一律是命名 Cmdlet，並宣告實作 Cmdlet 的 .NET 類別。 因為您正在撰寫 Cmdlet 來變更系統，所以應該據以命名。 因為這個 Cmdlet 會停止系統進程，所以它會使用 System.Management.Automation.Verbslifecycle類別所定義的動詞 Stop，並搭配名詞 Proc 來表示進程。 如需已核准 Cmdlet 動詞的詳細資訊，請參閱 Cmdlet 動詞名稱。

下列程式碼是這個 Stop-Proc Cmdlet 的類別定義。

[Cmdlet(VerbsLifecycle.Stop, "proc",
        SupportsShouldProcess = true)]
public class StopProcCommand : Cmdlet

定義系統修改的參數

您的 Cmdlet 必須定義支援系統修改和使用者意見反應的參數。 Cmdlet 應該定義 Name 參數或對等專案，讓 Cmdlet 能夠透過某種識別碼修改系統。 此外，Cmdlet 應該定義 Force 和 PassThru 參數。 如需這些參數的詳細資訊，請參閱 建立修改系統的 Cmdlet。

定義參數別名

參數別名可以是 Cmdlet 參數的替代名稱或定義完善的 1 個字母或 2 個字母的簡短名稱。 在這兩種情況下，使用別名的目標是簡化命令列的使用者輸入。 Windows PowerShell透過System.Management.Automation.Aliasattribute屬性支援參數別名，其使用宣告語法 [Alias()] 。

下列程式碼示範如何將別名新增至 Name 參數。

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]
[Alias("ProcessName")]
public string[] Name
{
  get { return processNames; }
  set { processNames = value; }
}
private string[] processNames;

除了使用System.Management.Automation.Aliasattribute屬性之外，Windows PowerShell執行時間也會執行部分名稱比對，即使未指定別名也一樣。 例如，如果您的 Cmdlet 有 FileName 參數，而且這是開頭的唯一參數 F ，則使用者可以輸入 Filename 、 Filenam 、 File 、 Fi 或 F ，而且仍會將專案辨識為 FileName 參數。

建立參數的說明

Windows PowerShell可讓您建立 Cmdlet 參數的說明。 針對用於系統修改和使用者意見反應的任何參數執行此動作。 若要讓每個參數支援 Help，您可以在 System.Management.Automation.Parameterattribute屬性宣告中設定 HelpMessage 屬性關鍵字。 此關鍵字會定義要向使用者顯示的文字，以取得參數的協助。 您也可以設定 HelpMessageBaseName 關鍵字，以識別要用於訊息的資源基底名稱。 如果您設定這個關鍵字，您也必須設定 HelpMessageResourceId 關鍵字來指定資源識別碼。

此 Cmdlet 中的下列程式碼 Stop-Proc 會定義 Name 參數的 HelpMessage 屬性關鍵字。

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]

覆寫輸入處理方法

您的 Cmdlet 必須覆寫輸入處理方法，通常是 System.Management.Automation.Cmdlet.ProcessRecord。 修改系統時，Cmdlet 應該呼叫 System.Management.Automation.Cmdlet.ShouldProcess 和 System.Management.Automation.Cmdlet.ShouldContinue 方法，讓使用者在進行變更之前提供意見反應。 如需這些方法的詳細資訊，請參閱 建立修改系統的 Cmdlet。

支援萬用字元擴充

若要允許選取多個物件，您的 Cmdlet 可以使用 System.Management.Automation.WildcardPattern 和 System.Management.Automation.WildcardOptions 類別來提供參數輸入的萬用字元擴充支援。 萬用字元模式的範例包括 lsa* 、 *.txt 和 [a-c]* 。 當模式包含應該常使用的字元時，請使用回引號字元 (`) 作為逸出字元。

檔案和路徑名稱的萬用字元擴充是常見案例的範例，其中 Cmdlet 可能會在需要選取多個物件時允許支援路徑輸入。 常見的案例是在檔案系統中，使用者想要查看位於目前資料夾中的所有檔案。

您應該只需要自訂的萬用字元模式比對實作很少。 在此情況下，您的 Cmdlet 應該支援完整的 POSIX 1003.2、3.13 規格，以進行萬用字元擴充或下列簡化的子集：

  • 問號 (?) 。 符合指定位置的任何字元。
  • 星號 (*) 。 比對從指定位置開始的零個或多個字元。
  • 開啟括弧 ([) 。 引進可包含字元或字元範圍的圖樣括號運算式。 如果需要範圍，則會使用連字號 (-) 來表示範圍。
  • 右括弧 (]) 。 結束模式括號運算式。
  • 回引號逸出字元 (`) 。 表示應該以常值方式採用下一個字元。 請注意，從命令列指定回引號字元時， (與以程式設計方式指定) 相反，必須指定回引號逸出字元兩次。

注意

如需萬用字元模式的詳細資訊，請參閱 在 Cmdlet 參數中支援萬用字元。

下列程式碼示範如何設定萬用字元選項，並定義用來解析此 Cmdlet 之 Name 參數的萬用字元模式。

WildcardOptions options = WildcardOptions.IgnoreCase |
                          WildcardOptions.Compiled;
WildcardPattern wildcard = new WildcardPattern(name,options);

下列程式碼示範如何測試進程名稱是否符合定義的萬用字元模式。 請注意，在此情況下，如果進程名稱不符合模式，Cmdlet 會繼續取得下一個進程名稱。

if (!wildcard.IsMatch(processName))
{
  continue;
}

程式碼範例

如需完整的 C# 範例程式碼，請參閱 StopProcessSample03 範例。

定義物件類型和格式設定

Windows PowerShell使用 .Net 物件在 Cmdlet 之間傳遞資訊。 因此，Cmdlet 可能需要定義自己的類型，或者 Cmdlet 可能需要擴充另一個 Cmdlet 所提供的現有類型。 如需定義新類型或擴充現有類型的詳細資訊，請參閱 擴充物件類型和格式設定。

建置 Cmdlet

實作 Cmdlet 之後，必須透過Windows PowerShell嵌入式管理單元向Windows PowerShell註冊。 如需註冊 Cmdlet 的詳細資訊，請參閱 如何註冊 Cmdlet、提供者和主應用程式。

測試 Cmdlet

當您的 Cmdlet 已註冊Windows PowerShell時，您可以在命令列上執行它來測試它。 讓我們測試範例Stop-Proc Cmdlet。 如需從命令列使用 Cmdlet 的詳細資訊，請參閱搭配使用 Windows PowerShell 的消費者入門。

  • 啟動Windows PowerShell，並使用 Stop-Proc 來停止使用 Name 參數的 ProcessName 別名的進程。

    PS> Stop-Proc -ProcessName notepad

    即會出現下列輸出。

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (3496)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y

  • 在命令列上建立下列專案。 因為 Name 參數是必要參數，所以系統會提示您輸入它。 輸入 !? 會顯示與 參數相關聯的解說文字。

    PS> Stop-Proc

    即會出現下列輸出。

    Cmdlet Stop-Proc at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
Name[0]: !?
The name of one or more processes to stop. Wildcards are permitted.
Name[0]: notepad

  • 現在，請讓下列專案停止符合萬用字元模式 *note* 的所有進程。 在停止符合模式的每個進程之前，系統會提示您。

    PS> Stop-Proc -Name *note*

    即會出現下列輸出。

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (1112)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y

    即會出現下列輸出。

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "ONENOTEM (3712)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N

    即會出現下列輸出。

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "ONENOTE (3592)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N

另請參閱