funções são uma ocorrência comum em PowerShell e para realmente entender a linguagem PowerShell, é importante que você saiba como as funções funcionam. Neste artigo, vamos mostrar como uma função PowerShell evolui de basicamente nada até ter parâmetros usando atributos de validação.

para demonstrar isso, vamos começar com uma função que não pode ficar mais simples.

function Write-Log {

param()
}

quando executado dentro de uma sessão PowerShell, esta função irá executar mas não fará nada porque não há código para executar. PowerShell simplesmente executa a função em si e retorna.

para que a função realmente faça algo, precisamos adicionar algum código. O código é adicionado entre o bloco de param e o último suporte curly. Você pode ver abaixo que eu estou fazendo minha função de registro de Escrita retornar a string “eu fiz algo” para o console.

function Write-Log {

param()
'I did something'
}
PS> Write-Log
I did something

Nossa função é chamada Write-Log então estou assumindo que esta será uma função que eventualmente irá escrever algum tipo de texto para um arquivo de log. Porque nós não queremos escrever a mesma coisa em um arquivo de log todas as vezes, nós precisamos fornecer alguma maneira de mudar a mensagem quando a função corre. Para isso, adicionaremos um parâmetro. Os parâmetros permitem que o usuário passe valores diferentes para a função em tempo de execução. Isto permite que a função reúna dados dinâmicos em tempo de execução.

para adicionar um parâmetro, vou adicionar uma variável. Neste caso, a variável é chamada de mensagem. Vou adicioná-lo dentro do bloco do param, como mostrado abaixo. Você pode então ver que eu posso referenciar esse parâmetro dentro da função em si. Quando executado, a função retornará qualquer valor que eu passar para o parâmetro da mensagem.

Você não tem que parar em apenas um parâmetro. Podemos acrescentar o que quisermos aqui. Abaixo, estou adicionando um parâmetro de gravidade, fornecendo um valor quando a função é executada e você pode ver que exibe o mesmo comportamento.

function Write-Log {

param($Message, $Severity)
"$Message - Severity: $Severity"
}
Write-Log -Message 'I did something' -Severity 1

Agora que sabemos como lidar com parâmetros, podemos entrar em tipos de parâmetros. Um parâmetro tem um tipo como qualquer outra coisa em PowerShell. Acima, usava um tipo, mas aceitava qualquer tipo de objeto imaginável. O parâmetro não foi escrito explicitamente. É uma boa prática fazer isso em todos os parâmetros para garantir que apenas os valores que você espera sejam passados.

para definir um tipo, podemos adicionar o tipo entre parêntesis rectos antes do parâmetro ser declarado.

function Write-Log {

param($Message)
$Message
}

Uma vez que um tipo explícito é atribuído ao parâmetro, PowerShell só aceitará entrada desse tipo ou um objeto que ele pode converter. Neste exemplo abaixo, estou passando o valor booleano $false para o parâmetro da mensagem. Você pode ver que o PowerShell não vai permitir isso. Isto é porque ele não pode converter um tipo booleano para um tipo de controlador de Serviço.

No entanto, se passarmos por um objecto de controlo de serviços que o Get-Service retorna, ele funciona muito bem.

PS> Write-Log -Message $service
Status Name DisplayName
------ ---- -----------
Stopped AdtAgent Microsoft Monitoring Agent Audit Fo...

também podemos usar atributos de parâmetros. Atributos de Parâmetros nos permitem definir diferentes características de cada parâmetro que determina como ele funciona. No exemplo abaixo, estou usando o parâmetro obrigatório. Estes atributos força o usuário a passar um valor para o parâmetro da mensagem senão a função não será executada.

também estou definindo um valor padrão no parâmetro de gravidade. Isto permite-me forçar a severidade a ser sempre 1 a menos que seja sobreposta no tempo de execução, passando um valor para esse parâmetro.

function Write-Log {

param(

$Message,

$Severity = 1
)
"$Message - Severity: $Severity"
}

finalmente, podemos usar atributos de validação de parâmetros. Atributos de validação de parâmetros são uma ótima maneira de restringir quais valores são passados a um parâmetro. No exemplo abaixo, estou usando o atributo validaterange () de validação. Este atributo é usado em parâmetros do tipo inteiro para definir um intervalo de números permitidos. Neste exemplo, estou apenas a permitir que os valores de gravidade sejam 1-5. Qualquer outro valor que não esteja nesse intervalo falhará.

function Write-Log {

param(

$Message,


$Severity
)
"$Message - Severity: $Severity"
}

Wrap Up

por agora você deve ter uma compreensão básica de como as funções funcionam em PowerShell. Nós cobrimos tudo o que você precisa saber para começar a construir funções úteis em PowerShell. Eu encorajo você a começar a notar tempos em seus scripts onde uma função seria útil e começar a comprá-los. Você verá com o tempo que seu código se tornará mais limpo e muito mais fácil de ler.