Partager via

Windows PowerShell

  • Article

RLMP : Rédiger Le Manuel Parfait

Don Jones

« LLMP » est l'un des acronymes préférés dans l'industrie informatique. Il signifie « Lire le manuel parfait », et est souvent donné en réponse à une question qui aurait sans doute pu obtenir une réponse plus rapide et plus complète si celui qui l'a posée avait simplement lu les instructions. Lorsque vous utilisez Windows PowerShell et que vous commencez à créer des scripts et des fonctions pour d'autres utilisateurs, vous assurez-vous qu'ils disposent des instructions nécessaires pour les utiliser ? Autrement dit, rédigez-vous le manuel parfait (RLMP) ?

« Sans commentaire » n'est jamais la bonne réponse

Si vous disposez d'une expérience quelconque dans le domaine de la programmation informatique ou de la rédaction de scripts, vous connaissez le principe de l'insertion de commentaires de code inline pour aider à documenter la fonction d'une section de code particulière. Windows PowerShell fournit naturellement la prise en charge des commentaires : l'environnement ignore toute ligne commençant par #, ce qui vous permet de placer les commentaires de votre choix.

Malheureusement, pour lire ces commentaires vous devez ouvrir le script dans le Bloc-notes Windows ou dans un autre éditeur, et ce comportement est différent de ce que vous utiliseriez probablement pour une applet de commande d'environnement, qui est incorporée au système d'aide intégré de l'environnement. L'un des concepts fondamentaux de Windows PowerShell est que vous ne devriez avoir besoin d'apprendre qu'un seul ensemble de compétences et de comportements pour toute tâche donnée ; si vous avez déjà appris à utiliser la commande Get-Help pour obtenir des instructions pour une applet de commande native, pourquoi les choses devraient-elles fonctionner différemment pour un script ou une fonction ?

Dans la version 2 de l'environnement, il n'est pas nécessaire que les choses fonctionnent différemment. Windows PowerShell v2 introduit une nouvelle forme de documentation appelée aide basée sur les commentaires. Globalement, l'environnement sait qu'il doit rechercher les commentaires mis en forme de manière spéciale à l'intérieur d'un script ou d'une fonction, et il analyse ces commentaires afin de générer le même type d'affichage d'aide que celui dont vous disposeriez dans une applet de commande native. L'aide de l'applet de commande est en fait écrite au format XML ; l'aide basée sur les commentaires est non seulement plus facile à générer manuellement, mais de plus elle se déplace avec la fonction ou le script auquel elle est attachée, ce qui rend votre script ou fonction autonome et plus simple à distribuer.

Fixons-nous comme objectif de produire un script ou une fonction capable d'afficher son aide par le biais de la commande Get-Help intégrée, en la mettant en forme exactement comme une applet de commande native, comme illustré à la figure 1.

 

Figure 1 Aide mise en forme comme une applet de commande native dans Windows PowerShell.

Pour RLMP, LLMP

Windows PowerShell offre une aide intégrée complète pour l'aide basée sur les commentaires : Il vous suffit d'exécuter help about_comment_based_help. En gros, les règles de l'aide basée sur les commentaires sont simples :

  • Les commentaires doivent être la première chose dans le script (si l'aide s'applique à l'ensemble du script) ou la fonction (si l'aide est spécifique à une fonction).
  • Les commentaires doivent utiliser une mise en forme et des mots clés spécifiques afin que la fonctionnalité d'aide de l'environnement puisse les analyser correctement.

Vous pouvez utiliser des commentaires d'une seule ligne, en faisant précéder chaque ligne d'un caractère #, ou utiliser les nouveaux blocs de commentaires. Ils sont plus simples d'utilisation, car il n'est pas nécessaire de placer un # au début de chaque ligne. Commencez un bloc de commentaire en tapant <# seul sur une ligne et terminez-le en tapant #> seul sur une ligne. Tout ce qui figure entre ces deux lignes sera considéré comme faisant partie du commentaire.

