Adam o Automator

ao criar funções do PowerShell, validar a entrada para parâmetros é importante. A validação de parâmetros permite limitar o que é passado para funções. Neste artigo, você aprenderá como detectar problemas antes que eles se tornem um com o atributo de validação do PowerShell ValidateScript.

usando a validação de Parâmetros, você não apenas garante que os problemas não surjam quando a função é executada, mas também promove um código mais limpo, pois a lógica de validação não é colocada no corpo da função.

existem vários atributos avançados de validação de parâmetros disponíveis no Powershell. Mas neste artigo, você aprenderá sobre uma das validações de parâmetros mais flexíveis, a validação do PowerShell ValidateScript.

você verá como funciona e também verá exemplos de como usá-lo.

Tabela de Conteúdo

Validação de Parâmetro (Uma Analogia)

Validação de Parâmetro

eu estava a almoçar e de repente eu me senti como tendo um refrigerante. Eu caminhei até a máquina de refrigerante, tirei uma nota de ₱100 do meu bolso e inseri-a no slot da conta. A máquina cospe imediatamente.

eu então notei que logo acima do slot diz que só aceita bills 20 e bills 50 contas. Acabei não tendo o refrigerante porque só tinha aquela conta de ₱100 comigo.

e como a história se relaciona com a validação de parâmetros do PowerShell? Vamos acabar com isso.

  • A maquina de refrigerante serve como a função
  • O projeto de lei é o parâmetro
  • O ₱50 e ₱20 projetos de lei são os valores de parâmetro válido
  • O ₱100 foi rejeitada porque ele é o errado valor do parâmetro
  • Como resultado, a máquina não processar o meu pedido, porque a entrada errada. Portanto, sem refrigerante para mim. ….e eu também estava com sede!

o cenário da máquina de refrigerante acima é apenas uma analogia para descrever o conceito de validação de parâmetros.

fluxo lógico de Validação de Parâmetros

o conceito de validação de parâmetros segue um fluxo de trabalho aproximado. A imagem abaixo mostra uma visão geral de como a validação de parâmetros funciona.

PowerShell Validação de parâmetros de Fluxo
  1. A função é executada em PowerShell chamando o seu nome e fornecendo os valores de parâmetro
  2. PowerShell avalia os valores fornecidos.
  3. se o resultado da validação for verdadeiro, o PowerShell permitirá que a função continue seu processo, antes de sair.
  4. se o resultado da validação for falso, o PowerShell exibirá um erro e a função será encerrada.

requisitos passo a passo

mais do que apenas falar sobre a validação do parâmetro da função PowerShell, o resto deste artigo terá exemplos que você pode copiar e experimentar por conta própria. Para acompanhar, você precisará de algumas coisas para acompanhar.

  • um computador Windows 10 com qualquer uma das versões do PowerShell abaixo:
  • Windows PowerShell 5.1
  • PowerShell Core 6.2
  • PowerShell Core 7 (a versão mais recente desta redação é a visualização 4)
  • um editor de script de sua escolha. Como, Notepad++, PowerShell ISE ou Visual Studio Code.

entendendo o atributo Validatescript Validation

ValidateScript é um dos atributos de validação de parâmetro disponíveis para uso no PowerShell introduzido no PowerShell 3.0. Ele pode ser adicionado dentro do bloco de definição de parâmetro de uma função, ou também pode ser usado diretamente no console do PowerShell.

ValidateScript é usado para validar o valor do parâmetro inserido. Se o resultado da validação for $true , o script continuará a ser executado. Por outro lado, se o resultado for $false, a função gerará um erro de terminação.Vamos mergulhar e ver como funciona.

usando ValidateScript em uma função

o uso mais comum do atributo ValidateScript é anexado a um parâmetro de função. Nesta seção, você criará uma função fictícia e aplicará a validação do parâmetro ValidateScript.

a função dummy executará as seguintes ações:

  1. aceite a entrada para o valor.
  2. valide se o valor inserido é igual aos valores aceitos.
  3. execute o processo se a validação for aprovada.
  4. exibir um erro se a validação falhou.

você aprenderá como construir esta função passo a passo na próxima seção. Abra seu editor de script e comece a codificar!

Construa a função

primeiro, crie uma função e dê um nome a ela. Este pode ser qualquer nome que você escolher. É uma prática recomendada seguir A Convenção de nomenclatura verbo-substantivo para tornar sua função descritiva. Para este exemplo, use o nome Get-Soda.

Function Get-Soda { param ()}

dentro do bloco param(), insira o nome do parâmetro que você usará, que é Bill.

Function Get-Soda { param ( $Bill )}

