Adam the Automator

Lors de la création de fonctions PowerShell, la validation des entrées de paramètres est importante. La validation des paramètres vous permet de limiter ce qui est passé aux fonctions. Dans cet article, vous allez apprendre à détecter les problèmes avant qu’ils ne ne fassent plus qu’un avec l’attribut de validation PowerShell ValidateScript.

En utilisant la validation des paramètres, vous vous assurez non seulement que les problèmes ne surviennent pas une fois la fonction exécutée, mais vous favorisez également un code plus propre car la logique de validation n’est pas placée dans le corps de la fonction.

Plusieurs attributs de validation de paramètres avancés sont disponibles dans Powershell. Mais dans cet article, vous découvrirez l’une des validations de paramètres les plus flexibles, la validation PowerShell ValidateScript.

Vous verrez comment cela fonctionne et verrez également des exemples de son utilisation.

Validation Des Paramètres (Une Analogie)

Je déjeunais et j’ai soudainement eu envie de prendre un soda. Je me suis dirigé vers la machine à soda, j’ai sorti un billet de 100 ₱ de ma poche et l’ai inséré dans la fente pour billets. La machine le crache immédiatement.

J’ai ensuite remarqué que juste au-dessus de la fente, il indique qu’il n’accepte que les billets de 20 et 50 bills. J’ai fini par ne pas avoir le soda parce que je n’avais que ce billet de 100 ₱ avec moi.

Et comment l’histoire se rapporte-t-elle à la validation des paramètres PowerShell? Décomposons-le.

• La machine à soda sert de fonction
• La facture est le paramètre
• Les factures de 50 ₱ et 20 bills sont les valeurs de paramètre valides
• Le 100 ₱ a été rejeté car il s’agit de la mauvaise valeur de paramètre
• Par conséquent, la machine n’a pas traité ma demande en raison de la mauvaise entrée. Donc, pas de soda pour moi. ….et j’avais soif aussi!

Le scénario de machine à soda ci-dessus n’est qu’une analogie pour décrire le concept de validation des paramètres.

Flux logique de validation des paramètres

Le concept de validation des paramètres suit un flux de travail approximatif. L’image ci-dessous montre un aperçu du fonctionnement de la validation des paramètres.

1. La fonction est exécutée dans PowerShell en appelant son nom et en fournissant les valeurs de paramètre
2. PowerShell évalue les valeurs fournies.
3. Si le résultat de la validation est vrai, PowerShell permettra à la fonction de poursuivre son processus, avant de quitter.
4. Si le résultat de la validation est faux, PowerShell affichera une erreur et la fonction se terminera.

Exigences de procédure pas à pas

Plus que de parler de la validation des paramètres de la fonction PowerShell, le reste de cet article contiendra des exemples que vous pourrez copier et essayer vous-même. Pour suivre, vous aurez besoin de quelques choses à suivre.

• Un ordinateur Windows 10 avec l’une des versions PowerShell ci-dessous:
• Windows PowerShell 5.1
• PowerShell Core 6.2
• PowerShell Core 7 (la dernière version de cette écriture est Preview 4)
• Un éditeur de script de votre choix. Comme, Notepad++, PowerShellSE ou code Visual Studio.

Comprendre l’attribut de validation ValidateScript

ValidateScript est l’un des attributs de validation de paramètres disponibles pour une utilisation dans PowerShell introduit dans PowerShell 3.0. Il peut être ajouté à l’intérieur du bloc de définition de paramètre d’une fonction, ou il peut également être utilisé directement dans la console PowerShell.

ValidateScript est utilisé pour valider la valeur du paramètre que vous avez entré. Si le résultat de validation est $true, le script continuera à s’exécuter. D’un autre côté, si le résultat est $false, la fonction lancera une erreur de fin.

Plongeons et voyons comment cela fonctionne.

Utilisation de ValidateScript dans une fonction

L’utilisation la plus courante de l’attribut ValidateScript est attachée à un paramètre de fonction. Dans cette section, vous allez créer une fonction factice et appliquer la validation des paramètres ValidateScript.

La fonction factice effectuera les actions suivantes:

1. Acceptez l’entrée pour le montant.
2. Validez si le montant saisi est égal aux valeurs acceptées.
3. Exécutez le processus si la validation est réussie.
4. Affiche une erreur si la validation a échoué.

Vous apprendrez à construire cette fonction étape par étape dans la section suivante. Lancez votre éditeur de script et commencez à coder!

Créez d’abord la fonction

, créez une fonction et donnez-lui un nom. Cela peut être n’importe quel nom que vous choisissez. Il est recommandé de suivre la convention de dénomination Verbe-Nom pour rendre votre fonction descriptive. Pour cet exemple, utilisez le nom Get-Soda.

Function Get-Soda { param ()}

Dans le bloc param(), insérez le nom du paramètre que vous utiliserez qui est Bill.

Function Get-Soda { param ( $Bill )}

