Share via

about_Comment_Based_Help

  • Article

Description courte

Décrit comment écrire des rubriques d’aide basées sur des commentaires pour les fonctions et les scripts.

Description longue

Vous pouvez écrire des rubriques d’aide basées sur des commentaires pour les fonctions et les scripts à l’aide de mots clés de commentaire d’aide spéciaux.

L’applet de commande Get-Help affiche l’aide basée sur les commentaires dans le même format qu’elle affiche les rubriques d’aide d’applet de commande générées à partir de fichiers XML. Les utilisateurs peuvent utiliser tous les paramètres de Get-Help, tels que Détaillé, Complet, Exemples et En ligne, pour afficher le contenu de l’aide basée sur les commentaires.

Vous pouvez également écrire des fichiers d’aide XML pour des fonctions et des scripts. Pour permettre à l’applet Get-Help de commande de rechercher le fichier d’aide XML d’une fonction ou d’un script, utilisez le .ExternalHelp mot clé. Sans cette mot clé, Get-Help impossible de trouver des rubriques d’aide XML pour les fonctions ou les scripts.

Cette rubrique explique comment écrire des rubriques d’aide pour les fonctions et les scripts. Pour plus d’informations sur l’affichage des rubriques d’aide pour les fonctions et les scripts, consultez Obtenir de l’aide.

Les applets de commande Update-Help et Save-Help fonctionnent uniquement sur les fichiers XML. L’aide pouvant être mise à jour ne prend pas en charge les rubriques d’aide basées sur les commentaires.

Syntaxe de l’aide basée sur les commentaires

La syntaxe de l’aide basée sur les commentaires est la suivante :

# .<help keyword>
# <help content>

ou

<#
.<help keyword>
<help content>
#>

L’aide basée sur les commentaires est écrite sous la forme d’une série de commentaires. Vous pouvez taper un symbole # de commentaire avant chaque ligne de commentaires, ou vous pouvez utiliser les <# symboles et #> pour créer un bloc de commentaires. Toutes les lignes du bloc de commentaires sont interprétées comme des commentaires.

Toutes les lignes d’une rubrique d’aide basée sur des commentaires doivent être contiguës. Si une rubrique d’aide basée sur des commentaires suit un commentaire qui ne fait pas partie de la rubrique d’aide, il doit y avoir au moins une ligne vide entre la dernière ligne de commentaire sans aide et le début de l’aide basée sur les commentaires.

Les mots clés définissent chaque section de l’aide basée sur les commentaires. Chaque mot clé d’aide basée sur les commentaires est précédé d’un point .. Les mots clés peuvent apparaître dans n’importe quel ordre. Les noms mot clé ne respectent pas la casse.

Par exemple, le .Description mot clé précède une description d’une fonction ou d’un script.

<#
.Description
Get-Function displays the name and syntax of all functions in the session.
#>

Le bloc de commentaires doit contenir au moins un mot clé. Certains mots clés, tels que .EXAMPLE, peuvent apparaître plusieurs fois dans le même bloc de commentaires. Le contenu d’aide de chaque mot clé commence sur la ligne après le mot clé et peut s’étendre sur plusieurs lignes.

Syntaxe de l’aide basée sur les commentaires dans les fonctions

L’aide basée sur les commentaires pour une fonction peut apparaître dans l’un des trois emplacements suivants :

  • Au début du corps de la fonction.
  • À la fin du corps de la fonction.
  • Avant le function mot clé. Il ne peut pas y avoir plus d’une ligne vide entre la dernière ligne de l’aide de la fonction et la function mot clé.

Par exemple :

function Get-Function
{
<#
.<help keyword>
<help content>
#>

  # function logic
}

or

function Get-Function
{
   # function logic

<#
.<help keyword>
<help content>
#>
}

or

<#
.<help keyword>
<help content>
#>
function Get-Function { }

Syntaxe de l’aide basée sur les commentaires dans les scripts

L’aide basée sur les commentaires d’un script peut apparaître dans l’un des deux emplacements suivants du script.

  • Au début du fichier de script. L’aide sur le script ne peut être précédée dans le script que de commentaires et de lignes vides.

    Si le premier élément du corps du script (après l’aide) est une déclaration de fonction, il doit y avoir au moins deux lignes vides entre la fin de l’aide du script et la déclaration de fonction. Sinon, l’aide est interprétée comme une aide pour la fonction, et non comme une aide pour le script.

  • À la fin du fichier de script. Toutefois, si le script est signé, placez l’aide basée sur les commentaires au début du fichier de script. La fin du script est occupée par le bloc de signature.

