Bien utiliser l’aide PowerShell

I. Présentation

Que ce soit en ligne ou dans la console, l'aide de PowerShell est indispensable pour obtenir des informations sur le fonctionnement d'un cmdlet, sur une méthode, etc... et obtenir des exemples d'utilisation. Dans ce chapitre, nous allons voir comment utiliser l'aide PowerShell de manière efficace.

Lors de l'utilisation de PowerShell, il y a forcément un moment donné où vous allez bloquer sur l'utilisation d'un cmdlet. En effet, peut-être que vous ne comprendrez pas le fonctionnement d'un paramètre, quels sont les paramètres obligatoires, etc... Dans ce cas, vous avez besoin d'aide.

Quand vous recherchez de l'aide pour de l'administration en ligne de commande avec PowerShell ou pour un script PowerShell, il y a plusieurs sources d'informations à privilégier.

• Les cmdlets PowerShell suivants : Get-Command, Get-Help et Get-Member
• La documentation officielle de Microsoft dédiée à PowerShell, accessible sur cette page.
• Les tutoriels disponibles sur Internet, notamment ceux disponibles sur IT-Connect, car ils peuvent vous fournir des exemples d'utilisation supplémentaires

Quand vous serez plus à l'aise avec PowerShell, vous pourrez également vous appuyer sur de l'intelligence artificielle, notamment avec GitHub Copilot ou ChatGPT. Mais, pour être capable de bien interpréter et adapter les propositions de ces outils IA, il est recommandé d'avoir de bonnes bases en PowerShell.

III. PowerShell et Get-Command

Vous avez besoin d'effectuer une action, mais vous ne connaissez pas le nom de la commande PowerShell correspondante ? Ou peut-être que vous ne vous souvenez plus exactement du nom de la commande que vous aviez utilisé la dernière fois... "Get-Command" peut vous venir en aide.

Ce cmdlet, que nous avons déjà utilisé précédemment, sert à obtenir la liste des commandes disponibles sur la machine locale. Il est particulièrement pratique lorsqu'il est utilisé avec le caractère wildcard (l'astérisque) car il permet une recherche via un mot clé.

Imaginez que vous souhaitiez redémarrer votre ordinateur en PowerShell, mais vous avez oublié le nom de la commande. Vous ne savez plus si c'est "Reboot-Computer", "Shutdown-Computer" ou encore "Restart-Computer". Avec "Get-Command", vous pouvez faire une recherche sur le mot clé "Computer" :

Get-Command *Computer*

Dans la sortie de la commande, nous pouvons repérer le cmdlet "Restart-Computer". Intéressant !

Ce cmdlet, présent dans le module "Microsoft.PowerShell.Management", correspond-il à notre besoin ? Autrement dit, permet-il de redémarrer l'ordinateur ? Bien que tout porte à croire que oui, nous allons le vérifier.

II. PowerShell et Get-Help

A. Obtenir de l'aide sur un cmdlet PowerShell

Le cmdlet "Get-Help" de PowerShell permet de consulter l'aide de chaque cmdlet, à partir des informations stockées en local sur notre machine. Elle va aider à en savoir plus sur l'utilité d'un cmdlet, sur ses paramètres, et elle va permettre d'obtenir des exemples d'utilisation.

Prenons le cmdlet "Restart-Computer" comme exemple :

Get-Help -Name Restart-Computer
# ou
Get-Help Restart-Computer

Nous pouvons constater que la commande retourne une aide composée de plusieurs sections : SYNOPSIS, SYNTAX, DESCRIPTION, etc. Nous pouvons lire ceci : "Restarts the operating system on local and remote computers", que l'on peut traduire en "Redémarrage du système d'exploitation sur les ordinateurs locaux et distants." - Désormais, nous en avons la certitude : le cmdlet "Restart-Computer" sert à redémarrer un ordinateur.

Sachez qu'il est également possible d'obtenir de l'aide, via "Get-Help", en utilisant cette syntaxe :

<Nom du cmdlet> -?
# Par exemple :
Restart-Computer -?

Si l'aide retournée par défaut ne vous convient pas et que vous souhaitez afficher plus d'informations, vous pouvez utiliser différents paramètres proposés par "Get-Help" :

• Obtenir des exemples d'utilisation (retourne uniquement les exemples) :

Get-Help Restart-Computer -Examples
# ou 
Restart-Computer -? -Examples

