Adición de parámetros que procesan la entrada de la línea de comandos

Artículo
2025-03-25

Un origen de entrada para un cmdlet es la línea de comandos. En este tema se describe cómo agregar un parámetro al cmdlet Get-Proc (que se describe en Creating Your First Cmdlet) para que el cmdlet pueda procesar la entrada desde el equipo local en función de objetos explícitos pasados al cmdlet. El cmdlet Get-Proc que se describe aquí recupera los procesos en función de sus nombres y, a continuación, muestra información sobre los procesos en un símbolo del sistema.

Definición de la clase de cmdlet

El primer paso en la creación de cmdlets es la nomenclatura de cmdlets y la declaración de la clase de .NET Framework que implementa el cmdlet. Este cmdlet recupera la información del proceso, por lo que el nombre del verbo elegido aquí es "Get". (Casi cualquier tipo de cmdlet que sea capaz de recuperar información puede procesar la entrada de la línea de comandos). Para obtener más información sobre los verbos de cmdlet aprobados, consulte Nombres de verbos de cmdlet.

Esta es la declaración de clase del cmdlet Get-Proc. Los detalles sobre esta definición se proporcionan en Creación del primer cmdlet.

[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

Declaración de parámetros

Un parámetro de cmdlet permite al usuario proporcionar la entrada al cmdlet. En el ejemplo siguiente, Get-Proc y Get-Member son los nombres de los cmdlets canalizaciones y MemberType es un parámetro para el cmdlet Get-Member. El parámetro tiene el argumento "property".

ps> Get-Proc ; Get-Member -MemberType (propiedad)

Para declarar parámetros para un cmdlet, primero debe definir las propiedades que representan los parámetros. En el cmdlet Get-Proc, el único parámetro es Name, que en este caso representa el nombre del objeto de proceso de .NET Framework que se va a recuperar. Por lo tanto, la clase de cmdlet define una propiedad de tipo string para aceptar una matriz de nombres.

Esta es la declaración de parámetros del parámetro Name del cmdlet Get-Proc.

/// <summary>
/// Specify the cmdlet Name parameter.
/// </summary>
  [Parameter(Position = 0)]
  [ValidateNotNullOrEmpty]
  public string[] Name
  {
    get { return processNames; }
    set { processNames = value; }
  }
  private string[] processNames;

  #endregion Parameters

<Parameter(Position:=0), ValidateNotNullOrEmpty()> _
Public Property Name() As String()
    Get
        Return processNames
    End Get

    Set(ByVal value As String())
        processNames = value
    End Set

End Property

Para informar al entorno de ejecución de Windows PowerShell de que esta propiedad es el parámetro Name, se agrega un atributo System.Management.Automation.ParameterAttribute a la definición de propiedad. La sintaxis básica para declarar este atributo es [Parameter()].

Nota:

Un parámetro debe marcarse explícitamente como público. El entorno de ejecución de Windows PowerShell no encuentra parámetros que no están marcados como valores predeterminados públicos como internos.

Este cmdlet usa una matriz de cadenas para el parámetro Name. Si es posible, el cmdlet también debe definir un parámetro como una matriz, ya que esto permite que el cmdlet acepte más de un elemento.

Cosas que recordar acerca de las definiciones de parámetros

Los nombres de parámetros y tipos de datos predefinidos de Windows PowerShell se deben reutilizar tanto como sea posible para asegurarse de que el cmdlet sea compatible con los cmdlets de Windows PowerShell. Por ejemplo, si todos los cmdlets usan el nombre de parámetro de Id predefinido para identificar un recurso, el usuario comprenderá fácilmente el significado del parámetro, independientemente del cmdlet que use. Básicamente, los nombres de parámetro siguen las mismas reglas que las usadas para los nombres de variable en Common Language Runtime (CLR). Para obtener más información sobre la nomenclatura de parámetros, consulte nombres de parámetros de cmdlet.
Windows PowerShell reserva algunos nombres de parámetro para proporcionar una experiencia de usuario coherente. No use estos nombres de parámetro: WhatIf, Confirm, Verbose, Debug, Warn, ErrorAction, ErrorVariable, OutVariabley OutBuffer. Además, se reservan los siguientes alias para estos nombres de parámetro: vb, db, ea, ev, ovy ob.
Name es un nombre de parámetro sencillo y común, recomendado para su uso en los cmdlets. Es mejor elegir un nombre de parámetro como este que un nombre complejo que sea único para un cmdlet específico y difícil de recordar.
Los parámetros no distinguen mayúsculas de minúsculas en Windows PowerShell, aunque el shell conserva mayúsculas y minúsculas de forma predeterminada. La distinción entre mayúsculas y minúsculas de los argumentos depende del funcionamiento del cmdlet. Los argumentos se pasan a un parámetro tal como se especifica en la línea de comandos.
Para obtener ejemplos de otras declaraciones de parámetros, vea Cmdlet Parameters.

Declarar parámetros como posicionales o con nombre

Un cmdlet debe establecer cada parámetro como un parámetro posicional o con nombre. Ambos tipos de parámetros aceptan argumentos únicos, varios argumentos separados por comas y valores booleanos. Un parámetro booleano, también denominado conmutador , controla solo la configuración booleana. El modificador se usa para determinar la presencia del parámetro . El valor predeterminado recomendado es false.

El cmdlet Get-Proc de ejemplo define el parámetro Name como un parámetro posicional con la posición 0. Esto significa que el primer argumento que el usuario escribe en la línea de comandos se inserta automáticamente para este parámetro. Si desea definir un parámetro con nombre, para el que el usuario debe especificar el nombre del parámetro desde la línea de comandos, deje la palabra clave Position fuera de la declaración de atributo.

Nota:

A menos que se deba asignar un nombre a los parámetros, se recomienda colocar los parámetros más usados para que los usuarios no tengan que escribir el nombre del parámetro.

Declarar parámetros como obligatorios o opcionales

Un cmdlet debe establecer cada parámetro como un parámetro opcional o obligatorio. En el cmdlet Get-Proc de ejemplo, el parámetro Name se define como opcional porque la palabra clave Mandatory no está establecida en la declaración de atributo.

Compatibilidad con la validación de parámetros

El cmdlet Get-Proc de ejemplo agrega un atributo de validación de entrada, System.Management.Automation.ValidateNotNullOrEmptyAttribute, al parámetro Name para habilitar la validación de que la entrada no está null ni vacía. Este atributo es uno de varios atributos de validación proporcionados por Windows PowerShell. Para obtener ejemplos de otros atributos de validación, consulte Validación de la entrada de parámetros.

[Parameter(Position = 0)]
[ValidateNotNullOrEmpty]
public string[] Name

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

Si el cmdlet va a controlar la entrada de la línea de comandos, debe invalidar los métodos de procesamiento de entrada adecuados. Los métodos básicos de procesamiento de entrada se presentan en Creating Your First Cmdlet.

El cmdlet Get-Proc invalida el método System.Management.Automation.Cmdlet.ProcessRecord para controlar la entrada del parámetro Name proporcionada por el usuario o un script. Este método obtiene los procesos de cada nombre de proceso solicitado o todos para los procesos si no se proporciona ningún nombre. Tenga en cuenta que en System.Management.Automation.Cmdlet.ProcessRecord, la llamada a System.Management.Automation.Cmdlet.WriteObject es el mecanismo de salida para enviar objetos de salida a la canalización. El segundo parámetro de esta llamada, enumerateCollection, se establece en true para informar al tiempo de ejecución de Windows PowerShell para enumerar la matriz de salida de objetos de proceso y escribir un proceso cada vez en la línea de comandos.

protected override void ProcessRecord()
{
  // If no process names are passed to the cmdlet, get all processes.
  if (processNames == null)
  {
    // Write the processes to the pipeline making them available
    // to the next cmdlet. The second argument of this call tells
    // PowerShell to enumerate the array, and send one process at a
    // time to the pipeline.
    WriteObject(Process.GetProcesses(), true);
  }
  else
  {
    // If process names are passed to the cmdlet, get and write
    // the associated processes.
    foreach (string name in processNames)
    {
      WriteObject(Process.GetProcessesByName(name), true);
    }
  }
}

Protected Overrides Sub ProcessRecord()

    '/ If no process names are passed to the cmdlet, get all processes.
    If processNames Is Nothing Then
        Dim processes As Process()
        processes = Process.GetProcesses()
    End If

    '/ If process names are specified, write the processes to the
    '/ pipeline to display them or make them available to the next cmdlet.

    For Each name As String In processNames
        '/ The second parameter of this call tells PowerShell to enumerate the
        '/ array, and send one process at a time to the pipeline.
        WriteObject(Process.GetProcessesByName(name), True)
    Next

End Sub 'ProcessRecord

Ejemplo de código

Para obtener el código de ejemplo de C# completo, consulte ejemplo GetProcessSample02.

Definición de tipos de objeto y formato

Windows PowerShell pasa información entre cmdlets mediante objetos de .NET Framework. Por lo tanto, un cmdlet podría necesitar definir su propio tipo o un cmdlet podría necesitar 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 mediante 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 registra con Windows PowerShell, puede probarlo ejecutándolo en la línea de comandos. Estas son dos maneras de probar el código para el cmdlet de ejemplo. Para obtener más información sobre el uso de cmdlets desde la línea de comandos, consulte Introducción a Windows PowerShell.

En el símbolo del sistema de Windows PowerShell, use el siguiente comando para enumerar el proceso de Internet Explorer, que se denomina "IEXPLORE".

Get-Proc -Name iexplore

Aparece la salida siguiente.

Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)   Id   ProcessName
-------  ------  -----   -----  -----   ------ --   -----------
    354      11  10036   18992    85   0.67   3284   iexplore

Para enumerar los procesos de Internet Explorer, Outlook y bloc de notas denominados "IEXPLORE", "OUTLOOK" y "NOTEPAD", use el siguiente comando. Si hay varios procesos, se muestran todos ellos.

Get-Proc -Name iexplore, outlook, notepad

Aparece la salida siguiente.

Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)   Id   ProcessName
-------  ------  -----   -----  -----  ------   --   -----------
    732      21  24696    5000    138   2.25  2288   iexplore
    715      19  20556   14116    136   1.78  3860   iexplore
   3917      62  74096   58112    468 191.56  1848   OUTLOOK
     39       2   1024    3280     30   0.09  1444   notepad
     39       2   1024     356     30   0.08  3396   notepad