Como Usar Funções do PowerShell

1. Diferença Entre Funções e Cmdlets no PowerShell
2. Introdução às Funções no PowerShell
3. Adicionar Parâmetros a Funções no PowerShell
4. Criar um Parâmetro Simples em uma Função no PowerShell

Quando escrevemos um script PowerShell, temos muitas opções. Por exemplo, poderíamos escrever mil linhas de código para tarefas, tudo em um único bloco de código.

No entanto, isso seria complicado. Assim, em vez disso, devemos escrever funções PowerShell.

As funções PowerShell aumentam drasticamente a usabilidade e a legibilidade do nosso código, tornando muito mais fácil trabalhar com ele. Neste artigo, aprenderemos a escrever funções, adicionar e gerenciar os parâmetros das nossas funções e configurar funções para aceitar entrada de pipeline.

Diferença Entre Funções e Cmdlets no PowerShell

O conceito de uma função PowerShell pode soar familiar porque se assemelha aos cmdlets nativos do PowerShell. Comandos como Write-Host e Start-Service, por exemplo, são muito semelhantes às funções.

No entanto, os cmdlets são pedaços de código nomeados que resolvem um único problema e não são facilmente personalizáveis. A diferença entre um cmdlet e uma função é como esses constructos são feitos.

Podemos ver quais comandos são cmdlets e funções usando o cmdlet Get-Command e seu parâmetro -CommandType.

Get-Command -CommandType Function

O comando acima retorna todas as funções atualmente carregadas em nossa sessão PowerShell ou dentro dos módulos disponíveis para o PowerShell.

Introdução às Funções no PowerShell

Usamos a palavra-chave function para definir uma função, seguida de um nome descritivo e definido pelo usuário e um conjunto de chaves. Dentro das chaves está um bloco de script que queremos que o PowerShell execute.

Abaixo, podemos ver uma função primária e a execução dessa função. A função, chamada Install-Software, usa Write-Host para exibir uma mensagem de saída no console (principalmente para simular a instalação).

Uma vez definida, podemos usar o nome dessa função para executar o código dentro de seu bloco de script.

Código de Exemplo:

function Install-Software {
    Write-Host 'The software has been installed.'
}

Install-Software

Saída:

The software has been installed.

Melhor Prática de Convenção de Nomes de Funções com a Sintaxe Verbo-Nome no PowerShell

O nome de uma função é essencial. Podemos nomear nossas funções como quisermos, mas o nome deve sempre descrever o que a função faz.

A melhor prática da convenção de nomes de funções no PowerShell é a sintaxe Verbo-Nome.

Devemos sempre começar um nome de função com um verbo seguido de um traço e um nome. Use o cmdlet Get-Verb para encontrar a lista de verbos aprovados.

Defina uma Função Avançada no PowerShell

O tutorial assume que copiamos e colamos o código anterior diretamente no console do PowerShell nesta seção. Também podemos definir funções em um script.

Estávamos trabalhando com uma função pequena na seção anterior, então defini-la no console não foi um grande problema. Na maioria das vezes, no entanto, teremos funções muito maiores.

Portanto, será mais fácil definir essas funções em um script ou módulo e, em seguida, chamar esse script ou módulo para carregar a função na memória.

Como podemos imaginar, reescrever uma função maior toda vez que quisermos ajustar sua funcionalidade pode ser confuso.

Adicionar Parâmetros a Funções no PowerShell

As funções podem ter qualquer número de parâmetros. Quando criamos nossas funções, teremos a opção de incluir parâmetros e decidir como esses parâmetros funcionam.

Os parâmetros podem ser opcionais ou obrigatórios, e podem ser forçados a aceitar um dos argumentos de uma lista limitada ou aceitar qualquer coisa.

Por exemplo, o software fictício que instalamos através da função Install-Software pode ter muitas versões possíveis anteriormente. Mas atualmente, a função Install-Software não oferece ao usuário nenhuma maneira de especificar qual versão deseja instalar.

Se fôssemos os únicos a usar a função, poderíamos alterar o código dentro dela toda vez que quiséssemos uma versão específica, mas isso consumiria muito tempo. Esse método também estaria sujeito a possíveis erros, e queremos que outros possam usar nosso código.

Introduzir parâmetros em nossa função permite que ela tenha variabilidade. Assim como as variáveis nos permitiram escrever scripts que pudessem lidar com muitas versões da mesma situação, os parâmetros nos permitirão escrever uma única função que faz uma coisa de várias maneiras.

Neste caso, queremos que instale versões do mesmo software e faça isso em muitos computadores.

Primeiro, vamos adicionar um parâmetro à função que permite a um usuário ou nós especificar a versão a ser instalada.

Criar um Parâmetro Simples em uma Função no PowerShell

Definir um parâmetro em uma função requer um bloco de parâmetros. O bloco de parâmetros contém todos os parâmetros para a função.

Defina um bloco de parâmetros com a palavra-chave param seguida de parênteses, como mostrado abaixo.

Código de Exemplo:

function Install-Software {
    [CmdletBinding()]
    param()

    Write-Host 'The software has been installed.'
}

Neste ponto, a funcionalidade real da nossa função não mudou nem um pouco. Apenas instalamos a infraestrutura, preparando a função para um parâmetro.

Uma vez que adicionamos o bloco param, podemos criar o parâmetro colocando-o dentro de seus parênteses, como mostrado abaixo.

Código de Exemplo:

function Install-Software {
    [CmdletBinding()]
    param(
        [Parameter()]
        [string] $Version
    )

    Write-Host "The software version $Version has been installed."

}

Dentro do bloco param acima, primeiro definiríamos o bloco Parameter. Usar o bloco Parameter() transformará o parâmetro em um “parâmetro avançado”.

Um bloco param vazio como o aqui não faz nada, mas é necessário; explicaremos como usá-lo na próxima seção.

Vamos focar no tipo [string] na frente do nome do parâmetro. Nós convertimos os parâmetros colocando o tipo do parâmetro entre colchetes antes do nome da variável do parâmetro.

O PowerShell sempre padroniza valores como uma string. Acima, qualquer coisa passada na variável $Version será sempre tratada como uma string.

Também adicionamos $Version em nossa instrução Write-Host. Então, quando executamos a função Install-Software com o parâmetro Version e passamos um número de versão, devemos receber uma mensagem mostrando isso.

Código de Exemplo:

Install-Software -Version 2

Saída:

The software version 2 has been installed.