Tipos de parámetros del cmdletTypes of Cmdlet Parameters

En este tema se describen los diferentes tipos de parámetros que se pueden declarar en los cmdlets de.This topic describes the different types of parameters that you can declare in cmdlets. Los parámetros de cmdlet pueden ser posicionales, con nombre, obligatorios, opcionales o modificadores.Cmdlet parameters can be positional, named, required, optional, or switch parameters.

Parámetros posicionales y con nombrePositional and Named Parameters

Todos los parámetros de cmdlet son parámetros con nombre o posicionales.All cmdlet parameters are either named or positional parameters. Un parámetro con nombre requiere que escriba el nombre y el argumento del parámetro al llamar al cmdlet.A named parameter requires that you type the parameter name and argument when calling the cmdlet. Un parámetro posicional solo requiere que se escriban los argumentos en orden relativo.A positional parameter requires only that you type the arguments in relative order. A continuación, el sistema asigna el primer argumento sin nombre al primer parámetro posicional.The system then maps the first unnamed argument to the first positional parameter. El sistema asigna el segundo argumento sin nombre al segundo parámetro sin nombre, y así sucesivamente.The system maps the second unnamed argument to the second unnamed parameter, and so on. De forma predeterminada, todos los parámetros de cmdlet son parámetros con nombre.By default, all cmdlet parameters are named parameters.

Para definir un parámetro con nombre, omita la Position palabra clave en la declaración de atributo de parámetro , tal y como se muestra en la siguiente declaración de parámetro.To define a named parameter, omit the Position keyword in the Parameter attribute declaration, as shown in the following parameter declaration.

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

Para definir un parámetro posicional, agregue la Position palabra clave en la declaración de atributo de parámetro y, a continuación, especifique una posición.To define a positional parameter, add the Position keyword in the Parameter attribute declaration, and then specify a position. En el ejemplo siguiente, el UserName parámetro se declara como un parámetro posicional con la posición 0.In the following sample, the UserName parameter is declared as a positional parameter with position 0. Esto significa que el primer argumento de la llamada se enlazará automáticamente a este parámetro.This means that the first argument of the call will be automatically bound to this parameter.

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

Nota

Un buen diseño de cmdlet recomienda que los parámetros más usados se declaren como parámetros posicionales para que el usuario no tenga que escribir el nombre del parámetro cuando se ejecute el cmdlet.Good cmdlet design recommends that the most-used parameters be declared as positional parameters so that the user does not have to enter the parameter name when the cmdlet is run.

Los parámetros con nombre y posicionales aceptan argumentos únicos o varios argumentos separados por comas.Positional and named parameters accept single arguments or multiple arguments separated by commas. Solo se permiten varios argumentos si el parámetro acepta una colección como una matriz de cadenas.Multiple arguments are allowed only if the parameter accepts a collection such as an array of strings. Puede mezclar parámetros posicionales y con nombre en el mismo cmdlet.You may mix positional and named parameters in the same cmdlet. En este caso, el sistema recupera primero los argumentos con nombre y, a continuación, intenta asignar los argumentos sin nombre restantes a los parámetros posicionales.In this case, the system retrieves the named arguments first, and then attempts to map the remaining unnamed arguments to the positional parameters.

Los siguientes comandos muestran las distintas formas en las que puede especificar argumentos únicos y varios para los parámetros del Get-Command cmdlet.The following commands show the different ways in which you can specify single and multiple arguments for the parameters of the Get-Command cmdlet. Observe que en los dos últimos ejemplos, no es necesario especificar -Name porque el Name parámetro se define como un parámetro posicional.Notice that in the last two samples, -name does not need to be specified because the Name parameter is defined as a positional parameter.

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 opcionalesMandatory and Optional Parameters

También puede definir parámetros de cmdlet como parámetros obligatorios u opcionales.You can also define cmdlet parameters as mandatory or optional parameters. (Debe especificarse 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.(A mandatory parameter must be specified before the Windows PowerShell runtime invokes the cmdlet.) By default, parameters are defined as optional.

Para definir un parámetro obligatorio, agregue la Mandatory palabra clave en la declaración de atributo de parámetro y establézcalo en true , como se muestra en la siguiente declaración de parámetro.To define a mandatory parameter, add the Mandatory keyword in the Parameter attribute declaration, and set it to true, as shown in the following parameter declaration.

[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 Mandatory palabra clave en la declaración de atributo de parámetro , tal y como se muestra en la siguiente declaración de parámetro.To define an optional parameter, omit the Mandatory keyword in the Parameter attribute declaration, as shown in the following parameter declaration.

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

Parámetros de modificadorSwitch Parameters

Windows PowerShell proporciona un tipo System. Management. Automation. parámetrodemodificador que permite definir un parámetro cuyo valor se establece automáticamente en false si no se especifica el parámetro cuando se llama al cmdlet.Windows PowerShell provides a System.Management.Automation.SwitchParameter type that allows you to define a parameter whose value is automatically set to false if the parameter is not specified when the cmdlet is called. Siempre que sea posible, use parámetros de modificador en lugar de parámetros booleanos.Whenever possible, use switch parameters in place of Boolean parameters.

Considere el ejemplo siguiente.Consider the following sample. De forma predeterminada, varios cmdlets de Windows PowerShell no pasan un objeto de salida a la canalización.By default, several Windows PowerShell cmdlets do not pass an output object down the pipeline. Sin embargo, estos cmdlets tienen un PassThru parámetro de modificador que invalida el comportamiento predeterminado.However, these cmdlets have a PassThru switch parameter that overrides the default behavior. Si PassThru se especifica el parámetro cuando se llama a estos cmdlets, el cmdlet devuelve un objeto de salida a la canalización.If the PassThru parameter is specified when these cmdlets are called, the cmdlet returns an output object to the pipeline.

Si necesita que el parámetro tenga un valor predeterminado de true cuando no se especifica el parámetro en la llamada, considere la posibilidad de invertir el sentido del parámetro.If you need the parameter to have a default value of true when the parameter is not specified in the call, consider reversing the sense of the parameter. En el ejemplo, en lugar de establecer el atributo de parámetro en un valor booleano de true , declare la propiedad como el tipo System. Management. Automation. parámetrodemodificador y, a continuación, establezca el valor predeterminado del parámetro en false .For sample, instead of setting the parameter attribute to a Boolean value of true, declare the property as the System.Management.Automation.SwitchParameter type, and then set the default value of the parameter to false.

Para definir un parámetro de modificador, declare la propiedad como el tipo System. Management. Automation. parámetrodemodificador , como se muestra en el ejemplo siguiente.To define a switch parameter, declare the property as the System.Management.Automation.SwitchParameter type, as shown in the following sample.

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

Para hacer que el cmdlet actúe sobre el parámetro cuando se especifica, utilice la siguiente estructura dentro de uno de los métodos de procesamiento de entrada.To make the cmdlet act on the parameter when it is specified, use the following structure within one of the input processing methods.

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

Consulte tambiénSee Also

Escribir un cmdlet de Windows PowerShellWriting a Windows PowerShell Cmdlet