Par exemple :

<#
.<help keyword>
<help content>
#>


function Get-Function { }

ou

function Get-Function { }

<#
.<help keyword>
<help content>
#>

Syntaxe de l’aide basée sur les commentaires dans les modules de script

Dans un module .psm1de script , l’aide basée sur les commentaires utilise la syntaxe pour les fonctions, et non la syntaxe des scripts. Vous ne pouvez pas utiliser la syntaxe de script pour fournir de l’aide pour toutes les fonctions définies dans un module de script.

Par exemple, si vous utilisez le .ExternalHelp mot clé pour identifier les fichiers d’aide XML pour les fonctions dans un module de script, vous devez ajouter un .ExternalHelp commentaire à chaque fonction.

# .ExternalHelp <XML-file-name>
function <function-name>
{
  ...
}

Mots clés d’aide basés sur les commentaires

Voici des mots clés d’aide valides basés sur des commentaires. Ils sont répertoriés dans l’ordre dans lequel ils apparaissent généralement dans une rubrique d’aide avec 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.

.SYNOPSIS

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

.DESCRIPTION

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

.PARAMETER

Description d’un paramètre. Ajoutez une .PARAMETER mot clé pour chaque paramètre dans la syntaxe de la fonction ou du script.

Tapez le nom du paramètre sur la même ligne que le .PARAMETER mot clé. Tapez la description du paramètre sur les lignes qui suivent la .PARAMETER mot clé. Windows PowerShell interprète tout le texte entre la .PARAMETER ligne et la mot clé suivante ou la fin du bloc de commentaires dans le cadre de la description du paramètre. La description peut inclure des sauts de paragraphe.

.PARAMETER  <Parameter-Name>

Les mots clés Parameter peuvent apparaître dans n’importe quel ordre dans le bloc de commentaires, mais la syntaxe de la fonction ou du script détermine l’ordre dans lequel les paramètres (et leurs descriptions) apparaissent dans la rubrique d’aide. Pour modifier l’ordre, modifiez la syntaxe.

Vous pouvez également spécifier une description de paramètre en plaçant un commentaire dans la syntaxe de la fonction ou du script juste avant le nom de la variable de paramètre. Pour que cela fonctionne, vous devez également disposer d’un bloc de commentaires avec au moins un mot clé.

Si vous utilisez à la fois un commentaire de syntaxe et un .PARAMETER mot clé, la description associée .PARAMETER au mot clé est utilisée et le commentaire de syntaxe est ignoré.

<#
.SYNOPSIS
    Short description here
#>
function Verb-Noun {
    [CmdletBinding()]
    param (
        # This is the same as .Parameter
        [string]$Computername
    )
    # Verb the Noun on the computer
}

.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 cette mot clé pour chaque exemple.

.INPUTS

Types .NET d’objets qui peuvent être redirigés vers la fonction ou le script. Vous pouvez également inclure une description des objets 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.

.NOTES

Informations supplémentaires sur la fonction ou le script.

Nom d’une rubrique associée. La valeur apparaît sur la ligne sous le mot clé «.LINK » et doit être précédée d’un symbole # de commentaire ou incluse dans le bloc de commentaires.

Répétez la .LINK mot clé pour chaque rubrique associée.

Ce contenu apparaît dans la section Liens connexes de la rubrique d’aide.

Le .Link contenu mot clé peut également inclure un URI (Uniform Resource Identifier) vers 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 à laquelle elle est lié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

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 les rubriques 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, HelpFileFunction, Provider, General, GlossaryFAQ, ScriptCommand, ExternalScript, , Filterou All. Utilisez cette mot clé pour éviter les conflits lorsqu’il existe des commandes portant le même nom.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

Spécifie une session qui contient la rubrique d’aide. Entrez une variable qui contient un objet PSSession . Cette mot clé est utilisée par l’applet de commande Export-PSSession pour rechercher les rubriques d’aide relatives aux 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 .ExternalHelp mot clé est requis lorsqu’une fonction ou un script est documenté dans des fichiers XML. Sans cette mot clé, Get-Help impossible de trouver le fichier d’aide XML pour la fonction ou le script.

Le .ExternalHelp mot clé est prioritaire sur d’autres mots clés d’aide basés sur les commentaires. Si .ExternalHelp est présent, Get-Help n’affiche pas d’aide basée sur les commentaires, même s’il ne trouve pas de rubrique d’aide correspondant à la valeur de l’mot clé .ExternalHelp .

