about_Comment_Based

RUBRIQUE
about_Comment_Based_Help

DESCRIPTION COURTE
Décrit comment écrire des rubriques d'aide basée sur des commentaires
pour les fonctions et les scripts.

DESCRIPTION LONGUE
Vous pouvez écrire des rubriques d'aide basée sur des commentaires
pour les fonctions et les scripts à l'aide de mots clés de
commentaires d'aide spéciaux.

L'applet de commande Get-Help affiche l'aide basée sur des
commentaires dans le même format que celui des rubriques d'aide
d'applet de commande générées à partir de fichiers XML. Les
utilisateurs peuvent employer tous les paramètres de Get-Help,
et notamment Detailed, Full, Example et Online, pour afficher
l'aide des fonctions et des scripts.

Vous pouvez également écrire des fichiers d'aide XML pour les
scripts et les fonctions à l'aide des mots clés de commentaires
d'aide ainsi que rediriger les utilisateurs vers un autre fichier
d'aide.

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 relatives aux fonctions et aux
scripts, consultez Get-Help.

SYNTAXE DE L'AIDE BASÉE SUR DES COMMENTAIRES
La syntaxe de l'aide basée sur des commentaires se présente comme
suit :
# .< mot clé d'aide>
# <contenu d'aide>

-ou -

<#
.< mot clé d'aide>
< contenu d'aide>
#>

L'aide basée sur des commentaires se présente sous la forme
d'une série de commentaires. Vous pouvez taper un symbole de
commentaire (#) avant chaque ligne de commentaires ou 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 celle-ci, une ligne vierge au moins doit séparer la dernière
ligne de commentaire non liée à l'aide et le début de l'aide
basée 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ée sur des commentaires
est précédé d'un point (.) Les mots clés peuvent apparaître dans
n'importe quel ordre. Les noms des mots clés ne respectent pas la
casse.

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

<#
.Description
Get-Function affiche le nom et la syntaxe de toutes les
fonctions de la session.
#>

Le bloc de commentaires doit contenir au moins un mot clé.
Certains mots clés, comme 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 qui suit le mot clé et peut
couvrir plusieurs lignes.

SYNTAXE DE L'AIDE BASÉE SUR DES COMMENTAIRES DANS LES FONCTIONS

L'aide basée sur des commentaires d'une fonction peut apparaître
dans l'un de trois emplacements suivants :

-- Au début du corps de la fonction.

-- À la fin du corps de la fonction.

-- Avant le mot clé Function. Il convient de ne pas inclure
plusieurs lignes vierges entre la dernière ligne de l'aide
relative à la fonction et le mot clé Function.

Par exemple :

function MyFunction
{
<#
.< mot clé d'aide>
< contenu d'aide>
#>

<commandes de fonction>
}

-ou -

function MyFunction
{
<commandes de fonction>

<#
.< mot clé d'aide>
< contenu d'aide>
#>
}

-ou -

<#
.< mot clé d'aide>
< contenu d'aide>
#>
function MyFunction { }

SYNTAXE DE L'AIDE BASÉE SUR DES COMMENTAIRES DANS LES SCRIPTS

L'aide basée sur des commentaires d'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 vierges
dans le script.

-- Si le premier élément du corps du script (après l'aide) est
une déclaration de fonction, deux lignes vierges au moins
doivent séparer la fin de l'aide du script et la déclaration
de fonction. Si tel n'est pas le cas, l'aide est interprétée
comme une aide relative à la fonction, et non pas au script.

-- À la fin du fichier de script.

Par exemple :

<#
.< mot clé d'aide>
< contenu d'aide>
#>

function MyFunction { }

-ou-

function MyFunction { }

<#
.< mot clé d'aide>
< contenu d'aide>
#>

MOTS CLÉS D'AIDE BASÉE SUR DES COMMENTAIRES
Vous trouverez ci-dessous une liste de mots clés d'aide basée sur
des commentaires valides. Ils sont répertoriés dans l'ordre selon
lequel ils apparaissent généralement dans une rubrique d'aide ;
l'usage auquel ces mots clés sont destinés est également indiqué.
Ces mots clés peuvent apparaître dans n'importe quel ordre dans
l'aide basée sur des 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 <Nom du paramètre>
Description d'un paramètre. Vous pouvez inclure un mot clé
Parameter pour chaque paramètre dans la syntaxe de la
fonction ou du script.

Les mots clés Parameter peuvent apparaître dans n'importe que
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 leur description) s'affichent dans la rubrique
d'aide. Pour changer 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 immédiatement avant le nom de variable du paramètre.
Si vous utilisez à la fois un commentaire de syntaxe et un
mot clé Parameter, la description associée au mot clé
Parameter est utilisée et le commentaire de syntaxe est ignoré.

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

.INPUTS
Types Microsoft .NET Framework des 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 Microsoft .NET Framework des objets que l'applet de commande
retourne. Vous pouvez également inclure une description des objets
retournés.

.NOTES
Informations supplémentaires relatives à la fonction ou au script.

.LINK
Nom d'une rubrique connexe. Répétez ce mot clé pour chaque
rubrique connexe.

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

Le contenu du mot clé Link peut également inclure l'URI
(Uniform Resource Identifier) d'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
Technologie ou fonctionnalité qui est utilisée par la
fonction ou le script, ou à laquelle ces derniers sont
associés. Ce contenu apparaît lorsque la commande Get-Help
inclut le paramètre Component de Get-Help.

.ROLE
Rôle d'utilisateur associé à la rubrique d'aide. Ce contenu
apparaît lorsque la commande Get-Help inclut le paramètre
Role de Get-Help.

.FUNCTIONALITY
Usage auquel la fonction est destinée. Ce contenu apparaît
lorsque la commande Get-Help inclut le paramètre
Functionality de Get-Help.

.FORWARDHELPTARGETNAME <Nom de commande>
Redirige vers la rubrique d'aide relative à la commande
spécifiée. Vous pouvez rediriger les utilisateurs vers toute
rubrique d'aide, notamment les rubriques d'aide relatives à
une fonction, un script, une applet de commande ou un
fournisseur.

.FORWARDHELPCATEGORY <Catégorie>
Spécifie la catégorie d'aide de l'élément dans ForwardHelpTarg
etName. Les valeurs valides sont Alias, Cmdlet, HelpFile, Function,
Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript,
Filter ou All. Utilisez ce mot clé pour éviter des conflits
lorsque plusieurs commandes portent le même nom.

.REMOTEHELPRUNSPACE <Variable de session PSSession>
Spécifie une session contenant la rubrique d'aide. Entrez une
variable contenant une session PSSession. Ce mot clé est
utilisé par l'applet de commande Export-PSSession pour la
recherche des rubriques d'aide relatives aux commandes exportées.

.EXTERNALHELP <Chemin d'accès au fichier d'aide XML>
Spécifie le chemin d'accès à un fichier d'aide XML associé au
script ou à la fonction.

Sous Windows Vista et les versions précédentes de Windows, si le
chemin d'accès spécifié au fichier XML contient des sous-répertoires
propres à la culture d'interface utilisateur, Get-Help recherche de
manière récursive dans les sous-répertoires un fichier XML avec le
nom du script ou de la fonction, conformément aux normes de langue
par défaut établies pour Windows Vista, comme pour toutes les
rubriques d'aide XML.

Pour plus d'informations sur le format de fichier d'aide XML
des applets de commande, consultez la rubrique " How to
Create Cmdlet Help (Comment créer une aide relative à une
applet de commande) " dans la bibliothèque MSDN (Microsoft
Developer Network) à l'adresse
https://go.microsoft.com/fwlink/?LinkID=123415.

