Une fonction aux allures de cmdlet avec CmdletBinding()

I. Présentation

Le simple fait d'ajouter l'instruction "[CmdletBinding()]" à l'intérieur d'une fonction lui permet de bénéficier de capacités supplémentaires, comme celles que nous retrouvons avec les cmdlets officiels. Nous allons voir comment l'intégrer dans une fonction et quels sont les bénéfices attendus.

II. Ajouter CmdletBinding() dans une fonction

Nous allons prendre comme point de départ la fonction Get-Login utilisée dans les chapitres précédents. Pour rappel, voici le code de base de cette fonction :

function Get-Login { 

    param($Nom,
          $Prenom)

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

    return $Identifiant
}

Actuellement, cette fonction a deux paramètres comme le montre l'image ci-dessous :

Désormais, nous allons faire évoluer le code de la fonction pour ajouter l'instruction [CmdletBinding()], comme ceci :

function Get-Login { 

    [CmdletBinding()]
    param($Nom,
          $Prenom)

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

    return $Identifiant
}

Puis, si nous chargeons en mémoire la fonction et que nous regardons la liste de ses paramètres, nous pouvons constater un résultat bien différent :

Comme pour les cmdlets PowerShell, nous pouvons voir que notre fonction dispose de différents paramètres tels que ErrorAction, WarningAction, ErrorVariable, Verbose, etc..., ce qui peut s'avérer très utile pour la gestion des événements et des erreurs dans nos scripts.

III. Fonction avec Begin, Process, End

Sachez que si vous souhaitez envoyer des valeurs dans une fonction par l'intermédiaire du pipeline, vous devez ajouter l'instruction "ValueFromPipeline" au paramètre de votre choix, sur le même principe que "Mandatory" que nous avons étudié précédemment.

Voici comment configurer un paramètre de cette façon :

param([Parameter(ValueFromPipeline=$true)]$Nombre)

Pour que toutes les valeurs envoyées via le pipeline soient traitée, nous devons aussi réviser la syntaxe globale de la fonction pour intégrer trois blocs : Begin{}, Process{} et End{}.

Quelques explications s'imposent pour vous expliquer l'intérêt de cette modification :

• Begin{} sera exécuté une seule fois, lors du premier appel de la fonction, avant de traiter la première valeur
• Process{} sera exécuté pour chaque valeur envoyée à la fonction via le pipeline
• End{} sera exécuté une seule fois, après avoir traité la dernière valeur envoyée via le pipeline

Ceci peut s'avérer utile pour ouvrir une connexion avant de traiter un ensemble de valeurs, puis à la fin, nous pouvons fermer la connexion.

Voici un exemple permettant de générer une liste de nombres :

Function Get-Number {
    Param([Parameter(ValueFromPipeline=$true)]$Number)
    Begin
    {
        Write-Host "Début de la liste"
    } 
    Process
    {
        Write-Host ">> $Number"
    }
    End
    {
        Write-Host "Fin de la liste"
    }
}

Puis, nous allons appeler cette fonction de cette façon :

1..15 | Get-Number

Cela signifie que nous allons envoyer les nombres 1 à 15 à la fonction.

À l'exécution, nous obtenons le résultat suivant. Nous voyons que la fonction a exécuté une seule fois les blocs Begin{} et End{}. Par contre, chaque valeur envoyée via le pipeline a été traité indépendamment.

IV. Conclusion

Grâce à ce simple ajout, nous venons passer d'une fonction à une fonction avancée en PowerShell. L'instruction [CmdletBinding()] est très utilisée lors de l'écriture de module pour que les cmdlets puissent bénéficier de ces paramètres natifs de PowerShell. De plus, le fait d'utiliser une structure de fonction basée sur "Begin{}", "Process{}" et "End{}" ouvre de nouvelles possibilités !