Comment écrire une aide basée sur des commentaires pour des scripts PowerShell

1. Aide Basée sur des Commentaires dans PowerShell
2. Mots-Clés Basés sur des Commentaires dans PowerShell

Cet article démontre comment nous pouvons écrire des sujets d’aide basés sur des commentaires pour des scripts et des fonctions. Nous utiliserons des mots-clés spéciaux d’aide par commentaire pour créer les sujets.

Nous utilisons la cmdlet Get-Help pour afficher des sujets d’aide basés sur des commentaires similaires à ceux générés par des fichiers XML.

Aide Basée sur des Commentaires dans PowerShell

Ci-dessous est illustrée la syntaxe pour l’aide basée sur des commentaires.

# .<help keyword>
# <help content>

ou

<#
.<help keyword>
<help content>
#>

Nous écrivons des sujets d’aide basés sur des commentaires sous forme d’une série de commentaires. Pour marquer les commentaires, nous pouvons soit ajouter le symbole # au début de chaque ligne de commentaire, soit utiliser <# et #> pour créer un bloc de commentaire.

La console considérera les lignes à l’intérieur du bloc de commentaire comme des commentaires.

Nous utilisons des mots-clés spéciaux pour définir chaque section d’un sujet d’aide basé sur des commentaires. Les mots-clés commencent par un . et ne font pas de distinction entre majuscules et minuscules.

Voici un exemple :

<#
.Description
Get-Clipboard fetches the content of our clipboard in the session.
#>

Dans l’exemple ci-dessus, le mot-clé .Description marque le commentaire comme étant la description de notre fonction.

Un bloc de commentaire doit avoir au moins un mot-clé. Certains mots-clés n’apparaissent qu’une seule fois, tandis que d’autres n’ont pas de limite.

Le contenu d’un mot-clé doit commencer à la ligne immédiatement après le mot-clé et n’a pas de limite.

Lors de l’ajout d’une aide basée sur des commentaires pour des fonctions, vous pouvez les ajouter dans l’un des trois emplacements discutés ci-dessous.

1. Au début du corps de la fonction.
2. À la fin du corps de la fonction.
3. Avant le mot-clé function. Séparé par pas plus d’une ligne vide.

Exemples :

function Get-Function
{
<#
.<help keyword>
<content>
#>

  # function logic
}

ou

function Get-Function
{
   # function logic

<#
.<help keyword>
<content>
#>
}

ou

<#
.<help keyword>
<content>
#>
function Get-Function { }

L’aide basée sur des commentaires pour les scripts peut apparaître soit au début du script, soit à la fin. Voici quelques exemples :

<#
.<help keyword>
<content>
#>

function Get-Function { }

ou

function Get-Function { }

<#
.<help keyword>
<content>
#>

Mots-Clés Basés sur des Commentaires dans PowerShell

Ci-dessous sont listés les mots-clés d’aide basés sur des commentaires valides. Ils peuvent apparaître dans n’importe quel ordre et ne font pas de distinction entre majuscules et minuscules.

.SYNOPSIS

Ceci est une courte description de la fonction ou du script. Le mot-clé ne devrait apparaître qu’une seule fois dans chaque sujet.

.DESCRIPTION

Ceci est une description détaillée d’une fonction ou d’un script. Nous l’utilisons une seule fois dans chaque sujet.

.PARAMETER

Ceci décrit les paramètres dans votre script ou fonction. Nous ajoutons un mot-clé .PARAMETER pour chaque paramètre dans nos scripts ou fonctions.

.PARAMETER <Parameter-Name>

Les mots-clés de paramètres ne suivent pas un ordre strict dans le bloc de commentaire. La syntaxe des paramètres dans le script ou la fonction déterminera l’ordre dans le sujet d’aide.

Vous pouvez changer l’ordre en modifiant la syntaxe.

Nous pouvons spécifier le contenu du mot-clé de paramètre en ajoutant un commentaire dans notre fonction ou script. Ce commentaire doit précéder le nom de la variable de paramètre.

PowerShell priorise la description associée au mot-clé de paramètre par rapport au commentaire de syntaxe où les deux sont utilisés.

<#
.SYNOPSIS
    Brief description
#>
function Noun-Verb {
    [CmdletBinding()]
    param (
        # It is the same as .Parameter
        [string]$CompName
    )
    # Logic
}

.EXAMPLE

Incluez une commande d’exemple qui utilise le script ou la fonction. Nous pouvons inclure ce mot-clé pour tous les exemples dans notre script ou fonction.

.INPUTS

Ce sont les objets .NET que nous pouvons transmettre à notre script ou fonction. Nous pouvons ajouter une description pour les objets d’entrée.

.OUTPUTS

Ce sont les objets .NET que notre cmdlet retourne. Nous pouvons ajouter une description pour les objets retournés.

.NOTES

Ce sont toutes les informations supplémentaires concernant le script ou la fonction. Les informations peuvent inclure la date à laquelle il a été codé, le nom de la fonction ou le nom du créateur.

.LINK

Ce sont les sujets connexes.

Voici un exemple d’aide basée sur des commentaires pour une fonction :

En conclusion, nous pouvons ajouter une aide basée sur des commentaires dans des fonctions ou des scripts en les plaçant dans un bloc de commentaire. Lors de l’ajout de sujets d’aide, utilisez le mot-clé dont nous avons discuté ci-dessus et rappelez-vous où placer les blocs de commentaires pour les scripts et les fonctions.