Adam l’automate

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

En utilisant des fonctions, vous pouvez rendre vos scripts plus modulaires. Cela vous permet d’être en mesure d’utiliser le même code dans de nombreux endroits sans copier et coller au code partout. L’utilisation de fonctions vous permet de passer moins de temps à apporter les mêmes modifications au même code partout où il est utilisé. Au lieu de cela, vous pouvez travailler à améliorer votre code à un seul endroit.

Pour amener les fonctions au niveau supérieur, vous pouvez combiner ces fonctions ensemble dans un module.

Un module est une collection de fonctions dans un fichier texte avec une extension psm1. Il y a quelques ajouts facultatifs, tels qu’un manifeste de module et une aide basée sur les commentaires ou une aide externe qui peuvent également être inclus. Ceux-ci seront couverts plus tard.

Conditions préalables

J’utiliserai Windows PowerShell 5.1 dans cet article. Si vous utilisez une version plus ancienne ou PowerShell Core, votre kilométrage peut varier quant aux résultats que vous obtenez.

Interagir avec les modules

Lorsque vous ouvrez une session PowerShell pour la première fois, vous démarrez 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, ce n’est pas une liste complète de tous les modules disponibles. Depuis PowerShell 3, les modules qui sont installés seront importés si nécessaire. Si vous exécutez une version plus ancienne de PowerShell, vous devrez utiliser la commande Import-Module pour d’abord importer le module avant d’utiliser l’une des commandes.

Il y a des moments où vous voudriez toujours utiliser Import-Module même dans les versions ultérieures. Si vous vouliez importer un module après qu’il soit déjà installé, vous pouvez utiliser Import-Module comme ceci:

Alors que Get-Module montrera tous les modules qui sont 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 qui sont exportées par le module. Vous pouvez constater quelques 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 comme cachée. Les auteurs de modules peuvent également utiliser le cmdlet Export-ModuleMember, mais cela sort du cadre de cet article.

Les auteurs de modules peuvent vouloir qu’une fonction soit cachée parce qu’elle est destinée à supporter d’autres fonctions, et non à être tournée vers l’utilisateur. Pour avoir une fonction cachée, l’auteur l’exclurait du tableau FunctionsToExport dans le manifeste. Ici, vous pouvez voir une vue étendue de la propriété ExportedCommands.

Importer des modules

Il existe plusieurs façons de commencer à utiliser des modules. Vous pouvez importer manuellement le module en utilisant le chemin d’accès aux fichiers du module. Cela vous permet d’être en mesure de tester et de mettre à jour le module sans avoir à faire beaucoup de travail. Mais cela ne permet pas une grande portabilité, puisque vous devez utiliser le chemin d’accès exact au module. PowerShell n’importera pas non plus automatiquement les modules qui ne sont pas dans la variable $env:PSModulePath.

Importation sélective de commandes

Vous pouvez utiliser Import-Module pour importer uniquement des fonctions spécifiques au lieu du module entier en utilisant le paramètre Function. Cela peut permettre de 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é-ajoutés, y compris tous les modules installés à l’aide de Install-Module en utilisant la portée par défaut AllUsers.

Modules de l’utilisateur actuel

Si vous installez un module mais ne voulez qu’un seul utilisateur pour l’utiliser, il existe une portée CurrentUser. Cela place les fichiers du module dans votre dossier Documents à l’adresse C:\Users\<username>\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 puisqu’ils partageraient tous deux le même dossier Documents.

Modules système

Pour être complet, il existe également un répertoire de modules à C:\Windows\System32\WindowsPowerShell\1.0\Modules. Bien que techniquement, un module placé dans ce chemin serait importé comme l’un des autres chemins, mais ce n’est pas recommandé car cela est réservé aux modules système de Microsoft.

Le nommage est important

Vous pouvez placer manuellement votre module dans l’un de ces chemins pour le rendre disponible par défaut avec une nouvelle session, mais vous devez vous assurer que vous respectez le nommage requis 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 le manifeste du module psd1 s’il y en a un.

L’utilisation de Get-Module -ListAvailable que nous avions mentionné précédemment référence ces chemins. Vous pouvez voir tous les chemins du module en utilisant $env:PSModulePath -Split ';'. Vous pouvez remarquer d’autres chemins dans la liste que ce qui est montré ici. De nombreux programmes ajoutent leurs propres chemins de modules lorsqu’ils sont installés. Un des exemples de ceci est SQL, qui a ses propres modules inclus dans ses propres chemins de modules.

