Tipos de parâmetros de cmdlet

Este tópico descreve os diferentes tipos de parâmetros que você pode declarar em cmdlets. Os parâmetros de cmdlet podem ser posicionais, nomeados, obrigatórios, opcionais ou parâmetros de opção.

Parâmetros posicionais e nomeados

Todos os parâmetros de cmdlet são parâmetros nomeados ou posicionais. Um parâmetro nomeado requer que você digite o nome e o argumento do parâmetro ao chamar o cmdlet . Um parâmetro posicional requer apenas que você digite os argumentos em ordem relativa. Em seguida, o sistema mapeia o primeiro argumento sem nome para o primeiro parâmetro posicional. O sistema mapeia o segundo argumento sem nome para o segundo parâmetro sem nome e assim por diante. Por padrão, todos os parâmetros de cmdlet são parâmetros nomeados.

Para definir um parâmetro nomeado, omita a Position palavra-chave na declaração de atributo Parameter, conforme mostrado na declaração de parâmetro a seguir.

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

Para definir um parâmetro posicional, adicione a palavra-chave na declaração de atributo Parameter e Position especifique uma posição. No exemplo a seguir, o UserName parâmetro é declarado como um parâmetro posicional com a posição 0. Isso significa que o primeiro argumento da chamada será automaticamente vinculado a esse parâmetro.

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

Observação

Um bom design de cmdlet recomenda que os parâmetros mais usados sejam declarados como parâmetros posicionais para que o usuário não tenha que inserir o nome do parâmetro quando o cmdlet for executado.

Parâmetros posicionais e nomeados aceitam argumentos individuais ou vários argumentos separados por vírgulas. Vários argumentos serão permitidos somente se o parâmetro aceitar uma coleção, como uma matriz de cadeias de caracteres. Você pode misturar parâmetros posicionais e nomeados no mesmo cmdlet. Nesse caso, o sistema recupera os argumentos nomeados primeiro e, em seguida, tenta mapear os argumentos sem nome restantes para os parâmetros posicionais.

Os comandos a seguir mostram as diferentes maneiras pelas quais você pode especificar argumentos individuais e múltiplos para os parâmetros do Get-Command cmdlet. Observe que, nas duas últimas amostras, -name não precisa ser especificado porque o parâmetro é Name definido como um 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 obrigatórios e opcionais

Você também pode definir parâmetros de cmdlet como parâmetros obrigatórios ou opcionais. (Um parâmetro obrigatório deve ser especificado antes que Windows PowerShell runtime invoque o cmdlet .) Por padrão, os parâmetros são definidos como opcionais.

Para definir um parâmetro obrigatório, adicione a palavra-chave na declaração de atributo Parameter e defina-a como , conforme Mandatory mostrado na declaração de parâmetro a true seguir.

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

Para definir um parâmetro opcional, omita a Mandatory palavra-chave na declaração de atributo Parameter, conforme mostrado na declaração de parâmetro a seguir.

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

Parâmetros de opção

Windows PowerShell fornece um tipo System.Management.Automation.SwitchParameter que permite definir um parâmetro cujo valor é definido automaticamente como se o parâmetro não for especificado quando o false cmdlet for chamado. Sempre que possível, use parâmetros de opção no lugar de parâmetros boolianas.

Considere o exemplo a seguir. Por padrão, vários Windows PowerShell cmdlets não passam um objeto de saída pelo pipeline. No entanto, esses cmdlets têm um PassThru parâmetro switch que substitui o comportamento padrão. Se o PassThru parâmetro for especificado quando esses cmdlets são chamados, o cmdlet retornará um objeto de saída para o pipeline.

Se você precisar que o parâmetro tenha um valor padrão de quando o parâmetro não for especificado na chamada, considere reverter o true sentido do parâmetro. Para exemplo, em vez de definir o atributo de parâmetro como um valor booliana de , declare a propriedade como o tipo true System.Management.Automation.SwitchParameter e de definido o valor padrão do parâmetro como false .

Para definir um parâmetro switch, declare a propriedade como o tipo System.Management.Automation.SwitchParameter, conforme mostrado no exemplo a seguir.

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

Para fazer com que o cmdlet atue no parâmetro quando ele for especificado, use a estrutura a seguir em um dos métodos de processamento de entrada.

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

Consulte Também

Escrevendo um Cmdlet do Windows PowerShell