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)
Comentários
https://aka.ms/ContentUserFeedback.
Brevemente: ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja:Submeter e ver comentários