À ce stade, la fonction n’effectue encore rien d’autre que d’accepter une valeur pour le paramètre Bill.

Assurez-vous d’avoir copié la fonction Get-Soda dans votre console PowerShell. Une fois la fonction importée dans la session PowerShell, testez la fonction en exécutant la commande : Get-Soda -Bill 100.

Lorsque vous exécutez la fonction Get-Soda, vous remarquerez qu’aucune erreur n’est générée et qu’elle ne fait rien. C’est prévu à ce stade.

Ajout de la validation des paramètres

Vous ne souhaitez peut-être pas autoriser toutes les valeurs à être transmises au paramètre Bill. En utilisant l’analogie expliquée en haut de cet article, la fonction ne devrait pas autoriser les billets de 100 ₱. Il ne devrait permettre que des billets de 50 et 20 bills.

Ajoutez la validation du paramètre ValidateScript en insérant avant le paramètre Bill. Votre fonction devrait ressembler au code ci-dessous.

Function Get-Soda { param ( $Bill )}

À l’intérieur du bloc , insérez le code de validation {$_ -eq 20}. Ce code de validation vérifie si la valeur fournie au paramètre bill est égale à 20. L’extrait ci-dessous explique à quoi devrait ressembler le code.

Remarque : Le $_ représente la valeur du paramètre courant dans la portée. Dans cet exemple, la valeur de $_ est la valeur du paramètre Bill.

Function Get-Soda { param ( $Bill )}

Exécutez à nouveau cette fonction pour confirmer que la validation des paramètres fonctionne en exécutant:

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

Ci-dessous, vous pouvez voir que lorsque 20 est passé en tant que valeur, rien ne se passe mais quand autre chose que 20 est passé, cela génère une erreur.

Lorsque la fonction Get-Soda ne génère pas d’erreur, cela signifie que la fonction est exécutée avec succès. Pour le démontrer, ajoutez le code suivant à l’intérieur de la fonction pour simplement renvoyer un message à la console.

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

La fonction Get-Soda ressemblera alors à la suivante:

Passez maintenant une valeur acceptée comme 20 au paramètre Bill. Vous devriez voir le résultat ci-dessous.

Afficher des messages d’erreur plus significatifs

Je suis sûr que vous avez déjà remarqué que le message d’erreur renvoyé lorsque la valeur du paramètre ne passe pas la validation n’est pas très intuitif et laid.

Malheureusement, vous ne pouvez rien faire sur l’apparence de l’erreur. Jusqu’à ce qu’une fonctionnalité qui active le formatage des erreurs de validation soit publiée (espérons-le), vous êtes coincé avec elle.

Mais, il est possible de l’améliorer un peu et de donner plus de sens aux erreurs qui peuvent bénéficier à vos utilisateurs. Vous verrez l’exemple de la façon de le faire ensuite.

Ajout d’une erreur de validation personnalisée à l’aide de Windows PowerShell (5.1)

En développant la fonction Get-Soda, il est possible de lancer un message d’erreur spécifique lorsque la valeur ne répond pas à la validation. Pour ce faire, vous pouvez ajouter une construction if /then à l’intérieur du bloc ValidateScript.

Créez une construction if /then simple comme dans l’exemple ci-dessous. Dans cet exemple, si la valeur du paramètre Bill n’est pas égale à 20, elle renverra un message d’erreur de votre choix (X is invalid. Valid value is 20 only.).

Vous pouvez voir un exemple de ce à quoi cela ressemble ci-dessous:

La capture d’écran ci-dessous montre le message d’erreur personnalisé en action. L’erreur semble toujours moche, mais cette fois, le message est clair et compréhensible.

Ajout d’Erreurs De Validation Personnalisées À l’aide De PowerShell Core (6+)

À partir de PowerShell Core 6, la possibilité d’ajouter des messages d’erreur personnalisés à la validation des paramètres ValidateScript est déjà intégrée. Appelons cela la technique du message erroné.

Dans le code de fonction Get-Soda modifié ci-dessous, le bloc inclut désormais une propriété ErrorMessage qui peut être utilisée en place throw. Maintenant, au lieu d’utiliser la variable $_, vous pouvez utiliser {0} qui représentera la valeur du paramètre passée.

La capture d’écran ci-dessous montre que la sortie attendue est exactement la même qu’avec l’utilisation de la technique if-else et throw.

Exemples d’utilisation de PowerShell ValidateScript

Voici quelques scénarios d’utilisation réels pour lesquels ValidateScript peut être appliqué. Examinez et testez ces exemples, puis essayez d’améliorer vous-même le message d’erreur en utilisant les techniques que vous avez apprises dans la section précédente.

Validation des paramètres de date

Cet extrait de code est une fonction qui accepte une date de début et une date de fin. Il effectue la validation que les dates saisies ne sont pas dans le futur et ne dépassent pas 90 jours.