neste ponto, a função ainda não executa nada além de aceitar qualquer valor para o parâmetro Bill.

certifique-se de ter copiado a função Get-Soda para o Console do PowerShell. Depois que a função for importada para a sessão do PowerShell, teste a função executando o comando: Get-Soda -Bill 100.

quando você executa a função Get-Soda, você notará que nenhum erro é lançado e não faz nada. Isso é esperado neste momento.

adicionando validação de parâmetro

talvez você não queira permitir que todos os valores sejam passados para o parâmetro Bill. Usando a analogia explicada no topo deste artigo, a função não deve permitir ₱100 contas. Só deve permitir contas de ₱50 e 2 20.

adicione a validação do parâmetro ValidateScript inserindo antes do parâmetro Bill. Sua função deve se parecer com o código abaixo.

Function Get-Soda { param ( $Bill )}

dentro do bloco , insira o código de validação {$_ -eq 20}. Este código de validação verifica se o valor fornecido ao parâmetro bill é igual a 20. O trecho abaixo é como o código deve ser.

Nota: O $_ representa o valor do parâmetro atual no escopo. Neste exemplo, o valor de $_ é o valor do parâmetro Bill.

Function Get-Soda { param ( $Bill )}

Agora execute esta função novamente para confirmar que a validação do parâmetro está funcionando executando:

PS51> Get-Soda -Bill 20PS51> Get-Soda -Bill 30

abaixo você pode ver que quando 20 é passado como um valor, nada acontece, mas quando algo diferente de 20 é passado, ele gera um erro.

erro

quando a função Get-Soda não gera um erro, isso significa que a função foi executada com sucesso. Para demonstrar isso, adicione o seguinte código dentro da função para simplesmente retornar uma mensagem ao console.

Write-Host "$Bill is an accepted value. Please select your soda."

a função Get-Soda será semelhante a seguir:

agora passe um valor aceito como 20 para o parâmetro Bill. Você deve ver o resultado abaixo.

saída de Get – soda-bill 20

exibindo mensagens de erro mais significativas

tenho certeza de que você já percebeu que a mensagem de erro retornada quando o valor do parâmetro não passa na validação não é muito intuitiva e feia.

erro de validação não está claro

infelizmente, não há nada que você possa fazer sobre como o erro parece. Até que um recurso que habilite a formatação dos erros de validação seja lançado (espero), você está preso a ele.

mas, é possível melhorá-lo um pouco e dar mais significado aos erros que podem beneficiar seus usuários. Você verá o exemplo de como fazer isso a seguir.

adicionando erro de validação personalizada usando o Windows PowerShell (5.1)

expandindo a função Get-Soda, é possível lançar uma mensagem de erro específica quando o valor não atende à validação. Para fazer isso, você pode adicionar uma construção if/then dentro do bloco ValidateScript.

crie uma construção if/then simples como no exemplo abaixo. Neste exemplo, se o valor do parâmetro Bill não for igual a 20, ele retornará uma mensagem de erro de sua escolha (X is invalid. Valid value is 20 only.).

você pode ver um exemplo de como isso se parece abaixo:

a captura de tela abaixo mostra a mensagem de erro personalizada em ação. O erro ainda parece feio, mas desta vez a mensagem é clara e compreensível.

ValidateScript com uma mensagem de erro personalizada (PowerShell 5.1)

Adicionar Personalizado Erros de Validação Usando PowerShell Núcleo (6+)

Começando com o PowerShell Core 6, a capacidade de adicionar mensagens de erro personalizadas para ValidateScript validação de parâmetro já está incorporada. Vamos chamar isso de ErrorMessage technique.

no código de função modificado Get-Soda abaixo, o bloco agora inclui uma propriedade ErrorMessageque pode ser usada no lugar throw. Agora, em vez de usar a variável $_, você pode usar {0} que representará o valor do parâmetro passado.

a captura de tela abaixo mostra que a saída esperada é exatamente a mesma que com o uso da técnica if-else e throw.

ValidateScript com uma mensagem de erro personalizada (PowerShell Core 7 de pré-visualização 4)

PowerShell ValidateScript Exemplos de Uso

Estes são alguns do mundo real de casos de uso cenários para os quais o ValidateScript pode ser aplicado. Revise e teste esses exemplos e tente melhorar a mensagem de erro por conta própria usando as técnicas aprendidas na seção anterior.

validação do parâmetro de data

este trecho é uma função que aceita uma data de início e término. Ele realiza a validação de que as datas inseridas não estão no futuro e não têm mais de 90 dias.

teste a função usando esses comandos. Você pode especificar seus próprios valores startDate eendDate

