Chemin de module PowerShell : Code réutilisable sans copier-coller

Travailler avec des modules PowerShell est une partie importante de l’automatisation PowerShell. Lorsque vous commencez à apprendre PowerShell, les premières étapes consistent généralement à utiliser des commandes simples. Cela conduit à la création de scripts, qui conduit ensuite à la création de fonctions.

En utilisant des fonctions, vous pouvez rendre vos scripts plus modulaires. Cela vous permet d’utiliser le même code à de nombreux endroits sans avoir à copier et coller du code partout. L’utilisation de fonctions vous permet de passer moins de temps à apporter la même modification au même code partout où il est utilisé. Au lieu de cela, vous pouvez travailler sur l’amélioration de votre code en un seul endroit.

Pour aller plus loin avec les fonctions, vous pouvez combiner ces fonctions dans un module.

A module is a collection of functions in a text file with a psm1 extension. There are some optional additions, such as a module manifest and comment-based or external help that may also be included. These will be covered later on.

Prérequis

I’ll be using Windows PowerShell 5.1 in this article. If you’re using an older version or PowerShell Core, your mileage may vary as to results you see.

Interaction avec les modules

Dès que vous ouvrez une session PowerShell, vous commencez avec deux modules. Le premier est Microsoft.PowerShell.Utility qui contient de nombreuses fonctions PowerShell de base que vous utilisez déjà. L’autre module est PSReadline. Vous pouvez voir ces modules de départ en utilisant la commande Get-Module.

Cela dit, cette liste n’est pas exhaustive de tous les modules disponibles. Depuis PowerShell 3, les modules installés sont importés au besoin. Si vous utilisez une version plus ancienne de PowerShell, vous devrez utiliser la commande Import-Module pour importer d’abord le module avant d’utiliser l’une des commandes.

Il y a des moments où vous voudrez toujours utiliser Import-Module même dans les versions ultérieures. Si vous souhaitez importer un module après son installation, vous pouvez utiliser Import-Module de cette manière :

Alors que Get-Module affiche tous les modules importés, vous ne verrez pas les modules qui n’ont pas encore été importés. Vous pouvez alors utiliser le paramètre ListAvailable pour afficher tous les autres modules disponibles.

Toutes les commandes ne sont pas affichées par défaut

La propriété ExportedCommands contient une liste de toutes les commandes disponibles exportées par le module. Vous pouvez constater certaines différences entre cette liste et ce qui se trouve dans le fichier du module. Les commandes exportées sont une fonctionnalité intégrée au manifeste du module qui permet à l’auteur de laisser une fonction masquée. Les auteurs de modules peuvent également utiliser la cmdlet Export-ModuleMember, mais cela dépasse le cadre de cet article.

Les auteurs de modules peuvent souhaiter masquer une fonction car elle est destinée à soutenir d’autres fonctions et n’est pas destinée à être utilisée par l’utilisateur. Pour masquer une fonction, l’auteur l’exclurait du tableau FunctionsToExport dans le manifeste. Ici, vous pouvez voir une vue détaillée de la propriété ExportedCommands.

Importation de modules

Il existe de nombreuses façons de commencer à utiliser des modules. Vous pouvez importer manuellement le module en utilisant le chemin vers les fichiers du module. Cela vous permet de tester et de mettre à jour le module sans avoir à faire beaucoup de travail. Cependant, cela ne permet pas une grande portabilité, car vous devriez utiliser le chemin exact vers le module. PowerShell n’importera pas automatiquement les modules qui ne se trouvent pas dans la variable $env:PSModulePath.

Importation sélective des commandes

Vous pouvez utiliser Import-Module pour n’importer que des fonctions spécifiques au lieu du module entier en utilisant le paramètre Function. Cela peut vous faire gagner du temps lors de l’importation de modules à partir de systèmes distants, tels que les modules Office 365.

Tous les modules utilisateur

Les modules installés pour tous les utilisateurs sont placés dans C:\Program Files\WindowsPowerShell\Modules. Ce répertoire contient de nombreux modules pré-installés, y compris tous les modules installés à l’aide de Install-Module en utilisant la portée par défaut AllUsers.

Modules utilisateur actuels

Si vous installez un module mais que vous voulez qu’un seul utilisateur l’utilise, il existe une portée CurrentUser. Cela place les fichiers du module dans votre dossier Documents à C:\Users\<nom_utilisateur>\Documents\WindowsPowerShell\Modules. Cela peut être utile dans un environnement où vous utilisez la redirection de dossier avec le dossier Documents.

