Ajout d’une syntaxe à une rubrique d’aide sur les applets de commande

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.

Avant de commencer à coder le code XML pour le diagramme de syntaxe dans le fichier d’aide de l’applet de commande, lisez cette section pour obtenir une image claire du type de données que vous devez fournir, telles que les attributs de paramètre et la façon dont ces données sont affichées dans le diagramme de syntaxe.

Attributs de paramètre

Obligatoire
- Si la valeur est true, le paramètre doit apparaître dans toutes les commandes qui utilisent le jeu de paramètres.
- Si la valeur est false, le paramètre est facultatif dans toutes les commandes qui utilisent le jeu de paramètres.
Position
- S’il est nommé, le nom du paramètre est requis.
- Si elle est positionnelle, le nom du paramètre est facultatif. Lorsqu’elle est omise, la valeur du paramètre doit être à la position spécifiée dans la commande. Par exemple, si la valeur est position="1 », la valeur du paramètre doit être la première ou seule valeur de paramètre non nommée dans la commande.
Entrée de pipeline
- Si la valeur est true (ByValue), vous pouvez diriger l’entrée vers le paramètre. L’entrée est associée au paramètre (« lié à ») même si le nom de la propriété et le type d’objet ne correspondent pas au type attendu. Les composants de liaison de paramètre PowerShell essaient de convertir l’entrée en type correct et d’échouer la commande uniquement lorsque le type ne peut pas être converti. Un seul paramètre d’un jeu de paramètres peut être associé par valeur.
- Si la valeur est true (ByPropertyName), vous pouvez diriger l’entrée vers le paramètre. Toutefois, l’entrée est associée au paramètre uniquement lorsque le nom du paramètre correspond au nom d’une propriété de l’objet d’entrée. Par exemple, si le nom du paramètre est Path, les objets dirigés vers l’applet de commande sont associés à ce paramètre uniquement lorsque l’objet a une propriété nommée path.
- Si la valeur est true (ByValue, ByPropertyName), vous pouvez diriger l’entrée vers le paramètre par nom de propriété ou par valeur. Un seul paramètre d’un jeu de paramètres peut être associé par valeur.
- Si la valeur est false, vous ne pouvez pas diriger l’entrée vers ce paramètre.
Globbing
- Si la valeur est true, le texte que l’utilisateur tape pour la valeur du paramètre peut inclure des caractères génériques.
- Si la valeur est false, le texte que l’utilisateur tape pour la valeur du paramètre ne peut pas inclure de caractères génériques.

Attributs de valeur de paramètre

Obligatoire
- Si la valeur est true, la valeur spécifiée doit être utilisée chaque fois que vous utilisez le paramètre dans une commande.
- Si la valeur est false, la valeur du paramètre est facultative. En règle générale, une valeur est facultative uniquement lorsqu’il s’agit de l’une des valeurs valides d’un paramètre, comme dans un type énuméré.

L’attribut Obligatoire d’une valeur de paramètre est différent de l’attribut Obligatoire d’un paramètre.

L’attribut requis d’un paramètre indique si le paramètre (et sa valeur) doit être inclus lors de l’appel de l’applet de commande. En revanche, l’attribut requis d’une valeur de paramètre est utilisé uniquement lorsque le paramètre est inclus dans la commande. Elle indique si cette valeur particulière doit être utilisée avec le paramètre.

En règle générale, les valeurs de paramètre qui sont des espaces réservés sont obligatoires et les valeurs de paramètre qui sont littérales ne sont pas requises, car elles sont l’une des valeurs qui peuvent être utilisées avec le paramètre.

Collecte des informations de syntaxe

Commencez par le nom de l’applet de commande.
```
SYNTAX
    Get-Tech
```
Répertoriez tous les paramètres de l’applet de commande. Tapez un trait d’union (-) avant chaque nom de paramètre. Séparez les paramètres en jeux de paramètres (certaines applets de commande peuvent avoir un seul jeu de paramètres). Dans cet exemple, l’applet de commande Get-Tech a deux jeux de paramètres.
```
SYNTAX
    Get-Tech -Name -Type
    Get-Tech -Id -List -Type
```
Démarrez chaque jeu de paramètres avec le nom de l’applet de commande.

Répertoriez d’abord le jeu de paramètres par défaut. Le paramètre par défaut est spécifié par la classe d’applet de commande.

Pour chaque jeu de paramètres, répertoriez d’abord son paramètre unique, sauf s’il existe des paramètres positionnels qui doivent apparaître en premier. Dans l’exemple précédent, les paramètres Name et Id sont des paramètres uniques pour les deux jeux de paramètres (chaque jeu de paramètres doit avoir un paramètre unique pour ce jeu de paramètres). Cela facilite l’identification par les utilisateurs du paramètre dont ils ont besoin pour le jeu de paramètres.

Répertoriez les paramètres dans l’ordre dans lequel ils doivent apparaître dans la commande. Si l’ordre n’a pas d’importance, répertoriez les paramètres associés ensemble ou listez les paramètres les plus fréquemment utilisés en premier.

Veillez à répertorier les paramètres WhatIf et Confirm si l’applet de commande prend en charge ShouldProcess.

