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 detrue
. Vários parâmetros podem definirValueFromPipelineByPropertyName
a palavra-chave com um valor detrue
.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;