Il y a aussi certains modules que vous installeriez avec un processus différent. L’un des exemples les plus significatifs à cet égard est le module ActiveDirectory. De Windows 7 jusqu’à Windows 10 1803, vous l’installeriez avec le programme d’installation des outils d’administration de serveur à distance (RSAT).

Sur les versions plus récentes de Windows 10 (1809+), cela n’est disponible que par le biais des fonctionnalités à la demande. L’installation de RSAT installe les modules ActiveDirectory et de nombreux autres que vous utiliseriez pour administrer d’autres rôles Windows. Sur les OS de serveur Windows, ces modules sont installés par le biais du gestionnaire de serveur.

Importer des modules distants (Remoting implicite)

Il existe certains cas où il n’est pas pratique d’avoir un module s’exécutant localement. Au lieu de cela, il est préférable de se connecter à un périphérique distant et d’importer un module installé sur celui-ci. Lorsque vous faites cela, les commandes sont réellement exécutées sur la machine distante. Cette méthode est fréquemment utilisée 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, elle est exécutée 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. Voici ce que vous obtiendriez 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 New-PSSession pour créer la session. Ensuite, vous importeriez le module disponible sur le périphérique distant en utilisant le paramètre PSSession avec 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 à l’autre bout des États-Unis, l’exécution de certaines commandes localement contre les serveurs peut prendre beaucoup plus de temps. Alors qu’exécuter les commandes sur un serveur et renvoyer la sortie vers votre session locale est beaucoup plus rapide.

Ajouter un préfixe de module

Vous pouvez également ajouter un préfixe sur les 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 du test de différentes versions d’un module côte à côte.

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

Dans ce cas, vous pouvez utiliser un préfixe pour montrer que ce n’est pas 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 sur l’endroit où le code est exécuté.

Suppression de modules

Vous pouvez également supprimer un module de la session actuelle sans utiliser Remove-Module. Ceci supprime un module de la session locale sans supprimer les fichiers du module. Vous pourriez vouloir utiliser ceci dans un cas où vous utilisiez une session distante pour utiliser un module. Vous pourriez utiliser Remove-Module pour nettoyer votre session et ensuite déconnecter la session distante.

Une autre utilisation de Remove-Module est si vous apportez des modifications à un module et que vous ne voulez 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 terminera le déchargement et le rechargement du module pour vous.

Ce qui compose un module PowerShell

Un module peut être constitué d’un ou plusieurs fichiers. Pour répondre aux exigences minimales d’un module, vous devez avoir un fichier de module. Il peut s’agir d’un fichier PSM1 ou de tout autre fichier de module tel qu’un fichier de module binaire. Pour construire à partir de cela, votre psm1 doit avoir des fonctions définies dans celui-ci, ou il ne sera pas très utile à quiconque.

Bien qu’il n’y ait pas d’exigences sur la façon dont les fonctions doivent se présenter ou ce qu’elles doivent faire, il y a quelques lignes directrices. Il est généralement préférable que toutes les fonctions d’un module soient construites autour du même concept.

Les modules contiennent des fonctions de même nature

Par exemple, le module ActiveDirectory ne comprend que des fonctions qui interagissent avec Active Directory d’une manière ou d’une autre. Habituellement, les noms des fonctions contiennent également un préfixe. En revenant au module ActiveDirectory comme exemple, tous les substantifs dans les noms de fonctions commencent par AD.

L’utilisation de ces directives aide à la découvrabilité des fonctions. Imaginez que vous venez d’importer ce nouveau module et que vous voulez passer en revue les fonctions. Cela est beaucoup plus facile à faire si toutes les fonctions ont une structure de nom similaire. Si vous voyez souvent des modules commençant par PS, ce préfixe est officiellement réservé aux modules Microsoft. Vous ne causerez probablement pas de problème si vous utilisez PS au début de votre module, vous pouvez créer un conflit avec le nom d’un autre module.

En utilisant ces directives, si vous aviez un tas de fonctions qui avaient toutes à faire avec l’interaction avec le registre, vous pourriez avoir quelque chose comme:

function Get-ATARegistryKey {...}function Set-ATARegistryKey {...}

Manifeste de module

Pour construire sur 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 incluez des informations sur l’auteur, la description du module, les autres modules requis et de nombreux autres attributs. Pour publier dans un référentiel, il est nécessaire que les champs Author et Description soient remplis.

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

