about_Comment_Based_Help

Article
01/22/2025

Description courte

Décrit comment rédiger le contenu d’aide basé sur des commentaires pour les fonctions et les scripts.

Description longue

Vous pouvez rédiger le contenu d’aide basé sur des commentaires pour les fonctions et les scripts en utilisant des mots-clés spéciaux pour l’aide dans les commentaires.

La commandelet Get-Help affiche l'aide basée sur les commentaires dans le même format que le contenu d'aide des commandelets généré à 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 des commentaires.

Vous pouvez également écrire des fichiers d’aide XML pour les fonctions et les scripts. Pour permettre à l’applet Get-Help de commande de rechercher le fichier d’aide XML pour une fonction ou un script, utilisez le .EXTERNALHELP mot clé. Sans ce mot-clé, Get-Help ne peut pas trouver le contenu d’aide basé sur XML pour les fonctions ou les scripts.

Cette rubrique explique comment rédiger le contenu d’aide pour les fonctions et les scripts. Pour obtenir des informations sur la manière d’afficher le contenu d’aide pour les fonctions et les scripts, veuillez consulter la section Obtenir de l’aide.

Les applets de commande Update-Help et Save-Help fonctionnent uniquement sur les fichiers XML. L’aide actualisable ne prend pas en charge le contenu d’aide basé sur des commentaires.

Syntaxe de l’aide basée sur des commentaires

Pour créer du contenu d’aide basé sur des commentaires, vous pouvez utiliser l’un ou l’autre style de commentaires : des commentaires sur une seule ligne ou des commentaires en bloc.

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

# .<help keyword>
# <help content>

<#
    .<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 <# les #> symboles 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 non destinée à l’aide et le début du contenu d’aide basé sur des commentaires.

Les mots clés définissent chaque section de l’aide basée sur des commentaires. Chaque mot clé d’aide basé sur des commentaires est précédé d’un point .. Les mots clés peuvent apparaître dans n’importe quel ordre. Les noms de mots clés ne sont pas sensibles à 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 des commentaires dans les fonctions

L’aide basée sur les commentaires pour une fonction peut apparaître à 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 le mot-clé function.

Par exemple :

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

    # function logic
}

function Get-Function {
    # function logic

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

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

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

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

Au début du fichier de script. L’aide du script peut être précédée uniquement par des commentaires et des 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 étant de l’aide pour la fonction, pas de l’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 { }

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

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

Les mots clés d’aide basés sur des commentaires valides sont les suivants. Ces mots-clés peuvent apparaître dans n’importe quel ordre dans l’aide basée sur des commentaires, et ils ne sont pas sensibles à la casse. Les mots clés sont répertoriés dans cet article dans l’ordre dans lequel ils apparaissent généralement dans une rubrique d’aide.

.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

Description d’un paramètre. Ajoutez un .PARAMETER mot clé pour chaque paramètre dans la syntaxe de fonction ou de 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 le .PARAMETER mot clé. Windows PowerShell interprète tout le texte entre la .PARAMETER ligne et le mot clé suivant 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 de paramètre peuvent apparaître dans n’importe quel ordre dans le bloc de commentaires, mais la fonction ou la syntaxe de 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 fonction ou de script immédiatement avant le nom de la variable de paramètre. Pour que cela fonctionne, vous devez également avoir un bloc de commentaires avec au moins un mot clé.

Si vous utilisez un commentaire de syntaxe et un .PARAMETER mot clé, la description associée au .PARAMETER 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 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.

.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.

.LINK

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 le .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 du mot clé 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

Le nom de la technologie ou de la fonctionnalité que la fonction ou le script utilise, ou à laquelle il est lié. Le paramètre Composant d’utilise cette valeur pour filtrer les résultats de Get-Help recherche retournés par Get-Help.

.ROLE

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

.FUNCTIONALITY

Mots clés qui décrivent l’utilisation prévue de la fonction. Le paramètre De fonctionnalité d’utilisation de cette valeur pour filtrer les résultats de Get-Help 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 le contenu d’aide pour une fonction, un script, une cmdlet 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, , CmdletHelpFile, FunctionProviderGeneralFAQGlossaryScriptCommandExternalScript, Filter, ou .All Utilisez ce 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 . Ce mot-clé est utilisé par la cmdlet Export-PSSession pour trouver 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 .EXTERNALHELP mot clé est requis lorsqu’une fonction ou un script est documenté dans des fichiers XML. Sans ce mot-clé, Get-Help ne trouve pas 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 des commentaires. Si .EXTERNALHELP est présent, Get-Help n’affiche pas le contenu d’aide basé sur des commentaires, même s’il ne peut pas trouver une rubrique d’aide correspondant à la valeur du mot-clé .EXTERNALHELP.

Si la fonction est exportée par un module, définissez la valeur du mot clé sur un nom de .EXTERNALHELP 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 de 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 vers le fichier d’aide basé sur 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 du fichier d’aide XML basé sur xml, consultez Comment écrire l’aide sur les applets de commande.

Contenu généré automatiquement

Le nom, la syntaxe, la liste des 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 Get-Help de 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. Le nom d’une rubrique d’aide de script est extrait du nom de fichier de script. Pour modifier le nom ou sa majuscule, modifiez la syntaxe de la fonction ou le nom de fichier de script.

Syntaxe

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

Liste de paramètres

La liste des paramètres de 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 du .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 fonction ou de script. L’orthographe et la mise en majuscules des noms de paramètres sont également extraites de la syntaxe. Il n’est pas affecté par le nom du paramètre spécifié par le mot-clé .Parameter.

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 est extraite de la syntaxe de fonction ou de script.

Ni les valeurs par défaut ni une valeur pour Accepter les caractères génériques n’apparaissent pas dans la table d’attributs des paramètres, 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.

Notes

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 son contenu.

Exemples

Aide basée sur des commentaires pour une fonction

L’exemple de fonction suivant inclut l’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 can't 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 can't 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 de la fonction

Cet exemple est le même que celui précédent, sauf que les descriptions des paramètres sont insérées dans la syntaxe de la fonction. Ce format est le plus 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 can't 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 des commentaires pour un script

L’exemple de script suivant inclut l’aide basée sur les commentaires. Notez les lignes vides entre la fermeture #> 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 dernier commentaire de 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 le 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 can't pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 doesn't 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. Comme le script n’est pas dans un répertoire répertorié dans la variable d’environnement $env:Path, la commande Get-Help qui récupère l’aide du script doit spécifier le chemin du script.

Get-Help -Name .\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 can't pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 doesn't 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 rédiger du contenu d’aide basé sur XML pour les fonctions et les scripts. Bien que le contenu d’aide basé sur des commentaires soit plus facile à mettre en œuvre, le contenu d’aide basé sur XML est requis pour Updatable Help et pour fournir du contenu 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 basée sur XML pour le script.

Notez que la valeur du .EXTERNALHELP mot clé apparaît sur la même ligne que le 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 placements valides du .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 mots clés et .ForwardHelpTargetName les .ForwardHelpCategory mots clés 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.
...

Partager via