Scripts de base

Un script est un ensemble de commandes permettant d'effectuer une tâche.

Objectifs

À la fin de ce chapitre, vous serez capable de :

• Comprendre la structure d’un script (en-tête, paramètres, fonctions, corps).
• Adapter la stratégie d’exécution et lancer un script de manière correcte.
• Appliquer des normes de codage (noms, variables, paramètres) et utiliser le débogage de base.

Script .ps1

Le fichier PowerShell aura une extension .ps1 et un double-clique provoque l'ouverture du fichier avec notepad et non pas son exécution.

Info

Notepad ne supportant pas l'encodage UTF-8, préférer l'utilisation de Notepad++, ou encore mieux de VS Code.

L'execution

Pour exécuter un script PowerShell, on utilise son nom précédé de .\ si l’on se trouve dans le dossier courant.

La commande la plus simple est :

.\MonScript.ps1

Avec chemin complet :

C:\Scripts\MonScript.ps1

Et si ton script attend des paramètres :

.\MonScript.ps1 -Nom "John" -Age 25

L'on peut aussi l'exécuter le script depuis ISE, depuis une boite de commande ou en utilisant le planificateur de tâches. Dans certains cas, les droits administrateurs sont requis.

Info

Par défaut, la stratégie de sécurité de Microsoft bloque l'exécution des scripts (Restricted).

Info

On active l'exécution des scripts sur une machine avec la commande Set-ExecutionPolicy et il est nécessaire d'avoir les droits administrateur. La stratégie Unrestricted s'applique dans notre cas, car nous sommes dans une école. Ce ne serait pas prudent dans une entreprise.

La structure

Un script est constitué de plusieurs zones d'un script sont :

• l'en-tête;
• la zone pour les paramètres et les variables;
• les fonctions;
• et enfin le corps du script.

L'en-tête

Pour les commentaires, on utilise le #, pour une seule ligne :

# commentaire
Write-Host "HELLO"

Et <#...#> pour plusieurs lignes :

<# commentaires
	commentaires
	commentaires
#>

Dans le canevas fourni dans la première page du cours, l'en-tête du fichier est composée de plusieurs parties.

L'aide de PowerShell utilise ces différentes parties : .NOTES, .SYNOPSIS, .DESCRIPTION,...

Chaque partie correspond à une rubrique de l'aide. Il est impératif de respecter le point et les majuscules.

Pour la totalité des possibilités pour l'aide, voir sur le site de Microsoft : Powershell help.

La partie du code qui affiche l'aide utilise $MyInvocation.MyCommand.Path pour obtenir le chemin complet du script en cours d'exécution, puis le passe à Get-Help :

Get-Help $MyInvocation.MyCommand.Path

$MyInvocation est une variable automatique qui contient des métadonnées sur l'exécution en cours (chemin du script, numéro de ligne, etc.). C'est bien Get-Help qui interprète et affiche l'aide commentée.

Lorsque l'aide s'affiche, le résultat donne :

Les parties .NOTES, .SYNOPSIS, .DESCRIPTION et .EXEMPLE sont toujours présentes et les autres sont ajoutées si besoin.

Possible seulement 1 fois : .NOTES, .SYNOPSIS, .DESCRIPTION, .OUTPUTS

Possible plusieurs fois : .PARAMETER, .EXEMPLE, .LINK

Élément	Description
.NOTES	informations sur l'auteur, date
.SYNOPSIS	max 1 ligne, comme un titre
.DESCRIPTION	explications complètes sur ce que fait le script, ce qui se passe en cas d'erreur, le résultat attendu
.PARAMETER	le nom du paramètre, ce qu'il fait, son type, les contraintes,... et un seul à la fois
.OUTPUTS	ce qui est généré, fichier d'erreurs, création d'utilisateur(s), modification d'une clé,...
.EXEMPLE	ligne pour lancer le script et aussi un seul à la fois et bien si min 2 exemples
.LINK	lien sur un site ou prérequis comme nom d'un ou plusieurs script(s) (par exemple : utilisation de 2 scripts Create-User et Create-Group dans un script Add-UserGroup)

Info

A noter que l'on peut aussi utiliser .INTPUTS pour défini ce qui peut provenir du pipe.

Normes de codage

On respecte les normes de codage définies dans l'école.