Dans ce cas, vous pouvez installer un module sur un ordinateur et l’utiliser sur un autre, car ils partageraient tous deux le même dossier Documents.

Modules système

Pour plus de complétude, il existe également un répertoire de modules à l’emplacement suivant : C:\Windows\System32\WindowsPowerShell\1.0\Modules. Techniquement, un module placé dans cet emplacement serait importé de la même manière que les autres emplacements, mais cela n’est pas recommandé car cet emplacement est réservé aux modules système de Microsoft.

Le nommage est important

Vous pouvez placer manuellement votre module dans l’un de ces emplacements pour le rendre disponible par défaut avec une nouvelle session, mais vous devez vous assurer de respecter les règles de nommage requises pour les modules. Le dossier dans lequel les fichiers du module sont placés doit avoir le même nom que le fichier du module psm1 et que le manifeste du module psd1 s’il en existe un.

L’utilisation de la commande Get-Module -ListAvailable dont nous avons parlé précédemment fait référence à ces emplacements. Vous pouvez voir tous les chemins des modules en utilisant la commande $env:PSModulePath -Split ';'. Vous pourriez remarquer d’autres chemins dans la liste que ceux qui sont affichés ici. De nombreux programmes ajoutent leurs propres chemins de modules lorsqu’ils sont installés. Un exemple de cela est SQL, qui a ses propres modules inclus dans ses propres chemins de modules.

Il existe également certains modules que vous installeriez avec un processus différent. L’un des exemples les plus significatifs est le module ActiveDirectory. De Windows 7 à Windows 10 1803, vous l’installeriez avec l’outil d’administration du serveur distant (RSAT).

Sur les nouvelles versions de Windows 10 (1809+), ce module est uniquement disponible via les fonctionnalités à la demande. L’installation de RSAT installe les modules ActiveDirectory et bien d’autres que vous utiliseriez pour administrer d’autres rôles Windows. Sur les systèmes d’exploitation Windows Server, ces modules sont installés via le Gestionnaire de serveur.

Importation de modules distants (Implicit Remoting)

Il existe des cas où il n’est pas pratique d’avoir un module en cours d’exécution localement. Il est préférable de se connecter à un appareil distant et d’importer un module installé sur celui-ci. Lorsque vous le faites, les commandes sont réellement exécutées sur la machine distante. Cela est fréquemment utilisé avec les modules Office 365 de Microsoft. Beaucoup d’entre eux se connectent à un serveur Office 365 qui importe ensuite un module. Lorsque vous exécutez l’une des commandes, elles sont exécutées sur le serveur distant, puis la sortie est renvoyée à votre session.

Une autre utilisation de l’importation de modules distants est lorsque vous n’avez pas le module installé localement. C’est ce qui se produirait si vous n’aviez pas le module ActiveDirectory installé, mais que vous essayiez de l’importer.

Pour importer un module distant, vous devez d’abord créer une PSSession. Vous pouvez utiliser la commande New-PSSession pour créer la session. Ensuite, vous importeriez le module disponible sur l’appareil distant en utilisant le paramètre PSSession avec la commande Import-Module.

PS51> $AdminServer = New-PSSession -ComputerName $AdminServerName -Credential (Get-Credential)
PS51> Import-Module -Name ActiveDirectory -PSSession $AdminServer -Prefix 'Rmt'

L’utilisation de cette méthode d’importation de modules distants permet une exécution plus rapide du code dans un environnement distribué. Par exemple, si vous travaillez depuis votre ordinateur, mais que les serveurs sur lesquels vous travaillez se trouvent à travers les États-Unis, il peut prendre beaucoup plus de temps pour exécuter certaines commandes localement sur les serveurs. En revanche, l’exécution des commandes sur un serveur et l’envoi de la sortie à votre session locale est beaucoup plus rapide.

Ajout d’un préfixe de module

Vous pouvez également ajouter un préfixe aux fonctions importées depuis la machine distante. Cette option est disponible lors de l’importation de modules locaux, mais est rarement utilisée en dehors des tests de différentes versions d’un module côte à côte.

Si vous exécutez la commande d’importation ci-dessus et que voici ce que vous verriez lorsque vous regardez les commandes :

Dans ce cas, vous pouvez utiliser un préfixe pour indiquer qu’il ne s’agit pas d’un module local. Cela peut être utilisé dans les cas où vous importez un module qui est également disponible localement. L’ajout du préfixe réduit la confusion quant à l’endroit où le code est exécuté.

Suppression de modules

