Partager via

Écriture d’aide pour les modules PowerShell

Les modules PowerShell peuvent inclure des rubriques d’aide sur le module et sur les membres du module, tels que les applets de commande, les fournisseurs, les fonctions et les scripts. L’applet Get-Help de commande affiche les rubriques d’aide du module au même format qu’elles affichent l’aide pour d’autres éléments PowerShell, et les utilisateurs utilisent des commandes standard Get-Help pour obtenir les rubriques d’aide.

Ce document explique le format et le positionnement correct des rubriques d’aide du module, et suggère des instructions pour le contenu de l’aide du module.

Types d’aide sur les modules

Un module peut inclure les types d’aide suivants.

  • Aide basée sur XML

    • Aide de l’applet de commande. Les rubriques d’aide qui décrivent les applets de commande dans un module sont des fichiers XML qui utilisent le schéma d’aide de commande
    • Aide du fournisseur. Les rubriques d’aide qui décrivent les fournisseurs dans un module sont des fichiers XML qui utilisent le schéma d’aide du fournisseur.
    • Aide de la fonction. Les rubriques d’aide qui décrivent les fonctions d’un module peuvent être des fichiers XML qui utilisent le schéma d’aide de commande ou les rubriques d’aide basées sur des commentaires dans la fonction, ou le script ou le module de script
    • Aide du script. Les rubriques d’aide qui décrivent des scripts dans un module peuvent être des fichiers XML qui utilisent le schéma d’aide de commande ou les rubriques d’aide basées sur des commentaires dans le script ou le module de script.
    • Le $PSHOME\Schemas\PSMaml dossier contient les fichiers de schéma qui définissent le format XML.

  • Fichiers texte d’aide (« À propos ») conceptuels

    Vous pouvez utiliser une rubrique d’aide conceptuelle (« à propos ») pour décrire le module et ses membres et expliquer comment les membres peuvent être utilisés ensemble pour effectuer des tâches. Par défaut, PowerShell inclut plus de 100 de ces rubriques d’aide conceptuelles. Le nom de fichier doit utiliser le about_<name>.help.txt format, tel que about_MyModule.help.txt.

    Note

    L’en-tête TOPIC de section doit commencer dans la première colonne de la première ligne du fichier. Le contenu de la section sur la deuxième ligne doit correspondre au nom de fichier, sans le .help.txt suffixe. Vous devez mettre en retrait le contenu exactement 4 espaces. La troisième ligne doit être vide. L’en-tête SYNOPSIS de section doit commencer dans la première colonne de la quatrième ligne. Vous devez mettre en retrait le contenu sur la cinquième ligne exactement 4 espaces. Ces exigences sont nécessaires pour que l’applet Get-Help de commande reconnaisse correctement le contenu.

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

    Vous pouvez utiliser l’exemple de modèle suivant comme point de départ pour écrire des rubriques d’aide conceptuelles. À l’exception des deux premières sections, la structure des rubriques d’aide conceptuelle est arbitraire. Les titres de section restants peuvent être appropriés pour votre contenu.

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

LONG DESCRIPTION

A detailed, full description of the subject or purpose of the module.

EXAMPLES

Examples of how to use the module or how the subject feature works in
practice.

TROUBLESHOOTING

Instructions for resolving common problems.

SEE ALSO

Text-only references for further reading. Hyperlinks can't work in the
PowerShell console.

    Vous pouvez utiliser n’importe quel style et balisage souhaité, mais PowerShell le voit en texte brut et il n’existe aucun rendu spécial du texte dans la console PowerShell. Les suggestions suivantes garantissent les meilleurs résultats d’affichage et la lisibilité.

    • Utilisez UTF-8 avec l’encodage BOM pour vous assurer que les caractères spéciaux (multioctets) s’affichent correctement.
    • Soulignez les en-têtes de section ou utilisez toutes les lettres majuscules pour les faire ressortir. Cela facilite l’analyse du contenu.
    • Limitez la longueur de chaque ligne à 80 caractères.
    • Retrait des blocs de code et exemple de sortie pour les séparer de la prose environnante.

Placement de l’aide du module

L’applet Get-Help de commande recherche les fichiers de rubrique d’aide du module dans les sous-répertoires spécifiques au langage du répertoire de module.

Par exemple, le diagramme de structure de répertoires suivant montre l’emplacement des rubriques d’aide pour le module SampleModule.

<ModulePath>
    \SampleModule
        \<en-US>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml
        \<fr-FR>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml

Note

Dans l’exemple, l’espace <ModulePath> réservé représente l’un des chemins d’accès dans la PSModulePath variable d’environnement, par $HOME\Documents\Modulesexemple, $PSHOME\Modulesou un chemin personnalisé spécifié par l’utilisateur.