Si la fonction est exportée par un module, définissez la valeur de l’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, mais une bonne pratique consiste à utiliser le format suivant :

<ScriptModule.psm1>-help.xml

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 et que le chemin contient des sous-répertoires spécifiques à la culture de l’interface utilisateur, Get-Help recherche de manière récursive un fichier XML portant le nom du script ou de la fonction conformément aux normes de secours de langue établies pour Windows, comme dans un répertoire de module.

Pour plus d’informations sur le format de fichier d’aide XML de l’aide de l’applet de commande, consultez Guide pratique pour écrire l’aide sur les applets de commande.

Contenu généré automatiquement

Le nom, la syntaxe, la liste de paramètres, la table d’attributs de paramètre, les paramètres communs et les remarques sont générés automatiquement par l’applet de Get-Help commande.

Nom

La section Nom d’une rubrique d’aide de fonction est extraite du nom de la fonction dans la syntaxe de la fonction. La rubrique d’aide Nom d’un script est extraite du nom de fichier du script. Pour modifier le nom ou sa mise en majuscule, modifiez la syntaxe de la fonction ou le nom de fichier du script.

Syntax

La section Syntaxe de la rubrique d’aide est générée à partir de la syntaxe de la fonction ou du script. Pour ajouter des détails à la syntaxe de la rubrique d’aide, comme le type .NET d’un paramètre, ajoutez les détails à la syntaxe. Si vous ne spécifiez pas de type de paramètre, le type d’objet est inséré comme valeur par défaut.

Liste de paramètres

La liste des paramètres dans la rubrique d’aide est générée à partir de la syntaxe de la fonction ou du script et des descriptions que vous ajoutez à l’aide de la .Parameter mot clé. Les paramètres de fonction apparaissent dans la section Paramètres de la rubrique d’aide dans le même ordre qu’ils apparaissent dans la syntaxe de la fonction ou du script. L’orthographe et la mise en majuscules des noms de paramètres sont également tirées de la syntaxe. Il n’est pas affecté par le nom de paramètre spécifié par le .Parameter mot clé.

Paramètres communs

Les paramètres Communs sont ajoutés à la syntaxe et à la liste des paramètres de la rubrique d’aide, même s’ils n’ont aucun effet. Pour plus d’informations sur les paramètres courants, consultez about_CommonParameters.

Table d’attributs de paramètre

Get-Help génère la table des attributs de paramètre qui s’affiche lorsque vous utilisez le paramètre Full ou Parameter de Get-Help. La valeur des attributs Required, Position et Default value est extraite de la syntaxe de la fonction ou du script.

Les valeurs par défaut et une valeur pour Accepter les caractères génériques n’apparaissent pas dans la table d’attributs de paramètre, même lorsqu’elles sont définies dans la fonction ou le script. Pour aider les utilisateurs, fournissez ces informations dans la description du paramètre.

Remarques

La section Remarques de la rubrique d’aide est générée automatiquement à partir du nom de la fonction ou du script. Vous ne pouvez pas modifier ou affecter son contenu.

Exemples

Aide basée sur les commentaires pour une fonction

L’exemple de fonction suivant inclut une aide basée sur les commentaires :

function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.

.PARAMETER Name
Specifies the file name.

.PARAMETER Extension
Specifies the extension. "Txt" is the default.

.INPUTS

None. You cannot pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension
or file name.

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

Les résultats sont les suivants :

Get-Help -Name "Add-Extension" -Full

NAME

Add-Extension

SYNOPSIS

Adds a file name extension to a supplied name.

SYNTAX

Add-Extension [[-Name] <String>] [[-Extension] <String>]
[<CommonParameters>]

DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

PARAMETERS

-Name
Specifies the file name.

Required?                    false
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-Extension
Specifies the extension. "Txt" is the default.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type
"get-help about_commonparameters".

INPUTS
None. You cannot pipe objects to Add-Extension.

OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

Example 1

PS> extension -name "File"
File.txt

Example 2

PS> extension -name "File" -extension "doc"
File.doc

Example 3

PS> extension "File" "doc"
File.doc

RELATED LINKS

http://www.fabrikam.com/extension.html
Set-Item

Descriptions des paramètres dans la syntaxe des fonctions

Cet exemple est le même que le précédent, sauf que les descriptions des paramètres sont insérées dans la syntaxe de la fonction. Ce format est particulièrement utile lorsque les descriptions sont brèves.