Le fait de pouvoir accéder à des exemples d'utilisation à partir de la console PowerShell est très pratique :

• Obtenir la vue détaillée, avec la description, les paramètres et les exemples d'utilisation :

Get-Help Restart-Computer -Detailed
# ou 
Restart-Computer -? -Detailed

• Obtenir l'aide complète, avec la description, les paramètres (et leur fonctionnement), les exemples, et les objets acceptés en entrée et en sortie :

Get-Help Restart-Computer -Full
# ou 
Restart-Computer -? -Full

B. Solliciter l'aide en ligne de Microsoft Learn

Consulter l'aide à partir de la console PowerShell, c'est bien, mais ce n'est pas toujours très agréable : l'aide de certains cmdlets est très longue. Dans ce cas, il est préférable de s'appuyer sur l'aide en ligne, accessible depuis un navigateur web. Il faut savoir que dans la documentation de Microsoft, il y a une page d'aide dédiée à chaque cmdlet PowerShell !

Pour accéder à cette aide, vous pouvez effectuer une recherche avec votre moteur de recherche préféré. Généralement, une recherche Google orientée simplement sur le nom du cmdlet fait ressortir en premier résultat la page correspondante dans la documentation officielle.

Sinon, et c'est à connaître, vous pouvez utiliser le cmdlet "Get-Help" de façon à ce qu'il vous amène directement sur la page d'aide correspondante à votre requête :

Get-Help Restart-Computer -Online

En effet, le paramètre "-Online" va ouvrir la page d'aide avec votre navigateur. Ainsi, vous n'avez pas besoin d'effectuer la recherche de cette page par vous-même.

Cette page d'aide contient les mêmes sections que l'aide locale, avec la description, la syntaxe, les paramètres, les exemples... En fait, vous avez directement accès à l'aide complète (équivalent du paramètre "-Full"). Le site Microsoft Learn est incontournable pour obtenir de l'aide sur PowerShell.

En complément, sur la gauche, vous pouvez sélectionner votre version de PowerShell : ceci vous permet d'afficher l'aide qui correspond à la version que vous utilisez (c'est important car un cmdlet peut évoluer d'une version à une autre).

Si vous avez besoin d'aide supplémentaire pour utiliser "Get-Help" lui-même, utilisez cette commande :

Get-Help Get-Help

III. Mettre à jour l'aide locale

Sachez que l'aide locale de PowerShell retournée par le cmdlet "Get-Help" peut être obsolète ou incomplète. En effet, dans certains cas, le résultat retourné par cette commande sera vide ! Ceci signifie que PowerShell n'a pas trouvé d'aide en local pour le cmdlet en question.

Microsoft a tout prévu puisque le cmdlet "Update-Help" sert à mettre à jour l'aide locale. Il va permettre de télécharger les fichiers d'aide les plus récents pour les stocker en local sur votre machine.

Pour mettre à jour toute l'aide, ce qui peut s'avérer assez long, il suffit d'exécuter le cmdlet sans aucun paramètre :

Update-Help

Vous pouvez mettre à jour l'aide d'un module spécifique en précisant son nom :

Update-Help -Module <nom du module>
# Exemple 
Update-Help -Module Microsoft.PowerShell*

Enfin, sachez que le cmdlet "Update-Help" est capable d'aller récupérer les fichiers d'aide à partir d'un emplacement réseau (partage réseau accessible via un chemin UNC) grâce au paramètre "-SourcePath". Ceci permet d'avoir une source locale pour mettre à jour l'aide sur un ensemble de machines. Ceci implique de télécharger les fichiers d'aide au préalable avec le cmdlet "Save-Help".

Pour approfondir ce point, vous pouvez consulter l'aide de ces deux cmdlets :

Get-Help Update-Help
Get-Help Save-Help

Gardez à l'esprit que l'aide en ligne proposée par Microsoft est la version la plus à jour.

Note : depuis PowerShell 6.0, vous devez être administrateur pour mettre à jour l'aide. Sinon, vous devez spécifier la porte de l'opération avec le paramètre "-Scope" introduit dans PowerShell 6.1.

IV. Conclusion

Désormais, vous êtes en mesure de consulter l'aide d'un cmdlet PowerShell, que ce soit à partir de la console ou de la documentation Microsoft. Le cmdlet "Get-Member" mentionné en introduction de ce chapitre, sera étudié dans le prochain chapitre de ce cours.