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

Aspectos que se deben conocer 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 de qué grupo de parámetros especifica el usuario.

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

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

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

Declaración de la clase de cmdlet

El primer paso en la creación de cmdlets siempre es asignar un nombre al cmdlet y declarar la clase .NET que implementa el cmdlet. Para este cmdlet, se usa el verbo del ciclo de vida "Stop" porque el cmdlet detiene los procesos del sistema. El nombre de 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 nombre 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 verbo 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 Force que administra lo que hace el cmdlet y un parámetro PassThru que determina si el cmdlet envía un objeto de salida a través de la 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 Creación de un cmdlet que modifica el sistema.

Declaración del parámetro name

Este parámetro de entrada permite al usuario especificar los nombres de los procesos que se van a detener. Tenga en cuenta que la palabra clave del atributo ParameterSetName del atributo System.Management.Automation.ParameterAttribute especifica el parámetro ProcessName establecido 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.

Declaración del parámetro Id

Este parámetro de entrada permite al usuario especificar los identificadores de los procesos que se van a detener. Tenga en cuenta que la palabra clave del atributo ParameterSetName del atributo System.Management.Automation.ParameterAttribute especifica el conjunto de parámetros 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

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 van a detener. Tenga en cuenta que la palabra clave del atributo ParameterSetName del atributo System.Management.Automation.ParameterAttribute especifica el parámetro InputObject establecido 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, asigne 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.

Invalidación de un método de procesamiento de entrada

Cada cmdlet debe invalidar un método de procesamiento de entrada, con más frecuencia 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 parámetro especificado por 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 llamados por la instrucción Select no se describen aquí, pero puede ver su implementación en el ejemplo de código completo de la sección siguiente.

Ejemplo de código

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

Definición de 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 ampliar tipos existentes, vea Extensión de tipos de objeto y formato.

Compilación del cmdlet

Después de implementar un cmdlet, debe registrarlo con Windows PowerShell a través de un complemento de Windows PowerShell. Para obtener más información sobre el registro de cmdlets, consulte Registro de cmdlets, proveedores y aplicaciones host.

Prueba del cmdlet

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

• Con Windows PowerShell iniciado, ejecute el cmdlet Stop-Proc con el parámetro ProcessId establecido para detener un proceso en función de su identificador. En este caso, el cmdlet usa el parámetro ProcessId 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 iniciado, ejecute el cmdlet Stop-Proc con el parámetro InputObject establecido para detener los procesos en el objeto Bloc de notas recuperado por el comando 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
  

Véase también

Crear un cmdlet que modifique el sistema

Creación de un cmdlet de Windows PowerShell

extensión de tipos de objeto y formato

Registro de cmdlets, proveedores y aplicaciones host

del SDK de Windows PowerShell