À propos des modules

Brève description

Explique comment installer, importer et utiliser des modules PowerShell.

Description longue

Un module est un package qui contient des commandes PowerShell, telles que des applets de commande, des fournisseurs, des fonctions, des flux de travail, 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. Les personnes qui reçoivent des modules peuvent ajouter les commandes qu’ils contiennent à leurs sessions PowerShell et les utiliser comme les commandes intégrées.

Cette rubrique explique comment utiliser les modules PowerShell. Pour plus d’informations sur l’écriture de modules PowerShell, consultez Écriture d’un module PowerShell.

Qu’est-ce qu’un module ?

Un module est un ensemble de commandes. Toutes les applets de commande et tous les fournisseurs de votre session sont ajoutés par un module ou un composant logiciel enfichable.

Chargement automatique du module

À compter de PowerShell 3.0, PowerShell importe automatiquement les modules la première fois que vous exécutez une commande dans un module installé. Vous pouvez désormais utiliser les commandes dans un module sans aucune configuration de configuration de profil, il n’est donc pas nécessaire de gérer les modules après les avoir installés sur votre ordinateur.

Les commandes d’un module sont également plus faciles à trouver. L’applet Get-Command de commande récupère désormais toutes les commandes de tous les modules installés, même s’ils ne sont pas encore dans la session, ce qui vous permet de trouver une commande et de l’utiliser sans l’importer.

Chacun des exemples suivants entraîne l’importation du module contenant Get-Mailbox dans votre session.

Exécuter la commande
```
Get-Mailbox -Identity Chris
```
Obtenir la commande
```
Get-Command Get-Mailbox
```
Obtenir de l’aide pour la commande
```
Get-Help Get-Mailbox
```

Get-Command Les commandes qui incluent un caractère générique (*) sont considérées comme étant destinées à la découverte, et non à l’utilisation, et n’importent aucun module.

Seuls les modules stockés à l’emplacement spécifié par la variable d’environnement PSModulePath sont automatiquement importés. Les modules situés à d’autres emplacements doivent être importés en exécutant l’applet Import-Module de commande.

En outre, les commandes qui utilisent des fournisseurs PowerShell n’importent pas automatiquement un module. Par exemple, si vous utilisez une commande qui nécessite le lecteur WSMan :, telle que l’applet Get-PSSessionConfiguration de commande, vous devrez peut-être exécuter l’applet Import-Module de commande pour importer le module Microsoft.WSMan.Management qui inclut le WSMan: lecteur.

Vous pouvez toujours exécuter la Import-Module commande d’importation d’un module et utiliser la variable pour activer, désactiver et configurer l’importation $PSModuleAutoloadingPreference automatique de modules. Pour plus d'informations, consultez about_Preference_Variables.

Comment utiliser un module

Pour utiliser un module, effectuez les tâches suivantes :

Installez le module. (C’est souvent fait pour vous.)
Recherchez les commandes que le module a ajoutées.
Utilisez les commandes ajoutées par le module.

Cette rubrique explique comment effectuer ces tâches. Il comprend également d’autres informations utiles sur la gestion des modules.

Comment installer un module

Si vous recevez un module sous la forme d’un dossier contenant des fichiers, vous devez l’installer sur votre ordinateur avant de pouvoir l’utiliser dans PowerShell.

La plupart des modules sont installés pour vous. PowerShell est livré avec plusieurs modules préinstallés, parfois appelés modules « core ». Sur les ordinateurs Windows, si les fonctionnalités incluses dans le système d’exploitation sont gérées par des applets de commande, ces modules sont préinstallés. Lorsque vous installez une fonctionnalité Windows, à l’aide, par exemple, de l’Assistant Ajout de rôles et de fonctionnalités dans le Gestionnaire de serveur ou de la boîte de dialogue Activer ou désactiver les fonctionnalités Windows dans le Panneau de configuration, tous les modules PowerShell qui font partie de la fonctionnalité sont installés. De nombreux autres modules sont livrés dans un programme d’installation ou un programme d’installation qui installe le module.

Utilisez la commande suivante pour créer un répertoire Modules pour l’utilisateur actuel :

New-Item -Type Directory -Path $HOME\Documents\WindowsPowerShell\Modules