Vous pouvez également supprimer un module de la session en cours sans utiliser Remove-Module. Cela supprime un module de la session locale sans supprimer les fichiers du module. Vous pouvez utiliser cela dans le cas où vous utilisiez une session distante pour utiliser un module. Vous pourriez utiliser Remove-Module pour nettoyer votre session, puis déconnecter la session distante.

Une autre utilisation de Remove-Module est si vous apportez des modifications à un module et que vous ne souhaitez pas lancer une nouvelle session PowerShell. Dans ce cas, vous utiliseriez Remove-Module suivi de Import-Module pour le recharger dans votre session. Alternativement, vous pouvez utiliser le paramètre Force avec Import-Module. Cela effectuera le déchargement et le rechargement complet du module pour vous.

Qu’est-ce qui constitue un module PowerShell

A module can consist of one or more files. To meet the minimum requirements for a module, you must have a module file. This can be a PSM1 file or any other module file such as a binary module file. To build upon that, your psm1 should have functions defined in it, or it will not be much use to anyone.

Bien qu’il n’y ait pas d’exigences concernant l’apparence ou les actions des fonctions, il existe certaines directives. Il est généralement préférable d’avoir toutes les fonctions dans un module construit autour du même concept.

Les modules contiennent des fonctions similaires

Par exemple, le module ActiveDirectory ne comprend que des fonctions qui interagissent d’une manière ou d’une autre avec Active Directory. En général, les noms des fonctions contiennent également un préfixe. Reprenons l’exemple du module ActiveDirectory, tous les noms de noms des fonctions commencent par AD.

L’utilisation de ces directives facilite la découverte des fonctions. Imaginez que vous venez d’importer ce nouveau module et que vous souhaitez parcourir les fonctions. C’est beaucoup plus facile à faire si toutes les fonctions ont une structure de nom similaire. Bien que vous puissiez fréquemment voir des modules commençant par PS, ce préfixe est officiellement réservé aux modules Microsoft uniquement. Vous ne créerez probablement pas de problème si vous utilisez PS au début de votre module, mais vous pourriez créer un conflit avec un autre nom de module.

En utilisant ces directives, si vous aviez un ensemble de fonctions qui interagissent toutes avec le registre, vous pourriez avoir quelque chose comme :

function Get-ATARegistryKey {...}

function Set-ATARegistryKey {...}

Manifeste de module

Pour compléter le fichier de module texte, vous pouvez également inclure un manifeste de module. Ces fichiers ont une extension PSD1 et contiennent des métadonnées sur le module. C’est là que vous incluriez des informations sur l’auteur, une description du module, d’autres modules requis et de nombreux autres attributs. Pour publier sur un référentiel, il est nécessaire de renseigner les champs Auteur et Description.

Voici un exemple de manifeste que nous pourrions avoir pour notre module de registre :

