about_Comment_Based_Help

Article
10/04/2023

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 d’aide spéciaux.

L’applet de commande Get-Help affiche l’aide basée sur les commentaires dans le même format dans lequel elle affiche les rubriques d’aide de l’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 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 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 Get-Help.

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

Syntaxe de l’aide basée sur des commentaires

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-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 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 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 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 plusieurs lignes vides entre la dernière ligne de l’aide de la fonction et le function mot clé.

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

Syntaxe de l’aide basée sur des 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 d’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 des commentaires

Les mots clés d’aide basés sur des commentaires valides sont les suivants. 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.

.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

Nom de la technologie ou de la fonctionnalité utilisée par la fonction ou le script, ou auquel 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 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, , CmdletHelpFile, GeneralFAQProviderFunctionScriptCommandExternalScriptGlossary, 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 l’applet de commande Export-PSSession pour rechercher les rubriques d’aide pour les 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 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 des commentaires. S’il .ExternalHelp est présent, Get-Help n’affiche pas l’aide basée sur les commentaires, même si elle ne trouve pas de rubrique d’aide qui correspond à la valeur du .ExternalHelp mot clé.

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

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 ou affecter 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 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 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 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 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 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 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 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 n’est 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 d’accès 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 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 basée sur XML est requise 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 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 .ForwardHelpCategory les .ForwardHelpTargetName 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