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

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

Parâmetros posicionais e nomeados

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

Para definir um parâmetro nomeado, omita a Position palavra-chave na declaração de atributos parâmetro, como indicado na seguinte declaração de parâmetro.

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

Para definir um parâmetro posicional, adicione a Position palavra-chave na declaração de atributos parâmetro e, em seguida, especifique uma posição. Na amostra seguinte, o UserName parâmetro é declarado como parâmetro posicional com a posição 0. Isto significa que o primeiro argumento da chamada será automaticamente ligado a este parâmetro.

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

Nota

Um bom design de cmdlet recomenda que os parâmetros mais utilizados sejam declarados como parâmetros posicionais para que o utilizador não tenha de introduzir 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ó são permitidos se o parâmetro aceitar uma coleção como uma matriz de cordas. Pode misturar parâmetros posicionais e nomeados no mesmo cmdlet. Neste caso, o sistema recupera primeiro os argumentos nomeados e, em seguida, tenta mapear os restantes argumentos não nomeados para os parâmetros posicionais.

Os seguintes comandos mostram as diferentes formas pelas quais pode especificar argumentos únicos e múltiplos para os parâmetros do Get-Command cmdlet. Note que nas duas últimas amostras, o nome não precisa de ser especificado porque o Name parâmetro é 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

Também pode definir os parâmetros cmdlet como parâmetros obrigatórios ou opcionais. (Um parâmetro obrigatório deve ser especificado antes do Windows PowerShell prazo de execução invoca o cmdlet.) Por predefinição, os parâmetros são definidos como opcionais.

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

[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 atributos parâmetro, como indicado na declaração de parâmetros seguinte.

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

Mudar parâmetros

Windows PowerShell fornece um tipo System.Management.Automation.SwitchParameter que lhe permite definir um parâmetro cujo valor é automaticamente definido false se o parâmetro não for especificado quando o cmdlet é chamado. Sempre que possível, utilize os parâmetros do interruptor no lugar dos parâmetros Booleanos.

Considere a seguinte amostra. Por predefinição, vários Windows PowerShell cmdlets não passam um objeto de saída pelo oleoduto. No entanto, estes cmdlets têm um PassThru parâmetro de comutação que sobrepõe o comportamento padrão. Se o PassThru parâmetro for especificado quando estes cmdlets são chamados, o cmdlet devolve um objeto de saída ao oleoduto.

Se necessitar do parâmetro para ter um valor predefinido true de quando o parâmetro não for especificado na chamada, considere inverter o sentido do parâmetro. Para a amostra, em vez de definir o atributo parâmetro para um valor Boolean de true , declarar a propriedade como o tipo System.Management.Automation.Automation.SwitchParameter e, em seguida, definir o valor predefinido do parâmetro para false .

Para definir um parâmetro de comutação, declare a propriedade como o tipo System.Management.Automation.SwitchParameter, como mostra a amostra seguinte.

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

Para fazer o cmdlet agir no parâmetro quando este for especificado, utilize a seguinte estrutura dentro de 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

Writing a Windows PowerShell Cmdlet (Escrever um Cmdlet do Windows PowerShell)