function Add-Extension
{
param
(

[string]
#Specifies the file name.
$name,

[string]
#Specifies the file name extension. "Txt" is the default.
$extension = "txt"
)

$name = $name + "." + $extension
$name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

.INPUTS

None. You cannot pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

Aide basée sur les commentaires pour un script

L’exemple de script suivant inclut de l’aide basée sur les commentaires. Notez les lignes vides entre l’instruction fermante #> et l’instruction Param . Dans un script qui n’a pas d’instruction Param , il doit y avoir au moins deux lignes vides entre le commentaire final dans la rubrique d’aide et la première déclaration de fonction. Sans ces lignes vides, Get-Help associe la rubrique d’aide à la fonction, et non au script.

<#
.SYNOPSIS

Performs monthly data updates.

.DESCRIPTION

The Update-Month.ps1 script updates the registry with new data generated
during the past month and generates a report.

.PARAMETER InputPath
Specifies the path to the CSV-based input file.

.PARAMETER OutputPath
Specifies the name and path for the CSV-based output file. By default,
MonthlyUpdates.ps1 generates a name from the date and time it runs, and
saves the output in the local directory.

.INPUTS

None. You cannot pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 does not generate any output.

.EXAMPLE

PS> .\Update-Month.ps1

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath `
C:\Reports\2009\January.csv
#>

param ([string]$InputPath, [string]$OutPutPath)

function Get-Data { }
...

La commande suivante obtient l’aide du script. Étant donné que le script ne se trouve pas dans un répertoire répertorié dans la $env:Path variable d’environnement, la Get-Help commande qui obtient l’aide du script doit spécifier le chemin du script.

Get-Help -Path .\update-month.ps1 -Full

# NAME

C:\ps-test\Update-Month.ps1

# SYNOPSIS

Performs monthly data updates.

# SYNTAX

C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
<String>] [<CommonParameters>]

# DESCRIPTION

The Update-Month.ps1 script updates the registry with new data
generated during the past month and generates a report.

# PARAMETERS

-InputPath
Specifies the path to the CSV-based input file.

Required?                    true
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-OutputPath
Specifies the name and path for the CSV-based output file. By
default, MonthlyUpdates.ps1 generates a name from the date
and time it runs, and saves the output in the local directory.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type,
"get-help about_commonparameters".

# INPUTS

None. You cannot pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 does not generate any output.

Example 1

PS> .\Update-Month.ps1

Example 2

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

Example 3

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv

# RELATED LINKS

Redirection vers un fichier XML

Vous pouvez écrire des rubriques d’aide xml pour les fonctions et les scripts. Bien que l’aide basée sur les commentaires soit plus facile à implémenter, l’aide XML est nécessaire pour l’aide pouvant être mise à jour et pour fournir des rubriques d’aide dans plusieurs langues.

L’exemple suivant montre les premières lignes du script Update-Month.ps1. Le script utilise le .ExternalHelp mot clé pour spécifier le chemin d’accès à une rubrique d’aide XML pour le script.

Notez que la valeur du .ExternalHelp mot clé apparaît sur la même ligne que la mot clé. Tout autre placement est inefficace.

# .ExternalHelp C:\MyScripts\Update-Month-Help.xml

param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...

Les exemples suivants montrent trois emplacements valides des .ExternalHelp mot clé dans une fonction.

function Add-Extension
{
# .ExternalHelp C:\ps-test\Add-Extension.xml

param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}

function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name

# .ExternalHelp C:\ps-test\Add-Extension.xml
}

# .ExternalHelp C:\ps-test\Add-Extension.xml
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}

Redirection vers une autre rubrique d’aide

Le code suivant est un extrait du début de la fonction d’aide intégrée dans PowerShell, qui affiche un écran de texte d’aide à la fois. Étant donné que la rubrique d’aide de l’applet Get-Help de commande décrit la fonction d’aide, la fonction d’aide utilise les .ForwardHelpTargetName mots clés et .ForwardHelpCategory pour rediriger l’utilisateur vers la rubrique d’aide de l’applet Get-Help de commande.

function help
{

<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
[CmdletBinding(DefaultParameterSetName='AllUsersView')]
param(
[Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
[System.String]
${Name},
...

La commande suivante utilise cette fonctionnalité :

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

Voir aussi

about_Functions

about_Functions_Advanced_Parameters

about_Scripts

Guide pratique pour écrire l’aide sur les applets de commande