Créer un fichier de configuration PSD1 pour un script PowerShell
Sommaire
I. Présentation
Dans ce tutoriel, je vais vous expliquer comment créer un fichier de configuration PSD1 pour votre script PowerShell. Avant cela, nous verrons les différentes possibilités.
Quel est l'objectif de créer un fichier de configuration ? Lorsque l'on développe un script PowerShell, nous sommes bien souvent amenés à intégrer des paramètres lorsqu'il commence à prendre de l'ampleur, afin de l'exécuter avec des valeurs personnalisées. Dans certains cas, et notamment lorsque le script a besoin d'être ultra-flexible et contenir de nombreux paramètres, il est plus simple (et pertinent) de s'appuyer sur un fichier de configuration externe pour son script PowerShell.
Tutoriel disponible au format vidéo :
II. Fichier de configuration en PowerShell : quelles solutions ?
Au moment d'évoquer la notion de fichier de configuration, plusieurs formats nous viennent à l'idée : XML, YAML, JSON, Registre Windows, INI, PSD1, voire même une base de données ou un fichier CSV. Toutes ces solutions sont applicables avec PowerShell, alors on peut se demander lequel choisir.
Les fichiers de configuration XML ne sont pas les plus faciles à lire, mais ils sont facilement exploitables en PowerShell car il y a des commandlets adaptés : Import-CliXml, Export-CliXml et ConvertTo-Xml. Le format JSON est beaucoup plus à la mode et il est utilisé par de nombreuses API, là encore PowerShell propose des commandlets lui correspondant : ConvertFrom-Json et ConvertTo-Json. On peut également consulter la base de registre en PowerShell, importer un fichier CSV facilement avec Import-CSV et aussi manipuler un fichier PSD1. Néanmoins, pour YAML il faudra s'appuyer sur le modèle externe PowerYAML.
Tout cela n'aide pas vraiment à faire le choix puisque nous avons de nombreuses commandes natives à notre disposition.
Personnellement, lorsque j'ai besoin de créer un fichier de configuration pour un script, je m'appuie sur le format PSD1. Pourquoi ? Et bien, il y a plusieurs raisons à cela :
- Compatible avec plusieurs niveaux (arborescence de paramètres) - comme JSON ou YAML
- Compréhensible facilement et lisible pour les personnes habituées à manipuler PowerShell
- Format utilisé pour créer un fichier manifeste d'un module PowerShell
- Récupérer les données à l'aide d'un simple cmdlet (Import-LocalizedData et Import-PowerShellDataFile)
- Gestion native des chemins "Microsoft" contrairement à JSON (où il faut faire un escape sur "\")
Le format PSD1 me semble adapté pour lire un fichier de configuration dans le but de récupérer un ensemble de données. Sinon, en alternative, je vous recommande l'utilisation du format JSON.
III. Fichier de configuration PSD1
Passons maintenant à la démonstration, nous allons créer un fichier de configuration au format PSD1 et le manipuler dans un script concocté pour l'occasion. Dans un fichier PSD1, chaque paramètre s'appelle un clé (key) et il n'y a pas d'en-tête particulière à indiquer.
A. Créer le fichier de configuration PowerShell
Commençons simplement par la création d'un bloc général et l'intégration de nos clés à l'intérieur.
@{
}
Pour créer un sous-bloc, on reprendra ce principe "@{ }" pour le déclarer. Prenons le fichier suivant comme exemple :
@{
SiteName = "IT-Connect"
SiteDetails = @{
URL = "https://www.it-connect.fr"
Protocol = "HTTPS"
Path = "C:\SiteWeb\IT-Connect\"
}
}
Le fichier ci-dessus contient différents paramètres avec une valeur associée : SiteName, SiteDetails.URL, SiteDetails.Protocol, SiteDetails.Path.
Lorsque l'on souhaitera lire un paramètre d'un sous-bloc, il sera indispensable de préciser son "chemin" complet. C'est pour cette raison que ci-dessus, j'ai spécifié "SiteDetails.URL" et pas simplement "URL".
Pour ma part, je vais enregistrer le fichier dans le dossier "C:\scripts" et le nommer "Exemple.psd1".
B. Importer le fichier de configuration PSD1
Il y a deux commandes disponibles pour importer les données d'un fichier PSD1 : Import-LocalizedData et Import-PowerShellDataFile
Le cmdlet "Import-LocalizedData" va gérer la culture, c'est-à-dire qu'il va permettre d'importer une version différente du fichier de configuration en fonction de la langue utilisée par l'utilisateur (il faudra stocker chaque version dans un sous-dossier nommé avec la langue, par exemple fr-FR). Pour importer un fichier, on doit utiliser deux paramètres
Import-LocalizedData -BaseDirectory "C:\scripts\" -FileName "Exemple.psd1"
Le second cmdlet, "Import-PowerShellDataFile" va simplement importer les données du fichier que l'on va spécifier. Le chemin complet vers le fichier est à préciser.
Import-PowerShellDataFile -Path "C:\scripts\Exemple.psd1"
Dans les deux cas, voici ce qui est retourné dans la console :
Name Value
---- -----
SiteDetails {Protocol, URL, Path}
SiteName IT-Connect
Pour consulter les données dans le script, on va stocker le contenu dans une variable :
$ConfigFile = Import-PowerShellDataFile -Path "C:\scripts\Exemple.psd1"
Le fichier de configuration étant indispensable et critique, on va modifier la commande d'import pour stopper l'exécution du script si l'importation échoue :
$ConfigFile = Import-PowerShellDataFile -Path "C:\scripts\Exemple.psd1" -ErrorAction Stop
C. Consulter les valeurs des clés du fichier de configuration
Pour consulter les valeurs définies dans le fichier de configuration, on va lire le contenu de l'objet $ConfigFile. Par exemple, pour afficher le contenu de la clé "SiteName", on va simplement faire :
$ConfigFile.SiteName
Si l'on souhaite afficher les clés du sous-bloc SiteDetails et leurs valeurs :
$ConfigFile.SiteDetails
Voici le retour que l'on obtient :
Name Value ---- ----- Protocol HTTPS URL https://www.it-connect.fr Path C:\SiteWeb\IT-Connect\
Comme expliqué précédemment, pour consulter la valeur d'une clé, le chemin complet doit être spécifié. Par exemple :
$ConfigFile.SiteDetails.Protocol
Pour utiliser une valeur, on peut la stocker dans une variable ou l'appeler directement. Ce qui donne :
$Protocol = $ConfigFile.SiteDetails.Protocol Write-Output "Le site IT-Connect utilise le protocole $Protocol"
ou alors :
Write-Output "Le site IT-Connect utilise le protocole $($ConfigFile.SiteDetails.Protocol)"
Le fait d'utiliser une variable pour stocker la valeur rend la chaîne plus facile à lire, en comparaison de la seconde syntaxe.
Note : si vous modifiez le fichier de configuration, il faut penser à relancer la commande d'import (Import-LocalizedData ou Import-PowerShellDataFile) pour mettre à jour le contenu de la variable $ConfigFile.
Désormais, c'est à vous de jouer et de créer votre propre fichier de configuration pour votre script PowerShell. Dans cet exemple, j'ai utilisé un bloc principal avec un sous-bloc, mais on pourrait créer un ou plusieurs sous-blocs supplémentaires dans le sous-bloc SiteDetails. Le fichier de configuration PSD1 représente une solution flexible pour définir des paramètres.
