Adición de conjuntos de parámetros a un cmdlet

Artículo
09/27/2021

Aspectos que debe saber sobre los conjuntos de parámetros

Windows PowerShell define un conjunto de parámetros como un grupo de parámetros que funcionan juntos. Al agrupar los parámetros de un cmdlet, puede crear un único cmdlet que pueda cambiar su funcionalidad en función del grupo de parámetros que especifique el usuario.

Un ejemplo de un cmdlet que usa dos conjuntos de parámetros para definir funcionalidades diferentes es el cmdlet proporcionado Get-EventLog por Windows PowerShell. Este cmdlet devuelve información diferente cuando el usuario especifica el List parámetro LogName o . Si se LogName especifica el parámetro , el cmdlet devuelve información sobre los eventos de un registro de eventos determinado. Si se especifica el parámetro , el cmdlet devuelve información sobre los propios archivos de List registro (no la información del evento que contienen). En este caso, los parámetros List y identifican dos conjuntos de parámetros LogName independientes.

Dos aspectos importantes que hay que recordar sobre los conjuntos de parámetros es que el entorno de ejecución de Windows PowerShell solo usa un conjunto de parámetros para una entrada determinada y que cada conjunto de parámetros debe tener al menos un parámetro que sea único para ese conjunto de parámetros.

Para ilustrar ese último punto, este cmdlet Stop-Proc usa tres conjuntos de parámetros: ProcessName ProcessId , y InputObject . Cada uno de estos conjuntos de parámetros tiene un parámetro que no está en los otros conjuntos de parámetros. Los conjuntos de parámetros podrían compartir otros parámetros, pero el cmdlet usa los parámetros únicos , y para identificar qué conjunto de parámetros debe usar el entorno Windows PowerShell ProcessName ProcessId InputObject runtime.

Declarar la clase cmdlet

El primer paso en la creación de cmdlets es asignar siempre un nombre al cmdlet y declarar la clase de .NET que implementa el cmdlet. Para este cmdlet, se usa el verbo de ciclo de vida "Stop" porque el cmdlet detiene los procesos del sistema. El nombre "Proc" se usa porque el cmdlet funciona en procesos. En la declaración siguiente, tenga en cuenta que el verbo del cmdlet y el nombre del sustantivo se reflejan en el nombre de la clase de cmdlet.

Nota

Para obtener más información sobre los nombres de verbos de cmdlet aprobados, vea Nombres de verbos de cmdlet.

El código siguiente es la definición de clase para este 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

Declarar los parámetros del cmdlet

Este cmdlet define tres parámetros necesarios como entrada para el cmdlet (estos parámetros también definen los conjuntos de parámetros), así como un parámetro que administra lo que hace el cmdlet y un parámetro que determina si el cmdlet envía un objeto de salida a través de la Force PassThru canalización. De forma predeterminada, este cmdlet no pasa un objeto a través de la canalización. Para obtener más información sobre estos dos últimos parámetros, vea Crear un cmdlet que modifica el sistema.

Declarar el parámetro Name

Este parámetro de entrada permite al usuario especificar los nombres de los procesos que se deben detener. Tenga en cuenta que la palabra clave attribute del atributo ParameterSetName System.Management.Automation.Parameterattribute especifica el ProcessName conjunto de parámetros para este parámetro.

[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

Tenga en cuenta también que el alias "ProcessName" se proporciona a este parámetro.

Declarar el parámetro Id

Este parámetro de entrada permite al usuario especificar los identificadores de los procesos que se deben detener. Tenga en cuenta que la palabra clave de atributo del atributo ParameterSetName System.Management.Automation.Parameterattribute especifica el conjunto ProcessId de parámetros.

[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

Tenga en cuenta también que el alias "ProcessId" se proporciona a este parámetro.

Declarar el parámetro InputObject

Este parámetro de entrada permite al usuario especificar un objeto de entrada que contiene información sobre los procesos que se deben detener. Tenga en cuenta que la palabra clave attribute del atributo ParameterSetName System.Management.Automation.Parameterattribute especifica el InputObject conjunto de parámetros para este parámetro.

[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

Tenga en cuenta también que este parámetro no tiene ningún alias.

Declarar parámetros en varios conjuntos de parámetros

Aunque debe haber un parámetro único para cada conjunto de parámetros, los parámetros pueden pertenecer a más de un conjunto de parámetros. En estos casos, dé al parámetro compartido una declaración de atributo System.Management.Automation.Parameterattribute para cada conjunto al que pertenece el parámetro. Si un parámetro está en todos los conjuntos de parámetros, solo tiene que declarar el atributo de parámetro una vez y no es necesario especificar el nombre del conjunto de parámetros.

Invalidar un método de procesamiento de entrada

Cada cmdlet debe invalidar un método de procesamiento de entrada, que suele ser el método System.Management.Automation.Cmdlet.ProcessRecord. En este cmdlet, el método System.Management.Automation.Cmdlet.ProcessRecord se invalida para que el cmdlet pueda procesar cualquier número de procesos. Contiene una instrucción Select que llama a un método diferente en función del conjunto de parámetros que haya especificado el usuario.

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

Los métodos auxiliares a los que llama la instrucción Select no se describen aquí, pero puede ver su implementación en el ejemplo de código completo en la sección siguiente.

Ejemplo de código

Para obtener el código de ejemplo de C# completo, vea StopProcessSample04 Sample.

Definir tipos de objeto y formato

Windows PowerShell pasa información entre cmdlets mediante objetos .NET. Por lo tanto, es posible que un cmdlet tenga que definir su propio tipo o que el cmdlet tenga que extender un tipo existente proporcionado por otro cmdlet. Para obtener más información sobre cómo definir nuevos tipos o extender los tipos existentes, vea Extender tipos de objeto y aplicar formatoa .

Compilar el cmdlet

Después de implementar un cmdlet, debe registrarlo con Windows PowerShell a través de un Windows PowerShell complemento. Para obtener más información sobre el registro de cmdlets, vea How to Register Cmdlets, Providers, and Host Applications.

Prueba del cmdlet

Cuando el cmdlet se haya registrado con Windows PowerShell, ejec cándalo en la línea de comandos. Estas son algunas pruebas que muestran cómo se pueden usar los parámetros y para ProcessId probar sus conjuntos de parámetros para detener un InputObject proceso.

Una Windows PowerShell, ejecute el cmdlet Stop-Proc con el parámetro establecido para detener ProcessId un proceso basado en su identificador. En este caso, el cmdlet usa el ProcessId parámetro establecido para detener el proceso.
```
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
```

Con Windows PowerShell, ejecute el cmdlet Stop-Proc con el parámetro establecido para detener los procesos en el objeto Bloc de notas recuperado InputObject por el Get-Process comando .

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