• Pour le nom des scripts, on utilise Firstname-Verb-Noun, avec des majuscules pour la première lettre du verbe et du nom.
• On ajoute le prénom devant le nom du script, pour que l'enseignant puisse différencier les scripts lors de contrôles !!!
• Pour les noms des paramètres (après "param") et des fonctions dans le script, on utilise UpperCamelCase.
• Pour les variables, on utilise lowerCamelCase.
• La notion de guard clauses permet l'optimisation du code en évitant de le parcourir entièrement en cas d'informations fausses ou manquantes.
• Il faut éviter d'utiliser la partie else et plutôt ajouter un exit dans la partie if .

Exemple de test vérification des droits administrateur :

# Vérification des droits administrateur
$estAdmin = ([Security.Principal.WindowsPrincipal] `
    [Security.Principal.WindowsIdentity]::GetCurrent()
).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

if (-not $estAdmin) {
    Write-Error "Ce script doit être exécuté avec des droits administrateur."
    exit 1
}

Write-Host "Le script est bien exécuté en tant qu'administrateur."

Les paramètres

Dans le script, la première ligne de code doit être param

Dans le cas d'un script, les paramètres non explicitement sélectionnés seront pris dans l'ordre, mais dans le cas d'une cmdlet, il ne tient compte que du premier de la liste.

Utilisation

Si le script est exécuté avec les paramètres.

Les paramètres d'un script que l'on a codé auront le même comportement, à savoir que lorsque l'on tape le - la liste des paramètres s'affiche dans un menu déroulant.

Dans l'aide, la liste des paramètres sera définie par .PARAMETER.

Concernant le menu des paramètres, il est établi lorsque l'on définit les variables du script.

Le corps du script se situe après la définition des paramètres et du test de la présence du(es) paramètre(s)

Ces attributs

On peut donner des caractéristiques particulières à un paramètre, dans le même esprit que pour typer une variable !

param(
    [Parameter(Mandatory=$True, Position=0, ValueFromPipeline=$True)][string]$RequiredParam,
    $NotRequiredParam
)

Ci-dessus 2 paramètres sont déclarés $RequiredParam et $NotRequiredParam.

• Ici, seul $RequiredParam possède des attributs de configuration avancés.
• $NotRequiredParam : déclare un second paramètre non typé et non obligatoire.

Description de la configuration avancée :

Élément	Explication
param(...)	définit les paramètres du script ou de la fonction
[Parameter(...)]	ajoute des options de configuration au paramètre qui suit
Mandatory=$True	rend ce paramètre obligatoire
Position=0	permet de passer ce paramètre en premier, sans devoir écrire son nom
ValueFromPipeline=$True	autorise la réception de la valeur depuis le pipeline
[string]$RequiredParam	déclare un paramètre nommé RequiredParam de type chaîne de caractères

Les arguments

Les arguments seront mis "de manière libre" après le nom du script.

Dans la liste des variables automatiques, il y a $Args et c'est un tableau des arguments passés lors de l'exécution d'un script.

Ce tableau peut contenir plusieurs sortes d'éléments et sa longueur s'obtient avec $Args.length.

Un script qui ne contient que $args, affichera le contenu du tableau des arguments fournis lors du lancement du script.

Exemple de test des paramètres :

# Test des paramètres du script
param(
    [string]$Nom,
    [int]$Age
)

if ([string]::IsNullOrWhiteSpace($Nom)) {
    Write-Error "Le paramètre -Nom est obligatoire."
    exit 1
}

if ($Age -lt 0) {
    Write-Error "Le paramètre -Age doit être supérieur ou égal à 0."
    exit 1
}

Write-Host "Paramètres valides : Nom=$Nom, Age=$Age"

Debug

Dans ISE, il y a un menu Déboguer.

Dans ISE et dans VS Code, les raccourcis sont :

• F5 : exécuter
• F9 : ajouter un point de debug
• F10 : pas à pas (step over)
• F11 : pas à pas détaillé (step into)
• On peut voir le contenu d'une variable en passant dessus lentement avec le curseur.

Avec VS Code, il faut ajouter un fichier texte et le sauvegarder en choisissant le type Powershell, et surtout avec l'extension .ps1.

Résumé

• Un script PowerShell est structuré et documenté via l’en-tête (comment-based help).
• Les paramètres et leurs attributs rendent les scripts plus robustes et réutilisables.
• Les normes de codage et le débogage facilitent la maintenance et le diagnostic.

Exercices

📥 Exo Scripts Base (PDF)