#Manifeste de module pour le module 'ATARegistry'
#Généré par : Tyler
#Généré le : 8/11/2019
@{
	#Module de script ou fichier binaire associé à ce manifeste.
	RootModule = 'ATARegistry'
	#Numéro de version de ce module.
	ModuleVersion = '1.0'
	#Éditions PSEdition prises en charge
	#CompatiblePSEditions = @()
	#ID utilisé pour identifier de manière unique ce module
	GUID = 'fef619fa-016d-4b11-a09d-b222e094de3e'
	#Auteur de ce module
	Author = 'Tyler Muir'
	#Société ou fournisseur de ce module
	CompanyName = 'Adam the Automator'
	#Déclaration de droits d'auteur pour ce module
	Copyright = '(c) 2019 tyler. All rights reserved.'
	#Description des fonctionnalités fournies par ce module
	Description = 'This is a test module.'
	#Version minimale du moteur Windows PowerShell requise par ce module
	#PowerShellVersion = ''
	#Nom de l'hôte Windows PowerShell requis par ce module
	#PowerShellHostName = ''
	#Version minimale de l'hôte Windows PowerShell requise par ce module
	#PowerShellHostVersion = ''
	#Version minimale de Microsoft .NET Framework requise par ce module. Cette condition préalable est valide uniquement pour l'édition PowerShell Desktop.
	#DotNetFrameworkVersion = ''
	#Version minimale du runtime du langage commun (CLR) requise par ce module. Cette condition préalable est valide uniquement pour l'édition PowerShell Desktop.
	#CLRVersion = ''
	#Architecture du processeur (None, X86, Amd64) requise par ce module
	#ProcessorArchitecture = ''
	#Modules qui doivent être importés dans l'environnement global avant d'importer ce module
	#RequiredModules = @()
	#Assemblées qui doivent être chargées avant d'importer ce module
	#RequiredAssemblies = @()
	#Fichiers de script (.ps1) qui sont exécutés dans l'environnement de l'appelant avant d'importer ce module.
	#ScriptsToProcess = @()
	#Fichiers de type (.ps1xml) à charger lors de l'importation de ce module
	#TypesToProcess = @()
	#Fichiers de format (.ps1xml) à charger lors de l'importation de ce module
	#FormatsToProcess = @()
	#Modules à importer en tant que modules imbriqués du module spécifié dans RootModule/ModuleToProcess
	#NestedModules = @()
	#Fonctions à exporter à partir de ce module, pour de meilleures performances, n'utilisez pas de jokers et ne supprimez pas l'entrée, utilisez un tableau vide s'il n'y a pas de fonctions à exporter.
	FunctionsToExport = @('Get-RegistryKey','Set-RegistryKey')
	#Cmdlets à exporter à partir de ce module, pour de meilleures performances, n'utilisez pas de jokers et ne supprimez pas l'entrée, utilisez un tableau vide s'il n'y a pas de cmdlets à exporter.
	CmdletsToExport = @()
	#Variables à exporter à partir de ce moduleVariablesToExport = '*'
	#Alias à exporter à partir de ce module, pour de meilleures performances, n'utilisez pas de jokers et ne supprimez pas l'entrée, utilisez un tableau vide s'il n'y a pas d'alias à exporter.
	AliasesToExport = @()
	#Ressources DSC à exporter à partir de ce module
	#DscResourcesToExport = @()
	#Liste de tous les modules empaquetés avec ce module
	#ModuleList = @()
	#Liste de tous les fichiers empaquetés avec ce module
	#FileList = @()
	#Données privées à transmettre au module spécifié dans RootModule/ModuleToProcess. Cela peut également contenir un hashtable PSData avec des métadonnées supplémentaires utilisées par PowerShell.
	PrivateData = @{
		PSData = @{
			#Balises appliquées à ce module. Elles facilitent la découverte des modules dans les galeries en ligne.
			#Tags = @()
			#URL de la licence de ce module.
			#LicenseUri = ''
			#URL du site Web principal de ce projet.
			#ProjectUri = ''
			#URL d'une icône représentant ce module.
			#IconUri = ''
			#Notes de version de ce module
			#ReleaseNotes = ''
		} 
		#Fin du hashtable PSData
	} 
	#Fin du hashtable PrivateData
	#URI HelpInfo de ce module
	#HelpInfoURI = ''
	#Préfixe par défaut des commandes exportées à partir de ce module. Remplacez le préfixe par défaut en utilisant Import-Module -Prefix.
	#DefaultCommandPrefix = ''
}

Bien que cela puisse sembler intimidant au début, Microsoft a une cmdlet pratique que vous pouvez utiliser pour générer un manifeste de module. La commande incluse est New-ModuleManifest. Pour générer le manifeste mentionné ci-dessus, vous pouvez utiliser :

PS51> New-ModuleManifest -Path .\Scripts\TestModule.psd1 -Author 'Tyler Muir' -CompanyName 'Adam the Automator' -RootModule 'TestModule.psm1' -FunctionsToExport @('Get-RegistryKey','Set-RegistryKey') -Description 'This is a test module.'

Fichiers d’aide externes

Vous pouvez également trouver des fichiers d’aide externes dans certains modules. Ils peuvent être identifiés par le <NomDuModule>-Help.xml à la fin du nom du fichier. Ces fichiers d’aide externes contiennent les mêmes informations que celles qui se trouvent normalement dans l’aide basée sur les commandes que vous pouvez trouver dans la définition d’une fonction.

Cela nécessiterait également d’ajouter # .ExternalHelp <CheminDuModule>-Help.xml à votre fonction pour qu’elle fonctionne correctement lors de l’utilisation de la commande Get-Help après l’importation du module. Il est généralement courant de trouver des fichiers d’aide externes avec des modules très volumineux et, de ce fait, ils sont hors de la portée.

Fichiers associés

Bien que ce soient les types de fichiers les plus courants que vous verrez dans un module, ce ne sont pas les seuls fichiers. Parfois, vous verrez des fichiers binaires en plus d’un module texte car il y a d’autres dépendances. En explorant les chemins des modules, vous pouvez trouver de nombreux exemples de types de fichiers supplémentaires dans les modules.