AUTOGENERATED CONTENT
Le nom, la syntaxe, la liste de paramètres, la table des
attributs de paramètres, les paramètres courants et les remarques
sont générés automatiquement par l'applet de commande Get-Help.

Nom :
La section Nom d'une rubrique d'aide de fonction est
générée à partir du nom de fonction figurant dans la
syntaxe de fonction. Le nom d'une rubrique d'aide de
script est issu du nom du fichier de script. Pour
modifier le nom ou sa mise en majuscules, changez la
syntaxe de la fonction ou le nom du fichier de script.

Syntaxe :
La section Syntaxe de la rubrique d'aide est générée à
partir de la syntaxe de la fonction ou du script. Vous
pouvez ajouter des détails à la syntaxe d'une rubrique
d'aide, tels que le type .NET Framework d'un paramètre.
Si vous ne spécifiez pas de type de paramètre, le type
" Object " est inséré comme valeur par défaut.

Liste de paramètres :
La liste de 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 mot clé
Parameters. Les paramètres de fonction apparaissent dans
la section " Paramètres " de la rubrique d'aide dans le
même ordre que dans la syntaxe de la fonction ou du script.
L'orthographe et la mise en majuscules des noms de
paramètre proviennent également de la syntaxe ; ils ne
sont pas affectés par le nom de paramètre spécifié par
le mot clé Parameter.

Paramètres courants :
Les paramètres courants sont ajoutés à la syntaxe et à
la liste de 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 des attributs de paramètres :
Get-Help génère la table des attributs de paramètres qui
apparaît lorsque vous utilisez les paramètres Full ou
Parameter de Get-Help. La valeur des attributs Obligatoire,
Position et Valeur par défaut est extraite de la syntaxe
de la fonction ou du script.

