将参数集添加到 Cmdlet

关于参数集需要了解的事情

Windows PowerShell 将参数集定义为一组一起运行的参数。通过对 cmdlet 的参数进行分组，您可以创建一个 cmdlet，该 cmdlet 可以根据用户指定的参数组来更改其功能。

使用两个参数集定义不同功能的 cmdlet 示例是 Windows PowerShell 提供的 Get-EventLog cmdlet。当用户指定 List 或 LogName 参数时，此 cmdlet 返回不同的信息。如果指定了 LogName 参数，cmdlet 将返回有关给定事件日志中的事件的信息。如果指定了 List 参数，cmdlet 将返回有关日志文件本身的信息（而不是它们包含的事件信息）。在本例中，List 和 LogName 参数标识两个单独的参数集。

关于参数集，需要记住的两件重要事情是，Windows PowerShell 运行时仅对特定输入使用一个参数集，并且每个参数集必须至少有一个对该参数集唯一的参数。

为了说明最后一点，此 Stop-Proc cmdlet 使用三个参数集：ProcessName、ProcessId 和 InputObject。这些参数集中的每一组都有一个不在其他参数集中的参数。参数集可以共享其他参数，但 cmdlet 使用唯一参数 ProcessName、ProcessId 和 InputObject 来标识哪个参数集是应使用 Windows PowerShell 运行时。

声明 Cmdlet 类

创建 cmdlet 的第一步始终是命名 cmdlet 并声明实现该 cmdlet 的 .NET 类。对于此 cmdlet，使用生命周期动词“Stop”，因为该 cmdlet 会停止系统进程。使用名词名称“Proc”是因为 cmdlet 在进程上运行。在下面的声明中，请注意 cmdlet 动词和名词名称反映在 cmdlet 类的名称中。

笔记

有关批准的 cmdlet 动词名称的详细信息，请参阅 Cmdlet 动词名称。

以下代码是此 Stop-Proc cmdlet 的类定义。

[Cmdlet(VerbsLifecycle.Stop, "Proc",
        DefaultParameterSetName = "ProcessId",
        SupportsShouldProcess = true)]
public class StopProcCommand : PSCmdlet

<Cmdlet(VerbsLifecycle.Stop, "Proc", DefaultParameterSetName:="ProcessId", _
SupportsShouldProcess:=True)> _
Public Class StopProcCommand
    Inherits PSCmdlet

声明 Cmdlet 的参数

此 cmdlet 定义了作为 cmdlet 输入所需的三个参数（这些参数还定义了参数集），以及一个用于管理 cmdlet 功能的 Force 参数和一个 PassThru确定 cmdlet 是否通过管道发送输出对象的参数。默认情况下，此 cmdlet 不通过管道传递对象。有关最后两个参数的详细信息，请参阅创建修改系统的 Cmdlet。

声明名称参数

此输入参数允许用户指定要停止的进程的名称。请注意，System.Management.Automation.Parameterattribute 属性的 ParameterSetName 属性关键字指定为此参数设置的 ProcessName 参数。

