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, necessários, opcionais ou [switch] parâmetros.

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 palavra-chave Position na declaração de atributo parâmetro, 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 Position na declaração de atributo Parameter e especifique uma posição. No exemplo a seguir, o parâmetro UserName é declarado como um parâmetro posicional com a posição 0. Isso significa que o primeiro argumento da chamada é automaticamente associado 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 precise inserir o nome do parâmetro quando o cmdlet for executado.

Parâmetros posicionais e nomeados aceitam argumentos únicos ou vários argumentos separados por vírgulas. Vários argumentos só serão permitidos 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 tenta mapear os argumentos não nomeados restantes para os parâmetros posicionais.

Os comandos a seguir mostram as diferentes maneiras pelas quais você pode especificar argumentos únicos e múltiplos para os parâmetros do cmdlet Get-Command. Observe que, nos dois últimos exemplos, -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 o runtime do PowerShell 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 Mandatory na declaração de atributo Parameter e defina-a como true, conforme mostrado na declaração de parâmetro a 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 palavra-chave Mandatory na declaração de atributo parâmetro, 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 [switch]

O PowerShell fornece um tipo System.Management.Automation.SwitchParameter que permite definir um parâmetro cujo valor padrão false, a menos que o parâmetro seja especificado quando o cmdlet for chamado. Sempre que possível, use [switch] parâmetros em vez de parâmetros boolianos.

Considere o exemplo a seguir. Muitos cmdlets do PowerShell retornam a saída. No entanto, esses cmdlets têm um PassThru[switch] parâmetro que substitui o comportamento padrão. Quando você usa o parâmetro PassThru, o cmdlet retorna objetos de saída para o pipeline.

O exemplo a seguir mostra como definir um [switch] parâmetro:

[Parameter()]
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

Por padrão, [switch] os parâmetros são excluídos dos parâmetros posicionais. Você pode substituir isso no atributo parâmetro, mas pode confundir os usuários.

Parâmetros [switch] de design para que o uso do parâmetro altere o comportamento padrão do comando para um modo menos comum ou mais complicado. O comportamento mais simples de um comando deve ser o comportamento padrão que não requer o uso de [switch] parâmetros. Baseie o comportamento controlado pelo [switch] parâmetro no valor do parâmetro, não em sua presença.

Há várias maneiras de testar a presença de um [switch] parâmetro:

• MyInvocation.BoundParameters contém o nome do [switch] parâmetro como uma chave
• PSCmdlet.ParameterSetName quando o [switch] parâmetro define um conjunto de parâmetros exclusivo

Por exemplo, é possível fornecer um valor explícito para a opção usando -MySwitch:$false ou splatting. Se você testar apenas a presença do parâmetro, o comando se comportará como se o valor do comutador fosse $true em vez de $false.

Consulte Também

Escritando um cmdlet do PowerShell Windows