Remarques :
La section Remarques de la rubrique d'aide est générée
automatiquement à partir du nom de la fonction ou du
script. Son contenu ne peut pas être modifié ni affecté.

EXEMPLES

Exemple 1 : Aide basée sur des commentaires se rapportant à une
fonction

L'exemple de fonction suivant inclut une aide basée sur des
commentaires :

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

<#
.SYNOPSIS
Ajoute une extension de nom de fichier à un nom fourni.

.DESCRIPTION
Ajoute une extension de nom de fichier à un nom fourni.
Accepte n'importe quelle chaîne pour le nom de fichier ou
l'extension.

.PARAMETER Nom
Spécifie le nom du fichier.

.PARAMETER Extension
Spécifie l'extension du nom de fichier. La valeur par
défaut est " txt ".

.INPUTS
Aucun. Vous ne pouvez pas diriger d'objets vers Add-Extension.

.OUTPUTS
System.String. Add-Extension retourne une chaîne avec
l'extension ou le nom de fichier.

.EXAMPLE
C:\PS> extension -name "Fichier"
Fichier.txt

.EXAMPLE
C:\PS> extension -name "Fichier" -extension "doc"
Fichier.doc

.EXAMPLE
C:\PS> extension "Fichier" "doc"
Fichier.doc

.LINK
Version en ligne : http://www.fabrikam.com/extension.html

.LINK
Set-Item
#>
}

Les résultats se présentent comme suit :

C:\PS> get-help add-extension -full

NOM
Add-Extension

SYNOPSIS
Ajoute une extension de nom de fichier à un nom fourni.

SYNTAXE
Add-Extension [[-Name] <Chaîne>] [[-Extension] <Chaîne>]
[<Paramètres courants>]
DESCRIPTION
Ajoute une extension de nom de fichier à un nom fourni.
Accepte n'importe quelle chaîne pour le nom de fichier ou
l'extension.

PARAMÈTRES
-Name
Spécifie le nom du fichier.

Obligatoire ? false
Position ? 0
Valeur par défaut
Accepter l'entrée de pipeline ? false
Accepter les caractères génériques ?

-Extension
Spécifie l'extension. La valeur par défaut est " txt ".

Obligatoire ? false
Position ? 1
Valeur par défaut
Accepter l'entrée de pipeline ? false
Accepter les caractères génériques ?

<Paramètres courants>
Cet applet de commande prend en charge les paramètres
courants : -Verbose, -Debug, ErrorAction,
-ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer et -OutVariable. Pour plus d'informations,
tapez " get-help about_commonparameters ".

INPUTs
Aucun. Vous ne pouvez pas diriger d'objets vers Add-Extension.

OUTPUTS
System.String. Add-Extension retourne une chaîne avec
l'extension ou le nom de fichier.

-------------------------- EXEMPLE 1 --------------------------
C:\PS> extension -name "Fichier"
Fichier.txt

-------------------------- EXEMPLE 2 --------------------------
C:\PS> extension -name "Fichier" -extension "doc"
Fichier.doc

-------------------------- EXEMPLE 3 --------------------------
C:\PS> extension "Fichier" "doc"
Fichier.doc

LIENS CONNEXES
Version en ligne : http://www.fabrikam.com/extension.html
Set-Item

Exemple 2 : Descriptions de paramètres dans la syntaxe de fonction

Cet exemple est identique au précédent, sauf que les
descriptions de paramètres sont insérées dans la syntaxe de
fonction. Ce format est très utile lorsque les descriptions
sont courtes.

function Add-Extension
{
param
(
[chaîne]
# Spécifie le nom du fichier.
$name,

[chaîne]
# Spécifie l'extension du nom de fichier. La valeur par défaut est " txt ".
$extension = "txt"
)
$name = $name + "." + $extension
$name

<#
.SYNOPSIS
Ajoute une extension de nom de fichier à un nom fourni.

.DESCRIPTION
Ajoute une extension de nom de fichier à un nom fourni.
Accepte n'importe quelle chaîne pour le nom de fichier ou
l'extension.

.INPUTS
Aucun. Vous ne pouvez pas diriger d'objets vers Add-Extension.

.OUTPUTS
System.String. Add-Extension retourne une chaîne avec
l'extension ou le nom de fichier.

.EXAMPLE
C:\PS> extension -name "Fichier"
Fichier.txt

.EXAMPLE
C:\PS> extension -name "Fichier" -extension "doc"
Fichier.doc

.EXAMPLE
C:\PS> extension "Fichier" "doc"
Fichier.doc

.LINK
Version en ligne : http://www.fabrikam.com/extension.html

.LINK
Set-Item
#>
}