[Parameter(
   Position = 0,
   ParameterSetName = "ProcessName",
   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;

<Parameter(Position:=0, ParameterSetName:="ProcessName", _
Mandatory:=True, _
ValueFromPipeline:=True, ValueFromPipelineByPropertyName:=True, _
HelpMessage:="The name of one or more processes to stop. " & _
    "Wildcards are permitted."), [Alias]("ProcessName")> _
Public Property Name() As String()
    Get
        Return processNames
    End Get
    Set(ByVal value As String())
        processNames = value
    End Set
End Property

Private processNames() As String

另请注意，为此参数指定了别名“ProcessName”。

声明 Id 参数

该输入参数允许用户指定要停止的进程的标识符。请注意，System.Management.Automation.Parameterattribute 属性的 ParameterSetName 属性关键字指定 ProcessId 参数集。

[Parameter(
           ParameterSetName = "ProcessId",
           Mandatory = true,
           ValueFromPipelineByPropertyName = true,
           ValueFromPipeline = true
)]
[Alias("ProcessId")]
public int[] Id
{
  get { return processIds; }
  set { processIds = value; }
}
private int[] processIds;

<Parameter(ParameterSetName:="ProcessId", _
Mandatory:=True, _
ValueFromPipelineByPropertyName:=True, _
ValueFromPipeline:=True), [Alias]("ProcessId")> _
Public Property Id() As Integer()
    Get
        Return processIds
    End Get
    Set(ByVal value As Integer())
        processIds = value
    End Set
End Property
Private processIds() As Integer

另请注意，为此参数指定了别名“ProcessId”。

声明 InputObject 参数

此输入参数允许用户指定包含有关要停止的进程的信息的输入对象。请注意，System.Management.Automation.Parameterattribute 属性的 ParameterSetName 属性关键字指定此参数的 InputObject 参数集。

[Parameter(
           ParameterSetName = "InputObject",
           Mandatory = true,
           ValueFromPipeline = true)]
public Process[] InputObject
{
  get { return inputObject; }
  set { inputObject = value; }
}
private Process[] inputObject;

<Parameter(ParameterSetName:="InputObject", _
Mandatory:=True, ValueFromPipeline:=True)> _
Public Property InputObject() As Process()
    Get
        Return myInputObject
    End Get
    Set(ByVal value As Process())
        myInputObject = value
    End Set
End Property
Private myInputObject() As Process

另请注意，此参数没有别名。

声明多个参数集中的参数

尽管每个参数集必须有一个唯一的参数，但参数可以属于多个参数集。在这些情况下，请为共享参数所属的每个集提供一个 System.Management.Automation.Parameterattribute 属性声明。如果某个参数在所有参数集中，则只需声明一次该参数属性，无需指定参数集名称。

重写输入处理方法

每个 cmdlet 都必须重写输入处理方法，最常见的是 System.Management.Automation.Cmdlet.ProcessRecord 方法。在此 cmdlet 中，重写了 System.Management.Automation.Cmdlet.ProcessRecord 方法，以便 cmdlet 可以处理任意数量的进程。它包含一个 Select 语句，该语句根据用户指定的参数集调用不同的方法。

protected override void ProcessRecord()
{
  switch (ParameterSetName)
  {
    case "ProcessName":
         ProcessByName();
         break;

    case "ProcessId":
         ProcessById();
         break;

    case "InputObject":
         foreach (Process process in inputObject)
         {
           SafeStopProcess(process);
         }
         break;

    default:
         throw new ArgumentException("Bad ParameterSet Name");
  } // switch (ParameterSetName...
} // ProcessRecord

Protected Overrides Sub ProcessRecord()
    Select Case ParameterSetName
        Case "ProcessName"
            ProcessByName()

        Case "ProcessId"
            ProcessById()

        Case "InputObject"
            Dim process As Process
            For Each process In myInputObject
                SafeStopProcess(process)
            Next process

        Case Else
            Throw New ArgumentException("Bad ParameterSet Name")
    End Select

End Sub 'ProcessRecord ' ProcessRecord

这里不描述 Select 语句调用的 Helper 方法，但您可以在下一节的完整代码示例中看到它们的实现。

代码示例

有关完整的 C# 示例代码，请参阅 StopProcessSample04 示例。

定义对象类型和格式

Windows PowerShell 使用 .NET 对象在 cmdlet 之间传递信息。因此，cmdlet 可能需要定义自己的类型，或者 cmdlet 可能需要扩展另一个 cmdlet 提供的现有类型。有关定义新类型或扩展现有类型的更多信息，请参阅扩展对象类型和格式。

构建 Cmdlet

实施 cmdlet 后，您必须通过 Windows PowerShell 管理单元将其注册到 Windows PowerShell。有关注册 cmdlet 的详细信息，请参阅如何注册 Cmdlet、提供程序和主机应用程序。

测试 Cmdlet

当您的 cmdlet 已注册到 Windows PowerShell 后，请通过在命令行上运行它来测试它。以下一些测试显示了如何使用 ProcessId 和 InputObject 参数来测试其参数集以停止进程。

• 启动 Windows PowerShell 后，运行 Stop-Proc cmdlet，并设置 ProcessId 参数以根据进程的标识符停止进程。在本例中，cmdlet 使用 ProcessId 参数集来停止进程。

  PS> stop-proc -Id 444
  Confirm
  Are you sure you want to perform this action?
  Performing operation "stop-proc" on Target "notepad (444)".
  [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
  

• 启动 Windows PowerShell 后，运行 Stop-Proc cmdlet，并设置 InputObject 参数，以停止 Get-Process 命令检索的记事本对象上的进程。

  PS> get-process notepad | stop-proc
  Confirm
  Are you sure you want to perform this action?
  Performing operation "stop-proc" on Target "notepad (444)".
  [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N
  

参见

创建修改系统的 Cmdlet

如何创建 Windows PowerShell Cmdlet

扩展对象类型和格式

如何注册 Cmdlet、提供程序和主机应用程序

Windows PowerShell SDK