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, obrigatórios, opcionais ou parâmetros de opção.
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 Position
palavra-chave na declaração de atributo Parameter, 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 na declaração de atributo Parameter e Position
especifique uma posição. No exemplo a seguir, o UserName
parâmetro é declarado como um parâmetro posicional com a posição 0. Isso significa que o primeiro argumento da chamada será automaticamente vinculado 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 tenha que inserir o nome do parâmetro quando o cmdlet for executado.
Parâmetros posicionais e nomeados aceitam argumentos individuais ou vários argumentos separados por vírgulas. Vários argumentos serã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 individuais e múltiplos para os parâmetros do Get-Command
cmdlet. Observe que, nas duas últimas amostras, -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 Windows PowerShell runtime 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 na declaração de atributo Parameter e defina-a como , conforme Mandatory
mostrado na declaração de parâmetro a true
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 Mandatory
palavra-chave na declaração de atributo Parameter, 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 de opção
Windows PowerShell fornece um tipo System.Management.Automation.SwitchParameter que permite definir um parâmetro cujo valor é definido automaticamente como se o parâmetro não for especificado quando o false
cmdlet for chamado. Sempre que possível, use parâmetros de opção no lugar de parâmetros boolianas.
Considere o exemplo a seguir. Por padrão, vários Windows PowerShell cmdlets não passam um objeto de saída pelo pipeline. No entanto, esses cmdlets têm um PassThru
parâmetro switch que substitui o comportamento padrão. Se o PassThru
parâmetro for especificado quando esses cmdlets são chamados, o cmdlet retornará um objeto de saída para o pipeline.
Se você precisar que o parâmetro tenha um valor padrão de quando o parâmetro não for especificado na chamada, considere reverter o true
sentido do parâmetro. Para exemplo, em vez de definir o atributo de parâmetro como um valor booliana de , declare a propriedade como o tipo true
System.Management.Automation.SwitchParameter e de definido o valor padrão do parâmetro como false
.
Para definir um parâmetro switch, declare a propriedade como o tipo System.Management.Automation.SwitchParameter, conforme mostrado no exemplo a seguir.
[Parameter(Position = 1)]
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
Consulte Também
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de