esta saída de amostra abaixo é quando valores de data válidos são inseridos.

resultado de pesquisa-Log com valores de parâmetro de data válidos

agora teste novamente com startDate com mais de 90 dias. Em seguida, confirme se a mensagem de erro é exibida.

validação do parâmetro de Processo do Windows

este próximo trecho é uma função que aceita o nome de um processo. Ele confirma que o processo está sendo executado na memória e mata todas as instâncias em execução desse processo ou saída, dependendo do resultado da validação.

teste-o usando este comando: Kill-Process -Name <process name>

a saída de amostra abaixo assume que você está testando com o processo chamado bloco de notas.

  • o primeiro comando foi executado com sucesso porque descobriu que o processo do bloco de notas estava em execução e começou a matá-lo.
  • o segundo comando falhou, pois o bloco de notas não está mais em execução e a função terminou com a mensagem de erro personalizada que você criou.
erro de validação de Parâmetro

a Validação de Parâmetros por Outro Valor do Parâmetro

Agora você deve ter uma ideia do valor de uso ValidateScript em suas funções. Bu há uma limitação que vale a pena mencionar. O escopo do ValidateScript está apenas dentro do parâmetro em uso. Isso significa que um parâmetro não pode usar o valor de outros parâmetros.

como solução alternativa, a verificação de valor entre parâmetros pode ser feita acessando a variável automática $PSBoundParameters.

talvez você tenha uma função chamada Send-Spam. Esta função tem três parâmetros:

  1. From – endereço de E-mail do remetente. (exemplo. ). Não obrigatório.
  2. To – endereço de E-mail do destinatário. (exemplo. ). Não obrigatório.
  3. SendEmail – um parâmetro switch que não requer um valor. Mas se usado, os valores dos parâmetros From e To serão necessários.

se o switch SendEmail for usado, um código de validação será executado para confirmar que os parâmetros From e To são usados. Em seguida, ele retornará o valor de True. Por outro lado, se From e To não estiverem em uso, a função lançará um erro e sairá.Copie e cole o código abaixo em sua sessão do PowerShell.

o comando mostrado abaixo resultará em uma validação bem-sucedida. Porque os parâmetros From e To foram usados junto com o switch SendEmail.

PS51> Send-Spam -From -To -SendEmail
saída do Send-Spam

agora Teste-o sem usar o parâmetro From ou To. Isso deve resultar em um erro porque o script de validação falhará. Veja o resultado do exemplo abaixo.

Executando o Envio de Spam, sem o parâmetro Para

Usando ValidateScript no Console

Embora o uso mais comum da ValidateScript atributo é usado para validar os parâmetros de uma função, ele também pode ser utilizado diretamente a partir do console do PowerShell. ValidateScript é útil para testar seu código de validação mesmo antes de incorporá-lo dentro de um script ou uma função.

abaixo estão alguns exemplos de Uso do ValidateScript fora de uma função.

validando o valor inteiro

este exemplo abaixo valida que um determinado valor inteiro é maior que cinco.

$i=4

depois de executar o código acima, o resultado esperado falha porque o valor dado é 4, que é menor que 5. A captura de tela de exemplo abaixo é o que você esperaria ver.

falha de Validação de

a Validação de um Valor de Data

O seguinte código de exemplo abaixo mostra como validar que a data mais recente do que ou igual à data atual.

$date = (Get-Date)$date = (Get-Date).AddHours(-1)

depois de executar a primeira linha do código no trecho acima, o resultado esperado é passado (True), pois o valor de data e hora fornecido é o mesmo ou alguns segundos maior.

a segunda linha de código produzirá um resultado com falha porque o valor DateTime é uma hora menor que o tempo atual. Veja a imagem abaixo para a saída da amostra.

falha na validação do parâmetro de data

resumo

neste artigo, você aprendeu o que é validação de parâmetro e como usar o atributo validatescript parameter validation.

você também aprendeu a expandir sua capacidade de exibir uma mensagem de erro mais descritiva. Ao seguir os exemplos, você experimentou os resultados da validação bem-sucedida e com falha.

agora você deve entender a limitação do ValidateScript em termos de referência entre parâmetros e como você pode contornar essa limitação utilizando a variável automática $PSBoundParameters.

espero que você tenha aprendido o suficiente neste artigo que você pode aplicar em sua jornada de criação de ferramentas do PowerShell!

Leitura Adicional

  • PowerShell Functions introdução
  • compreender e construir módulos PowerShell
  • ValidateScript validation attribute
  • about Throw

Deixe uma resposta

O seu endereço de email não será publicado.