Tipos de parámetros de cmdlet

Este tema describe los diferentes tipos de parámetros que puede declarar en cmdlets. Los parámetros del cmdlet pueden ser parámetros posicionales, con nombre, obligatorios, opcionales o de cambio.

Parámetros posicionales y con nombre

Todos los parámetros del cmdlet son parámetros con nombre o posicionales. Un parámetro con nombre requiere que escriba el nombre del parámetro y el argumento al llamar al cmdlet. Un parámetro posicional sólo requiere que escriba los argumentos en orden relativo. Luego, el sistema asigna el primer argumento sin nombre al primer parámetro posicional. El sistema asigna el segundo argumento sin nombre al segundo parámetro sin nombre, y así sucesivamente. De forma predeterminada, todos los parámetros del cmdlet se denominan parámetros.

Para definir un parámetro con nombre, omita la palabra clave Position en la declaración del atributo Parameter, como se muestra en la siguiente declaración de parámetro.

[Parameter(ValueFromPipeline=true)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

Para definir un parámetro posicional, agregue la palabra clave Position en la declaración del atributo Parameter y luego especifique una posición. En el siguiente ejemplo, el parámetro UserName se declara como un parámetro posicional con posición 0. Esto significa que el primer argumento de la llamada se vinculará automáticamente a este parámetro.

[Parameter(Position = 0)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

Los parámetros posicionales y con nombre aceptan argumentos únicos o múltiples separados por comas. Se permiten múltiples argumentos sólo si el parámetro acepta una colección como una matriz de cadenas. Puede combinar parámetros posicionales y con nombre en el mismo cmdlet. En este caso, el sistema recupera primero los argumentos con nombre y luego intenta asignar los argumentos sin nombre restantes a los parámetros posicionales.

Los siguientes comandos muestran las diferentes formas en que puede especificar argumentos únicos y múltiples para los parámetros del cmdlet Get-Command. Tenga en cuenta que en los dos últimos ejemplos, no es necesario especificar -name porque el parámetro Name está definido como un parámetro posicional.

Get-Command -Name get-service
Get-Command -Name get-service,set-service
Get-Command get-service
Get-Command get-service,set-service

Parámetros obligatorios y opcionales

También puede definir parámetros de cmdlet como parámetros obligatorios u opcionales. (Se debe especificar un parámetro obligatorio antes de que el tiempo de ejecución de Windows PowerShell invoque el cmdlet). De forma predeterminada, los parámetros se definen como opcionales.

Para definir un parámetro obligatorio, agregue la palabra clave Mandatory en la declaración del atributo Parameter y configúrela en true, como se muestra en la siguiente declaración de parámetros.

[Parameter(Position = 0, Mandatory = true)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

Para definir un parámetro opcional, omita la palabra clave Mandatory en la declaración del atributo Parameter, como se muestra en la siguiente declaración de parámetro.

[Parameter(Position = 0)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

Cambiar parámetros

Windows PowerShell proporciona un tipo System.Management.Automation.SwitchParameter que le permite definir un parámetro cuyo valor se establece automáticamente en false si el parámetro no se especifica cuando se llama al cmdlet. Siempre que sea posible, utilice parámetros de cambio en lugar de parámetros booleanos.

Considere el siguiente ejemplo. De forma predeterminada, varios cmdlets de Windows PowerShell no pasan un objeto de salida por la canalización. Sin embargo, estos cmdlets tienen un parámetro de cambio PassThru que anula el comportamiento predeterminado. Si se especifica el parámetro PassThru cuando se llama a estos cmdlets, el cmdlet devuelve un objeto de salida a la canalización.

Si necesita que el parámetro tenga un valor predeterminado de true cuando el parámetro no se especifica en la llamada, considere invertir el sentido del parámetro. Por ejemplo, en lugar de establecer el atributo del parámetro en un valor booleano de true, declare la propiedad como del tipo System.Management.Automation.SwitchParameter y luego establezca el valor predeterminado del parámetro en falso.

Para definir un parámetro de cambio, declare la propiedad como del tipo System.Management.Automation.SwitchParameter, como se muestra en el siguiente ejemplo.

[Parameter(Position = 1)]
public SwitchParameter GoodBye
{
  get { return goodbye; }
  set { goodbye = value; }
}
private bool goodbye;

Para que el cmdlet actúe sobre el parámetro cuando se especifica, use la siguiente estructura dentro de uno de los métodos de procesamiento de entrada.

protected override void ProcessRecord()
{
  WriteObject("Switch parameter test: " + userName + ".");
  if(goodbye)
  {
    WriteObject(" Goodbye!");
  }
} // End ProcessRecord

Ver también

Escribir un cmdlet de Windows PowerShell