Pour que les fichiers de module non standard soient correctement publiés, vous devez inclure d’autres fichiers dans le paramètre FileList de votre manifeste de module.

Dans le manifeste du module, vous remarquerez de nombreux autres paramètres qui sont actuellement vides. Vous pouvez les utiliser pour définir d’autres exigences pour l’utilisation de votre module. Par exemple, vous pouvez définir les versions de PowerShell avec lesquelles le module peut fonctionner. Si vous essayez d’importer le module sur une version non prise en charge de PowerShell, voici ce que vous verrez :

PSRepositories

l’une des principales options de distribution pour les modules est un PSRepository. À un niveau élevé, un PSRepository est un emplacement local où plusieurs personnes ou plusieurs appareils peuvent accéder aux fichiers du module. Il s’agit fréquemment de serveurs Web sur lesquels vous pouvez publier des fichiers.

Vous pouvez également utiliser un répertoire pour le référentiel, mais cela limite les fonctionnalités de votre référentiel. Vous pouvez héberger vous-même un PSRepository, ou vous pouvez utiliser l’une des nombreuses options disponibles sur Internet, comme la Galerie PowerShell. Vous pouvez voir vos PSRepositories en utilisant la commande Get-PSRepository.

Par défaut, vous n’aurez qu’une seule entrée, qui sera pour la Galerie PowerShell. Vous remarquerez peut-être qu’elle est marquée comme non approuvée. Cela signifie que PowerShell vous informe que, en utilisant la Galerie PowerShell, vous pouvez utiliser du code qui n’a pas été écrit et approuvé par Microsoft. Cela signifie que vous devrez donner une autorisation explicite avant d’installer des modules à partir de celle-ci.

Ajout de PSRepositories

Vous pouvez également ajouter vos propres référentiels. Pour faire confiance à la Galerie PowerShell, vous pouvez exécuter la commande Get-PSRepository -Name PSGallery | Set-PSRepository -InstallationPolicy Trusted ou vous pouvez accepter l’avertissement la première fois que vous installez un module à partir de la Galerie PowerShell.

Toutes les commandes que vous utiliseriez pour interagir avec ces PSRepositories peuvent être trouvées dans le module PowerShellGet. Vous pouvez voir les fonctions ici :

Il se peut que le module PowerShellGet doive être mis à jour avant d’interagir avec certains dépôts.

Recherche de modules

Une autre fonctionnalité clé de l’utilisation d’un PSRepository est la possibilité de rechercher des modules. Cela se fait à l’aide de la commande Find-Module. Il existe plusieurs façons de filtrer pour trouver précisément ce que vous recherchez, mais pour l’instant, vous pouvez rechercher les modules VMware de cette manière :

Cela affichera tous les modules qui commencent par VMware. Bien que la plupart d’entre eux proviennent de VMware, vous devez regarder l’attribut de l’auteur pour voir qui a publié le module.

Comme n’importe qui peut télécharger sur PowerShell Gallery, il existe des milliers de modules disponibles. Cela signifie que vous pouvez trouver des modules qui ne fonctionnent pas correctement pour votre cas d’utilisation. La plupart des modules que vous trouverez sont open source, vous pouvez donc contribuer à les améliorer.

Installation de modules

Pour utiliser la commande Install-Module, vous devez disposer d’un PSRepository de confiance qui héberge le module. Il peut s’agir de PowerShell Gallery, d’un autre PSRepository sur Internet ou d’un site auto-hébergé. Vous pouvez utiliser la commande Find-Module pour afficher le module avant de l’installer.

Vous pouvez également définir la version d’un module en utilisant les paramètres MinimumVersion, MaximumVersion ou RequiredVersion.

Pour voir tous les modules installés à l’aide de la commande Install-Module, vous pouvez utiliser la commande Get-InstalledModule. Cela listera tous les modules installés dans la portée AllUsers ou votre portée CurrentUser.

Désinstallation des modules

Tout comme vous pouvez installer un module, vous pouvez également le désinstaller. Si le module n’a pas été installé via la commande Install-Module, vous ne pourrez pas le désinstaller avec la commande Uninstall-Module.

Comme vous pouvez le voir ici, nous essayons de désinstaller le module ActiveDirectory. Étant donné que ce module n’est pas installé avec Install-Module, vous recevrez une erreur lorsque vous essayez d’utiliser Uninstall-Module. Pour désinstaller ce module, vous devriez inverser ce que vous avez utilisé pour l’installer.