Ne répertoriez pas les paramètres courants (tels que Verbose, Debug et ErrorAction) dans votre diagramme de syntaxe. L’applet de commande Get-Help ajoute ces informations quand elle affiche la rubrique d’aide.
Ajoutez les valeurs de paramètre. Dans PowerShell, les valeurs de paramètre sont représentées par leur type .NET. Toutefois, le nom du type peut être abrégé, par exemple « string » pour System.String.
```
SYNTAX
    Get-Tech -Name string -Type Basic Advanced
    Get-Tech -Id int -List -Type Basic Advanced
```
Les types abrégés tant que leur signification est claire, comme chaîne pour system.String et int pour System.Int32.

Répertoriez toutes les valeurs d’énumérations, telles que le paramètre -Type dans l’exemple précédent, qui peut être défini sur de base ou avancé.

Les paramètres de commutateur, tels que -List dans l’exemple précédent, n’ont pas de valeurs.
Ajoutez des crochets à des valeurs de paramètres qui sont des espaces réservés, par rapport aux valeurs de paramètre qui sont des littéraux.
```
SYNTAX
    Get-Tech -Name <string> -Type Basic Advanced
    Get-Tech -Id <int> -List -Type Basic Advanced
```

Placez les paramètres facultatifs et leurs vales entre crochets.

SYNTAX
    Get-Tech -Name <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]

Placez les noms de paramètres facultatifs (pour les paramètres positionnels) entre crochets. Le nom des paramètres qui sont positionnels, tels que le paramètre Name dans l’exemple suivant, n’a pas besoin d’être inclus dans la commande.
```
SYNTAX
    Get-Tech [-Name] <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]
```
Si une valeur de paramètre peut contenir plusieurs valeurs, telles qu’une liste de noms dans le paramètre Name, ajoutez une paire de crochets directement après la valeur du paramètre.
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type Basic Advanced]
    Get-Tech -Id <int[]> [-List] [-Type Basic Advanced]
```
Si l’utilisateur peut choisir parmi les paramètres ou les valeurs de paramètre, telles que le paramètre Type, placez les choix entre crochets courbés et séparez-les par le symbole OR exclusif (;)).
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```
Si la valeur du paramètre doit utiliser une mise en forme spécifique, telle que des guillemets ou des parenthèses, affichez le format dans la syntaxe.
```
SYNTAX
    Get-Tech [-Name] <"string[]"> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```

Codage du diagramme de syntaxe XML

Le nœud de syntaxe du code XML commence immédiatement après le nœud de description, qui se termine par la balise </maml:description>. Pour plus d’informations sur la collecte des données utilisées dans le diagramme de syntaxe, consultez collecte des informations de syntaxe.

Ajout d’un nœud de syntaxe

Le diagramme de syntaxe affiché dans la rubrique d’aide de l’applet de commande est généré à partir des données dans le nœud de syntaxe du code XML. Le nœud de syntaxe est placé entre deux balises <command:syntax>. Avec chaque jeu de paramètres de l’applet de commande placé entre une paire de balises <command:syntaxitem>. Il n’existe aucune limite au nombre de balises <command:syntaxitem> que vous pouvez ajouter.

L’exemple suivant montre un nœud de syntaxe qui a des nœuds d’élément de syntaxe pour deux jeux de paramètres.

<command:syntax>
  <command:syntaxItem>
    ...
    <!--Parameter Set 1 (default parameter set) parameters go here-->
    ...
  </command:syntaxItem>
  <command:syntaxItem>
    ...
    <!--Parameter Set 2 parameters go here-->
    ...
  </command:syntaxItem>
</command:syntax>

Ajout du nom de l’applet de commande aux données du jeu de paramètres

Chaque jeu de paramètres de l’applet de commande est spécifié dans un nœud d’élément de syntaxe. Chaque nœud d’élément de syntaxe commence par une paire de balises <maml:name> qui incluent le nom de l’applet de commande.

L’exemple suivant inclut un nœud de syntaxe qui a des nœuds d’élément de syntaxe pour deux jeux de paramètres.

<command:syntax>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
</command:syntax>

Ajout de paramètres

Chaque paramètre ajouté au nœud d’élément de syntaxe est spécifié dans une paire de balises <command:parameter>. Vous avez besoin d’une paire de balises <command:parameter> pour chaque paramètre inclus dans le jeu de paramètres, à l’exception des paramètres communs fournis par PowerShell.

Les attributs de la balise d’ouverture <command:parameter> déterminent la façon dont le paramètre apparaît dans le diagramme de syntaxe. Pour plus d’informations sur les attributs de paramètre, consultez Attributs de paramètre.

Remarque

La balise <command:parameter> prend en charge un élément enfant <maml:description> dont le contenu n’est jamais affiché. Les descriptions des paramètres sont spécifiées dans le nœud de paramètre du code XML. Pour éviter les incohérences entre les informations contenues dans l’élément de syntaxe et le nœud de paramètre, omettez le (<maml:description> ou laissez-le vide.

L’exemple suivant inclut un nœud d’élément de syntaxe pour un jeu de paramètres avec deux paramètres.

<command:syntaxItem>
  <maml:name>Cmdlet-Name</maml:name>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByValue)" position="1">
    <maml:name>ParameterName1</maml:name>
    <command:parameterValue required="true">
      string[]
    </command:parameterValue>
  </command:parameter>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByPropertyName)">
    <maml:name>ParameterName2</maml:name>
    <command:parameterValue required="true">
      int32[]
    </command:parameterValue>
  </command:parameter>
</command:syntaxItem>

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-03-25