Exemple 3 : Aide basée sur des commentaires se rapportant à un script

L'exemple de script ci-dessous inclut une aide basée sur des
commentaires.

Notez les lignes vierges entre le symbole de fermeture "#>"
et l'instruction Param. Dans un script ne comportant pas
d'instruction Param, deux lignes vierges au moins doivent
séparer le dernier commentaire de la rubrique d'aide et la
première déclaration de fonction. Sans ces lignes vierges,
Get-Help associe la rubrique d'aide à la fonction, et non pas
au script.

<#
.SYNOPSIS
Effectue des mises à jour de données mensuelles.

.DESCRIPTION
Le script Update-Month.ps1 met à jour le Registre avec les
nouvelles données générées le mois précédent et génère un
rapport.

.PARAMETER Chemin d'entrée
Spécifie le chemin d'accès au fichier d'entrée CSV.

.PARAMETER Chemin de sortie
Spécifie le nom et le chemin d'accès du fichier de sortie
CSV. Par défaut, MonthlyUpdates.ps1 génère un nom à partir
de la date et de l'heure d'exécution, puis enregistre la
sortie dans le répertoire local.

.INPUTS
Aucun. Vous ne pouvez pas diriger d'objets vers
Update-Month.ps1.

.OUTPUTS
Aucun. Update-Month.ps1 ne génère pas de sortie.

.EXAMPLE
C:\PS> .\Update-Month.ps1

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

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

param ([chaîne]$InputPath, [chaîne]$OutPutPath)

function Get-Data { }
...

La commande ci-dessous permet d'obtenir l'aide du script.
Étant donné que le script ne figure pas dans un répertoire
répertorié dans la variable d'environnement Path, la commande
Get-Help permettant d'obtenir l'aide du script doit spécifier
le chemin d'accès à ce dernier.

PS C:\ps-test> get-help .\update-month.ps1 -full

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

SYNOPSIS
Effectue des mises à jour de données mensuelles.

SYNTAXE
C:\ps-test\Update-Month.ps1 [-InputPath] <Chaîne> [[-
OutputPath] ]<Chaîne>] [<Paramètres courants>]

DESCRIPTION
Le script Update-Month.ps1 met à jour le Registre
avec les nouvelles données générées le mois précédent
et génère un rapport.

PARAMÈTRES
-InputPath
Spécifie le chemin d'accès au fichier d'entrée CSV.

Obligatoire ? true
Position ? 0
Valeur par défaut
Accepter l'entrée de pipeline ? false
Accepter les caractères génériques ?

-OutputPath
Spécifie le nom et le chemin d'accès du fichier de
sortie CSV. Par défaut, MonthlyUpdates.ps1 génère
un nom à partir de la date et de l'heure
d'exécution, puis enregistre la sortie dans le
répertoire local.

Obligatoire ? false
Position ? 1
Valeur par défaut
Accepter l'entrée de pipeline ? false
Accepter les caractères génériques ?
<Paramètres courants>
Cet applet de commande prend en charge les
paramètres courants : -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction,
-WarningVariable, OutBuffer et -OutVariable.
Pour plus d'informations, tapez " get-help
about_commonparameters ".

INPUTS
Aucun. Vous ne pouvez pas diriger d'objets vers
Update-Month.ps1.

OUTPUTS
Aucun. Update-Month.ps1 ne génère pas de sortie.

-------------------------- EXEMPLE 1 --------------------------
C:\PS> .\Update-Month.ps1

-------------------------- EXEMPLE 2 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\Janvier.csv

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

LIENS CONNEXES

Exemple 4 : 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 des
commentaires soit plus facile à implémenter, l'aide XML est
requise si vous souhaitez contrôler plus précisément le
contenu d'aide ou si vous traduisez des rubriques d'aide dans
plusieurs langues.

L'exemple ci-dessous présente les premières lignes du script
Update-Month.ps1. Le script utilise le mot clé ExternalHelp
pour spécifier le chemin d'accès à une de ses rubriques
d'aide XML.

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

param ([chaîne]$InputPath, [chaîne]$OutPutPath)

function Get-Data { }
...

L'exemple suivant illustre l'utilisation du mot clé
ExternalHelp dans une fonction.

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

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

Exemple 5 : Redirection vers une autre rubrique d'aide

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

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é :

C:\PS> get-help help

NOM
Get-Help

SYNOPSIS
Affiche des informations sur les applets de commande
et les concepts Windows PowerShell.
...

VOIR AUSSI
about_Functions
about_Functions_Advanced_Parameters
about_Scripts
" Comment écrire l'aide d'une applet de commande " (https://go.microsoft.com/fwlink/?LinkID=123415)

about_Comment_Based_Help

Table des matières