Vos instructions d'aide seront construites sous la forme d'une série de blocs. Chaque bloc commence par un mot clé de section tel que .SYNOPSIS ou .DESCRIPTION. Le mot clé en question est précédé d'un point, et le point doit être le premier caractère sur la ligne, à l'exception des espaces ou du caractère #. Le fichier about_comment_based_help répertorie tous les mots clés possibles, mais les principaux sont les suivants :

  • .SYNOPSIS – brève explication de ce que fait le script ou la fonction.
  • .DESCRIPTION – explication plus détaillée de ce que fait le script ou la fonction.
  • .PARAMETER nom – explication concernant un paramètre spécifique. Remplacez nom par le nom du paramètre. Vous pouvez avoir l'une de ces sections pour chaque paramètre utilisé par le script ou la fonction.
  • .EXAMPLE – exemple d'utilisation du script ou de la fonction. Vous pouvez avoir plusieurs sections .EXAMPLE si vous souhaitez fournir plusieurs exemples.
  • .NOTES – éventuelles remarques concernant le script ou la fonction.
  • .LINK – référence croisée à une autre rubrique d'aide ; il peut y en avoir plusieurs. Si vous spécifiez une URL commençant par http:// ou https://, l'environnement ouvre cette URL lorsque le paramètre –online de la commande Help est utilisé.

Chaque mot clé figure seul sur une ligne et est suivi d'une ou plusieurs lignes de texte. Voici un exemple :

<#.SYNOPSISRetrieves service pack and operating system information from one or more remote computers..DESCRIPTIONThe Get-Inventory function uses Windows Management Instrumentation (WMI) toretrieve service pack version, operating system build number, and BIOS serial number from one or more remote computers. Computer names or IP addresses are expected as pipeline input, or may bepassed to the –computerName parameter. Each computer is contacted sequentially, not in parallel..PARAMETER computerNameAccepts a single computer name or an array of computer names. You mayalso provide IP addresses..PARAMETER pathThe path and file name of a text file. Any computers that cannot be reached will be logged to this file. This is an optional parameter; if it is notincluded, no log file will be generated..EXAMPLERead computer names from Active Directory and retrieve their inventory information.Get-ADComputer –filter * | Select{Name="computerName";Expression={$_.Name}} | Get-Inventory.EXAMPLERead computer names from a file (one name per line) and retrieve their inventory informationGet-Content c:\names.txt | Get-Inventory.NOTESYou need to run this function as a member of the Domain Admins group; doing so is the only way to ensure you have permission to query WMI from the remote computers.#>

La figure 2 illustre ce à quoi cela pourrait ressembler à l'intérieur d'une fonction réelle.

 

Figure 2 Helpinstructions dans une fonction.

La commande Help continue de suivre ses règles normales concernant les parties de l'aide à afficher. Par exemple, vous ne verrez que la section .EXAMPLE si vous utilisez le paramètre –example, tandis que vous verrez toutes les sections si vous utilisez le paramètre –full.  Dans tous les cas, vous constaterez (comme à la figure 3) que l'aide de cette fonction a une apparence identique à celle d'une applet de commande native.

 

Figure 3 Aide d'une fonction qui ressemble à celle d'une applet de commande native.

Méthodes conseillées pour l'aide basée sur les commentaires

En général, je préfère inclure au moins une section .SYNOPSIS et .DESCRIPTION dans chaque script ou fonction que j'écris. Si le script ou la fonction utilise un ou plusieurs paramètres, je les documente avec une section .PARAMETER. Ainsi, toute personne qui doit utiliser ultérieurement le script ou la fonction sera en mesure de déterminer facilement ce que fait ce script ou cette fonction. De toutes façons, six mois plus tard j'aurai probablement oublié ce que j'ai écrit, et c'est moi qui aurai besoin de quelques indices, fort heureusement fournis par l'aide basée sur les commentaires.

Plus votre code est structuré et réutilisable, plus votre aide doit être détaillée. Par exemple, j'ai structuré mon exemple de fonction Get-Inventory comme une « fonction avancée », ce qui signifie que son aspect et son comportement s'apparentent à ceux d'une applet de commande native. Il s'agit de la forme de vie la plus élevée dans le monde de l'environnement ; il faut donc que je fournisse le même niveau d'aide détaillée qu'une applet de commande « réelle », y compris documenter les exemples, remarques, références croisées, entrées et sorties, et ainsi de suite.

De plus en plus d'utilitaires tiers commencent à s'appuyer sur l'aide. Par exemple, les environnements d'écriture de scripts intégrés tiers analysent souvent l'aide afin de fournir des fonctionnalités de conseil et de remplissage de code semblables à IntelliSense dans leurs environnements d'édition ; en incluant une aide basée sur les commentaires complète et correctement mise en forme, vous simplifiez l'utilisation de vos scripts et fonctions depuis ces outils tiers.

Et puis c'est agréable d'avoir des scripts et des fonctions qui ressemblent le plus possible à de « vraies » applets de commande, notamment avec une sortie d'aide nette et fluide.

Contenu associé