Testez la fonction en utilisant ces commandes. Vous pouvez spécifier vos propres valeurs startDate et endDate

Cet exemple de sortie ci-dessous correspond à la saisie de valeurs de date valides.

Maintenant, testez-le à nouveau avec startDate qui a plus de 90 jours. Confirmez ensuite que le message d’erreur s’affiche.

Validation des paramètres de processus Windows

Cet extrait suivant est une fonction qui accepte le nom d’un processus. Il confirme que le processus s’exécute en mémoire, puis tue toutes les instances en cours d’exécution de ce processus ou se termine en fonction du résultat de la validation.

Testez-le à l’aide de cette commande: Kill-Process -Name <process name>

L’exemple de sortie ci-dessous suppose que vous testez avec le processus nommé bloc-notes.

• La première commande s’est exécutée avec succès car elle a constaté que le processus du bloc-notes était en cours d’exécution et a procédé à son élimination.
• La deuxième commande a échoué car le bloc-notes n’est plus en cours d’exécution et la fonction s’est terminée par le message d’erreur personnalisé que vous avez créé.

Validation des paramètres par une autre valeur de paramètre

Maintenant, vous devriez avoir une idée de la valeur de l’utilisation de ValidateScript dans vos fonctions. Bu il y a une limitation qui mérite d’être mentionnée. La portée de ValidateScript se trouve uniquement dans le paramètre utilisé. Cela signifie qu’un paramètre ne peut pas utiliser la valeur des autres paramètres.

Comme solution de contournement, la vérification de la valeur des paramètres croisés peut être effectuée en accédant à la variable automatique $PSBoundParameters.

Peut-être avez-vous une fonction appelée Send-Spam. Cette fonction a trois paramètres:

1. From – L’adresse e-mail de l’expéditeur. (par exemple. ). Non obligatoire.
2. To – L’adresse e-mail du destinataire. (par exemple. ). Non obligatoire.
3. SendEmail – Un paramètre de commutateur qui ne nécessite pas de valeur. Mais si elles sont utilisées, les valeurs des paramètres From et To seront requises.

Si le commutateur SendEmail est utilisé, un code de validation s’exécutera pour confirmer que les paramètres From et To sont utilisés. Ensuite, il retournera la valeur True. D’autre part, si From et To ne sont pas utilisés, la fonction lancera une erreur et se terminera.

Copiez et collez le code ci-dessous dans votre session PowerShell.

La commande affichée ci-dessous entraînera une validation réussie. Parce que les paramètres From et To ont été utilisés avec le commutateur SendEmail.

PS51> Send-Spam -From -To -SendEmail

Testez-le maintenant sans utiliser le paramètre From ou le paramètre To. Cela devrait entraîner une erreur car le script de validation échouera. Voir l’exemple de résultat ci-dessous.

Utilisation de ValidateScript dans la Console

Bien que l’utilisation la plus courante de l’attribut ValidateScript soit utilisée pour valider les paramètres de fonction, il peut également être utilisé directement depuis la console PowerShell. ValidateScript est utile pour tester votre code de validation avant même de l’intégrer dans un script ou une fonction.

Voici quelques exemples d’utilisation de ValidateScript en dehors d’une fonction.

Validation de la valeur entière

Cet exemple ci-dessous valide qu’une valeur entière donnée est supérieure à cinq.

$i=4

Après avoir exécuté le code ci-dessus, le résultat attendu échoue car la valeur donnée est 4, ce qui est inférieur à 5. L’exemple de capture d’écran ci-dessous est ce que vous vous attendez à voir.

Validation d’une valeur de date

L’exemple de code suivant ci-dessous montre comment valider que la date donnée est supérieure ou égale à la date actuelle.

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

Après avoir exécuté la première ligne du code dans l’extrait de code ci-dessus, le résultat attendu est passé (True) car la valeur DateTime fournie est la même ou quelques secondes plus grande.

La deuxième ligne de code produira un résultat échoué car la valeur DateTime est inférieure d’une heure à l’heure actuelle. Voir la capture d’écran ci-dessous pour l’exemple de sortie.

Résumé

Dans cet article, vous avez appris ce qu’est la validation des paramètres et comment utiliser l’attribut de validation des paramètres ValidateScript.

Vous avez également appris à étendre sa capacité à afficher un message d’erreur plus descriptif. En suivant les exemples, vous avez constaté les résultats de la validation réussie et de l’échec.

Vous devez maintenant comprendre la limitation de ValidateScript en termes de référencement entre paramètres, et comment vous pouvez contourner cette limitation en utilisant la variable automatique $PSBoundParameters.

J’espère que vous avez suffisamment appris dans cet article pour pouvoir l’appliquer dans votre parcours de fabrication d’outils PowerShell!

Lecture supplémentaire

• Introduction des fonctions Powershell
• Comprendre et construire des modules PowerShell
• Attribut de validation ValidateScript
• À propos de Throw