Obtention de l’aide sur le module

Lorsqu’un utilisateur importe un module dans une session, les rubriques d’aide de ce module sont importées dans la session avec le module. Vous pouvez répertorier les fichiers de rubrique d’aide dans la valeur de la clé FileList dans le manifeste du module, mais les rubriques d’aide ne sont pas affectées par l’applet Export-ModuleMember de commande.

Vous pouvez fournir des rubriques d’aide de module dans différentes langues. L’applet Get-Help de commande affiche automatiquement les rubriques d’aide du module dans la langue spécifiée pour l’utilisateur actuel dans l’élément Options régionales et linguistiques du Panneau de configuration. Dans Windows Vista et les versions ultérieures de Windows, Get-Help recherche les rubriques d’aide dans les sous-répertoires propres à la langue du répertoire de module conformément aux normes de secours linguistiques établies pour Windows.

À compter de PowerShell 3.0, l’exécution d’une Get-Help commande pour une applet de commande ou d’une fonction déclenche l’importation automatique du module. L’applet Get-Help de commande affiche immédiatement le contenu des rubriques d’aide dans le module.

Si le module ne contient pas de rubriques d’aide et qu’il n’existe aucune rubrique d’aide pour les commandes du module sur l’ordinateur de l’utilisateur, Get-Help affiche l’aide générée automatiquement. L’aide générée automatiquement inclut la syntaxe de commande, les paramètres et les types d’entrée et de sortie, mais n’inclut aucune description. L’aide générée automatiquement inclut du texte qui dirige l’utilisateur à essayer d’utiliser l’applet Update-Help de commande pour télécharger de l’aide pour la commande à partir d’Internet ou d’un partage de fichiers. Il recommande également d’utiliser le paramètre Online de l’applet Get-Help de commande pour obtenir la version en ligne de la rubrique d’aide.

Prise en charge de l’aide pouvant être mise à jour

Les utilisateurs de PowerShell 3.0 et versions ultérieures de PowerShell peuvent télécharger et installer des fichiers d’aide mis à jour pour un module à partir d’Internet ou à partir d’un partage de fichiers local. Les Update-Help applets de commande et Save-Help masquent les détails de gestion de l’utilisateur. Les utilisateurs exécutent l’applet Update-Help de commande, puis utilisent l’applet Get-Help de commande pour lire les fichiers d’aide les plus récents pour le module à l’invite de commandes PowerShell. Les utilisateurs n’ont pas besoin de redémarrer Windows ou PowerShell.

Les utilisateurs derrière des pare-feu et ceux qui n’ont pas accès à Internet peuvent également utiliser l’aide pouvant être mise à jour. Les administrateurs disposant d’un accès Internet utilisent l’applet Save-Help de commande pour télécharger et installer les fichiers d’aide les plus récents sur un partage de fichiers. Ensuite, les utilisateurs utilisent le paramètre Path de l’applet Update-Help de commande pour obtenir les fichiers d’aide les plus récents à partir du partage de fichiers.

Les auteurs de modules peuvent inclure des fichiers d’aide dans le module et utiliser l’aide pouvant être mise à jour pour mettre à jour les fichiers d’aide, ou omettre les fichiers d’aide du module et utiliser l’aide updatable pour les installer et les mettre à jour.

Pour plus d’informations sur l’aide pouvant être mise à jour, consultez Prise en charge de l’aide pouvant être mise à jour.

Prise en charge de l’aide en ligne

Les utilisateurs qui ne peuvent pas ou ne peuvent pas installer les fichiers d’aide mis à jour sur leurs ordinateurs s’appuient souvent sur la version en ligne des rubriques d’aide du module. Le paramètre En ligne de l’applet Get-Help de commande ouvre la version en ligne d’une applet de commande ou d’une rubrique d’aide de fonction avancée pour l’utilisateur dans son navigateur Internet par défaut.

L’applet Get-Help de commande utilise la valeur de la propriété HelpUri de l’applet de commande ou de la fonction pour rechercher la version en ligne de la rubrique d’aide.

À compter de PowerShell 3.0, vous pouvez aider les utilisateurs à trouver la version en ligne de l’applet de commande et des rubriques d’aide de fonction en définissant l’attribut HelpUri sur la classe d’applet de commande ou la propriété HelpUri de l’attribut CmdletBinding . La valeur de l’attribut est la valeur de la propriété HelpUri de l’applet de commande ou de la fonction.

Pour plus d’informations, consultez Prise en charge de l’aide en ligne.

Voir aussi

  • Last updated on