#Module manifest for module 'ATARegistry'#Generated by: Tyler#Generated on: 8/11/2019@{#Script module or binary module file associated with this manifest.RootModule = 'ATARegistry'#Version number of this module.ModuleVersion = '1.0'#Supported PSEditions#CompatiblePSEditions = @()#ID used to uniquely identify this moduleGUID = 'fef619fa-016d-4b11-a09d-b222e094de3e'#Author of this moduleAuthor = 'Tyler Muir'#Company or vendor of this moduleCompanyName = 'Adam the Automator'#Copyright statement for this moduleCopyright = '(c) 2019 tyler. All rights reserved.'#Description of the functionality provided by this moduleDescription = 'This is a test module.'#Minimum version of the Windows PowerShell engine required by this module#PowerShellVersion = ''#Name of the Windows PowerShell host required by this module#PowerShellHostName = ''#Minimum version of the Windows PowerShell host required by this module#PowerShellHostVersion = ''#Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.#DotNetFrameworkVersion = ''#Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.#CLRVersion = ''#Processor architecture (None, X86, Amd64) required by this module#ProcessorArchitecture = ''#Modules that must be imported into the global environment prior to importing this module#RequiredModules = @()#Assemblies that must be loaded prior to importing this module#RequiredAssemblies = @()#Script files (.ps1) that are run in the caller's environment prior to importing this module.#ScriptsToProcess = @()#Type files (.ps1xml) to be loaded when importing this module#TypesToProcess = @()#Format files (.ps1xml) to be loaded when importing this module#FormatsToProcess = @()#Modules to import as nested modules of the module specified in RootModule/ModuleToProcess#NestedModules = @()#Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.FunctionsToExport = @('Get-RegistryKey','Set-RegistryKey')#Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.CmdletsToExport = @()#Variables to export from this moduleVariablesToExport = '*'#Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.AliasesToExport = @()#DSC resources to export from this module#DscResourcesToExport = @()#List of all modules packaged with this module#ModuleList = @()#List of all files packaged with this module#FileList = @()#Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.PrivateData = @{PSData = @{#Tags applied to this module. These help with module discovery in online galleries.#Tags = @()#A URL to the license for this module.#LicenseUri = ''#A URL to the main website for this project.#ProjectUri = ''#A URL to an icon representing this module.#IconUri = ''#ReleaseNotes of this module#ReleaseNotes = ''} #End of PSData hashtable} #End of PrivateData hashtable#HelpInfo URI of this module#HelpInfoURI = ''#Default prefix for commands exported from this module. Override the default prefix using 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 présenté ci-dessus, vous pourriez 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 voir des fichiers d’aide externes dans certains modules. Ils pourraient être identifiés par le <Nom du module>-Help.xml à la fin du nom du fichier. Ces fichiers d’aide externes contiennent les mêmes informations que celles qui seraient normalement contenues dans l’aide par commande que vous pouvez trouver dans une définition de fonction.

Cela nécessiterait également que vous ajoutiez # .ExternalHelp <ModulePath>-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 n’est généralement courant de voir des fichiers d’aide externes qu’avec de très grands modules et, en raison de cela, ils sont hors de la portée.

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 à travers les chemins du module, vous pouvez trouver de nombreux exemples de types de fichiers supplémentaires dans les modules.

Pour avoir des fichiers de module non standard correctement publiés, vous incluriez d’autres fichiers dans le paramètre FileList de votre manifeste de module.

Dans le manifeste de 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 supportée de PowerShell, voici ce que vous verriez :

PSRepositories

L’une des options de distribution clés pour les modules est un PSRepository. À une vue 1000′, un PSRepository est un local où plusieurs personnes ou plusieurs appareils peuvent accéder aux fichiers du module. Ce sont fréquemment des serveurs web où vous pouvez publier des fichiers.

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

Par défaut, vous n’aurez qu’une seule entrée et ce sera pour la PowerShell Gallery. Vous pouvez remarquer qu’il sera indiqué untrusted. C’est parce que PowerShell vous fait savoir qu’en utilisant la galerie PowerShell, vous pouvez utiliser du code qui n’est pas écrit et approuvé par Microsoft. Cela signifie qu’avant d’installer des modules à partir de celle-ci, vous devrez donner une permission explicite.

Ajout de PSRepositories

Vous pouvez également ajouter vos propres dépôts. Pour faire confiance à la galerie PowerShell, vous pouvez exécuter Get-PSRepository -Name PSGallery | Set-PSRepository -InstallationPolicy Trusted ou vous pouvez accepter l’avertissement la première fois que vous installez un module de la galerie PowerShell.

Toutes les commandes que vous utiliseriez pour interagir avec ces PSRepositories se trouvent dans le module PowerShellGet. Vous pouvez voir les fonctions ici :

