Guide pratique pour ajouter des exemples à une rubrique d’aide d’applet de commande

Éléments à connaître sur les exemples de l’aide sur les applets de commande

• Répertorie tous les noms de paramètres dans la commande, même si les noms de paramètres sont facultatifs. Cela permet à l’utilisateur d’interpréter facilement la commande.

• Évitez les alias et les noms de paramètres partiels, même s’ils fonctionnent dans PowerShell.

• Dans l’exemple de description, expliquez le raisonnement pour la construction de la commande. Expliquez pourquoi vous avez choisi des paramètres et des valeurs particuliers et comment utiliser des variables.

• Si la commande utilise des expressions, expliquez-les en détail.

• Si la commande utilise des propriétés et des méthodes d’objets, en particulier les propriétés qui n’apparaissent pas dans l’affichage par défaut, utilisez l’exemple comme une opportunité pour indiquer à l’utilisateur l’objet.

Vues d’aide qui affichent des exemples

Les exemples apparaissent uniquement dans les vues détaillées et complètes de l’aide sur les applets de commande.

Ajout d’un nœud exemples

Le code XML suivant montre comment ajouter un nœud exemples qui contient un seul nœud exemple . Ajoutez des exemples de nœuds supplémentaires pour chaque exemple que vous souhaitez inclure dans la rubrique.

<command:examples>
  <command:example>
  </command:example>
</command:examples>

Ajout d’un titre d’exemple

Le code XML suivant montre comment ajouter un titre pour l’exemple. Le titre est utilisé pour définir l’exemple, à l’exception des autres exemples. PowerShell utilise un en-tête standard qui comprend un numéro d’exemple séquentiel.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
  </command:example>
</command:examples>

Ajout de caractères précédents

le code XML suivant montre comment ajouter des caractères, tels que l’invite Windows PowerShell, qui s’affichent immédiatement avant l’exemple de commande (sans espaces intermédiaires). PowerShell utilise l’invite de Windows PowerShell : C:\PS> .

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
</command:example>
</command:examples>

Ajout de la commande

Le code XML suivant montre comment ajouter la commande réelle de l’exemple. Lorsque vous ajoutez la commande, tapez le nom complet (n’utilisez pas d’alias) des applets de commande et des paramètres. En outre, utilisez des caractères minuscules dans la mesure du possible.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
</command:example>
</command:examples>

Ajout d’une description

Le code XML suivant montre comment ajouter une description pour l’exemple. PowerShell utilise un ensemble unique de <maml:para> balises pour la description, même si plusieurs <maml:para> balises peuvent être utilisées.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
    <dev:remarks>
      <maml:para> command description </maml:para>
    </dev:remarks>
</command:example>
</command:examples>

Ajout d’un exemple de sortie

Le code XML suivant montre comment ajouter la sortie de la commande. Les informations sur les résultats de la commande sont facultatives, mais dans certains cas, il est utile d’illustrer l’effet de l’utilisation de paramètres spécifiques. PowerShell utilise deux jeux de <maml:para> balises vides pour séparer la sortie de commande de la commande.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
    <dev:remarks>
      <maml:para> command description </maml:para>
      <maml:para></maml:para>
      <maml:para></maml:para>
      <maml:para> command output </maml:para>
</dev:remarks>
</command:example>
</command:examples>