Embedded Files
Para uma melhor experiência com caixas de código, experimente ver o site em um Desktop.
Scripts mais inteligentes e reutilizáveis
Scripts mais inteligentes e reutilizáveis
Introdução
Introdução
Quem escreve scripts em PowerShell logo percebe que copia os mesmos trechos de código de um lado para o outro. Funções e parâmetros resolvem isso: o código fica organizado em blocos com nome, que você chama sempre que precisar, passando valores diferentes a cada vez.
Neste tutorial, vamos ver o básico: como criar uma função, como passar parâmetros para ela, como deixar um parâmetro opcional ou obrigatório e, no fim, como juntar tudo em um exemplo prático.
Os exemplos foram escritos para o Windows PowerShell 5.1, a versão que já vem instalada no Windows 10, no Windows 11 e no Windows Server.
Para escrever e testar os exemplos, use o Windows PowerShell ISE, que já vem com o Windows: procure por "ISE" no menu Iniciar (se não aparecer, ele pode ser adicionado em Recursos opcionais, nas Configurações do Windows). O ISE junta editor e console na mesma janela: o F5 executa o script inteiro e o F8 executa só o trecho selecionado, o que facilita testar uma função logo depois de escrevê-la.
Depois de pegar o básico, vale migrar para o Visual Studio Code com a extensão PowerShell. O ISE não recebe mais novidades da Microsoft e só trabalha com o Windows PowerShell 5.1, enquanto o VS Code é a ferramenta recomendada hoje e também funciona com o PowerShell 7.
Dica: se salvar os exemplos em um arquivo .ps1, grave o arquivo como UTF-8 com BOM. Sem o BOM, o PowerShell 5.1 lê o arquivo com outra codificação e o "Olá" aparece como "Olá".
O que são funções?
O que são funções?
Uma função é um bloco de código com um nome. Você define o bloco uma vez e depois o executa quantas vezes quiser, apenas chamando o nome. Isso evita código repetido e deixa o script mais fácil de ler.
Vamos criar uma função chamada Saudar, que exibe uma mensagem:
# Windows PowerShell 5.1
function Saudar {
Write-Output "Olá! Bem-vindo ao PowerShell!"
}
Para executar a função, basta digitar o nome dela:
# Windows PowerShell 5.1
Saudar
O que são parâmetros?
O que são parâmetros?
Parâmetros são valores que você passa para a função no momento em que a chama. Com eles, a mesma função funciona com entradas diferentes.
Vamos alterar a função Saudar para receber o nome da pessoa no parâmetro -Nome:
# Windows PowerShell 5.1
function Saudar {
param (
[string]$Nome
)
Write-Output "Olá, $Nome! Bem-vindo ao PowerShell!"
}
Agora chame a função passando um nome:
# Windows PowerShell 5.1
Saudar -Nome "Maria"
Parâmetros opcionais
Parâmetros opcionais
Um parâmetro com valor padrão é opcional: se ele não for informado, a função usa o valor padrão. Vamos acrescentar o parâmetro -Saudacao, que usa "Olá" quando nada é passado:
# Windows PowerShell 5.1
function Saudar {
param (
[string]$Nome,
[string]$Saudacao = "Olá" # opcional: usa "Olá" se nada for informado
)
Write-Output "$Saudacao, $Nome! Bem-vindo ao PowerShell!"
}
# Com os dois parâmetros
Saudar -Nome "Maria" -Saudacao "Bom dia"
# Só com o nome: a saudação padrão é usada
Saudar -Nome "João"
Parâmetros obrigatórios e validação
Parâmetros obrigatórios e validação
Na versão anterior, nada impede alguém de chamar Saudar sem informar o nome. O resultado seria "Olá, ! Bem-vindo ao PowerShell!". Para evitar isso, marque o parâmetro como obrigatório com [Parameter(Mandatory)].
Também dá para limitar os valores aceitos. O [ValidateSet()] define uma lista de opções; qualquer valor fora dela é recusado com um erro.
# Windows PowerShell 5.1
function Saudar {
param (
[Parameter(Mandatory)]
[string]$Nome,
[ValidateSet("Olá", "Bom dia", "Boa tarde", "Boa noite")]
[string]$Saudacao = "Olá"
)
Write-Output "$Saudacao, $Nome! Bem-vindo ao PowerShell!"
}
Saudar # o PowerShell pede o valor de Nome
Saudar -Nome "Maria" -Saudacao "Oi" # erro: "Oi" não está na lista
Ao chamar Saudar sem o nome, o PowerShell não executa a função: ele para e pede o valor ("Supply values for the following parameters"). Um nome vazio ("") também é recusado.
Outro detalhe útil do [ValidateSet()]: no console, depois de digitar -Saudacao, a tecla Tab completa as opções da lista.
Exemplo prático: total de despesas
Exemplo prático: total de despesas
Agora vamos juntar tudo em uma função que soma as despesas de um usuário. Ela recebe o nome do usuário (obrigatório) e uma lista de valores.
[decimal[]]$Despesas # lista de valores
Write-Output "Nenhuma despesa registrada para $Usuario."
foreach ($despesa in $Despesas) {
Write-Output ("As despesas totais de $Usuario são: R$ {0:N2}" -f $total)
Get-TotalDespesa -Usuario "Maria" -Despesas 100.50, 200.75, 50.25
Get-TotalDespesa -Usuario "João"
A primeira chamada mostra "As despesas totais de Maria são: R$ 351,50", e a segunda, "Nenhuma despesa registrada para João.". O {0:N2} formata o total com duas casas decimais, no padrão de número do Windows: em um Windows em português aparece 351,50; em inglês ou japonês, 351.50.
Dois detalhes desse exemplo:
[decimal] é o tipo indicado para valores em dinheiro, porque guarda casas decimais sem os pequenos erros de arredondamento de tipos como [float].
O nome segue o padrão do PowerShell, Verbo-Substantivo, com um verbo aprovado (Get). O comando Get-Verb lista todos os verbos aprovados. Com um verbo fora da lista, como "Calcular", o PowerShell exibe um aviso quando a função faz parte de um módulo.
Por que usar funções com parâmetros
Por que usar funções com parâmetros
Reutilização: a mesma função atende a vários casos, só mudando os parâmetros.
Leitura: o script fica dividido em blocos com nomes claros.
Segurança: parâmetros obrigatórios e validados barram valores errados antes de o código rodar.
Para fechar
Para fechar
Com funções e parâmetros, um script deixa de ser uma sequência de comandos repetidos e passa a ser um conjunto de ferramentas que você reaproveita. Comece transformando em função aquele trecho que você mais copia e cola. Em um próximo post, vamos aplicar isso em scripts que usamos no dia a dia da infraestrutura.
Para saber mais
Para saber mais
Page updated
Google Sites
Report abuse