Pour voir une désinstallation réussie d’un module, vous pouvez désinstaller le module VMware.PowerCLI que vous avez installé précédemment.

Même si vous avez désinstallé VMware.PowerCLI, vous pouvez voir qu’il reste encore de nombreuses dépendances installées. Si vous souhaitez désinstaller tous les modules, vous pouvez utiliser la commande Get-InstalledModule VMware.* | Uninstall-Module -Force.

La raison pour laquelle vous auriez autant de difficultés à désinstaller complètement ce module est qu’il a de nombreuses dépendances. De plus, certains de ces modules sont des dépendances les uns des autres, c’est pourquoi le paramètre Force serait nécessaire.

Mise à jour des modules

Maintenant que vous savez comment installer et désinstaller un module, vous vous demandez peut-être comment mettre à jour un module que vous avez installé.

Tout comme les autres processus, si le module n’a pas été installé à l’aide de la commande Install-Module, vous ne pouvez pas le mettre à jour en utilisant les commandes PowerShell. Vous pouvez utiliser la commande Update-Module pour mettre à jour un module vers la dernière version ou vers une version spécifique plus récente.

Il existe également un interrupteur AllowPreRelease qui vous permet de mettre à jour vers une version qui n’a pas encore été officiellement publiée. Parfois, cela peut être utile car il peut y avoir une correction d’un bogue que vous rencontrez ou une nouvelle fonctionnalité qui a été ajoutée et que vous souhaitez utiliser.

Inspection/Sauvegarde d’un module

Une des commandes beaucoup moins utilisées mais très utiles lors de la vérification des modules avant leur utilisation est la commande Save-Module. En utilisant cette commande, vous pouvez télécharger un module vers un chemin sans l’installer.

Vous pouvez ensuite inspecter les fichiers et si le module n’est pas un module binaire, vous pouvez l’ouvrir et examiner le code qui le compose. Cela peut être utile non seulement pour vous assurer qu’un module ne fait rien de malveillant, mais aussi pour apprendre comment les autres structurent leurs modules.

Dans cet exemple, non seulement le module VMware.PowerCLI est téléchargé, mais aussi toutes les dépendances. Voici ce qui s’affiche dans le dossier VMware.PowerCLI:

Ceci est un bon exemple montrant qu’il y a parfois des fichiers de module non standard inclus dans le module, tels que le contrat de licence utilisateur final.

Écrire votre propre module

Vous avez maintenant vu comment interagir avec le module de quelqu’un d’autre. Maintenant, vous voulez apprendre à créer le vôtre afin de pouvoir commencer à optimiser votre code pour la scalabilité.

Créer des fichiers de modèle

Tout d’abord, vous devez créer un dossier pour tous vos fichiers de module. Une fois que vous avez le conteneur, vous devez créer votre fichier de module. Vous devez vous assurer que votre fichier de module a le même nom que votre dossier, sinon lorsque vous essayez de publier votre module, PowerShell ne découvrira pas le module correctement.

PS51> New-Item -Path .\Scripts -Name ATARegistry -ItemType Directory
PS51> New-Item -Path .\Scripts\ATARegistry -Name ATARegistry.psm1

Maintenant, vous voulez également utiliser un manifeste, vous devrez aussi lui donner le même nom que le conteneur et le fichier de module.

PS51> New-ModuleManifest -Path .\Scripts\ATARegistry\ATARegistry.psd1 -Author 'Tyler Muir' -CompanyName 'Adam the Automator' -RootModule ATARegistry.psm1 -Description 'Used for interacting with registry keys'

Avec le conteneur, le fichier de module et le fichier de manifeste, vous avez un module entièrement fonctionnel. Vous pouvez publier ce module sur un PSRepository et commencer à l’installer n’importe où vous le souhaitez. Cependant, étant donné que le fichier de module est vide, il ne vous sera probablement pas très utile. Vous pouvez toujours utiliser ces fichiers pour tester la publication afin de vous assurer que votre référentiel fonctionne.

Inscription d’un PSRepository

Avant de pouvoir publier votre module, vous devrez ajouter un autre PSRepository à votre session. Pour les tests, vous pouvez utiliser un chemin local comme votre PSRepository, car il sera facile à configurer et à supprimer.

Normalement, si vous alliez configurer un PSRepository avec un répertoire, vous voudriez vous assurer que plusieurs ordinateurs y ont accès. Vous pouvez créer un référentiel local de cette manière :

PS51> New-Item -Path C:\ -Name Repo -ItemType Directory
PS51> Register-PSRepository -Name 'LocalRepo' -SourceLocation 'C:\Repo' -PublishLocation 'C:\Repo' -InstallationPolicy Trusted

