Sommaire
- Introduction
- Présentation du système d’aide intégrée
- Jouer avec l’aide intégrée
- Apprendre avec les exemples
- Exemple 1 : Afficher des informations d’aide de base sur une applet de commande
- Exemple 2: Afficher les informations de base page par page
- Exemple 8: Afficher une liste d’articles conceptuels
- Exemple 9: Recherche d’un mot dans l’aide de l’applet de commande
- Exemple 10: afficher une liste d’articles contenant un mot
- Aides alternatives en français
- Ajouter de l’aide dans vos scripts et vos fonctions
- Allez plus loin avec l’auto-apprentissage de Powershell
Introduction
Derrière ce titre accrocheur se cache l’idée qu’il est possible d’apprendre beaucoup sur Powershell grâce à son système d’aide intégrée sans solliciter systématiquement Internet ou des ouvrages spécialisés sur le sujet.
Bien que j’apprécie particulièrement son approche, je ne souhaite pas non plus plagier le second chapitre de l’excellent eBook “PowerShell 101” de Mike F Robbins, dont une traduction française est disponible ici https://github.com/MicrosoftDocs/PowerShell-Docs.fr-fr/blob/live/reference/docs-conceptual/learn/ps101/02-help-system.md
Notez que depuis la version 5, (2016) Microsoft a passé Powershell en open source (https://github.com/powershell/powershell) et la documentation associée est désormais maintenue par la communauté.
Présentation du système d’aide intégrée
Depuis ses débuts, Powershell (sur Windows) est fourni avec un système d’aide intégrée basé sur un ensemble de fichiers de type TXT et XML. Ces derniers étaient initialement stockés dans un sous-dossier régional de Powershell, soit
Get-ChildItem "$PSHOME\$PSCulture"
Malheureusement, à partir de la version 3, cette aide n’était plus présente par défaut sur le système et il est depuis nécessaire de la télécharger à partir Internet. De plus, n’en déplaise à certains, cette aide n’est disponible que dans la langue de Shakespeare 🙁
Mise à jour de l’aide locale
Pour télécharger et mettre à jour ces fichiers d’aide, il suffit d’utiliser
Update-Help
Toutefois, si la machine ne dispose pas d’un accès Internet, il faudra préalablement télécharger ces fichiers à partir d’un autre ordinateur ayant ce type d’accès puis les publier dans un dossier partagé le cas échéant. Le téléchargement peut être propre au module spécifié ou à défaut, (-module *) s’applique à l’ensemble des modules disponibles sur la machine :
(Get-Module -ListAvailable | select Name)
Attention : L’aide partagée doit correspondre à la version de Powershell installée sur votre machine.
Effectuez une sauvegarde locale dans un dossier temporaire à partir du poste ayant l’accès Internet (et disposant de la version de Powershell souhaitée)
New-Item -Path C:\Temp\PSHelp-V$($PSVersionTable.PSVersion.Major) -ItemType Directory -Force Save-Help -DestinationPath C:\Partages\PSHelp-V4 -UICulture fr-FR,en-US -Force
Ensuite, utilisez la commande de mise à jour de l’aide en stipulant la ressource partagée (sans oublier les éventuels identifiants pour l’accès au partage 😀 )
$cred = Get-Credential Labo\Administrateur Update-Help -SourcePath \\WS2019-DC1\PSHelp-V4 -UICulture en-US -Credential $cred
Jouer avec l’aide intégrée
Les commandes d’aide
Pour solliciter l’aide locale, il suffit d’utiliser la cmdlet dédiée “Get-Help” ou la fonction “help” ou bien encore l’alias “man“. Sans paramètre, la commande “Get-Help” vous renvoie l’aide complète associée à son utilisation propre.
Get-Help
Vous pourrez constater que cette aide est affichée en français. En revanche, dès que l’on stipule le nom d’une commande sur laquelle on désire de l’aide, en l’occurrence “Get-Help”, l’affichage bascule en anglais.
Get-Help Get-Help -full
En fait, la première commande, sans paramètre, utilise l’aide de base installée par défaut. On pourrait pratiquement remplacer cette commande par :
Get-Content "$PSHOME\$PSCulture\default.help.txt"
A noter que le commutateur “-?” affiche également l’aide de base sur une commande donnée. Par exemple, les commandes suivantes sont similaires
Get-Command -? Get-Help Get-Command help gcm
Comme toutes les applets de commande, plusieurs paramètres, vous sont proposés par “Get-Help”. Je ne reviendrais pas sur une description exhaustive de ces paramètres, mais prenez un moment pour observer leur combinaisons ainsi que la classification des informations retournées par chacun d’entre eux, souvent riches d’enseignements.
Principaux paramètres et commutateurs de l’aide
| -Name | Précise le nom de la commande ou du concept dont on souhaite afficher l’aide. (Paramètre positionnel implicite) Help -Name Get-Command Help Get-Command |
| –Full | Affiche l’aide complète sur une commande Help Get-Command -full |
| –Online | Affiche l’aide en ligne via le navigateur par défaut (Requiert une connexion Internet) – L’adresse du lien est mentionnée au niveau de la catégorie “Liens Connexes” |
| -Parameter | Affiche l’aide détaillée sur le paramètre de la commande indiquée Help Get-Help -parameter full |
| –ShowWindow | Affiche l’aide dans une fenêtre dédiée (Powershell v3 ou +) Par défaut dans ISE lors de l’appui de la touche [F1] |
| –Examples | Affiche les exemples relatifs au nom de la commande ou au concept indiqué. |
Apprendre avec les exemples
En matière d’apprentissage, le commutateur “-Examples” est probablement le plus approprié.
Pour la commande d’aide elle-même, une douzaine d’exemples, vous sont proposés.
Help Get-Help -Examples
J’ai repris et sensiblement modifiés, certains de ces exemples 😀
Exemple 1 : Afficher des informations d’aide de base sur une applet de commande
Get-Help Format-Table Get-Help -Name Format-Table Format-Table -?
“Get-Help <cmdlet-name>” est la syntaxe la plus simple et par défaut de l’applet de commande “Get-Help”. Vous pouvez omettre le paramètre Name.
La syntaxe “<cmdlet-name> -?” Ne fonctionne que pour les applets de commande.
L’usage de “-?” est assez méconnu et à mon humble avis, une mauvaise habitude. A l’instar des alias, il peut vous induire en erreur en oubliant la logique Powershell.
Exemple 2: Afficher les informations de base page par page
help Format-Table man Format-Table Get-Help Format-Table | Out-Host -Paging
“help” est une fonction qui exécute l’applet de commande “Get-Help” en interne et affiche le résultat page par page.
“man” est un alias de la fonction “help”.
“Get-Help Format-Table” envoie l’objet dans le pipeline. “Out-Host -Paging” reçoit la sortie du pipeline et l’affiche une page à la fois.
Offrant par défaut un affichage page par page, il est plus simple et pratique, d’utiliser les commandes help ou man pour obtenir de l’aide.
Allons un peu plus loin 🙂
On peut vérifier que le type de la commande “help” est bien “function” puis éventuellement en afficher le contenu via le lecteur dédié (PSdrive) “function:“
Get-Command help Get-Content function:\help
Sous Powershell v5 (donc Windows uniquement) vous pourrez constater que la fonction “help” est un simple artifice qui associe l’applet de commande “Get-Help” avec la commande “more“. Et en regardant cette dernière, vous trouverez une autre fonction faisant appel au programme “more.com“
En revanche, avec Powershell Core ou v7, la fonction “help” a dû être entièrement repensée afin d’adapter l’outil de pagination en fonction de la plateforme (“more.com” sous Windows, et “less” sous Linux / Mac OS)
Exemple 8: Afficher une liste d’articles conceptuels
Get-Help about_*
Aparté sur les fichiers d’aide conceptuelle “About_”
Après avoir éventuellement mis à jour localement les fichiers d’aide, vous pourrez constater la présence de nombreux fichiers texte commençant par “about” dans le dossier de Powershell
Get-ChildItem "$PSHOME\en-US\about*"
Ces fichiers peuvent être édités avec l’éditeur de texte par défaut (bloc-notes) comme par exemple
Invoke-Item "$PSHOME\en-US\about_Remote.help.txt"
Vous pourrez aussi obtenir un résultat très similaire et convivial en utilisant la commande :
Get-Help about_Remote -ShowWindow
Exemple 9: Recherche d’un mot dans l’aide de l’applet de commande
Get-Help Add-Member -Full | Out-String -Stream | Select-String -Pattern Clixml
“Get-Help” utilise le paramètre Full pour obtenir des informations d’aide sur l’applet de commande “Add-Member“. L’objet “MamlCommandHelpInfo” est envoyé dans le pipeline. “Out-String” utilise le paramètre Stream pour convertir l’objet en une chaîne. “Select-String” utilise le paramètre Pattern pour rechercher la chaine Clixml dans ce contenu.
Afficher le type de l’objet “MamlCommandHelpInfo#Microsoft.PowerShell.Utility#Add-Member#FullView”
Get-Help Add-Member -Full | Get-Member | select Name, TypeName
Vous pouvez constater que cet objet complexe contient plusieurs propriétés. Il faut donc convertir ces différents contenus en chaines de caractères avant d’effectuer une recherche.
Get-Help Add-Member -Full | Out-String -Stream | Get-Member
A ce stade, grâce à la commande “Out-String -Stream”, l’objet est bien converti en un flux de caractères, que l’applet de commande “Select-String” peut traiter sans problème.
Similaire à Grep sous Linux, la commande “Select-String” est très pratique au quotidien. A ne pas confondre avec “select“, alias de “Select-Object“, son alias est “sls“.
Exemple 10: afficher une liste d’articles contenant un mot
Get-Help -Name remoting
Vous pouvez constater le resultat affiche les commandes contenant le terme “remoting” sans avoir eu besoin d’ajouter les caractères génériques en début ou à la fin.
Aides alternatives en français
Attention, la plupart de ces traductions comportent des erreurs, particulièrement au niveau des exemples, dans lesquels certains mots clés du code ont été malencontreusement traduits.
PowerShell 101
Comme mentionné dans l’introduction, vous pouvez consulter la traduction française de l’ouvrage “PowerShell 101” de Mike F Robbins (10 chapitres) ici : https://github.com/MicrosoftDocs/PowerShell-Docs.fr-fr/tree/live/reference/docs-conceptual/learn/ps101
RIP Tutorial
Outil d’apprentissage gratuit “RIP Tutorial” (Archives documentaires de Stackoverflow)
https://riptutorial.com/fr/powershell
@RipTutorial
Archived Stack Overflow Documentation RIP Tutorial is a practical free learning tool. Find plenty of information available in 10 languages.
Portail d’aide officielle
Vous trouverez à cette adresse, toutes les documentations relatives à Powershell ainsi que les liens vers des ressources et technologies associées.
https://docs.microsoft.com/fr-fr/powershell/
Ou plus précisément, le guide de démarrage de Powershell 5.1:
https://docs.microsoft.com/fr-fr/powershell/scripting/overview?view=powershell-5.1
Forsenergy – Help and Support
Un site d’aide sur de nombreux sujets – Hormis que le propriétaire semble être basé à Moscou, j’ignore tout de l’origine de ce site ou de sa gestion. S’agit-il de traductions dynamiques de contenus, ou autre chose, cette adresse constitue un support intéressant pour ceux qui préfère apprendre certains concepts dans leur langue natale.
https://forsenergy.com/fr-fr/windowspowershellhelp/html/defed09e-2acd-4042-bd22-ce4bf92c2f24.htm
Ajouter de l’aide dans vos scripts et vos fonctions
Lors de l’écriture d’un script ou d’une fonction, la documentation reste souvent le parent pauvre de l’auteur du code.
Powershell offre toutefois la possibilité d’ajouter des blocs de commentaires enrichis.
Pour afficher la documentation associée à ce concept, utilisez la commande :
help about_Comment_Based_Help
Pour illustrer rapidement ces propos, je me contenterais de reprendre les exemples cités dans cette documentation (sensiblement corrigés 😉 ). Ouvrez simplement l’éditeur ISE, puis recopiez-y le code mentionné.
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 ([string]$Name,[string]$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> add-extension -name "Fichier"
Fichier.txt
.EXAMPLE
C:\PS> add-extension -name "Fichier" -extension "doc"
Fichier.doc
.EXAMPLE
C:\PS> add-extension "Fichier" "doc"
Fichier.doc
.LINK
Version en ligne : http://www.fabrikam.com/add-extension.html
.LINK
Set-Item
#>
}
Sélectionnez cette fonction puis exécutez-la via [F8]
Testez le fonctionnement de l’aide associée
help add-extension help Add-Extension -Detailed help Add-Extension -Parameter extension
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 directement dans le bloc “param” de la fonction. Ce format est très utile lorsque les descriptions sont courtes.
function Add-Extension
{
param
(
[string]
# Spécifie le nom du fichier.
$name,
[string]
# 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> add-extension -name "Fichier"
Fichier.txt
.EXAMPLE
C:\PS> add-extension -name "Fichier" -extension "doc"
Fichier.doc
.EXAMPLE
C:\PS> add-extension "Fichier" "doc"
Fichier.doc
.LINK
Version en ligne : http://www.fabrikam.com/add-extension.html
.LINK
Set-Item
#>
}
Sélectionnez cette fonction puis exécutez-la via [F8]
Testez le fonctionnement de l’aide associée
help add-extension help Add-Extension -Detailed help Add-Extension -Parameter extension
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 InputPath
Spécifie le chemin d'accès au fichier d'entrée CSV.
.PARAMETER 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.
.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 ([string]$InputPath, [string]$OutPutPath)
function Get-Data {
# votre code
}
Enregistrez ce code dans un fichier “update-month.ps1” puis testez le fonctionnement de l’aide associée.
Get-Help .\update-month.ps1 -full help .\update-month.ps1 -Parameter inputpath help .\update-month.ps1 -Examples
Avec le temps et un brin d’altruisme, je vous invite à renseigner quelques indications dans vos créations.
Allez plus loin avec l’auto-apprentissage de Powershell
Les sources d’information sur Powershell sont très nombreuses et les ouvrages sur et autour le sont tout autant. Je vous encourage toutefois à lire les rubriques “Apprentissage de Powershell … En profondeur” disponibles sur le portail de documentation en français.
Tout ce que vous avez toujours voulu savoir sur les tableaux
Tout ce que vous avez toujours voulu savoir sur les tables de hachage
Powershellement votre 😀
Christophe M.