Ajouter des contrôles sur les paramètres de fonction

I. Présentation

Lors de la création d'une fonction en PowerShell, nous avons l'opportunité d'ajouter un ensemble de paramètres pour cette fonction. Désormais, nous allons apprendre à ajouter des contrôles sur ces paramètres de fonction, ce qui permettra de vérifier les données envoyées en entrée de la fonction. Ceci permettra également de rendre un paramètre obligatoire ou non.

II. Rendre un paramètre obligatoire avec mandatory

Pour certaines de vos fonctions, vous aurez certainement besoin de rendre un ou plusieurs paramètres obligatoires. En effet, si vous attendez une valeur sur un paramètre et que l'utilisateur n'indique pas de valeur, ceci pourra "faire planter" la fonction et retourner un résultat inattendu.

Nous allons prendre pour exemple la fonction nommée "Get-Login". Cette option permet de retourner un identifiant sous la forme "<Première lettre du prenom>.<nom>" à partir d'un prénom et d'un nom envoyé à la fonction. Pour cela, nous avons deux paramètres : "$Nom" et "$Prenom". Cet identifiant doit être retourné en minuscule.

function Get-Login { 

    param($Nom,
          $Prenom)

    $Identifiant = (($Prenom).Substring(0,1)).ToLower() + "." + ($Nom).ToLower()

    return $Identifiant
}

$Login = Get-Login -Prenom "Florian" -Nom "Burnel"

Cette fonction PowerShell retourne bien le résultat attendu puisqu'avec le prénom "Florian" et le nom "Burnel", nous obtenons l'identifiant "f.burnel.

Le problème, c'est qu'actuellement, je peux appeler la fonction en omettant l'une des deux valeurs, ou les deux valeurs. Ceci va retourner une erreur.

Nous allons modifier la fonction pour rendre les deux paramètres obligatoires. Ainsi, la fonction refusera de s'exécuter s'il manque le prénom et/ou le nom. Nous devons ajouter l'instruction "[Parameter(Mandatory=$true)]" devant le nom de chaque paramètre à rendre obligatoire. Enfin, c'est surtout le positionnement du paramètre "Mandatory" sur "$true" qui le rend obligatoire.

Nous obtenons le code suivant :

function Get-Login { 

    param([Parameter(Mandatory=$true)]$Nom,
          [Parameter(Mandatory=$true)]$Prenom)

    $Identifiant = (($Prenom).Substring(0,1)).ToLower() + "." + ($Nom).ToLower()

    return $Identifiant
}

Désormais, si nous appelons la fonction sans préciser le prénom ou le nom, PowerShell restera en attente d'une valeur.

$Login = Get-Login -Prenom "Florian"

Voici un exemple où la fonction est appelée sans valeur pour le paramètre "-Nom" :

Si nous indiquons une valeur et que nous appuyons sur Entrée, la fonction sera exécutée. Cet exemple montre bien l'importance et l'utilité de pouvoir rendre obligatoire certains paramètres de fonction.

III. Contrôle sur les paramètres

En plus de jouer sur le caractère obligatoire ou non d'un paramètre, vous pouvez ajouter des contrôles sur les paramètres. Ceci est très pratique pour s'assurer que la valeur correspond à un format précis, que la valeur correspond à un ensemble de valeurs acceptées, que la valeur respecte une certaine longueur ou encore pour exécuter une commande de validation de cette valeur.

A. ValidatePattern

Pour commencer, nous allons peaufiner notre exemple précédent en ajoutant un contrôle sur les paramètres "$Nom" et "$Prenom" afin de nous assurer qu'ils ne contiennent que des lettres, en minuscules ou majuscules. Ceci évite qu'un chiffre ou un nombre soit indiqué dans le prénom et/ou le nom.

Nous devons ajouter le paramètre "ValidatePattern" qui permet de définir une expression régulière pour valider la valeur associée au paramètre en question. Ici, nous vérifions l'utilisation de lettres, exclusivement.

