Conjuntos de parâmetros de cmdlet

O PowerShell usa conjuntos de parâmetros para permitir que você escreva um único cmdlet que pode fazer ações diferentes para cenários diferentes. Os conjuntos de parâmetros permitem expor parâmetros diferentes ao usuário. E, para retornar informações diferentes com base nos parâmetros especificados pelo usuário.

Exemplos de conjuntos de parâmetros

Por exemplo, o cmdlet do PowerShell retorna informações diferentes dependendo se o usuário especifica o parâmetro Get-EventLog List ou LogName. Se o parâmetro List for especificado, o cmdlet retornará informações sobre os próprios arquivos de log, mas não as informações de evento que eles contêm. Se o parâmetro LogName for especificado, o cmdlet retornará informações sobre os eventos em um log de eventos específico. Os parâmetros List e LogName identificam dois conjuntos de parâmetros separados.

Parâmetro exclusivo

Cada conjunto de parâmetros deve ter um parâmetro exclusivo que o runtime do PowerShell usa para expor o conjunto de parâmetros apropriado. Se possível, o parâmetro exclusivo deve ser um parâmetro obrigatório. Quando um parâmetro é obrigatório, o usuário deve especificar o parâmetro e o runtime do PowerShell usa esse parâmetro para identificar o conjunto de parâmetros. O parâmetro exclusivo não poderá ser obrigatório se o cmdlet for projetado para ser executado sem especificar nenhum parâmetro.

Vários conjuntos de parâmetros

Na ilustração a seguir, a coluna esquerda mostra três conjuntos de parâmetros válidos. O parâmetro A é exclusivo para o primeiro conjunto de parâmetros, o parâmetro B é exclusivo para o segundo conjunto de parâmetros e o parâmetro C é exclusivo para o terceiro conjunto de parâmetros. Na coluna direita, os conjuntos de parâmetros não têm um parâmetro exclusivo.

Requisitos do conjunto de parâmetros

Os requisitos a seguir se aplicam a todos os conjuntos de parâmetros.

• Cada conjunto de parâmetros deve ter pelo menos um parâmetro exclusivo. Se possível, faça desse parâmetro um parâmetro obrigatório.

• Um conjunto de parâmetros que contém vários parâmetros posicionais deve definir posições exclusivas para cada parâmetro. Nenhum parâmetro posicional pode especificar a mesma posição.

• Somente um parâmetro em um conjunto pode declarar a ValueFromPipeline palavra-chave com um valor de true . Vários parâmetros podem definir ValueFromPipelineByPropertyName a palavra-chave com um valor de true .

• Se nenhum conjunto de parâmetros for especificado para um parâmetro, o parâmetro pertence a todos os conjuntos de parâmetros.

Observação

Para um cmdlet ou função, há um limite de 32 conjuntos de parâmetros.

Conjuntos de parâmetros padrão

Quando vários conjuntos de parâmetros são definidos, você pode usar a palavra-chave do DefaultParameterSetName atributo Cmdlet para especificar o conjunto de parâmetros padrão. O PowerShell usará o conjunto de parâmetros padrão se ele não puder determinar o conjunto de parâmetros a ser usado com base nas informações fornecidas pelo comando. Para obter mais informações sobre o atributo cmdlet, consulte Declaração de atributo de cmdlet.

Declarando conjuntos de parâmetros

Para criar um conjunto de parâmetros, você deve especificar a palavra-chave ao declarar o atributo ParameterSetName Parameter para cada parâmetro no conjunto de parâmetros. Para parâmetros que pertencem a vários conjuntos de parâmetros, adicione um atributo Parameter para cada conjunto de parâmetros. Esse atributo permite que você defina o parâmetro de forma diferente para cada conjunto de parâmetros. Por exemplo, você pode definir um parâmetro como obrigatório em um conjunto e opcional em outro. No entanto, cada conjunto de parâmetros deve conter um parâmetro exclusivo. Para obter mais informações, consulte Declaração de atributo de parâmetro.

No exemplo a seguir, o parâmetro UserName é o parâmetro exclusivo do conjunto de parâmetros e o parâmetro ComputerName é o parâmetro exclusivo do Test01 conjunto de Test02 parâmetros. O parâmetro SharedParam pertence a ambos os conjuntos e é obrigatório para o conjunto Test01 de parâmetros, mas opcional para o conjunto de Test02 parâmetros.

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

[Parameter(Position = 0, Mandatory = true, ParameterSetName = "Test02")]
public string ComputerName
{
  get { return computerName; }
  set { computerName = value; }
}
private string computerName;

[Parameter(Mandatory= true, ParameterSetName = "Test01")]
[Parameter(ParameterSetName = "Test02")]
public string SharedParam
{
    get { return sharedParam; }
    set { sharedParam = value; }
}
private string sharedParam;