Windows PowerShell : commentez votre contribution à l'aide
Vous pouvez ajouter vos propres commentaires à vos scripts et créer ainsi votre propre système d'aide et de didacticiel en ligne.
Don Jones
L'un des plus jolis choses à propos de Windows PowerShell est son système d'aide. L'aide fichiers incluent des aperçus de la syntaxe, des explications détaillées, des exemples et ainsi de suite.
Étant donné qu'un shell de ligne de commande ne peut pas offrent des fonctionnalités de découverte telles que les menus contextuels, barres d'outils, rubans et ainsi de suite, le fichier d'aide se dresse sur sa propre comme un attrait caractéristique. Utilisez il avec des caractères génériques, par exemple, à la découverte de nouvelles commandes. Ensuite, vous pouvez lire leur aide pour savoir comment s'en servir.
Que vous produisez vos propres commandes tant que les fonctions et les scripts, vous feriez bien de garder votre travail aussi poli que les applets de commande Windows PowerShell native. Vous devez toujours vous efforcer de rendre votre travail aussi cohérente que possible avec le reste de la coque. Partie de cette cohérence et polonais est comment vous préparez et fournir de l'aide.
Vous pouvez produire le même type exact des fichiers d'aide XML qui utilise Windows PowerShell lui-même. Il y a plus de discussion sur ce sujet dans mon livre auto-publié, « Windows PowerShell Scripting et fabrication d'outils. » Cependant, la plupart d'entre vous n'aurez pas besoin de la flexibilité, les fichiers d'aide offrent, comme la possibilité de fournir une aide dans plusieurs langues.
Vous pouvez prendre beaucoup une voie plus facile. Vous pouvez simplement utiliser aide basée sur des commentaires.
Règles de l'aide basée sur des commentaires
Il y a quelques règles à l'aide basée sur des commentaires que je devrais couvrir juste avant :
- En général, vous aurez envie de joindre vos blocs de commentaires spéciaux dans le < bloc # commentaire #> marqueurs. Il est également légal de chaque ligne en commentaire simplement en commençant par le caractère de commentaire #.
- Aide basée sur des commentaires devrait être la première chose dans le fichier de script. Il est préférable d'inclure l'aide au sein de la fonction plutôt que juste avant. Qui aide à garder le commentaire « partie » de la fonction et permet à que Windows PowerShell ne confondez pas pour autre chose. Il est également légal de mettre l'aide basée sur des commentaires de script à la fin du fichier, mais je n'aime pas faire cela parce que cela diminue les autres avantages de l'utilisation de l'aide basée sur des commentaires.
- Si vous êtes l'aide pour une fonction, le bloc d'aide basée sur des commentaires peut venir immédiatement avant ou immédiatement après le nom de la fonction et l'accolade d'ouverture.
- Lorsque vous insérez plusieurs fonctions dans un script, tel qu'un module de script, vous pouvez fournir l'aide pour le fichier en mettant le bloc de commentaires en haut. Assurez-vous d'ajouter au moins quelques-unes lignes vides après ce bloc de commentaire, afin que toute aide spécifique ultérieure se tiendra dehors correctement.
- Si vous orthographiez mal tous les mots clés d'aide basée sur des commentaires, Windows PowerShell peut ignorer le bloc entier. Donc attention à votre orthographe, parce que ça compte.
Syntaxe de l'aide basée sur des commentaires
Aide basée sur des commentaires se compose d'une ou plusieurs sections. Chaque section commence par un mot-clé en pointillé, suivi d'une ou plusieurs lignes de texte. Par exemple :
<# .SYNOPSIS The synopsis goes here. This can be one line, or many. .DESCRIPTION The description is usually a longer, more detailed explanation of what the script or function does. Take as many lines as you need. .PARAMETER computername Here, the dotted keyword is followed by a single parameter name. Don't precede that with a hyphen. The following lines describe the purpose of the parameter: .PARAMETER filePath Provide a PARAMETER section for each parameter that your script or function accepts. .EXAMPLE There's no need to number your examples. .EXAMPLE PowerShell will number them for you when it displays your help text to a user. #>
Cet exemple inclut les quatre mots-clés en pointillés plus couramment utilisés. Vous remarquerez ces commencer par un point ou un point. Windows PowerShell n'est pas sensible à la casse sur ceux qui, bien que la documentation répertorie dans toutes les majuscules (alors j'ai tendance à faire de même). À l'aide de majuscules rend également les sections se démarquer un peu plus quand vous lisez le code dans un éditeur de script.
Une autre section soignée, que vous pouvez utiliser est la référence. Avec cela, vous pouvez inclure une URL, commençant par l'adresse http://, pour une version en ligne de votre aide. L'affichage de votre aide sur un site intranet, par exemple, permet une personne obtenir plus de détails, peut-être plus d'exemples, Découvrez comment vous contacter et ainsi de suite.
Windows PowerShell génère automatiquement contenu de l'aide supplémentaire en regardant votre script ou une fonction. Il dérive le nom, la syntaxe de base (y compris les types de données et les noms de paramètres) et d'autres informations. Il ne détecte pas toutes les valeurs par défaut que vous pouvez avoir codé dans un paramètre :
Param($computername = 'localhost')
Par conséquent, veillez à documenter les paramètres par défaut à l'aide du paramètre lui-même, ou même dans la description.
Awesomeness basée sur des commentaires
Un autre avantage de l'aide basée sur des commentaires, c'est qu'il propose deux types d'aide. L'un est pour les gens qui dirigent l'aide contre vos scripts et fonctions. L'autre est pour quelqu'un qui lit vos scripts.
En d'autres termes, bien écrit aide basée sur des commentaires peut également doubler comme la documentation en ligne que vous préférez sans doute mettre dans n'importe quel type de vos scripts.
.jpg)
Don Jones est un destinataire Microsoft MVP Award et auteur de "Apprendre Windows PowerShell dans un mois de repas » (Manning Publications, 2011), un livre conçu pour aider n'importe quel administrateur devenir efficace avec Windows PowerShell. Jones offre également une formation de Windows PowerShell publique et sur place. Vous pouvez le contacter via ConcentratedTech.com ou bit.ly/AskDon.