Prise en charge de l’aide en ligne

Article
2025-03-25

Remarque

La création manuelle d’aide basée sur XML est très difficile. Le module PlatyPS vous permet d’écrire de l’aide dans Markdown, puis de le convertir en aide XML. Cela facilite beaucoup l’écriture et la maintenance de l’aide. platyPS pouvez également créer les packages d’aide pouvant être mis à jour pour vous. Pour plus d’informations, consultez Créer une aide xml à l’aide de PlatyPS.

À compter de PowerShell 3.0, il existe deux façons de prendre en charge la fonctionnalité Get-Help Online pour les commandes PowerShell. Cette rubrique explique comment implémenter cette fonctionnalité pour différents types de commandes.

À propos de l’aide en ligne

L’aide en ligne a toujours été une partie essentielle de PowerShell. Bien que l’applet de commande Get-Help affiche des rubriques d’aide à l’invite de commandes, de nombreux utilisateurs préfèrent l’expérience de lecture en ligne, y compris le codage de couleurs, les liens hypertexte et le partage d’idées dans le contenu communautaire et les documents wiki. Plus important encore, avant l’avènement de l’aide pouvant être mise à jour, l’aide en ligne a fourni la version la plus up-to-date des fichiers d’aide.

Avec l’avènement de l’aide pouvant être mise à jour dans PowerShell 3.0, l’aide en ligne joue toujours un rôle vital. En plus de l’expérience utilisateur flexible, l’aide en ligne fournit de l’aide aux utilisateurs qui ne peuvent pas ou ne peuvent pas utiliser l’aide pouvant être mise à jour pour télécharger des rubriques d’aide.

Fonctionnement de Get-Help -Online

Pour aider les utilisateurs à trouver les rubriques d’aide en ligne pour les commandes, la commande Get-Help a un paramètre En ligne qui ouvre la version en ligne de la rubrique d’aide pour une commande dans le navigateur Internet par défaut de l’utilisateur.

Par exemple, la commande suivante ouvre la rubrique d’aide en ligne pour l’applet de commande Invoke-Command.

Get-Help Invoke-Command -Online

Pour implémenter Get-Help -Online, l’applet de commande Get-Help recherche un URI (Uniform Resource Identifier) pour la rubrique d’aide de version en ligne dans les emplacements suivants.

Le premier lien dans la section Liens connexes de la rubrique d’aide pour la commande. La rubrique d’aide doit être installée sur l’ordinateur de l’utilisateur. Cette fonctionnalité a été introduite dans PowerShell 2.0.
Propriété HelpUri de n’importe quelle commande. La propriété HelpUri est accessible même lorsque la rubrique d’aide de la commande n’est pas installée sur l’ordinateur de l’utilisateur. Cette fonctionnalité a été introduite dans PowerShell 3.0.

Get-Help recherche un URI dans la première entrée de la section Liens connexes avant d’obtenir la valeur de propriété HelpUri. Si la valeur de propriété est incorrecte ou a changé, vous pouvez la remplacer en entrant une autre valeur dans le premier lien associé. Toutefois, le premier lien associé fonctionne uniquement lorsque les rubriques d’aide sont installées sur l’ordinateur de l’utilisateur.

Vous pouvez prendre en charge Get-Help -Online pour n’importe quelle commande en ajoutant un URI valide à la première entrée de la section Liens connexes de la rubrique d’aide basée sur XML pour la commande. Cette option est valide uniquement dans les rubriques d’aide XML et fonctionne uniquement lorsque la rubrique d’aide est installée sur l’ordinateur de l’utilisateur. Lorsque la rubrique d’aide est installée et que l’URI est rempli, cette valeur est prioritaire sur la propriété HelpUri de la commande.

Pour prendre en charge cette fonctionnalité, l’URI doit apparaître dans l’élément maml:uri sous le premier élément maml:relatedLinks/maml:navigationLink dans l’élément maml:relatedLinks.

Le code XML suivant montre le positionnement correct de l’URI. Le texte Online version: dans l’élément maml:linkText est une bonne pratique, mais il n’est pas obligatoire.

<maml:relatedLinks>
    <maml:navigationLink>
        <maml:linkText>Online version:</maml:linkText>
        <maml:uri>https://go.microsoft.com/fwlink/?LinkID=113279</maml:uri>
    </maml:navigationLink>
    <maml:navigationLink>
        <maml:linkText>about_History</maml:linkText>
        <maml:uri/>
    </maml:navigationLink>
</maml:relatedLinks>

Ajout de la propriété HelpUri à une commande

Cette section montre comment ajouter la propriété HelpUri aux commandes de différents types.

Ajout d’une propriété HelpUri à une applet de commande

Pour les applets de commande écrites en C#, ajoutez un attribut HelpUri à la classe Cmdlet. La valeur de l’attribut doit être un URI qui commence par http ou https.

Le code suivant montre l’attribut HelpUri de la classe d’applet de commande Get-History.

[Cmdlet(VerbsCommon.Get, "History", HelpUri = "https://go.microsoft.com/fwlink/?LinkID=001122")]

Ajout d’une propriété HelpUri à une fonction avancée

Pour les fonctions avancées, ajoutez une propriété HelpUri à l’attribut CmdletBinding. La valeur de la propriété doit être un URI qui commence par « http » ou « https ».

Le code suivant montre l’attribut HelpUri de la fonction New-Calendar

function New-Calendar {
    [CmdletBinding(SupportsShouldProcess=$true,
    HelpUri="https://go.microsoft.com/fwlink/?LinkID=01122")]

Ajout d’un attribut HelpUri à une commande cim

Pour les commandes CIM, ajoutez un attribut HelpUri à l’élément CmdletMetadata dans le fichier CDXML. La valeur de l’attribut doit être un URI qui commence par http ou https.

Le code suivant montre l’attribut HelpUri de la commande CIM Start-Debug

<CmdletMetadata Verb="Debug" HelpUri="https://go.microsoft.com/fwlink/?LinkID=001122"/>

Ajout d’un attribut HelpUri à un flux de travail

Pour les flux de travail écrits dans le langage PowerShell, ajoutez un mot clé de commentaire .EXTERNALHELP au code de flux de travail. La valeur du mot clé doit être un URI qui commence par http ou https.

Remarque

La propriété HelpUri n’est pas prise en charge pour les flux de travail XAML dans PowerShell.

Le code suivant montre le mot clé .EXTERNALHELP dans un fichier de flux de travail.

# .EXTERNALHELP "https://go.microsoft.com/fwlink/?LinkID=138338"

Partager via