向 Cmdlet 添加参数集

项目
09/27/2021

有关参数集的要了解内容

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

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

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

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

声明 Cmdlet 类

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

备注

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

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

[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 执行哪些操作的参数，以及一个用于确定 cmdlet 是否通过管道发送输出 Force PassThru 对象的参数。默认情况下，此 cmdlet 不会通过管道传递对象。有关最后两个参数的信息，请参阅创建修改系统的Cmdlet。

声明 Name 参数

此输入参数允许用户指定要停止的进程的名称。请注意 ParameterSetName ，System.Management.Automation.Parameterattribute 特性的 attribute 关键字指定此 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 参数

此输入参数允许用户指定要停止的进程的标识符。请注意 ParameterSetName ，System.Management.Automation.Parameterattribute 特性的 attribute 关键字指定 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 参数

此输入参数允许用户指定一个输入对象，该对象包含有关要停止的进程的信息。请注意 ParameterSetName ，System.Management.Automation.Parameterattribute 特性的 attribute 关键字指定此 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 语句调用的帮助程序方法，但可以在下一部分的完整代码示例中查看这些方法的实现。

代码示例

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

定义对象类型和格式设置

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

生成 Cmdlet

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

测试 Cmdlet

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

启动Windows PowerShell后，使用参数Stop-Proc运行 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