向 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 参数创建帮助。对用于系统修改和用户反馈的任何参数执行此操作。对于支持帮助的每个参数，您可以在 System.Management.Automation.Parameterattribute 属性声明中设置 HelpMessage 属性关键字。该关键字定义向用户显示的文本，以帮助用户使用参数。您还可以设置 HelpMessageBaseName 关键字来标识用于消息的资源的基本名称。如果设置此关键字，则还必须设置 HelpMessageResourceId 关键字来指定资源标识符。

此 Stop-Proc cmdlet 中的以下代码定义 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 后，必须通过 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
  

参见

• 创建修改系统的 Cmdlet
• 如何创建 Windows PowerShell Cmdlet
• 扩展对象类型和格式
• 如何注册 Cmdlet、提供程序和主机应用程序
• 支持 Cmdlet 参数中的通配符
• Windows PowerShell SDK