Fonctions avancées

Introduction

La fonction est un élément incontournable de la programmation. Il est important de maîtriser cette notion pour arriver à produire un code clair et évolué. Et c’est d’autant plus vrai que les fonctions avancées sous PowerShell proposent une multitude d’outils pour simplifier cette tâche. Toutefois, l’apprentissage peut s’avérer un peu ardu. Il est donc nécessaire de relire ce chapitre à plusieurs reprises, ainsi que de tester et retester les exemples qui y sont proposés.

Les fonctions avancées sont présentes depuis la version 2.0 de PowerShell. Elles reproduisent un fonctionnement comparable aux applets de commandes (cmdlet) natives PowerShell.

Aujourd’hui, la majeure partie des modules créés par la communauté exportent des fonctions avancées pouvant être utilisées comme des cmdlets natives.

Les atouts dont dispose une fonction avancée comparée à une fonction "basique" sont nombreux :

Structure

Ce qui définit une fonction comme avancée est sa structure. En effet, des attributs sont à rajouter dans la structure pour que celle-ci devienne "avancée". On retrouve notamment l’attribut CmdletBinding().

Voici schématiquement ce que cela donne :

Function <Nom_de_la_fonction> { 
    [CmdletBinding()] 
    Param (<liste_des_paramètres>) 
    DynamicParam {...} 
    Begin {...} 
    Process {...} 
    End {...} 
} 

Il est également possible de rendre une fonction "avancée" en ajoutant l’attribut Parameter() sur l’un des paramètres, par exemple :

Function <Nom_de_la_fonction> { 
   Param 
     [parameter( mandatory = $true = 
   ) 
... 
} 

L’option mandatory rend un paramètre obligatoire ou optionnel. Une explication plus approfondie sera donnée plus loin dans le chapitre.

#Première Méthode : 
Function <Nom_de_la_fonction> (<bloc_de_paramètres>) { 
... 
} 
#Seconde Méthode : 
Function <Nom_de_la_fonction> { 
    Param ( 
         <Bloc_de_paramètres> 
    ) 
    ... 
} 

Param...

Mise en situation

Dans cette section, les mises en situation présentées regroupent des syntaxes plus globales à la fonction, qui font intervenir différents éléments présentés précédemment, notamment la mise en place de jeux de paramètres, ou encore l’acceptation d’entrée par le pipeline.

PS > get-help get-process  
 
NOM  
   Get-Process 
 
RÉSUMÉ 
   Gets the processes that are running on the local computer or 
a remote computer. 
 
 
SYNTAXE 
   Get-Process [[-Name] <String[]>] [-ComputerName <String[]>] 
[-FileVersionInfo] [-Module] [<CommonParameters>] 
 
   Get-Process [-ComputerName <String[]>] [-FileVersionInfo] -Id 
<Int32[]> [-Module] [<CommonParameters>] 
 
   Get-Process [-ComputerName <String[]>] [-FileVersionInfo] 
-InputObject <Process[]> [-Module] [<CommonParameters>] 
 
   Get-Process -Id <Int32[]> -IncludeUserName [<CommonParameters>] 
 
   Get-Process [[-Name] <String[]>] -IncludeUserName 
[<CommonParameters>] 
 
   Get-Process -IncludeUserName -InputObject <Process[]> 
[<CommonParameters>] 

Paramètre Dynamique

Il existe des cas d’usage où les options vues jusqu’ici ne répondent pas aux besoins. Prenons par exemple le cas d’un paramètre dont le contenu change en fonction de la valeur d’un autre paramètre, ou encore en fonction du provider (FileSystem, Registry, ActiveDirectory, etc.) dans lequel l’utilisateur se trouve.

C’est dans ces différentes situations que les paramètres dynamiques peuvent s’adapter et offrir des paramètres et/ou des valeurs changeantes en fonction du contexte.

Param() 
DynamicParam{ 
  ... 
} 

    $attributeCollection = New-Object ` System.Collections.
ObjectModel.Collection[System.Attribute] 

ArgumentCompleter et Dynamic ValidateSet

Les attributs ArgumentCompletions, ArgumentCompleter et Dynamic ValidateSet sont traités à part, car ils présentent quelques particularités. ArgumentCompletion a été ajouté avec la version 6.0 de PowerShell, et les deux autres ont une gestion dynamique de la validation ou de la complétion.

Param (  
   [Parameter(Mandatory=$true)]  
   [ArgumentCompletions('Info','Warning','Error')]  
   [String]$Type  
) 

Register-ArgumentCompleter

La commande Register-ArgumentCompleter enregistre un compléteur d’argument (argument completer) personnalisé. L’idée est de faire la même chose que l’attribut ArgumentCompleter vu dans la section précédente.

La différence est que l’attribut se positionne sur un paramètre d’une fonction que l’on a écrite. La commande Register-ArgumentCompleter a un périmètre d’intervention plus vaste. Il est possible de positionner des Argument Completer sur des commandes PowerShell natives, comme Get-Service ou encore Get-Process. Il est également possible d’interagir sur des binaires comme ping.exe ou bien nslookup.exe.

Dans cette section, on va se concentrer essentiellement sur l’intégration sur des commandes PowerShell et non des exécutables.

Register-ArgumentCompleter permet également d’outrepasser l’autocomplétion déjà en place sur un paramètre. Par exemple, la commande Start-Service dispose d’une autocomplétion sur le paramètre -Name de l’ensemble des services présents sur la machine, sans distinction de leur état d’exécution. Pour se simplifier la tâche, il est possible d’enregistrer un Argument Completer qui proposerait seulement les services en état arrêté...

Splatting

Le splatting est une fonctionnalité disponible depuis PowerShell V2.0, mais recommandée en utilisation avec PowerShell V3.0. De quoi s’agit-il exactement ? Le premier avantage direct est la minimisation de la saisie des paramètres lors de l’utilisation d’une commande. En effet, certaines commandes ont un nombre assez important de paramètres obligatoires et cela peut rapidement devenir illisible, malgré l’utilisation du caractère ` ([Alt Gr]+7).

Exemple avec la commande Send-MailMessage

Send-MailMessage -Body 'Hello' ` 
    -From nicolas@akalya.fr ` 
    -SmtpServer mail.akalya.fr ` 
    -Subject 'Envoie par PowerShell' ` 
    -To stephane.vangulick@frpsug.fr ` 
    -Port 465 ` 
    -UseSsl 

Dans un autre cas, il n’est pas rare de devoir réutiliser une commande plusieurs fois avec les mêmes paramètres. D’ordinaire, on définit les paramètres un à un. Le bon réflexe est de centraliser les valeurs dans des variables, puis de les assigner aux paramètres de chaque commande.

Exemple

$ForegrounColor = 'Yellow' 
 
Write-host 'Hello' -ForegroundColor $ForegrounColor 
 
Write-Host 'World' -ForegroundColor $ForegrounColor...