Le module PowerShellGet peut devoir être mis à jour avant d’interagir avec certains référentiels.

Recherche de modules

Une autre caractéristique clé de l’utilisation d’un PSRepository est de pouvoir rechercher des modules. Ceci est accompli en utilisant la commande Find-Module. Il existe de multiples façons de filtrer pour trouver spécifiquement ce que vous recherchez, mais pour l’instant vous pouvez rechercher les modules VMware comme ceci :

Cela montrera 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.

Puisque tout le monde peut télécharger sur PowerShell Gallery, il y a des milliers de modules disponibles. Cela signifie que vous pouvez trouver des modules qui ne fonctionnent pas correctement pour votre cas d’utilisation. De nombreux modules que vous trouverez sont open source, vous pouvez donc y contribuer pour améliorer la fonctionnalité du module.

Installation des modules

Pour utiliser la commande Install-Module, vous devez avoir un PSRepository de confiance qui héberge le module. Il peut s’agir de la galerie PowerShell, d’un autre PSRepository internet ou d’un site auto-hébergé. Vous pouvez pipe de la commande Find-Module pour être disponible pour confirmer facilement 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 Install-Module, vous pouvez utiliser Get-InstalledModule. Cela listera tous les modules installés sur le scope AllUsers ou votre scope CurrentUser.

Désinstallation des modules

De même que vous pouvez installer un module, vous pouvez également désinstaller un module. Si le module n’a pas été installé via la commande Install-Module, vous ne pouvez pas le désinstaller avec la commande Uninstall-Module.

Comme vous pouvez le voir ici, nous essayons de désinstaller le module ActiveDirectory. Comme ce module n’est pas installé avec Install-Module, vous recevriez une erreur en essayant d’utiliser Uninstall-Module. Pour que vous puissiez désinstaller ce module, nous devrions le désinstaller en inversant ce que vous avez utilisé pour installer le module.

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 que de nombreuses dépendances sont encore installées. Si vous vouliez désinstaller tous les modules, nous pourrions utiliser Get-InstalledModule VMware.* | Uninstall-Module -Force.

La raison pour laquelle vous auriez de telles difficultés à désinstaller complètement ce module est qu’il a tellement de dépendances. En plus de cela, 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é.

Comme pour les autres processus, si le module n’a pas été installé en utilisant Install-Module, vous ne pouvez pas mettre à jour le en utilisant les commandes PowerShell. Vous pouvez utiliser Update-Module pour mettre à jour un module à la version la plus récente, ou à une version spécifique plus récente.

Il y a aussi un commutateur à AllowPreRelease qui vous permettrait de mettre à jour à une version qui n’a pas été officiellement publiée. Parfois, cela peut aider car il peut y avoir eu un correctif à un bogue que vous rencontrez ou une nouvelle fonctionnalité qui a été ajoutée et que vous aimeriez utiliser.

Inspecter/sauvegarder un module

L’une des commandes beaucoup moins utilisées qui est très utile lors du contrôle des modules avant utilisation est Save-Module. En utilisant cette commande, vous pouvez télécharger un module sur un chemin sans l’installer.

Vous pouvez ensuite inspecter les fichiers et si le module n’est pas un module binaire, vous pouvez ouvrir et regarder le code qui compose le module. Cela peut être bon non seulement pour s’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 apparaît dans le dossier VMware.PowerCLI:

C’est un bon exemple pour montrer comment il y a parfois des fichiers de module non standard inclus dans le module, comme le contrat de licence de l’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 que vous puissiez commencer à optimiser votre code pour l’évolutivité.

Créer des fichiers de modèle

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 ou sinon, lorsque vous essayez de publier votre module, PowerShell ne découvrira pas le module correctement.

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

Maintenant, vous voulez également utiliser un manifeste, vous devrez également le nommer de la même façon 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 fonctionnant pleinement. Vous pourriez publier ce module dans un PSRepository et commencer à l’installer où vous voulez. Cependant, comme le fichier de module est vide, cela ne vous servira probablement pas à grand-chose. Vous pouvez toujours utiliser ces fichiers pour tester la publication afin de vous assurer que votre dépôt fonctionne.

Enregistrer 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 à mettre en place et à démonter.

Normalement, si vous alliez mettre en place un PSRepository avec un répertoire, vous voudriez vous assurer que plusieurs ordinateurs peuvent y accéder. Vous pouvez créer un dépôt local comme ceci :

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