function Get-Login { 

    param([Parameter(Mandatory=$true)][ValidatePattern("^[a-z]+$")]$Nom,
          [Parameter(Mandatory=$true)][ValidatePattern("^[a-z]+$")]$Prenom)

    $Identifiant = (($Prenom).Substring(0,1)).ToLower() + "." + ($Nom).ToLower()

    return $Identifiant
}

Ainsi, si nous exécutons ceci :

$Login = Get-Login -Prenom "Florian1" -Nom "Burnel"

Nous obtenons une erreur, car la valeur "Florian1" ne respecte pas le modèle définit au sein de "ValidatePattern".

Get-Login : Impossible de valider l'argument sur le paramètre «Prenom». L'argument «Florian1» ne correspond pas au modèle «^[a-z]+$». Indiquez un argument qui correspond à «^[a-z]+$ et réessayez.

Nous pourrions également utiliser "ValidatePattern" pour vérifier que la valeur correspond à une adresse e-mail sur un nom de domaine spécifique. Par exemple, la ligne ci-dessous permet de s'assurer que l'adresse e-mail contient bien "@it-connect.fr". :

param([ValidatePattern("@it-connect.fr$")]$Email)

Il est à noter que PowerShell 7 prend en charge la possibilité de spécifier un message personnalisé à retourner à l'utilisateur lorsque la validation échoue. La syntaxe est la suivante :

[Parameter(Mandatory=$true)][ValidatePattern("^[a-z]+$",ErrorMessage="Valeur incorrecte")]$Nom

Dans l'exemple ci-dessus, si la valeur pour le paramètre Nom n'est pas acceptée, PowerShell retournera le texte "Valeur incorrecte".

B. ValidateSet

Le paramètre "ValidateSet" permet de définir un ensemble de valeurs acceptées. Il s'utilise de la façon suivante :

param([ValidateSet(1,2,3,10,20,30,100)]$Nombre)

Au sein des parenthèses, vous devez indiquer les valeurs autorisées. Si la valeur du paramètre "$Nombre" est différente, alors la fonction ne s'exécutera pas.

C. ValidateLength

Le paramètre "ValidateLength" permet de définir une longueur minimale et maximale pour un paramètre. Il s'utilise de cette façon :

param([ValidateSet(1,10)]$Chaine)

Dans l'exemple ci-dessus, la valeur du paramètre "$Chaine" doit être comprise entre 1 et 10 caractères, car le nombre de caractères correspond à sa longueur.

D. ValidateScript

Le paramètre "ValidateScript" permet d'exécuter un script de validation pour accepter ou non la valeur d'un paramètre. Il s'utilise de cette façon :

param([ValidateScript({Test-Path $_})]$Path)

Dans l'exemple ci-dessus, le paramètre "$Path" est destiné à avoir pour valeur le chemin vers un répertoire. Grâce au script présent dans "ValidateScript", nous allons exécuter la commande "Test-Path" pour tester l'existence de ce chemin : cette commande retournera un booléen (vrai ou faux). Si le chemin est valide, la valeur sera acceptée et la fonction pourra s'exécuter !

E. ValidateNotNullOrEmpty

Le paramètre "ValidateNotNullOrEmpty" permet d'indiquer que ce paramètre n'accepte pas une valeur non nulle ou vide. Il s'utilise de cette façon :

param([ValidateNotNullOrEmpty()]$Chaine)

Dans l'exemple ci-dessus, la valeur du paramètre "$Chaine" ne peut pas être vide ou nulle, sinon nous obtenons une erreur. Autrement dit, nous ne pouvons pas appeler le paramètre en indiquant :

Nom-Fonction -Chaine ""

IV. Conclusion

Grâce à ces nouvelles notions, vous êtes en mesure de mieux contrôler et configure vos paramètres de configuration en PowerShell. Dans la suite de ce cours, nous verrons qu'il est possible d'aller encore plus loin dans la configuration des paramètres !