Copiez l’intégralité du dossier module dans le répertoire Modules. Vous pouvez utiliser n’importe quelle méthode pour copier le dossier, y compris l’Explorateur Windows et Cmd.exe, ainsi que PowerShell. Dans PowerShell, utilisez l’applet de commande Copy-Item. Par exemple, pour copier le dossier MyModule depuis C:\ps-test\MyModule le répertoire Modules, tapez :

Copy-Item -Path C:\ps-test\MyModule -Destination `
    $HOME\Documents\WindowsPowerShell\Modules

Vous pouvez installer un module à n’importe quel emplacement, mais l’installation de vos modules dans un emplacement de module par défaut facilite leur gestion. Pour plus d’informations sur les emplacements de module par défaut, consultez la section Emplacements des ressources de module et DSC et PSModulePath .

Comment trouver les modules installés

Pour rechercher les modules installés dans un emplacement de module par défaut, mais qui n’ont pas encore été importés dans votre session, tapez :

Get-Module -ListAvailable

Pour rechercher les modules qui ont déjà été importés dans votre session, à l’invite PowerShell, tapez :

Get-Module

Pour plus d’informations sur l’applet Get-Module de commande, consultez Get-Module.

Comment trouver les commandes dans un module

Utilisez l’applet de commande Get-Command pour rechercher toutes les commandes disponibles. Vous pouvez utiliser les paramètres de l’applet de commande Get-Command pour filtrer des commandes par module, nom et nom commun.

Pour rechercher toutes les commandes d’un module, tapez :

Get-Command -Module <module-name>

Par exemple, pour trouver les commandes 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 pour les commandes d’un module

Si le module contient des fichiers d’aide pour les commandes qu’il exporte, l’applet Get-Help de commande affiche les rubriques d’aide. Utilisez le même Get-Help format de commande que celui que vous utiliseriez pour obtenir de l’aide pour n’importe quelle commande dans PowerShell.

À partir de PowerShell 3.0, vous pouvez télécharger les fichiers d’aide d’un module et télécharger les mises à jour des fichiers d’aide afin qu’ils ne soient jamais obsolètes.

Pour obtenir de l’aide pour une commande dans un module, tapez :

Get-Help <command-name>

Pour obtenir de l’aide en ligne sur la commande d’un module, tapez :

Get-Help <command-name> -Online

Pour télécharger et installer les fichiers d’aide des 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 devrez peut-être importer un module ou importer un fichier de module. L’importation est requise lorsqu’un module n’est pas installé aux emplacements spécifiés par la variable d’environnement PSModulePath , $env:PSModulePathou que le module se compose d’un fichier, tel qu’un fichier .dll ou .psm1, au lieu d’un module classique fourni sous la forme d’un dossier.

Vous pouvez également choisir d’importer un module afin de pouvoir utiliser les paramètres de la Import-Module commande, tels que le paramètre Prefix, qui ajoute un préfixe distinctif aux noms de toutes les commandes importées, ou le paramètre NoClobber , qui empêche le module d’ajouter des commandes qui masqueraient ou remplaceraient les commandes existantes dans la session.

Pour importer des modules, utilisez l’applet de Import-Module commande.

Pour importer des modules dans un emplacement PSModulePath dans la session en cours, utilisez le format de commande suivant.

Import-Module <module-name>

Par exemple, la commande suivante importe le module BitsTransfer dans la session en cours.

Import-Module BitsTransfer

Pour importer un module qui ne se trouve pas dans un emplacement de module par défaut, utilisez le chemin d’accès complet au dossier module dans la commande.

Par exemple, pour ajouter le module TestCmdlets dans l’annuaire C:\ps-test à votre session, tapez :

Import-Module C:\ps-test\TestCmdlets

Pour importer un fichier de module qui n’est pas contenu dans un dossier de module, utilisez le chemin d’accès complet au fichier de 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 PowerShell actuelle. Pour importer un module dans chaque session PowerShell que vous démarrez, ajoutez la commande Import-Module à votre profil PowerShell.

Pour plus d’informations sur les profils, consultez about_Profiles.

Comment retirer un module

Lorsque 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 le format de commande suivant.

Remove-Module <module-name>

Par exemple, la commande suivante supprime le module BitsTransfer de la session en cours.

Remove-Module BitsTransfer

La suppression d’un module inverse l’opération d’importation d’un module. La suppression d’un module ne désinstalle pas le module. Pour plus d’informations, veuillez consulter la section Remove-Module.

Emplacements des ressources Module et DSC, et PSModulePath

Voici les emplacements par défaut des modules PowerShell. À partir de PowerShell 4.0, avec l’introduction de DSC, un nouveau module par défaut et un nouveau dossier de ressources DSC ont été introduits. Pour plus d’informations sur les DSC, reportez-vous à la about_DesiredStateConfiguration.

Système : $PSHOME\Modules ou ($env:windir\System32\WindowsPowerShell\v1.0\Modules) Les modules système sont ceux qui sont livrés avec Windows et PowerShell.

À compter de PowerShell 4.0, lorsque la configuration de l’état souhaité (DSC) PowerShell a été introduite, les ressources DSC incluses avec PowerShell sont également stockées dans $PSHOME\Modules, dans le $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources dossier.
Utilisateur actuel : $HOME\Documents\WindowsPowerShell\Modules ($env:UserProfile\Documents\WindowsPowerShell\Modules)

ou

$HOME\My Documents\WindowsPowerShell\Modules ($env:UserProfile\My Documents\WindowsPowerShell\Modules)

Il s’agit de l’emplacement des modules ajoutés par l’utilisateur avant PowerShell 4.0.

Dans PowerShell 4.0 et les versions ultérieures de PowerShell, les modules ajoutés par l’utilisateur et les ressources DSC sont stockés dans C:\Program Files\WindowsPowerShell\Modules. Les modules et les ressources DSC de cet emplacement sont accessibles à tous les utilisateurs de l’ordinateur. Cette modification était nécessaire car le moteur DSC s’exécute en tant que système local et ne pouvait pas accéder aux chemins d’accès spécifiques à l’utilisateur, tels que $home\Documents\WindowsPowerShell\Modules.

À compter de PowerShell 5.0, avec l’ajout du module PowerShellGet et de la galerie PowerShell des ressources de la communauté et créées par Microsoft, la Install-Module commande installe les modules et les ressources DSC par C:\Program Files\WindowsPowerShell\Modules défaut.

Remarque : Pour ajouter ou modifier des fichiers dans le $env:Windir\System32 répertoire, démarrez 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 est modélisée sur la variable d’environnement Path et a le même format.

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 (;) de 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 C:\ps-test\Modules répertoire, tapez :

$Env:PSModulePath + ";C:\ps-test\Modules"

Lorsque vous ajoutez un chemin d’accès à PSModulePathGet-Module et Import-Module que les commandes incluent des modules dans ce chemin.

La valeur que vous définissez n’affecte que la session en cours. Pour que la modification soit persistante, ajoutez la commande à votre profil PowerShell ou utilisez Système dans le Panneau de configuration pour modifier la valeur de la variable d’environnement PSModulePath dans le registre.

En outre, pour rendre la modification persistante, vous pouvez également 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.

Conflits de modules et de noms

Les conflits de noms se produisent lorsque plusieurs commandes de la session ont le même nom. L’importation d’un module provoque un conflit de noms lorsque les commandes du module ont les mêmes noms que les commandes ou les éléments de la session.

Les conflits de noms peuvent entraîner des commandes masquées ou remplacées.

Caché

Une commande est masquée lorsqu’il ne s’agit pas de la commande qui s’exécute lorsque vous tapez le nom de la commande, mais que vous pouvez l’exécuter à l’aide d’une autre méthode, par exemple en qualifiant le nom de la commande avec le nom du module ou du composant logiciel enfichable dont elle provient.

Remplacé

Une commande est remplacée lorsque vous ne pouvez pas l’exécuter parce qu’elle a été remplacée par une commande du même nom. Même lorsque 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. De plus, les commandes de votre session peuvent masquer les commandes ajoutées par le module.

Pour détecter les conflits de noms, utilisez le paramètre All de l’applet de commande Get-Command. À partir de PowerShell 3.0, Get-Command seules les commandes qui s’exécutent lorsque vous tapez le nom de la commande sont obtenues. Le paramètre All obtient toutes les commandes avec le nom spécifique dans la session.

Pour éviter les conflits de noms, utilisez les paramètres noClobber ou préfixe de l’applet de commande Import-Module. Le paramètre Prefix ajoute un préfixe aux noms des commandes importées afin qu’elles soient uniques dans la session. Le paramètre NoClobber n’importe pas les commandes qui masqueraient ou remplaceraient les commandes existantes dans la session.

Vous pouvez également utiliser les paramètres d'alias , de cmdlet , de fonction et de variable de 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 empêcher les conflits de noms à l’aide de la propriété DefaultCommandPrefix du manifeste du module pour ajouter un préfixe par défaut à tous les noms de commandes. 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 dans lequel elle provient.

Les règles de priorité des commandes PowerShell déterminent quelle commande s’exécute lorsque la session inclut des commandes portant le même nom.

Par exemple, lorsqu’une session inclut une fonction et une applet de commande portant le même nom, PowerShell exécute la fonction par défaut. Lorsque la session inclut des commandes du même type portant le même nom, telles que deux applets de commande portant le même nom, par défaut, elle exécute la commande la plus récente ajoutée.

Pour plus d’informations, notamment une explication des règles de précédence et des instructions relatives à l’exécution de 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 commandes, y compris des applets de commande, des fournisseurs et des fonctions, ainsi que des éléments, tels que des variables, des alias et des lecteurs 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 quelles commandes seront supprimées.

Pour trouver la source d’une applet de commande dans votre session, utilisez le format de commande suivant :

Get-Command <cmdlet-name> | Format-List -Property verb,noun,pssnapin,module

Par exemple, pour rechercher la source de l’applet Get-Date de commande, tapez :

Get-Command Get-Date | Format-List -Property verb,noun,module

Pour plus d’informations sur les composants logiciels enfichables PowerShell, consultez about_PSSnapins.

Les commandes qu’un module exporte doivent suivre les règles de nommage des commandes PowerShell. Si le module que vous importez exporte des applets de commande ou des fonctions dont le nom contient des verbes non approuvés, l’applet Import-Module de commande affiche le message d’avertissement suivant.

AVERTISSEMENT : Certains noms de commandes importés incluent des verbes non approuvés qui peuvent les rendre moins détectables. Utilisez le paramètre Verbose pour plus de détails ou de type Get-Verb pour afficher la liste des verbes approuvés.

Ce message n’est qu’un avertissement. Le module complet est toujours importé, y compris les commandes non conformes. Bien que le message s’affiche aux utilisateurs du module, le problème de nommage doit être résolu par l’auteur du module.

Pour supprimer le message d’avertissement, utilisez le paramètre DisableNameChecking de l’applet Import-Module de commande.

Modules intégrés et composants logiciels enfichables

Dans PowerShell 2.0 et dans les programmes hôtes de style plus ancien dans PowerShell 3.0 et versions ultérieures, les commandes principales installées avec PowerShell sont empaquetées dans des composants logiciels enfichables qui sont ajoutés automatiquement à chaque session PowerShell.

À partir de PowerShell 3.0, pour les programmes hôtes qui implémentent l’API d’état de session InitialSessionState.CreateDefault2 initiale, 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 New-PSSession de commande, sont des sessions de style ancien dans lesquelles les commandes intégrées sont empaquetées dans des composants logiciels enfichables.

Les modules (ou composants logiciels enfichables) suivants sont installés avec PowerShell.

Microsoft.PowerShell.Archive
Microsoft.PowerShell.Core
Microsoft.PowerShell.Diagnostics
Microsoft.PowerShell.Host
Microsoft.PowerShell.Gestion
Microsoft.PowerShell.ODataUtils
Microsoft.PowerShell.Sécurité
Microsoft.PowerShell.Utilitaire
Microsoft.WSMan.Management
Gestion des Paquets
PowerShellObtenir
PSDesiredStateConfiguration
PSReadline
PSScheduledJob
PSWorkflow
PSWorkflowUtility
ISE

Journaux des événements de module

À compter de PowerShell 3.0, vous pouvez enregistrer des événements d’exécution pour les applets de commande et les fonctions dans les modules et les composants logiciels enfichables PowerShell en définissant la propriété LogPipelineExecutionDetails des modules et des composants logiciels enfichables sur $True. Vous pouvez également utiliser un paramètre de stratégie de groupe, Activer la journalisation des modules, pour activer la journalisation des modules dans toutes les sessions PowerShell. Pour plus d’informations, consultez about_EventLogs et about_Group_Policy_Settings.