Si vous ne faisiez que télécharger à partir du PSRepository et ne publiiez jamais, vous pourriez exclure le paramètre PublishLocation.

Publier votre module

Puisque vous avez déjà défini la politique d’installation sur trusted, vous n’obtiendrez pas de confirmation pour autoriser l’installation d’un module à partir du dépôt. Maintenant que vous avez un nouveau PSRepository disponible, vous pouvez publier votre module à l’aide de Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo.

Après avoir publié votre module, vous pouvez utiliser les commandes du 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. Comme vous n’avez pas ajouté de fonctions 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 pourriez ajouter une fonction pour retourner une clé de registre afin qu’elle ressemble à ceci :

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

Si vous laissiez le manifeste tel quel et essayiez de télé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à sur votre référentiel. C’est parce que vous n’avez pas changé la version du module dans le fichier manifeste.

Exportation des fonctions du module

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

Alors que votre fonction pourrait être utilisée sans la lister dans la liste FunctionsToExport, cela la rendrait beaucoup plus difficile à localiser.

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

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 que précédemment.

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

Mise à jour de votre module

La dernière étape serait pour vous de 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 de l’aide

Une des options qui a été passée plus tôt est le système d’aide qui est intégré dans PowerShell. Vous avez à un moment donné probablement utilisé Get-Help sur une fonction. Cette information peut être ajoutée de deux façons 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 façon que de nombreux rédacteurs de modules mettent en œuvre. L’autre façon est d’utiliser un fichier d’aide externe. Vous pouvez utiliser le paramètre Full pour montrer tout ce que l’aide a à offrir.

Comme vous pouvez le voir, il n’y a vraiment pas beaucoup d’informations et le peu d’informations que vous obtenez ne serait probablement pas utile à quiconque.

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

Pour l’instant, vous pouvez mettre à jour votre fonction pour qu’elle ressemble à ce qui suit. Il s’agit d’une liste des paramètres d’aide les plus couramment utilisés, mais tous ces paramètres sont toujours facultatifs et il y en a d’autres qui pourraient être ajoutés à la place.

Maintenant, votre fonction ressemble à ceci:

 function Get-RegistryKey {<# .SYNOPSIS Returns registry key using provided path. .DESCRIPTION The function uses the Get-Item command to return the information for a provided registry key. .PARAMETER Path The path that will be searched for a registry key. .EXAMPLE Get-RegistryKey -Path 'HKLM:\HARDWARE\DESCRIPTION\System' .INPUTS System.String .OUTPUTS Microsoft.Win32.RegistryKey .NOTES This module is an example of what a well documented function could look. .LINKhttps://adamtheautomator.com#>param($Path)Get-Item $Path}

Il existe quelques paramètres d’aide spéciaux, comme .FORWARDHELPTARGETNAME. Cette option transmet toutes les demandes d’aide entrantes à une commande différente. Cela pourrait être utilisé dans un cas où l’aide devrait montrer la même information 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 pour la fonction, vous pouvez voir qu’il y a beaucoup plus d’informations disponibles. C’est une excellente façon d’inclure de la documentation sur la façon d’utiliser les fonctions, en particulier pour quelqu’un qui est moins expérimenté et qui peut ne pas être en mesure de comprendre rapidement ce que fait le module en regardant le code.

Dans le cas d’un fichier d’aide externe, l’information ajoutée est la même, mais l’information est placée dans un fichier séparé et liée dans 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 retournez dans votre chemin PSRepository C:\Repo que vous avez créé plus tôt, vous pouvez voir un tas de fichiers NUPKG. Il y en aura un pour chaque version qui a été publiée. Ce sont des versions compressées de ce que vous avez publié en utilisant Publish-Module.

Résumé

Une fois que vous avez maîtrisé la console PowerShell, PowerShell en tant que langage et l’écriture de scripts, la construction de vos propres modules est la dernière étape. Les modules vous permettent de commencer à développer des outils utiles dans PowerShell. S’ils sont conçus et construits correctement en créant des modules dans un but unique, vous vous retrouverez inévitablement à écrire de moins en moins de code au fil du temps. Vous commencerez à référencer vos fonctions de module dans plus de code et à construire à partir de là.

Les fonctions de module vous permettent d’abstraire le code que vous vous retrouvez à répéter dans les scripts. Elles représentent des « étiquettes » à référencer plus tard 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à accompli votre objectif précédemment. Les modules sont le « packaging » final du code PowerShell qui regroupe du code de même nature pour éviter de perdre du temps sur des problèmes que vous avez déjà résolus.