mots clés d’aide Comment-Based

Cette rubrique répertorie et décrit les mots clés dans l’aide basée sur les commentaires.

Mots clés dans Comment-Based Aide

Voici des mots clés d’aide basés sur des commentaires valides. Ils sont répertoriés dans l’ordre dans lequel ils apparaissent généralement dans une rubrique d’aide ainsi que leur utilisation prévue. Ces mots clés peuvent apparaître dans n’importe quel ordre dans l’aide basée sur les commentaires, et ils ne respectent pas la casse.

Notez que le mot clé .EXTERNALHELP est prioritaire sur tous les autres mots clés d’aide basés sur des commentaires. Lorsque .EXTERNALHELP est présent, l’applet de commande Get-Help n’affiche pas d’aide basée sur les commentaires, même si elle ne trouve pas de fichier d’aide qui correspond à la valeur du mot clé.

.SYNOPSIS

Brève description de la fonction ou du script. Ce mot clé ne peut être utilisé qu’une seule fois dans chaque rubrique.

.DESCRIPTION

Description détaillée de la fonction ou du script. Ce mot clé ne peut être utilisé qu’une seule fois dans chaque rubrique.

.PARAMETER <Parameter-Name>

Description d’un paramètre. Vous pouvez inclure un mot clé .PARAMETER pour chaque paramètre dans la fonction ou le script.

Les mots clés .PARAMETER peuvent apparaître dans n’importe quel ordre dans le bloc de commentaires, mais l’ordre dans lequel les paramètres apparaissent dans l’instruction ou la déclaration de fonction param détermine l’ordre dans lequel les paramètres apparaissent dans la rubrique d’aide. Pour modifier l’ordre des paramètres dans la rubrique d’aide, modifiez l’ordre des paramètres dans l’instruction ou la déclaration de fonction param.

Vous pouvez également spécifier une description de paramètre en plaçant un commentaire dans l’instruction param immédiatement avant le nom de la variable de paramètre. Si vous utilisez à la fois un commentaire d’instruction param et un mot clé .PARAMETER, la description associée au mot clé .PARAMETER est utilisée et le commentaire de l’instruction param est ignoré.

.EXAMPLE

Exemple de commande qui utilise la fonction ou le script, éventuellement suivi d’un exemple de sortie et d’une description. Répétez ce mot clé pour chaque exemple.

.INPUTS

Types .NET d’objets pouvant être redirigés vers la fonction ou le script. Vous pouvez également inclure une description des objets d’entrée. Répétez ce mot clé pour chaque type d’entrée.

.OUTPUTS

Type .NET des objets retournés par l’applet de commande. Vous pouvez également inclure une description des objets retournés. Répétez ce mot clé pour chaque type de sortie.

.NOTES

Informations supplémentaires sur la fonction ou le script.

.LINK

Nom d’une rubrique associée. Répétez ce mot clé pour chaque rubrique associée. Ce contenu apparaît dans la section Liens connexes de la rubrique d’aide.

Le contenu du mot clé .LINK peut également inclure un URI (Uniform Resource Identifier) dans une version en ligne de la même rubrique d’aide. La version en ligne s’ouvre lorsque vous utilisez le paramètre Online de Get-Help. L’URI doit commencer par http ou https.

.COMPONENT

Nom de la technologie ou de la fonctionnalité utilisée par la fonction ou le script, ou auquel elle est associée. Le paramètre Component de Get-Help utilise cette valeur pour filtrer les résultats de recherche retournés par Get-Help.

.ROLE

Nom du rôle d’utilisateur pour la rubrique d’aide. Le paramètre Role de Get-Help utilise cette valeur pour filtrer les résultats de recherche retournés par Get-Help.

.FUNCTIONALITY

Mots clés qui décrivent l’utilisation prévue de la fonction. Le paramètre Functionality de Get-Help utilise cette valeur pour filtrer les résultats de recherche retournés par Get-Help.

.FORWARDHELPTARGETNAME <Command-Name>

Redirige vers la rubrique d’aide pour la commande spécifiée. Vous pouvez rediriger les utilisateurs vers n’importe quelle rubrique d’aide, y compris le contenu d’aide pour une fonction, un script, une applet de commande ou un fournisseur.

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

Spécifie la catégorie d'aide de l'élément dans .FORWARDHELPTARGETNAME. Les valeurs valides sont Alias, Cmdlet, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filterou All. Utilisez ce mot clé pour éviter les conflits lorsqu’il existe des commandes portant le même nom.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE <PSSession-variable>

Spécifie une session qui contient la rubrique d’aide. Entrez une variable qui contient un objet PSSession. Ce mot clé est utilisé par l’applet de commande [Export-PSSession][09] pour rechercher le contenu d’aide des commandes exportées.

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

Spécifie un fichier d’aide XML pour le script ou la fonction.

# .EXTERNALHELP <XML Help File>

Le mot clé .EXTERNALHELP est requis lorsqu’une fonction ou un script est documenté dans des fichiers XML. Sans ce mot clé, Get-Help ne peut pas trouver le fichier d'aide au format XML pour la fonction ou le script.

Le mot clé .EXTERNALHELP est prioritaire sur d’autres mots clés d’aide basés sur des commentaires. Si .EXTERNALHELP est présent, Get-Help n’affiche pas d’aide basée sur les commentaires, même si elle ne trouve pas de rubrique d’aide qui correspond à la valeur du mot clé .EXTERNALHELP.

Si la fonction est exportée par un module, définissez la valeur du mot clé .EXTERNALHELP sur un nom de fichier sans chemin d’accès. Get-Help recherche le nom de fichier spécifié dans un sous-répertoire spécifique à la langue du répertoire du module. Il n’existe aucune exigence pour le nom du fichier d’aide XML pour une fonction. À compter de PowerShell 5.0, les fonctions exportées par un module peuvent être documentées dans un fichier d’aide nommé pour le module. Vous n’avez pas besoin d’utiliser .EXTERNALHELP le mot clé de commentaire. Par exemple, si la Test-Function fonction est exportée par le MyModule module, vous pouvez nommer le fichier MyModule-help.xmld’aide. L’applet Get-Help de commande recherche de l’aide pour la Test-Function fonction dans le fichier dans le MyModule-help.xml répertoire du module.

Si la fonction n’est pas incluse dans un module, incluez un chemin d’accès au fichier d’aide XML. Si la valeur inclut un chemin d’accès et que le chemin contient des sous-répertoires spécifiques à la culture de l’interface utilisateur, Get-Help recherche les sous-répertoires de manière récursive pour un fichier XML portant le nom du script ou de la fonction conformément aux normes de secours linguistiques établies pour Windows, comme dans un répertoire de module.

Pour plus d'informations sur le format de fichier d'aide XML de la cmdlet, voir Comment écrire l'aide de la cmdlet.