Si vous ne téléchargiez qu’à partir du PSRepository et ne publiez jamais, vous pouvez exclure le paramètre PublishLocation.

Publication de votre module

Étant donné que vous avez déjà défini la politique d’installation en tant que fiable, vous ne recevrez pas de confirmation pour autoriser l’installation d’un module à partir du référentiel. Maintenant que vous avez un nouveau PSRepository disponible, vous pouvez publier votre module en utilisant Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo.

Après avoir publié votre module, vous pouvez utiliser les commandes ci-dessus pour trouver le module et l’installer.

Maintenant que vous avez installé le module, vous pouvez utiliser Get-Module pour voir le module importé dans votre session locale. Étant donné que vous n’avez ajouté aucune fonction au tableau FunctionsToExport dans le manifeste, la propriété ExportedCommands est vide.

Ajout à votre module

Maintenant que vous savez que vous pouvez publier et installer votre module, vous pouvez commencer à lui ajouter des fonctionnalités. Vous pouvez ajouter une fonction pour renvoyer une clé de registre, de sorte que cela ressemble à ceci :

function Get-ATARegistryKey {
    param (
        [string]$Path
    )
    Get-Item $Path
}

Si vous avez laissé le manifeste tel quel et avez essayé de charger votre nouveau module, vous rencontreriez deux problèmes. Le premier est que vous recevriez une erreur indiquant que la version de votre module existe déjà dans votre référentiel. C’est parce que vous n’avez pas modifié la version du module dans le fichier de manifeste.

Exportation des fonctions du module

L’autre problème serait qu’après avoir importé le module, vous ne verriez toujours aucune fonction dans la propriété ExportedCommands car vous n’avez pas ajouté votre nouvelle fonction au manifeste.

Bien que votre fonction puisse être utilisée sans la répertorier dans la liste FunctionsToExport, cela rendrait beaucoup plus difficile de la localiser.

Tant que vous ne définissez pas un tableau vide, @(), pour votre FunctionsToExport, toutes les fonctions, variables et alias sont exportés par défaut.

Pour résoudre ces deux problèmes, vous pouvez mettre à jour votre fichier de module comme ceci :

ModuleVersion = '1.1'
FunctionsToExport = 'Get-RegistryKey'

Maintenant que vous avez ajouté une fonction à votre module et que vous avez mis à jour votre manifeste pour refléter ces changements, vous pouvez publier la nouvelle version de votre module en utilisant la même commande qu’auparavant.

PS51> Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo.

Choisir entre FunctionsToExport et Export-ModuleMember

Il existe deux fonctionnalités similaires dans PowerShell lors de l’exportation des membres d’un module. Le défi consiste à choisir entre les deux. Les deux sont corrects, mais l’un peut mieux fonctionner pour vous, selon vos besoins.

Lorsque vous souhaitez contrôler dynamiquement les fonctions à exporter, utilisez Export-ModuleMember car vous pouvez passer une liste de fonctions à exporter. Cela est généralement utilisé lors de l’inclusion de plusieurs fichiers PS1 de fonctions individuelles. En divisant les fonctions internes dans un dossier privé et les fonctions exportables dans un dossier public, vous pouvez facilement exporter celles-ci en passant toutes les fonctions publiques à la fonction Export-ModuleMember.

A few notes about Export-ModuleMember:

• Remplace le comportement de FunctionsToExport, par conséquent, si une commande Export-ModuleMember est utilisée, FunctionsToExport n’a aucun effet.
• Export-ModuleMember n’exporte pas les variables et les alias sans les définir explicitement, contrairement à FunctionsToExport, qui exporte ces valeurs.
• Plusieurs commandes Export-ModuleMember peuvent être utilisées et elles s’empilent plutôt que de prendre le pas sur les précédentes.

Si vous ne prévoyez pas d’avoir de modifications dans votre liste de fonctions, l’utilisation de la configuration FunctionsToExport dans le manifeste du module fonctionne très bien et ne nécessite pas l’exportation explicite de variables et d’alias.

Pour mettre à jour votre module

La dernière étape consiste à mettre à jour votre module dans votre session pour pouvoir utiliser les fichiers mis à jour. En utilisant Update-Module ATARegistry, vous téléchargez la mise à jour que vous venez de publier dans le dépôt.

Maintenant, vous pouvez voir que vous avez la nouvelle version du module et vous pouvez voir la fonction que vous avez définie dans le manifeste.

