Uma vez que você se acostuma a escrever scripts do PowerShell, precisa aprender sobre modularização de código. Modularização é apenas um termo 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.
Ao escrever um script do PowerShell, você tem muitas opções sobre 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.
As funções aumentam drasticamente 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 de suas funções e configurar funções para aceitar entrada de pipeline. Mas primeiro, vamos dar uma olhada em um pouco de terminologia.
Este post foi extraído do meu livro PowerShell para Sysadmins: Automação de Fluxo de Trabalho Facilitada. Se você aprender algo neste tutorial, não deixe de conferir o livro para aprender mais sobre funções e muitos outros recursos do PowerShell.
Funções vs Cmdlets
O conceito de uma função pode parecer familiar porque soa um pouco como os cmdlets que você provavelmente já está usando. Comandos como Start-Service e Write-Host, por exemplo, são semelhantes a funções. Estes são pedaços de código nomeados 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, como mostrado abaixo
Este comando acima retorna todas as funções atualmente carregadas em sua sessão PowerShell, ou dentro de módulos que estão disponíveis para o PowerShell.
Relacionado: Entendendo e Construindo Módulos do PowerShell
Pré-requisitos
Se você deseja seguir com todos os exemplos, 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 poder usar uma função, você precisa defini-la. Para definir uma função, você utiliza a palavra-chave `function`, seguida por um nome descritivo definido pelo usuário, e então um conjunto de chaves. Dentro das chaves, há um bloco de script que você deseja que o PowerShell execute.
Abaixo, você pode ver uma função básica e a execução dessa função. Essa função chamada Install-Software usa o 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.
Nomenclatura 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 iniciar o nome de uma função com um verbo seguido por 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 desejar alterar o comportamento de uma função, você pode simplesmente modificar o código que a função executa, como 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ê simplesmente copiou e colou o código diretamente no console do PowerShell. Mas essa 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. No entanto, na maioria das vezes, você terá funções muito maiores. Será mais fácil defini-las em um script ou em um módulo e, em seguida, 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ê quiser 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 do PowerShell podem ter qualquer número de parâmetros. Quando você cria suas próprias funções, terá a opção de incluir parâmetros e decidir como esses parâmetros funcionam. Os parâmetros podem ser obrigatórios ou opcionais, e podem aceitar qualquer coisa ou serem forçados a aceitar um dos possíveis argumentos de uma lista limitada.
Relacionado: Tudo o que você sempre quis saber sobre parâmetros do PowerShell
Por exemplo, o software fictício que você está instalando por meio da função Install-Software anterior pode ter várias versões. Mas atualmente, a função Install-Software não oferece uma maneira para o usuário especificar qual versão deseja instalar.
Se você fosse o único a usar a função, poderia alterar o código dentro dela cada vez que quisesse uma versão específica, mas isso seria um desperdício de tempo. Esse processo também seria propenso a erros potenciais, sem mencionar que você deseja que outras pessoas possam usar seu código.
A introdução de parâmetros em sua função permite que ela tenha variabilidade. Assim como as variáveis permitiram que você escrevesse scripts que pudessem lidar 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 ele instale versões do mesmo software e faça isso 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
Para criar um parâmetro em uma função, é necessário 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 canalização, preparando a função para um parâmetro.
Por enquanto, a função na verdade não está instalando nenhum software. Ela está apenas usando 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() assim o transformará em um “parâmetro avançado”. Um bloco de parâmetro vazio como este não faz nada, mas é necessário; vou explicar como usá-lo na próxima seção.
Vamos focar 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ê converte o valor do parâmetro para um tipo específico. O PowerShell sempre tentará converter qualquer valor 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 o casting do seu parâmetro para um tipo não é obrigatório, mas eu o incentivo fortemente. Isso define explicitamente o tipo e reduzirá significativamente os erros no futuro.
Você também adiciona $Version à 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á obter uma instrução como 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âmetros 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 que chame 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âmetros, como mostrado abaixo.
Se você executar a função acima, você deverá receber o seguinte prompt:
Uma vez que você definiu o atributo Obrigatório, a execução da função sem o parâmetro será interrompida 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 Versão. 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, como mostrado abaixo.
Valores padrão de parâmetro
Por exemplo, se você se encontrar passando o mesmo valor para um parâmetro repetidamente, você pode definir um valor padrão para o parâmetro. Parâmetros padrão são úteis quando você espera um determinado valor para um parâmetro na maioria das vezes.
Por exemplo, se você deseja instalar a versão 2 deste software 90% do tempo e não quiser ter que definir o valor toda vez que executar esta função, você pode atribuir um valor padrão de 2 para o parâmetro $Versão. Você pode ver este exemplo abaixo.
Ter um parâmetro padrão não impede que você passe um valor. O valor passado substituirá o valor padrão.
Adicionando Atributos de Validação de Parâmetros
Sempre é uma boa ideia limitar os valores que você pode passar para uma função por meio de 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 de 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 cada usuário sabe quais versões existem, portanto, não leva em consideração 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
Confira o exemplo abaixo quando você utiliza a string $Version em um caminho de arquivo. Se alguém passar um valor que não completa um nome de pasta existente (por exemplo, SoftwareV3 ou SoftwareV4), o código falhará.
Você poderia escrever código de tratamento de erro para lidar com esse problema, ou poderia resolver o problema 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
Existem vários tipos de validação de parâmetros, mas em relação à sua função Install-Software, o atributo [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ê estiver considerando apenas a string 1 ou 2, certifique-se de 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 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 Versão são 1 ou 2. Se um usuário tentar passar algo além do que está no conjunto, ele receberá uma mensagem de erro como mostrado abaixo, notificando que ele tem 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 uma análise completa de todas as maneiras pelas quais os valores dos parâmetros podem ser restritos, confira a documentação da Microsoft.
Aceitando Entrada pelo 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 de passar valores para parâmetros usando o pipeline do PowerShell. Vamos adicionar capacidades de pipeline à nossa função Install-Software.
Relacionado: Aceitando Entrada pelo Pipeline no Artigo de Parâmetros do ATA PowerShell
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 agora iterar sobre uma lista de nomes de computador 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 ter a função Install-Software atualizada carregada, chame-a assim:
Execute o script novamente e você deverá obter algo como isto:
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 Processo
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 de pipeline. Adicione um bloco de processo ao seu script conforme mostrado abaixo.
Agora chame a função novamente exatamente como fez antes. 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 deseja executar. Você também pode usar os 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 seu 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!