Aide et Autoformation 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

-NamePré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
FullAffiche l’aide complète sur une commande
Help Get-Command -full
OnlineAffiche 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”
-ParameterAffiche l’aide détaillée sur le paramètre de la commande indiquée
Help Get-Help -parameter full
ShowWindowAffiche 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]
ExamplesAffiche 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

https://docs.microsoft.com/fr-fr/powershell/scripting/learn/deep-dives/everything-about-arrays?view=powershell-5.1

Tout ce que vous avez toujours voulu savoir sur les tables de hachage

https://docs.microsoft.com/fr-fr/powershell/scripting/learn/deep-dives/everything-about-hashtable?view=powershell-5.1

Powershellement votre 😀

Christophe M.

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur comment les données de vos commentaires sont utilisées.