about_Modules
Mis à jour: mai 2014
S'applique à: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
RUBRIQUE
about_Modules
DESCRIPTION COURTE
Explique comment installer, importer et utiliser des modules Windows PowerShell.
DESCRIPTION DÉTAILLÉE
Un module est un package qui contient des commandes Windows PowerShell, notamment des applets de commande, des fournisseurs, des fonctions, des workflows, des variables et des alias.
Les personnes qui écrivent des commandes peuvent utiliser des modules pour organiser leurs commandes et les partager avec d'autres utilisateurs. Celles qui reçoivent des modules peuvent ajouter les commandes contenues dans ces modules à leurs sessions Windows PowerShell, puis les utiliser de la même façon que des commandes intégrées.
Cette rubrique explique comment utiliser les modules Windows PowerShell. Pour plus d'informations sur l'écriture de modules Windows PowerShell, consultez « Écriture d'un module Windows PowerShell » dans la bibliothèque MSDN (Microsoft Developer Network) à l'adresse https://go.microsoft.com/fwlink/?LinkId=144916.
QU'EST-CE QU'UN MODULE ?
Un module est un package de commandes. L'ensemble des applets de commande et des fournisseurs dans votre session sont ajoutés par un module ou un composant logiciel enfichable.
NOUVEAUTÉS DES MODULES : CHARGEMENT AUTOMATIQUE DES MODULES
À compter de Windows PowerShell 3.0, Windows PowerShell importe automatiquement les modules à la première exécution d'une commande dans un module installé. Vous pouvez désormais exécuter les commandes d'un module sans configuration ni création de profil au préalable. Après avoir installé un module sur votre ordinateur, vous n'avez plus à vous en occuper.
Vous pouvez aussi trouver plus facilement les commandes contenues dans un module. L'applet de commande Get-Command vous permet d'obtenir toutes les commandes de l'ensemble des modules installés, y compris ceux qui ne sont pas encore importés dans votre session. Vous pouvez donc rechercher une commande et l'exécuter sans importer le module associé.
Utilisez l'une des commandes suivantes pour importer un module dans votre session.
#Run the command
Get-Mailbox –Identity Chris
#Get the command
Get-Command Get-Mailbox
#Get help for the command
Get-Help Get-Mailbox
Les commandes Get-Command contenant un caractère générique (*) sont considérées comme des commandes de découverte. À ce titre, elles n'importent pas de modules.
Seuls les modules stockés à l'emplacement spécifié par la variable d'environnement PSModulePath sont importés automatiquement. Les modules installés à d'autres emplacements doivent être importés en exécutant l'applet de commande Import-Module.
Par ailleurs, les commandes qui utilisent des fournisseurs Windows PowerShell n'importent pas automatiquement les modules. Par exemple, si vous utilisez une commande qui nécessite le lecteur WSMan:, comme l'applet de commande Get-PSSessionConfiguration, vous devrez peut-être exécuter l'applet de commande Import-Module pour importer le module Microsoft.WSMan.Management qui inclut ce lecteur.
Vous pouvez toujours exécuter la commande Import-Module pour importer un module et utiliser la variable $PSModuleAutoloadingPreference pour activer, désactiver et configurer l'importation automatique des modules. Pour plus d'informations, consultez about_Preference_Variables.
COMMENT UTILISER UN MODULE
Pour utiliser un module, procédez comme suit :
1. Installez le module. (Bien souvent, cette tâche ne vous incombe pas.)
2. Recherchez les commandes ajoutées par le module.
3. Utilisez les commandes ajoutées par le module.
Cette rubrique explique comment effectuer ces tâches. Elle contient également d'autres informations utiles sur la gestion des modules.
COMMENT INSTALLER UN MODULE
Si vous recevez un module sous forme d'un dossier contenant des fichiers, vous devez installer ce dossier sur votre ordinateur avant de pouvoir l'utiliser dans Windows PowerShell.
La plupart des modules sont installés pour vous. Windows PowerShell est fourni avec plusieurs modules préinstallés, parfois appelés modules « de base ». Sur les ordinateurs Windows qui intègrent des fonctionnalités gérées par des applets de commande, ces modules sont préinstallés. Quand vous installez une fonctionnalité Windows, en utilisant, par exemple, l'Assistant Ajout de rôles et de fonctionnalités dans le Gestionnaire de serveur ou bien la boîte de dialogue Activer ou désactiver des fonctionnalités Windows dans le Panneau de configuration, les modules Windows PowerShell qui font partie de cette fonctionnalité sont installés. D'autres modules sont fournis avec un programme d'installation.
Pour installer un dossier de module :
1. S'il n'existe pas, créez un répertoire Modules pour l'utilisateur actuel.
Pour créer un répertoire Modules, tapez :
New-Item -Type Directory -Path $home\Documents\WindowsPowerShell\Modules
2. Copiez le dossier du module en totalité dans le répertoire Modules.
Vous pouvez utiliser la méthode de votre choix pour copier le dossier, y compris l'Explorateur Windows, Cmd.exe ou Windows PowerShell.
Dans Windows PowerShell, utilisez l'applet de commande Copy-Item. Par exemple, pour copier le dossier MyModule situé dans C:\ps-test\MyModule dans le répertoire Modules, tapez :
Copy-Item -Path c:\ps-test\MyModule -Destination $home\Documents\WindowsPowerShell\Modules
Vous pouvez installer vos modules n'importe où, mais nous vous recommandons de les installer dans un emplacement de module par défaut pour faciliter leur gestion. Pour plus d'informations sur les emplacements par défaut des modules, consultez la section « EMPLACEMENTS DES MODULES ET DES RESSOURCES DSC, ET PSMODULEPATH ».
COMMENT RECHERCHER DES MODULES INSTALLÉS
Pour trouver les modules qui sont installés dans un emplacement par défaut, mais qui ne sont pas encore dans votre session, tapez :
Get-Module -ListAvailable
Pour trouver les modules qui ont déjà été importés dans votre session, à l'invite Windows PowerShell, tapez :
Get-Module
Pour plus d'informations sur l'applet de commande Get-Module, consultez Get-Module.
COMMENT TROUVER LES COMMANDES DANS UN MODULE
Utilisez l'applet de commande Get-Command pour trouver toutes les commandes disponibles. Vous pouvez utiliser les paramètres de l'applet de commande Get-Command pour filtrer les commandes (par exemple par module ou par nom).
Pour trouver toutes les commandes dans un module, tapez :
Get-Command -Module <module-name>
Par exemple, pour rechercher les commandes contenues dans le module BitsTransfer, tapez :
Get-Command -Module BitsTransfer
Pour plus d'informations sur l'applet de commande Get-Command, consultez Get-Command.
COMMENT OBTENIR DE L'AIDE SUR LES COMMANDES D'UN MODULE
Si le module comporte des fichiers d'aide pour les commandes exportées, l'applet de commande Get-Help affiche les rubriques d'aide correspondantes. Utilisez la même syntaxe de commande Get-Help que celle permettant d'obtenir de l'aide sur les commandes Windows PowerShell.
À compter de Windows PowerShell 3.0, vous pouvez télécharger les fichiers d'aide d'un module ainsi que leurs mises à jour pour bénéficier de la dernière version des fichiers d'aide.
Pour obtenir de l'aide sur une commande d'un module, tapez :
Get-Help <command-name>
Pour afficher l'aide en ligne relative à une commande d'un module, tapez :
Get-Help <command-name> -Online
Pour télécharger et installer les fichiers d'aide liés aux commandes d'un module, tapez :
Update-Help –Module <module-name>
Pour plus d'informations, consultez Get-Help et Update-Help.
COMMENT IMPORTER UN MODULE
Vous pouvez être amené à importer un module ou un fichier de module. Une importation est requise lorsqu'un module n'est pas installé dans les emplacements spécifiés par la variable d'environnement PSModulePath ($env:PSModulePath) ou lorsque le module se présente sous forme d'un fichier, .dll ou .psm1 par exemple, et non sous forme d'un dossier de module standard.
Vous pouvez également choisir d'importer un module pour utiliser les paramètres de la commande Import-Module, comme le paramètre Prefix qui ajoute un préfixe unique aux noms de toutes les commandes importées. Vous pouvez aussi utiliser le paramètre NoClobber pour empêcher le module d'ajouter des commandes susceptibles de masquer ou de remplacer des commandes existantes dans la session.
Pour importer des modules, utilisez l'applet de commande Import-Module.
Pour importer des modules dans un emplacement PSModulePath de la session active, utilisez le format de commande suivant.
Import-Module <module-name>
Par exemple, la commande suivante importe le module BitsTransfer dans la session active.
Import-Module BitsTransfer
Pour importer un module qui ne figure pas dans un emplacement de module par défaut, utilisez le chemin d'accès complet au dossier du module dans la commande.
Par exemple, pour ajouter le module TestCmdlets situé dans le répertoire C:\ps-test à votre session, tapez :
Import-Module c:\ps-test\TestCmdlets
Pour importer un fichier de module qui ne figure pas dans un dossier de module, utilisez le chemin d'accès complet au fichier du module dans la commande.
Par exemple, pour ajouter le module TestCmdlets.dll dans le répertoire C:\ps-test à votre session, tapez :
Import-Module c:\ps-test\TestCmdlets.dll
Pour plus d'informations sur l'ajout de modules à votre session, consultez Import-Module.
COMMENT IMPORTER UN MODULE DANS CHAQUE SESSION
La commande Import-Module importe des modules dans votre session Windows PowerShell active. Cette commande affecte uniquement la session active.
Pour importer un module dans chaque session Windows PowerShell que vous démarrez, ajoutez la commande Import-Module à votre profil Windows PowerShell.
Pour plus d'informations sur les profils, consultez about_Profiles.
COMMENT SUPPRIMER UN MODULE
Quand vous supprimez un module, les commandes ajoutées par le module sont supprimées de la session.
Pour supprimer un module de votre session, utilisez la syntaxe de commande suivante.
Remove-Module <module-name>
Par exemple, la commande suivante supprime le module BitsTransfer de la session active.
Remove-Module BitsTransfer
Le fait de supprimer un module annule l'opération d'importation d'un module. Toutefois, le module supprimé n'est pas désinstallé. Pour plus d'informations sur l'applet de commande Remove-Module, consultez Remove-Module.
EMPLACEMENTS DES MODULES ET DES RESSOURCES DSC, ET PSMODULEPATH
Voici les emplacements par défaut des modules Windows PowerShell. À compter de Windows PowerShell 4.0, qui a introduit la configuration DSC (Desired State Configuration), un nouveau dossier par défaut est utilisé pour les modules et les ressources DSC. Pour plus d'informations sur DSC, consultez about_DesiredStateConfiguration.
Système :
$pshome\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules). Les modules système sont ceux fournis avec Windows et Windows PowerShell.
À compter de Windows PowerShell 4.0, qui a introduit la configuration DSC (Desired State Configuration) Windows PowerShell, les ressources DSC fournies dans Windows PowerShell sont également stockées dans $pshome\Modules, dans le dossier $pshome\Modules\PSDesiredStateConfiguration\DSCResources.
Utilisateur actuel :
$home\Documents\WindowsPowerShell\Modules (%UserProfile%\Documents\WindowsPowerShell\Modules)
- ou-
$home\My Documents\WindowsPowerShell\Modules (%UserProfile%\My Documents\WindowsPowerShell\Modules). C'est l'emplacement des modules ajoutés par l'utilisateur dans les versions antérieures à Windows PowerShell 4.0.
Dans Windows PowerShell 4.0 et les versions ultérieures de Windows PowerShell, les ressources DSC et les modules ajoutés par l'utilisateur sont stockés dans C:\Program Files\WindowsPowerShell\Modules. Les modules et les ressources DSC stockés à cet emplacement sont accessibles à tous les utilisateurs de l'ordinateur. Cette modification était nécessaire, car le moteur DSC, qui s'exécute en tant que système local, ne pouvait pas accéder aux chemins d'accès spécifiques à l'utilisateur, tels que $home\Documents\WindowsPowerShell\Modules.
Remarque :
Pour ajouter ou modifier des fichiers dans le répertoire %Windir%\System32, démarrez Windows PowerShell avec l'option « Exécuter en tant qu'administrateur ».
Vous pouvez modifier les emplacements par défaut des modules sur votre système en modifiant la valeur de la variable d'environnement PSModulePath ($Env:PSModulePath). La variable d'environnement PSModulePath a le même format que la variable d'environnement Path sur laquelle elle est modélisée.
Pour afficher les emplacements par défaut des modules, tapez :
$env:psmodulepath
Pour ajouter un emplacement de module par défaut, utilisez le format de commande suivant.
$env:psmodulepath = $env:psmodulepath + ";<path>"
Le point-virgule (;) dans la commande sépare le nouveau chemin d'accès du chemin d'accès qui le précède dans la liste.
Par exemple, pour ajouter le répertoire C:\ps-test\Modules, tapez :
$env:psmodulepath + ";c:\ps-test\Modules"
Quand vous ajoutez un chemin d'accès à PSModulePath, les commandes Get-Module et Import-Module incluent les modules dans ce chemin d'accès.
La valeur que vous définissez affecte uniquement la session active. Pour rendre le changement persistant, ajoutez la commande à votre profil Windows PowerShell ou ouvrez Système dans le Panneau de configuration et modifiez la valeur de la variable d'environnement PSModulePath dans le Registre.
Vous pouvez également, pour rendre le changement persistant, utiliser la méthode SetEnvironmentVariable de la classe System.Environment pour ajouter un chemin d'accès à la variable d'environnement PSModulePath.
Pour plus d'informations sur la variable PSModulePath, consultez about_Environment_Variables.
MODULES ET CONFLITS DE NOMS
Des conflits de noms se produisent quand plusieurs commandes portent le même nom dans la session. Quand vous importez un module, un conflit survient si les noms des commandes de ce module sont identiques à ceux de commandes ou d'éléments présents dans la session.
Les conflits de noms peuvent entraîner le masquage ou le remplacement de commandes.
--Masquage. Une commande est masquée si elle ne s'exécute pas quand vous tapez son nom. Vous pouvez toutefois l'exécuter en utilisant une autre méthode, par exemple en qualifiant le nom de la commande avec le nom du module ou du composant logiciel enfichable d'où elle provient.
--Remplacement. Une commande est remplacée quand vous ne pouvez pas l'exécuter parce qu'elle a été remplacée par une commande du même nom. Même quand vous supprimez le module à l'origine du conflit, vous ne pouvez pas exécuter une commande remplacée, à moins de redémarrer la session.
Import-Module peut ajouter des commandes qui masquent et remplacent des commandes dans la session active. Par ailleurs, les commandes dans votre session peuvent masquer les commandes ajoutées par le module.
Pour détecter des conflits de noms, utilisez le paramètre All de l'applet de commande Get-Command. À compter de Windows PowerShell 3.0, Get-Command affiche uniquement les commandes qui s'exécutent quand vous tapez le nom de la commande. Le paramètre All obtient toutes les commandes portant le nom spécifique dans la session.
Pour éviter les conflits de noms, utilisez les paramètres NoClobber ou Prefix de l'applet de commande Import-Module. Le paramètre Prefix ajoute un préfixe aux noms des commandes importées pour les rendre uniques dans la session. Le paramètre NoClobber n'importe aucune commande susceptible de masquer ou de remplacer des commandes existantes dans la session.
Vous pouvez également utiliser les paramètres Alias, Cmdlet, Function et Variable de l'applet de commande Import-Module pour sélectionner uniquement les commandes que vous souhaitez importer, et vous pouvez exclure les commandes qui provoquent des conflits de noms dans votre session.
Les auteurs de modules peuvent éviter les conflits de noms à l'aide de la propriété DefaultCommandPrefix du manifeste de module pour ajouter un préfixe par défaut à tous les noms de commande. La valeur du paramètre Prefix a priorité sur la valeur de DefaultCommandPrefix.
Même si une commande est masquée, vous pouvez l'exécuter en qualifiant le nom de la commande avec le nom du module ou du composant logiciel enfichable d'où elle provient.
Les règles de précédence des commandes Windows PowerShell déterminent la commande qui est exécutée quand la session inclut plusieurs commandes du même nom.
Par exemple, quand une session comprend une fonction et une applet de commande avec un nom identique, Windows PowerShell exécute la fonction par défaut. Quand la session inclut des commandes du même type avec le même nom, par exemple deux applets de commande avec le même nom, la commande la plus récemment ajoutée est exécutée par défaut.
Pour obtenir plus d'informations, y compris une explication des règles de précédence et des instructions pour exécuter des commandes masquées, consultez about_Command_Precedence.
MODULES ET COMPOSANTS LOGICIELS ENFICHABLES
Vous pouvez ajouter des commandes à votre session à partir de modules et de composants logiciels enfichables. Les modules peuvent ajouter tous les types de commande, y compris des applets de commande, des fournisseurs, des fonctions et des éléments comme des variables, des alias et des lecteurs Windows PowerShell. Les composants logiciels enfichables peuvent uniquement ajouter des applets de commande et des fournisseurs.
Avant de supprimer un module ou un composant logiciel enfichable de votre session, utilisez les commandes suivantes pour déterminer les commandes qui seront supprimées.
Pour rechercher la source d'une applet de commande dans votre session, utilisez la syntaxe de commande suivante :
get-command <cmdlet-name> | format-list -property verb, noun, pssnapin, module
Par exemple, pour rechercher la source de l'applet de commande Get-Date, tapez :
get-command get-date | format-list -property verb, noun, pssnapin, module
Pour plus d'informations sur les composants logiciels enfichables Windows PowerShell, consultez about_PSSnapins.
ERREURS ET AVERTISSEMENTS LIÉS AUX MODULES
Les commandes exportées par un module doivent suivre les règles d'affectation des noms de commande Windows PowerShell. Si le module que vous importez exporte des applets de commande ou des fonctions dont les noms comportent des verbes non approuvés, l'applet de commande Import-Module affiche le message d'avertissement suivant.
AVERTISSEMENT : Certains noms de commandes importés contiennent des verbes non approuvés qui les rendent moins détectables. Utilisez le paramètre Verbose pour obtenir plus d'informations ou tapez Get-Verb pour afficher la liste des verbes approuvés.
Ce message n'est qu'un avertissement. L'ensemble du module est toujours importé, y compris les commandes non conformes. Bien que le message soit affiché aux utilisateurs du module, le problème d'affectation de noms doit être corrigé par l'auteur du module.
Pour supprimer le message d'avertissement, utilisez le paramètre DisableNameChecking de l'applet de commande Import-Module.
MODULES INTÉGRÉS ET COMPOSANTS LOGICIELS ENFICHABLES
Dans Windows PowerShell 2.0 et dans les anciens programmes hôtes dans Windows PowerShell 3.0 et versions ultérieures, les commandes de base installées avec Windows PowerShell sont empaquetées dans des composants logiciels enfichables qui sont ajoutés automatiquement à chaque session Windows PowerShell.
À compter de Windows PowerShell 3.0, dans les nouveaux programmes hôtes (ceux qui implémentent l'API d'état de session initial InitialSessionState.CreateDefault2), les commandes de base sont empaquetées dans des modules. Par défaut, il s'agit de Microsoft.PowerShell.Core, qui est toujours un composant logiciel enfichable.
Le composant logiciel enfichable Microsoft.PowerShell.Core est ajouté à chaque session par défaut. Les modules sont chargés automatiquement lors de la première utilisation.
REMARQUE : Les sessions distantes, y compris les sessions démarrées à l'aide de l'applet de commande New-PSSession, sont des sessions anciennes dans lesquelles les commandes intégrées sont packagées dans des composants logiciels enfichables.
Les modules (ou composants logiciels enfichables) suivants sont installés avec Windows PowerShell.
Microsoft.PowerShell.Core
Microsoft.PowerShell.Diagnostics
Microsoft.PowerShell.Host
Microsoft.PowerShell.Management
Microsoft.PowerShell.ScheduledJob
Microsoft.PowerShell.Security
Microsoft.PowerShell.Utility
Microsoft.WSMan.Management
PSDesiredStateConfiguration
PSWorkflow
PSWorkflowUtility
ISE
JOURNALISATION DES ÉVÉNEMENTS DES MODULES
À compter de Windows PowerShell 3.0, vous pouvez enregistrer les événements d'exécution des applets de commande et des fonctions dans les modules et les composants logiciels enfichables Windows PowerShell. Pour cela, affectez la valeur $True à la propriété LogPipelineExecutionDetails des modules et des composants logiciels enfichables. Vous pouvez également utiliser le paramètre de stratégie de groupe Activer l'enregistrement des modules pour activer la journalisation des modules dans toutes les sessions Windows PowerShell. Pour plus d'informations, consultez about_EventLogs (https://go.microsoft.com/fwlink/?LinkID=113224) et about_Group_Policy_Settings (https://go.microsoft.com/fwlink/?LinkID=251696).
VOIR AUSSI
about_Command_Precedence
about_DesiredStateConfiguration
about_EventLogs
about_Group_Policy_Settings
about_PSSnapins
Get-Command
Get-Help
Get-Module
Import-Module
Remove-Module