Comment intégrer de l’aide à ses scripts PowerShell ?

I. Présentation

Lorsque l'on scripte avec PowerShell, il n'est pas rare de faire appel au commandlet "Get-Help" ou son alias "Help" pour obtenir l'aide sur l'utilisation d'un commandlet justement. Lorsque l'on envisage de diffuser un script, sur GitHub par exemple comme je peux le faire ces derniers temps, il est intéressant d'une part de le coder proprement, mais aussi d'inclure de l'aide au sein de son script.

Comment allez-vous me dire ? C'est ce que nous allons voir dans ce tutoriel et ça se trouve sans le savoir, vous produisez déjà cette aide.

L'ensemble de mes scripts publiés sur GitHub intègre une aide accessible directement depuis la console PowerShell, voici au passage l'accès à mes scripts : GitHub

II. Syntaxe de l'aide

En fait, il y a deux méthodes pour fournir de l'aide avec ses scripts, soit directement au sein du fichier .PS1 de votre script, soit au sein d'un fichier XML externe qui respecte la syntaxe MAML (Microsoft Assistance Markup Language). Pour ma part, à ce jour j'utilise seulement la méthode interne au script que nous allons voir dans ce script, pour la méthode XML, je vous oriente en premier lieu vers cet article : MSDN - Help XML

La méthode interne au script se base en fait sur vos commentaires, et principalement sur le bloc de commentaires que l'on intègre généralement au début du script. Pour rappel, en PowerShell un bloc de commentaires comment par "<#" et se termine par "#>".

À l'intérieur de ce bloc, on va indiquer différents mots clés prédéfinis et que Get-Help pourra interpréter. Parmi lesquels :

.SYNOPSIS
.DESCRIPTION
.PARAMETER <nom-du-parametre-numero-1>
.PARAMETER <nom-du-parametre-numero-2>
.EXAMPLE
.INPUTS
.OUTPUTS
.NOTES

Le point qui précède le mot clé est important dans la syntaxe de votre aide. Dans la structure c'est très simple, il suffit d'ajouter à la suite de chaque mot clé (ou sur les lignes en dessous) la description associée.

Pour le mot clé "PARAMETER" qui permet de déclarer les paramètres de votre script, on utilisera une itération du mot clé par paramètre, en précisant le nom du paramètre et son objectif. On utilisera le même principe pour les exemples.

Vous pouvez inclure de l'aide au sein de vos fonctions sur le même principe, à savoir de l'aide basée sur un bloc de commentaires. Ce bloc de commentaire pour l'aide peut-être inclus au début ou à la fin de la fonction.

Note : Si dans votre script, le bloc de commentaires correspondant à l'aide globale du script est suivi de la déclaration d'une fonction, l'aide sera associée à cette fonction. Ainsi pour que l'aide soit associée au script, il faut laisser deux lignes blanches entre la fin du bloc commentaire et la déclaration de la fonction.

III. Exemple

Si je prends exemple de l'une de mes créations, voici le bloc que j'ai inclus en guise d'aide :

<#
.SYNOPSIS
    This script geolocation one or several IP address by a web request on the website geoipview.com

.DESCRIPTION
    Specify a list of IP address that you want to geolocation, and the function return the city and the country (origin) of the IP.

.PARAMETER IPToCheck
    The list of IP address, it's a required parameter.

.EXAMPLE
    .\Get-IPLocation -IPToCheck "4.4.4.4","8.8.8.8"
    Get the location of two IP address : 4.4.4.4 and 8.8.8.8

.INPUTS

.OUTPUTS
    
.NOTES
    NAME:    Get-IPLocation.ps1
    AUTHOR:    Florian Burnel
    EMAIL:    [email protected]
    WWW:    www.it-connect.fr
    Twitter:@FlorianBurnel

    VERSION HISTORY:

    1.0     2017.01.17
            Initial Version

#>

Ensuite à partir d'une console PowerShell, si l'on exécute la commande "help .\Get-IPLocation.ps1" où "Get-IPLocation.ps1" est le nom de mon script, alors on obtient ceci en retour :

PS C:\Users\Florian\Documents\GitHub\PowerShell\NETWORK-Get-IPLocation> help .\Get-IPLocation.ps1

NOM
    C:\Users\Florian\Documents\GitHub\PowerShell\NETWORK-Get-IPLocation\Get-IPLocation.ps1

RÉSUMÉ
    This script geolocation one or several IP address by a web request on the website geoipview.com

SYNTAXE
    C:\Users\Florian\Documents\GitHub\PowerShell\NETWORK-Get-IPLocation\Get-IPLocation.ps1 [[-IPToCheck] <IPAddress[]>] [<CommonParameters>]

DESCRIPTION
    Specify a list of IP address that you want to geolocation, and the function return the city and the country (origin) of the IP.

LIENS CONNEXES

REMARQUES
    Pour consulter les exemples, tapez : "get-help C:\Users\Florian\Documents\GitHub\PowerShell\NETWORK-Get-IPLocation\Get-IPLocation.ps1 -examples".
    Pour plus d'informations, tapez : "get-help C:\Users\Florian\Documents\GitHub\PowerShell\NETWORK-Get-IPLocation\Get-IPLocation.ps1 -detailed".
    Pour obtenir des informations techniques, tapez : "get-help C:\Users\Florian\Documents\GitHub\PowerShell\NETWORK-Get-IPLocation\Get-IPLocation.ps1 -full".

Ce qui donne en image :

De la même manière, si l'on exécute "help .\Get-IPLocation.ps1 -Full" pour obtenir l'aide complète, on remarquera que l'aide est retournée entièrement c'est-à-dire avec la description des paramètres, de l'entrée, de la sortie ainsi que les notes. Ce qui n'était pas le cas avec l'aide basique qui retourne seulement ce que l'on peut appeler la présentation du script.

Vous pourrez obtenir plus d'informations sur les blocs d'aide via cette commande :

help about_comment_based_help

...Ou en consultant cette page : About_Comment_Based_Help

Enfin, je reviens pour finir sur l'aide externalisée avec un fichier XML, il existe un éditeur sympa publié sur CodePlex pour créer plus facilement une aide basée sur cette méthode, il s'agit de Cmdlet Help Editor.

J'espère que ce tutoriel vous permettra de progresser dans l'écriture de vos scripts et qu'il vous permettra d'intégrer une aide digne de ce nom associé à votre travail, ceci facilitera l'utilisation de votre code par une personne tierce.