Todos os comandos do PowerShell podem ter um ou mais parâmetros, às vezes chamados de argumentos. Se você não estiver usando parâmetros do PowerShell em suas funções do PowerShell, você não está escrevendo um bom código do PowerShell!
Neste artigo, você vai aprender praticamente todos os aspectos de criar e usar parâmetros ou argumentos do PowerShell!
Este é um exemplo do meu livro PowerShell para SysAdmins. Se você quer aprender PowerShell ou aprender alguns truques da área, confira!
Por que Você Precisa de um Parâmetro?
Ao começar a criar funções, você terá a opção de incluir parâmetros ou não e como esses parâmetros funcionam.
Vamos dizer que você tem uma função que instala o Microsoft Office. Talvez ela chame o instalador do Office silenciosamente dentro da função. O que a função faz não importa para nossos propósitos. A função básica se parece com isso com o nome da função e o bloco de script.
Neste exemplo, você simplesmente executou Install-Office sem parâmetros e ele faz o que deve fazer.
Não importava se a função Install-Office tinha parâmetros ou não. Aparentemente, não tinha nenhum parâmetro obrigatório; caso contrário, o PowerShell não teria nos deixado executá-lo sem usar um parâmetro.
Quando Usar um Parâmetro do PowerShell
O Office possui muitas versões diferentes. Talvez seja necessário instalar o Office 2013 e 2016. Atualmente, você não tem como especificar isso. Você poderia alterar o código da função toda vez que quisesse mudar o comportamento.
Por exemplo, você poderia criar duas funções separadas para instalar versões diferentes.
Fazer isso funciona, mas não é escalável. Isso o força a criar uma função separada para cada versão do Office que é lançada. Você terá que duplicar muito código quando não precisa.
Em vez disso, você precisa de uma maneira de passar valores diferentes durante a execução para mudar o comportamento da função. Como fazer isso?
Sim! Parâmetros ou o que algumas pessoas chamam de argumentos.
Como gostaríamos de instalar diferentes versões do Office sem alterar o código toda vez, você precisa adicionar pelo menos um parâmetro a esta função.
Antes de pensar rapidamente em um parâmetro do PowerShell para usar, é essencial primeiro se fazer uma pergunta: “Qual é a menor alteração ou alterações que você espera que sejam necessárias nesta função?”.
Lembre-se de que você precisa executar esta função novamente sem alterar nenhum código dentro dela. Neste exemplo, o parâmetro provavelmente está claro para você; você precisa adicionar um parâmetro Version. Mas, quando você tem uma função com dezenas de linhas de código, a resposta não será tão óbvia. Contanto que você responda a essa pergunta da maneira mais precisa possível, sempre ajudará.
Então, você sabe que precisa de um parâmetro Version. E agora? Agora você pode adicionar um, mas como em qualquer grande linguagem de programação, existem várias maneiras de fazer isso.
Neste tutorial, vou mostrar a maneira “melhor” de criar parâmetros com base em minha experiência de quase uma década com o PowerShell. No entanto, saiba que esta não é a única maneira de criar um parâmetro.
Existe algo chamado parâmetros posicionais. Esses parâmetros permitem que você passe valores para os parâmetros sem especificar o nome do parâmetro. Parâmetros posicionais funcionam, mas não são considerados “melhores práticas”. Por quê? Porque são mais difíceis de ler, especialmente quando você tem muitos parâmetros definidos em uma função.
Criando um parâmetro simples no PowerShell
Para criar um parâmetro em uma função, são necessários dois componentes principais: um bloco de parâmetros e o próprio parâmetro. Um bloco param é definido pela palavra-chave param, seguida por um conjunto de parênteses.
Neste ponto, a funcionalidade real da função não mudou nada. Apenas reunimos algumas estruturas básicas, preparando-nos para o primeiro parâmetro.
Depois de ter o bloco param no lugar, agora você criará o parâmetro. O método que estou sugerindo para criar um parâmetro inclui o bloco Parameter, seguido do tipo de parâmetro, que é seguido pelo nome da variável do parâmetro abaixo.
Agora criamos um parâmetro de função no PowerShell, mas o que exatamente aconteceu aqui?
O bloco Parameter é uma peça opcional, mas recomendada, de cada parâmetro. Assim como o bloco param, é uma “estrutura básica da função” que prepara o parâmetro para adicionar funcionalidades adicionais. A segunda linha é onde você define o tipo de parâmetro que é.
Neste caso, escolhemos converter o parâmetro Versão para uma string. Definir explicitamente um tipo significa que qualquer valor passado para este parâmetro sempre tentará ser “convertido” para uma string se ainda não o for.
O tipo não é obrigatório, mas é altamente recomendado. Definir explicitamente o tipo do parâmetro reduzirá significativamente muitas situações indesejadas no futuro. Confie em mim.
Agora que você definiu o parâmetro, pode executar o comando Install-Office com o parâmetro Versão passando uma string de versão, como 2013. O valor passado para o parâmetro Versão é às vezes chamado de argumentos ou valores do parâmetro.
O que está acontecendo aqui afinal? Você disse que queria instalar a versão 2013, mas ainda está dizendo que instalou a versão 2016. Quando você adiciona um parâmetro, lembre-se de alterar o código da função para uma variável. Quando o parâmetro é passado para a função, essa variável será expandida para ser qualquer valor que foi passado.
Altere o texto estático de 2016 e substitua pelo variável do parâmetro Versão, convertendo as aspas simples para aspas duplas para que a variável seja expandida.
Agora você pode ver que qualquer valor que você passe para o parâmetro Versão será então passado para a função como a variável $Versão.
O Atributo de Parâmetro Obrigatório
Lembre-se de que mencionei que a linha [Parameter()] era apenas “encanamento da função” e precisava preparar a função para um trabalho posterior? Adicionar atributos ao parâmetro é o trabalho adicional ao qual eu estava me referindo anteriormente.
A parameter doesn’t have to be a placeholder for a variable. PowerShell has a concept called parameter attributes and parameter validation. Parameter attributes change the behavior of the parameter in a lot of different ways.
Por exemplo, um dos atributos de parâmetro mais comuns que você definirá é a palavra-chave Mandatory. Por padrão, você poderia chamar a função Install-Office sem usar o parâmetro Version e ela seria executada normalmente. O parâmetro Version seria opcional. Concedido, ele não expandiria a variável $Version dentro da função porque não havia valor, mas ainda seria executado.
Muitas vezes, ao criar um parâmetro, você desejará que o usuário sempre use esse parâmetro. Você dependerá do valor do parâmetro dentro do código da função em algum lugar e, se o parâmetro não for passado, a função falhará. Nestes casos, você deseja forçar o usuário a passar o valor deste parâmetro para sua função. Você quer que esse parâmetro se torne obrigatório.
Forçar os usuários a usar um parâmetro é simples assim que você tem o esboço básico construído como temos aqui. Você precisa incluir a palavra-chave Mandatory dentro dos parênteses do parâmetro. Uma vez que você tenha isso em vigor, a execução da função sem o parâmetro interromperá a execução até que um valor tenha sido inserido.
A função aguardará até você especificar um valor para o parâmetro Version. Uma vez feito isso e pressionar Enter, o PowerShell executará a função e seguirá em frente. Se você fornecer um valor para o parâmetro, o PowerShell não solicitará o parâmetro toda vez.
Validação de Atributos de Parâmetro no PowerShell
Tornar um parâmetro obrigatório é um dos atributos de parâmetro mais comuns que você pode adicionar, mas também é possível usar atributos de validação de parâmetro. Na programação, é sempre essencial restringir a entrada do usuário o máximo possível. Limitar as informações que os usuários (ou mesmo você!) podem passar para suas funções ou scripts eliminará código desnecessário dentro de sua função que precisa lidar com todo tipo de situação.
Aprendendo por Exemplo
Por exemplo, na função Install-Office, eu demonstrei passar o valor 2013 para ela porque eu sabia que funcionaria. Eu escrevi o código! Estou assumindo (nunca faça isso no código!) que é óbvio que qualquer pessoa que saiba alguma coisa especificaria a versão como sendo 2013 ou 2016. Bem, o que é óbvio para você pode não ser tão óbvio para outras pessoas.
Se você quiser ser técnico sobre as versões, provavelmente seria mais preciso especificar a versão 2013 como 15.0 e 2016 como 16.0 se a Microsoft ainda estivesse usando o esquema de numeração que eles usaram no passado. Mas e se, como você está assumindo que eles vão especificar uma versão de 2013 ou 2016, você tem o código dentro da função que procura por pastas com essas versões ou algo assim?
Abaixo está um exemplo de onde você pode estar usando a string $Version em um caminho de arquivo. Se alguém passar um valor que não completa um nome de pasta como Office2013 ou Office2016, isso falhará ou fará algo pior, como remover pastas inesperadas ou alterar coisas que você não considerou.
Para limitar o usuário ao que você espera que ele insira, você pode adicionar alguma validação de parâmetro do PowerShell.
Usando o Atributo de Validação de Parâmetro ValidateSet
Há vários tipos de validação de parâmetro que você pode usar. Para uma lista completa, execute Get-Help about_Functions_Advanced_Parameters. Neste exemplo, o atributo ValidateSet provavelmente seria o melhor.
O atributo de validação ValidateSet permite que você especifique uma lista de valores que são permitidos como valor do parâmetro. Como estamos considerando apenas a string 2013 ou 2016, gostaria de garantir que o usuário só possa especificar esses valores. Caso contrário, a função falhará imediatamente, notificando-os do motivo.
Você pode adicionar atributos de validação de parâmetro logo abaixo da palavra-chave Parameter original. Neste exemplo, dentro dos parênteses do atributo do parâmetro, você tem uma matriz de itens; 2013 e 2016. Um atributo de validação de parâmetro informa ao PowerShell que os únicos valores válidos para Version são 2013 ou 2016. Se você tentar passar algo diferente do que está no conjunto, receberá um erro informando que você possui apenas um número específico de opções disponíveis.
O atributo ValidateSet é um atributo de validação comum para usar. Para uma análise completa de todas as formas como os valores dos parâmetros podem ser restritos, confira o tópico de ajuda Functions_Advanced_Parameters executando Get-Help about_Functions_Advanced_Parameters.
Conjuntos de Parâmetros
Vamos supor que você queira apenas certos parâmetros do PowerShell usados com outros parâmetros. Talvez você tenha adicionado um parâmetro Path à função Install-Office. Este caminho instalará qualquer versão que o instalador seja. Neste caso, você não deseja que o usuário utilize o parâmetro Version.
Você precisa de conjuntos de parâmetros.
Os parâmetros podem ser agrupados em conjuntos que só podem ser usados com outros parâmetros no mesmo conjunto. Usando a função abaixo, agora você pode usar tanto o parâmetro Version quanto o parâmetro Path para obter o caminho para o instalador.
Isto apresenta um problema, no entanto, porque o usuário pode usar ambos os parâmetros. Além disso, como ambos os parâmetros são obrigatórios, eles serão obrigados a usar ambos quando isso não é o que você quer. Para corrigir isso, podemos colocar cada parâmetro em um conjunto de parâmetros como abaixo.
Ao definir um nome de conjunto de parâmetros em cada parâmetro, isso permite que você controle grupos de parâmetros juntos.
O Conjunto de Parâmetros Padrão
E se o usuário tentar executar Install-Office sem parâmetros? Isso não é considerado, e você verá uma mensagem de erro amigável.
Para corrigir isso, você precisará definir um conjunto de parâmetros padrão dentro da área CmdletBinding(). Isso informa à função para escolher um conjunto de parâmetros a ser usado se nenhum parâmetro for usado explicitamente, alterando [CmdletBinding()] para [CmdletBinding(DefaultParameterSetName = 'ByVersion')].
Agora, sempre que você executar Install-Office, ele solicitará o parâmetro Version, pois estará usando esse conjunto de parâmetros.
Entrada de Pipeline
Nos exemplos até agora, você vem criando funções com um parâmetro do PowerShell que só pode ser passado usando a sintaxe típica -ParameterName Value. Mas, como você já aprendeu, o PowerShell possui um pipeline intuitivo que permite passar objetos de forma transparente de um comando para outro sem usar a sintaxe “típica”.
Quando você usa o pipeline, “encadeia” comandos com o símbolo de pipe |, permitindo que um usuário envie a saída de um comando como Get-Service para Start-Service como um atalho para passar o parâmetro Name para Start-Service.
O “Antigo” Método Usando um Loop
Na função personalizada com a qual você está trabalhando, você está instalando o Office e tem um parâmetro Version. Digamos que você tenha uma lista de nomes de computadores em um arquivo CSV em uma linha com a versão do Office que precisa ser instalada neles na segunda linha. O arquivo CSV se parece com isso:
Você gostaria de instalar a versão do Office que está ao lado de cada computador nesse computador.
Primeiro, você precisará adicionar um parâmetro ComputerName à função para passar um nome de computador diferente para cada iteração da função. Abaixo, criei um pseudocódigo que representa algum código que pode estar na função fictícia e adicionei uma instância Write-Host para ver como as variáveis se expandem dentro da função.
Depois de adicionar o parâmetro ComputerName à função; você pode fazer isso lendo o arquivo CSV e passando os valores para o nome do computador e a versão para a função Install-Office.
Criando Entrada de Pipeline para Parâmetros
Este método de ler as linhas do CSV e usar um loop para passar as propriedades de cada linha para a função é a forma “antiga” de fazer isso. Nesta seção, você deseja abandonar completamente o loop foreach e usar o pipeline em vez disso.
Como está, a função não suporta o pipeline de forma alguma. Faria sentido intuitivo supor que você poderia passar cada nome de computador e versão para a função usando o pipeline. Abaixo, estamos lendo o CSV e passando diretamente para Install-Office, mas isso não funciona.
Você pode presumir o quanto quiser, mas isso não faz com que funcione magicamente. Estamos sendo solicitados para o parâmetro Version quando você sabe que Import-Csv está enviando-o como uma propriedade do objeto. Por que não está funcionando? Porque você ainda não adicionou suporte para pipeline.
Há dois tipos de entrada de pipeline em uma função do PowerShell; PorValor (objeto inteiro) e PorNomeDaPropriedade (uma única propriedade do objeto). Qual você acha que é a melhor maneira de conectar a saída de Import-Csv com a entrada de Install-Office?
Sem nenhuma refatoração, você poderia usar o método PorNomeDaPropriedade, já que, afinal, Import-Csv já está retornando as propriedades Version e ComputerName, já que elas são colunas no CSV.
Adicionar suporte para pipeline a uma função personalizada é muito mais simples do que você pode estar pensando. É apenas um atributo de parâmetro representado com uma das duas palavras-chave; ValueFromPipeline ou ValueFromPipelineByPropertyName.
No exemplo, você deseja vincular as propriedades ComputerName e Version retornadas de Import-Csv aos parâmetros Version e ComputerName de Install-Office, então você estará usando ValueFromPipelineByPropertyName.
Já que queremos vincular ambos esses parâmetros, você adicionará essa palavra-chave a ambos os parâmetros conforme mostrado abaixo e executará novamente a função usando o pipeline.
Isso é estranho. Ele só foi executado para a última linha no CSV. O que está acontecendo? Ele executou a função apenas para a última linha porque você pulou sobre um conceito que não é necessário ao construir funções sem suporte de pipeline.
Não esqueça o Bloco de Processo!
Quando você precisa criar uma função que envolve suporte de pipeline, você deve incluir (no mínimo) um bloco “embutido” dentro da sua função chamado. process. Este bloco de processo diz ao PowerShell que ao receber entrada do pipeline, execute a função para cada iteração. Por padrão, ele executará apenas a última.
Você poderia tecnicamente adicionar outros blocos como begin e end também, mas os scripters não os usam com tanta frequência.
Para dizer ao PowerShell para executar esta função para cada objeto que entra, vou adicionar um bloco process que inclui o código dentro dele.
Agora você pode ver que as propriedades Version e ComputerName de cada objeto retornadas de Import-Csv foram passadas para Install-Office e vinculadas aos parâmetros Version e ComputerName.
Recursos
Para entender melhor como os parâmetros de função funcionam, confira meu post no blog sobre funções do PowerShell.
I also encourage you to check my Pluralsight course entitled Building Advanced PowerShell Functions and Modules for an in-depth breakdown of everything there is to know about PowerShell functions, function parameters, and PowerShell modules.