Comment imposer des prérequis dans ses scripts PowerShell ?
Sommaire
I. Présentation
Vous commencez à avoir une belle collection de scripts PowerShell, mais vous ne savez jamais comment les lancer ? Pour celui-ci, faut-il avoir les droits administrateur ? Faut-il le lancer en tant qu’utilisateur classique ? Doit-on le lancer dans Windows PowerShell version 5.1, ou plutôt dans PowerShell 7 ? Et côté modules, que faut-il installer sur la machine avant de lancer ce script ?
Si vous vous posez ces questions à chaque fois que vous souhaitez lancer un script, alors cet article est pour vous.
Car vous ne le savez peut-être pas, mais il est tout à fait possible d’imposer des prérequis à respecter dans un script PowerShell, sous peine de quoi le script refusera de se lancer, car les prérequis ne sont pas respectés.
Plus besoin d’ouvrir le script dans un éditeur et de le parcourir pour vérifier quels sont les prérequis en fonction des commandes inscrites.
II. Prérequis
- Windows PowerShell version 5.1 ou PowerShell 7
III. L’instruction Requires en PowerShell
A. Quelques exemples
Certains d’entre vous ont contourné le problème en ajoutant dans un commentaire en début de script que celui-ci doit être lancé en tant qu’administrateur. D’autres font un test en début de script pour vérifier si la session PowerShell est une session de type administrateur ou non.
Mais ces solutions ne sont pas viables : l'une oblige à modifier le script et consulter les commentaires systématiquement avant de le lancer, l'autre est plutôt lourde à coder et en fonction de votre environnement (notamment pour PowerShell Core sur des machines autres que Windows), votre code pourrait ne pas fonctionner.
Il y a pourtant bien plus simple : l’instruction Requires.
Il s’agit d’une instruction très simple, qui demande à PowerShell de vérifier avant toute exécution du script les prérequis listés :
- La version minimum de PowerShell à utiliser
- Les modules qui doivent être préalablement installés, ainsi que leur version
- L’édition de PowerShell (Desktop ou Core) à utiliser
- Une session PowerShell ouverte en tant qu’administrateur
L’un de ces prérequis n’est pas respecté ? Le script refuse de se lancer. Par exemple, j’ai ici ajouté une instruction demandant à être administrateur, mais j’ai lancé mon script en tant qu’utilisateur.
Autre exemple : cette fois, j’ai indiqué que le prérequis était de lancer le script sur une édition Desktop. Autrement dit, il ne peut se lancer que sur Windows PowerShell.
Pour le vérifier, j’ai tenté de lancer le script sur PowerShell édition Core (version 7), et sur Windows PowerShell (édition Desktop, version 5.1). Et voici le résultat :
B. Comment ça marche ?
Concrètement, comment ça marche ? Vous allez voir, c’est d’une simplicité enfantine.
Il vous suffit d’ajouter l’instruction #Requires dans votre script, suivi du paramètre choisi.
Si vous avez plusieurs prérequis différents à respecter, par exemple lancer un script en tant qu’administrateur tout en utilisant PowerShell version 5.1 minimum, il vous faudra mettre chaque instruction sur une ligne séparée. Et ... C’est tout !
Vous pouvez glisser cette instruction n’importe où dans votre script, mais je vous conseille pour des raisons de maintenabilité de l’ajouter au début. Avant toute exécution de votre script, PowerShell va chercher si une instruction #Requires est présente, et si c’est le cas, va vérifier que les prérequis sont bien respectés.
Note : Veillez bien à respecter le # avant le Requires. Bien que le dièse est habituellement utilisé pour ajouter des commentaires, cette instruction ne fonctionnera pas sans. Voyez ça comme un commentaire spécial.
IV. Les paramètres de #Requires en PowerShell
Vous pouvez utiliser les paramètres suivants avec l’instruction Requires :
A. -Version
Ce paramètre sert à spécifier la version minimum de PowerShell à respecter afin de pouvoir lancer le script. Vous pouvez indiquer une version majeure (par exemple 5), ou une version mineure, par exemple 5.1.
#Requires -Version 5.1
PowerShell devra être à minima en version 5.1 pour lancer ce script.
#Requires -Version 7
PowerShell devra être à minima en version 7 afin d'exécuter ce script.
B. -PSEdition
Ce paramètre sert à spécifier l'édition de PowerShell à respecter. Pour rappel, si vous utilisez PowerShell en version 5.1, ou via Windows PowerShell (la version préinstallée sur votre OS), vous êtes en édition Desktop. Si vous utilisez PowerShell en version 7, ou sur un Linux / MacOS, vous êtes en version Core.
#Requires -PSEdition Desktop
Impose l'utilisation de Windows PowerShell pour lancer le script.
#Requires -PSEdition Core
Impose l'utilisation de PowerShell en version Core. A privilégier pour les scripts cross-platform.
Note : Vous pouvez coupler ce paramètre avec le paramètre -Version afin d'avoir un contrôle plus fin sur vos prérequis.
C. -RunAsAdministrator
Sans nul doute le paramètre qui vous servira le plus souvent, et qui vous permet d'imposer qu'une session soit lancée en tant qu'administrateur pour que le script s'exécute.
#Requires -RunAsAdministrator
D. -PSSnapin
Ce paramètre sert à préciser les snap-ins requis pour l'exécution du script. Vous pouvez également indiquer, sur la même ligne (et de manière optionnelle) la version du snap-in à utiliser.
#Requires -PSSnapin DiskSnapin -Version 1.2
Note : Pour tout savoir sur les snapins, rendez-vous ici.
E. -Modules
Ce paramètre sert à spécifier les modules devant être installés sur votre machine préalablement avant l'exécution du script. Le module est absent ? Le script refuse de s'exécuter.
Optionnellement, vous pouvez préciser la version minimum, la version exacte ou la version maximum à utiliser pour ce module. Petite précision d'importance : vous ne pouvez utiliser qu'un seul de ces paramètres à la fois, à vous donc de choisir celui qui se rapproche le plus de ce que vous souhaitez faire.
Voici quelques exemples :
#Requires -Modules ActiveDirectory
➡ Le module ActiveDirectory doit être installé.
#Requires -Modules ActiveDirectory, AzureAD
➡ Les modules ActiveDirectory & AzureAD doivent être préalablement installés.
#Requires -Modules @{ModuleName= "AzureRM.Netcore" ; ModuleVersion= "0.12.0"}
➡ Le module AzureRM.Netcore doit être présent minimum en version 0.12.0.
#Requires -Modules @{ModuleName= "AzureRM.Netcore" ; RequiredVersion= "0.12.0"}
➡ Le module AzureRM.Netcore doit être présent exactement en version 0.12.0.
#Requires -Modules @{ModuleName= "AzureRM.Netcore" ; MaximumVersion= "0.12.0"}
➡ Le module AzureRM.Netcore doit être présent et au maximum en version 0.12.0.
Note : Si l'on souhaite préciser la version du module à utiliser, on passe cette information en plus du nom dans une hashtable : la notation @{}
Vous l’aurez compris, plus besoin de vous lancer dans des tests compliqués en début de script pour vérifier les modules installés ou non, si la session est une session administrateur, etc.
Avec l’instruction Requires, vous allez littéralement vous simplifier la vie !