Construction du contenu d’aide

Une des options qui a été mentionnée précédemment est le système d’aide intégré à PowerShell. Vous avez probablement utilisé à un moment donné la commande Get-Help sur une fonction. Ces informations peuvent être ajoutées de deux manières principales.

La première consiste à ajouter une aide basée sur des commentaires dans la définition de la fonction. C’est généralement la méthode utilisée par de nombreux auteurs de modules. L’autre façon est d’utiliser un fichier d’aide externe. Vous pouvez utiliser le paramètre Full pour afficher toutes les informations fournies par l’aide.

Comme vous pouvez le voir, il n’y a vraiment pas beaucoup d’informations et les quelques informations que vous obtenez ne seraient probablement pas utiles pour quiconque.

Vous pouvez ajouter une aide basée sur des commentaires à votre fichier de module pour remplir ces champs dans le système d’aide. Vous pouvez en savoir plus sur toutes les options de l’aide basée sur des commentaires en utilisant Get-Help about_Comment_Based_Help.

Pour l’instant, vous pouvez mettre à jour votre fonction comme suit. Il s’agit d’une liste des paramètres d’aide les plus couramment utilisés, mais tous sont facultatifs et d’autres peuvent être ajoutés à la place.

Maintenant, votre fonction ressemble à ceci :

 function Get-RegistryKey {
	<#
	    .SYNOPSIS
	    Renvoie la clé de registre à l'aide du chemin fourni.
	    .DESCRIPTION
	    La fonction utilise la commande Get-Item pour renvoyer les informations d'une clé de registre fournie.
	    .PARAMETER Path
	    Le chemin qui sera recherché pour une clé de registre.
	    .EXAMPLE
	    Get-RegistryKey -Path 'HKLM:\HARDWARE\DESCRIPTION\System'
	    .INPUTS
	    System.String
	    .OUTPUTS
	    Microsoft.Win32.RegistryKey
	    .NOTES
	    Ce module est un exemple de ce à quoi pourrait ressembler une fonction bien documentée.
	    .LINK
	
ATA Learning

	#>
	param(
		[string]$Path
	)
	Get-Item $Path
}

Il existe certains paramètres d’aide spéciaux, comme .FORWARDHELPTARGETNAME. Cette option transfère toutes les demandes d’aide entrantes vers une commande différente. Cela pourrait être utilisé dans un cas où l’aide devrait afficher les mêmes informations pour plusieurs commandes.

Maintenant que vous avez ajouté l’aide, vous pouvez mettre à jour la version dans le manifeste du module, publier la nouvelle version et mettre à jour la version installée pour votre session comme vous l’avez fait précédemment.

Si vous regardez maintenant l’aide de la fonction, vous pouvez voir qu’il y a beaucoup plus d’informations disponibles. C’est une excellente façon d’inclure une documentation sur la façon d’utiliser les fonctions, surtout pour quelqu’un qui a moins d’expérience et qui ne peut pas rapidement comprendre ce que fait le module en regardant le code.

Dans le cas d’un fichier d’aide externe, les informations ajoutées sont les mêmes, mais les informations sont placées dans un fichier séparé et liées à la fonction.

Si vous regardez dans le chemin du module AllUsers, vous pouvez voir la version du module et tous les fichiers du module que vous avez installés.

Si vous revenez à votre chemin PSRepository C:\Repo que vous avez créé précédemment, vous pouvez voir une série de fichiers NUPKG. Il y en aura un pour chaque version publiée. Ce sont des versions compressées de ce que vous avez publié en utilisant Publish-Module.

Résumé

Une fois que vous maîtrisez la console PowerShell, PowerShell en tant que langage et l’écriture de scripts, la création de vos propres modules est la dernière étape. Les modules vous permettent de commencer à développer des outils utiles en PowerShell. Si vous concevez et construisez correctement des modules pour un usage spécifique, vous finirez inévitablement par écrire de moins en moins de code au fil du temps. Vous commencerez à référencer les fonctions de votre module dans davantage de code et à développer à partir de là.

Les fonctions de module vous permettent d’abstraire le code que vous vous trouvez à répéter dans les scripts. Elles représentent des « étiquettes » à référencer ultérieurement dans le code, qui peuvent être appelées à tout moment plutôt que de réinventer la roue et d’essayer de comprendre comment vous aviez déjà atteint votre objectif précédemment. Les modules sont le « packaging » final du code PowerShell qui regroupe du code similaire pour éviter de perdre du temps sur des problèmes que vous avez déjà résolus.