Types of Cmdlet Parameters (Tipos de Parâmetros de Cmdlets)

Este tópico descreve os diferentes tipos de parâmetros que você pode declarar em cmdlets. Os parâmetros do cmdlet podem ser posicionais, nomeados, obrigatórios, opcionais ou [switch] parâmetros.

Parâmetros posicionais e nomeados

Todos os parâmetros do cmdlet são parâmetros nomeados ou posicionais. Um parâmetro nomeado requer que você digite o nome do parâmetro e o argumento 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 do cmdlet são nomeados parâmetros.

Para definir um parâmetro nomeado, omita a palavra-chave Position na declaração Parameter attribute, 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 do 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 vinculado a esse parâmetro.

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

Observação

O bom design do 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.

Os parâmetros posicionais e nomeados aceitam argumentos únicos ou múltiplos argumentos separados por vírgulas. Vários argumentos sã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 ú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 Nome é 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 tempo de execução 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 Parameter atributo, 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;

[switch] Parâmetros

O PowerShell fornece um tipo de 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 é chamado. Sempre que possível, use [switch] parâmetros em vez de parâmetros booleanos.

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

O exemplo seguinte 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 aja sobre o 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 defeito, [switch] os parâmetros são excluídos dos parâmetros posicionais. Você pode substituir isso no atributo Parameter, mas isso pode confundir os usuários.

Parâmetros de design [switch] para que, ao usar o parâmetro, o comportamento padrão do comando seja alterado para um modo menos comum ou mais complicado. O comportamento mais simples de um comando deve ser o comportamento padrão que não exige o uso de [switch] parâmetros. Baseia o comportamento controlado pelo [switch] parâmetro no valor do parâmetro, não na sua presença.

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

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

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

Ver também

A escrever um Windows PowerShell Cmdlet