Assim que você se acostumar a escrever scripts em PowerShell, é necessário aprender sobre modularização de código. Modularização é apenas uma palavra chique para criar código em blocos de construção. No mundo do PowerShell, as funções do PowerShell são uma das melhores maneiras de fazer isso.
Quando você escreve um script em PowerShell, tem várias opções de como escrever o código. Você poderia escrever mil linhas de código que realizam centenas de tarefas, tudo em um único bloco de código ininterrupto. Isso seria um desastre. Em vez disso, você deve escrever funções.
Funções aumentam significativamente a usabilidade e a legibilidade do seu código, tornando-o muito mais fácil de trabalhar. Neste tutorial, você aprenderá a escrever funções, adicionar e gerenciar os parâmetros das suas funções, e configurar funções para aceitar entrada do pipeline. Mas primeiro, vamos dar uma olhada em um pouco de terminologia.
Este post foi extraído do meu livro PowerShell para Administradores de Sistemas: Automação de Fluxo Facilitada. Se você aprender algo neste tutorial, não deixe de conferir o livro para saber mais sobre funções e muitas outras funcionalidades interessantes do PowerShell.
Funções vs. Cmdlets
O conceito de uma função pode parecer familiar porque se parece um pouco com os cmdlets que você provavelmente já está usando. Comandos como Start-Service e Write-Host, por exemplo, são semelhantes a funções. Estas são peças de código nomeadas que resolvem um único problema. A diferença entre uma função e um cmdlet é como cada um desses construtos é feito.
A cmdlet isn’t written with PowerShell. It’s written in another language, typically something like C#. The cmdlet is then compiled and made available inside PowerShell.
Funções, por outro lado, são escritas em PowerShell; não em outra linguagem.
Você pode ver quais comandos são cmdlets e quais são funções usando o cmdlet Get-Command e seu parâmetro CommandType conforme mostrado abaixo
Este comando acima retorna todas as funções atualmente carregadas em sua sessão do PowerShell, ou dentro de módulos que estão disponíveis para o PowerShell.
Relacionado: Compreendendo e Construindo Módulos do PowerShell
Pré-requisitos
Se você gostaria de acompanhar todos os exemplos, por favor, certifique-se de ter uma versão do PowerShell disponível. Não há requisitos específicos de versão para este tutorial. Além disso, certifique-se de ter um bom editor de código como Visual Studio Code para copiar, colar e executar alguns trechos de código.
Construindo uma Função Simples
Antes de você poder usar uma função, você precisa defini-la. Para definir uma função, você usa a palavra-chave `function`, seguida por um nome descritivo definido pelo usuário, seguido por um conjunto de chaves. Dentro das chaves está um bloco de script que você quer que o PowerShell execute.
Abaixo você pode ver uma função básica e como executar essa função. Essa função chamada Install-Software usa Write-Host para exibir uma mensagem no console. Uma vez definida, você pode usar o nome dessa função para executar o código dentro do seu bloco de script.
Nomeando com Verbo-Substantivo
A function’s name is important. You can name your functions whatever you want, but the name should always describe what the function does. The function-naming convention in PowerShell is the Verb-Noun syntax.
Você sempre deve começar o nome de uma função com um verbo seguido de um traço e um substantivo. Para encontrar a lista de verbos “aprovados”, use o cmdlet Get-Verb.
Alterando o Comportamento da Função
Se você deseja alterar o comportamento de uma função, pode simplesmente alterar o código que a função executa, conforme mostrado abaixo.
Agora que você alterou o código dentro da função, ela exibirá uma mensagem ligeiramente diferente.
Definindo uma Função Avançada
Você pode definir funções em muitos lugares diferentes. Na seção anterior, o tutorial assume que você apenas copiou e colou o código diretamente no console do PowerShell. Mas esta não é a única maneira. Você também pode definir funções em um script.
Na seção anterior, você estava trabalhando com uma função pequena, então defini-la no console não foi um grande problema. Na maioria das vezes, porém, você terá funções muito maiores. Será mais fácil definir essas funções em um script ou em um módulo e então chamar esse script ou módulo para carregar a função na memória.
Como você pode imaginar, digitar novamente uma função maior toda vez que você deseja ajustar sua funcionalidade pode ser um pouco frustrante.
I suggest you now open your favorite editor and store the function in a .ps1 file as you work through the rest of the tutorial.
Adicionando Parâmetros às Funções
As funções no PowerShell podem ter qualquer número de parâmetros. Ao criar suas próprias funções, você terá a opção de incluir parâmetros e decidir como esses parâmetros funcionarão. Os parâmetros podem ser obrigatórios ou opcionais, e podem aceitar qualquer coisa ou serem forçados a aceitar um dos itens de uma lista limitada de argumentos possíveis.
Relacionado: Tudo o que você sempre quis saber sobre Parâmetros no PowerShell
Por exemplo, o software fictício que você está instalando através da função Install-Software pode ter muitas versões. Mas atualmente, a função Install-Software não oferece ao usuário nenhuma maneira de especificar qual versão deseja instalar.
Se você fosse o único usando a função, você poderia alterar o código dentro dela cada vez que quisesse uma versão específica, mas isso seria uma perda de tempo. Esse processo também seria propenso a erros potenciais, sem mencionar que você deseja que outras pessoas possam usar seu código.
Introduzir parâmetros em sua função permite que ela tenha variabilidade. Assim como as variáveis permitiram que você escrevesse scripts que lidam com muitas versões da mesma situação, os parâmetros permitem que você escreva uma única função que faça uma coisa de várias maneiras.
Neste caso, você quer que ela instale versões do mesmo software e o faça em muitos computadores.
Vamos primeiro adicionar um parâmetro à função que permite a você ou a um usuário especificar a versão a ser instalada.
Criando um Parâmetro Simples
Criar um parâmetro em uma função requer um bloco param. O bloco param contém todos os parâmetros da função. Defina um bloco param com a palavra-chave param seguida por parênteses conforme mostrado abaixo.
Neste ponto, a funcionalidade real da sua função não mudou nada. Você apenas instalou a parte básica, preparando a função para um parâmetro.
Por enquanto, a função não está realmente instalando nenhum software. Está apenas utilizando o cmdlet
Write-Hostpara simular a instalação do software para que você possa se concentrar em escrever a função.
Depois de adicionar o bloco param, você pode criar o parâmetro colocando-o dentro dos parênteses do bloco param, conforme mostrado abaixo.
Dentro do bloco param acima, você primeiro definiria o bloco de Parâmetro. Usar o bloco Parameter() dessa forma o transformará em um “parâmetro avançado”. Um bloco de Parâmetro vazio como este não faz nada, mas é necessário; explicarei como usá-lo na próxima seção.
Vamos nos concentrar no tipo [string] na frente do nome do parâmetro. Ao colocar o tipo do parâmetro entre colchetes antes do nome da variável do parâmetro, você faz um *cast* do valor do parâmetro para um tipo específico. O PowerShell sempre tentará converter qualquer valor que seja passado para este parâmetro em uma string – se ainda não for uma. Acima, qualquer coisa passada como $Version será sempre tratada como uma string.
Fazer *cast* do seu parâmetro para um tipo não é obrigatório, mas eu o encorajo fortemente. Isso define explicitamente o tipo e reduzirá significativamente os erros futuros.
Você também adiciona $Version em sua instrução Write-Host agora. Isso significa que quando você executar a função Install-Software com o parâmetro Version e passar um número de versão, você deverá receber uma declaração dizendo isso, conforme mostrado abaixo.
Vamos ver o que você pode fazer com este parâmetro agora.
O Atributo de Parâmetro Obrigatório
Você pode usar o bloco de Parâmetro para controlar vários atributos do parâmetro, o que permitirá que você altere o comportamento do parâmetro. Por exemplo, se você quiser garantir que qualquer pessoa chamando a função tenha que passar um determinado parâmetro, você pode definir esse parâmetro como Obrigatório.
Por padrão, os parâmetros são opcionais. Vamos forçar o usuário a passar uma versão usando a palavra-chave Obrigatório dentro do bloco de Parâmetro, como mostrado abaixo.
Se você executar a função acima, deverá receber o seguinte prompt:
Assim que você definiu o atributo Obrigatório, executar a função sem o parâmetro interromperá a execução até que o usuário insira um valor. A função agora espera até que o usuário especifique um valor para o parâmetro Version. Uma vez inserido, o PowerShell executa a função.
Para evitar a solicitação do parâmetro obrigatório, basta passar um valor para o parâmetro ao chamar a função conforme mostrado abaixo.
Valores Padrão de Parâmetro
Se, por exemplo, você se vê passando o mesmo valor para um parâmetro repetidas vezes, você pode definir um valor padrão para o parâmetro. Parâmetros padrão são úteis quando você espera um certo valor para um parâmetro na maioria das vezes.
Por exemplo, se você deseja instalar a versão 2 deste software 90 por cento do tempo, e prefere não ter que definir o valor toda vez que executar esta função, você poderia atribuir um valor padrão de 2 ao parâmetro $Version. Você pode ver este exemplo abaixo.
Ter um parâmetro padrão não impede que você passe um. Seu valor passado substituirá o valor padrão.
Adicionando Atributos de Validação de Parâmetros
É sempre uma boa ideia limitar quais valores você pode passar para uma função via parâmetros. A melhor maneira de fazer isso é com atributos de validação de parâmetros.
Limitar as informações que os usuários (ou até mesmo você!) podem passar para suas funções ou scripts eliminará código desnecessário dentro da sua função. Por exemplo, digamos que você passe o valor 3 para sua função Install-Software, sabendo que a versão 3 é uma versão existente.
Sua função assume que todo usuário sabe quais versões existem, então não considera o que acontece quando você tenta especificar a versão 4. Nesse caso, a função não conseguirá encontrar a pasta apropriada porque ela não existe.
Vida sem Validação de Parâmetros
Dê uma olhada no exemplo abaixo quando você usa a string $Version em um caminho de arquivo. Se alguém passar um valor que não complete o nome de uma pasta existente (por exemplo, SoftwareV3 ou SoftwareV4), o código falhará.
Você poderia escrever código de tratamento de erros para lidar com esse problema, ou poderia resolver o problema desde o início exigindo que o usuário passe apenas uma versão existente do software. Para limitar a entrada do usuário, adicione validação de parâmetros.
Adicionando Validação de Parâmetros
Vários tipos de validação de parâmetro existem, mas em relação à sua função Install-Software, o atributo de validação [ValidateSet](https://adamtheautomator.com/powershell-validateset/) funciona melhor. O atributo de validação ValidateSet permite que você especifique uma lista de valores permitidos para o parâmetro. Se você está considerando apenas a string 1 ou 2, você garantiria que o usuário possa especificar apenas esses valores; caso contrário, a função falhará imediatamente e notificará o usuário do motivo.
Adicione os atributos de validação de parâmetros dentro do bloco param, logo abaixo do bloco Parameter original, como mostrado abaixo.
Ao adicionar um conjunto de itens (1 e 2) dentro dos parênteses finais do atributo ValidateSet, isso indica ao PowerShell que os únicos valores válidos para Version são 1 ou 2. Se um usuário tentar passar algo diferente do que está no conjunto, eles receberão uma mensagem de erro, conforme mostrado abaixo, notificando que eles têm apenas um número específico de opções disponíveis.
O atributo ValidateSet é um atributo de validação comum, mas outros estão disponíveis. Para obter uma análise completa de todas as formas como os valores do parâmetro podem ser restritos, confira a documentação da Microsoft.
Aceitando Entrada do Pipeline
Até agora, você criou uma função com um parâmetro que pode ser passado apenas usando a sintaxe típica -NomeDoParâmetro <Valor>. Isso funciona, mas você também tem outra opção para passar valores para parâmetros usando o pipeline do PowerShell. Vamos adicionar capacidades de pipeline à nossa função Install-Software.
Relacionado: Aceitando Entrada do Pipeline no Artigo sobre Parâmetros do PowerShell do ATA
Primeiro, adicione outro parâmetro ao seu código que especifique o computador no qual você deseja instalar o software. Além disso, adicione esse parâmetro à sua referência Write-Host para simular a instalação.
Depois de adicionar o parâmetro ComputerName à função, você poderia iterar sobre uma lista de nomes de computadores e passar os valores para o nome do computador e a versão para a função Install-Software, como abaixo.
Em vez de fazer tudo isso, você deveria aprender a usar o pipeline.
Tornando a Função Compatível com o Pipeline
Infelizmente, você não pode aproveitar o pipeline do PowerShell com apenas uma função simples construída anteriormente. Você deve decidir qual tipo de entrada de pipeline deseja que a função aceite e implementar.
A PowerShell function uses two kinds of pipeline input: ByValue (entire object) and ByPropertyName (a single object property). Here, because the $computers array contains only strings, you’ll pass those strings via ByValue.
Para adicionar suporte ao pipeline, adicione um atributo de parâmetro ao parâmetro desejado usando uma das duas palavras-chave: ValueFromPipeline ou ValueFromPipelineByPropertyName, conforme mostrado abaixo.
Depois de atualizar a função Install-Software, carregue-a e chame-a assim:
Execute o script novamente e você deverá obter algo como isso:
Observe que Install-Software é executado apenas para a última string no array. Você verá como corrigir isso na próxima seção.
Adicionando um Bloco de Processamento
Para dizer ao PowerShell para executar esta função para cada objeto que chega, você deve incluir um bloco de processo. Dentro do bloco de processo, coloque o código que deseja executar cada vez que a função recebe entrada do pipeline. Adicione um bloco de processo ao seu script conforme mostrado abaixo.
Agora chame a função novamente da mesma forma que fez anteriormente. A função Install-Software agora retornará três linhas (uma para cada objeto).
O bloco de processo contém o código principal que você deseja executar. Você também pode usar blocos begin e end para o código que será executado no início e no final da chamada da função. Você pode aprender mais sobre os blocos begin, process, e end através da documentação da Microsoft.
Próximos Passos
As funções permitem que você compartimentalize o código em blocos de construção discretos. Elas não apenas ajudam a dividir o trabalho em partes menores e mais gerenciáveis, mas também o obrigam a escrever código legível e testável.
I now challenge you to look through some old scripts and see where you can add a PowerShell function. Look for patterns in code. Build a function from those patterns. Notice where you’re copying/pasting code snippets and turn those into PowerShell functions!