about_Modules

  • Article

Description courte

Explique comment installer, importer et utiliser des modules PowerShell.

Description longue

Un module est un package qui contient des membres PowerShell, tels que 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. Les personnes qui reçoivent des modules peuvent ajouter les commandes dans les modules à leurs sessions PowerShell et les utiliser comme les commandes intégrées.

Cette rubrique explique comment utiliser des 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 package qui contient des membres PowerShell, tels que des applets de commande, des fournisseurs, des fonctions, des workflows, des variables et des alias. Les membres de ce package peuvent être implémentés dans un script PowerShell, une DLL compilée ou une combinaison des deux. Ces fichiers sont généralement regroupés dans un seul répertoire. Pour plus d’informations, consultez Présentation d’un module Windows PowerShell dans la documentation du Kit de développement logiciel (SDK).

Chargement automatique des modules

À compter de PowerShell 3.0, PowerShell importe automatiquement les modules la première fois que vous exécutez n’importe quelle commande dans un module installé. Vous pouvez désormais utiliser les commandes d'un module sans même le configurer ni définir de profil. Une fois vos modules installés sur votre ordinateur, vous n'avez pas à vous en occuper.

Vous pouvez aussi trouver plus facilement les commandes contenues dans un module. L’applet Get-Command de commande obtient désormais toutes les commandes de tous les modules installés, même si elles ne sont pas encore dans la session. Vous pouvez trouver une commande et l’utiliser sans avoir besoin d’importer le module en premier.

Chacun des exemples suivants entraîne l’importation du module CimCmdlets, qui contient Get-CimInstance, dans votre session.

  • Exécuter la commande

    Get-CimInstance Win32_OperatingSystem

  • Obtenir la commande

    Get-Command Get-CimInstance

  • Obtenir de l’aide pour la commande

    Get-Help Get-CimInstance

Get-Command Les commandes qui incluent un caractère générique (*) sont considérées comme destinées à la découverte, ne sont pas utilisées 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 dans d’autres emplacements doivent être importés en exécutant l’applet de Import-Module 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: comme 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 pour importer un module et utiliser la $PSModuleAutoloadingPreference variable pour activer, désactiver et configurer l’importation automatique de modules. Pour plus d’informations, consultez about_Preference_Variables.

Utilisation d’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.

Installation d’un module

Si vous recevez un module en tant que 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 fourni avec plusieurs modules préinstallés, parfois appelés modules principaux . Sur les ordinateurs Windows, si les fonctionnalités incluses dans le système d’exploitation ont des applets de commande pour les gérer, 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 Gestionnaire de serveur, ou de la boîte de dialogue Activer ou désactiver les fonctionnalités Windows dans Panneau de configuration, tous les modules PowerShell qui font partie de la fonctionnalité sont installés. D'autres modules sont fournis avec un programme d'installation.

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

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

Copiez le dossier du module en totalité 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 Copy-Item commande. Par exemple, pour copier le dossier MyModule du C:\ps-test\MyModule répertoire Modules, tapez :

Copy-Item -Path C:\ps-test\MyModule -Destination `
    $HOME\Documents\PowerShell\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 de module par défaut, consultez la section Modules et DSC Resource Locations et PSModulePath .

Guide pratique pour 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 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 rechercher les commandes dans un module

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

Pour trouver toutes les commandes dans un module, tapez :

Get-Command -Module <module-name>

Par exemple, pour rechercher les commandes dans le module BitsTransfer, tapez :

Get-Command -Module BitsTransfer

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

Comment obtenir de l’aide pour les commandes dans 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.

À compter de PowerShell 3.0, vous pouvez télécharger des fichiers d’aide pour 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 sur une commande d'un module, tapez :

Get-Help <command-name>

Pour obtenir de l’aide en ligne pour la commande dans un module, tapez :

Get-Help <command-name> -Online

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

Vous pouvez également choisir d’importer un module pour 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 noms de toutes les commandes importées, ou le paramètre NoClobber , ce qui empêche le module d’ajouter des commandes qui masquent ou remplacent 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 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 dans le C:\ps-test répertoire à 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 C:\ps-test répertoire à 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 Import-Module commande importe des modules dans votre session PowerShell actuelle. Pour importer un module dans chaque session PowerShell que vous démarrez, ajoutez la Import-Module commande à votre profil PowerShell.

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

Guide pratique pour 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 le format de commande suivant.

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, consultez Remove-Module.

Emplacements des ressources module et DSC et PSModulePath

La $env:PSModulePath variable d’environnement contient une liste d’emplacements de dossiers qui sont recherchés pour rechercher des modules et des ressources.

Par défaut, les emplacements effectifs auxquels il est attribué $env:PSModulePath sont les suivants :

  • Emplacements à l’échelle du système : $PSHOME\Modules

    Ces dossiers contiennent des modules qui sont fournis avec Windows et PowerShell.

    Les ressources DSC incluses dans PowerShell sont stockées dans le $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources dossier.

  • Modules spécifiques à l’utilisateur : il s’agit de modules installés par l’utilisateur dans l’étendue de l’utilisateur. Install-Module a un paramètre Scope qui vous permet de spécifier si le module est installé pour l’utilisateur actuel ou pour tous les utilisateurs. Pour plus d’informations, consultez Install-Module.

    L’emplacement CurrentUser spécifique à l’utilisateur sur Windows est le PowerShell\Modules dossier situé dans l’emplacement Documents de votre profil utilisateur. Le chemin d’accès spécifique de cet emplacement varie selon la version de Windows et si vous utilisez ou non la redirection de dossiers. Microsoft OneDrive peut également modifier l’emplacement de votre dossier Documents .

    Par défaut, sur Windows 10 et versions ultérieures, cet emplacement est $HOME\Documents\PowerShell\Modules. Sur Linux ou Mac, l’emplacement CurrentUser est $HOME/.local/share/powershell/Modules.

    Notes

    Vous pouvez vérifier l’emplacement de votre dossier Documents à l’aide de la commande suivante : [Environment]::GetFolderPath('MyDocuments')

  • L’emplacement AllUsers se trouve $env:PROGRAMFILES\PowerShell\Modules sur Windows. Sur Linux ou Mac, les modules sont stockés sur /usr/local/share/powershell/Modules.

Notes

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 de module par défaut 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 (;) dans la commande sépare le nouveau chemin d’accès qui l’précède dans la liste.

Par exemple, pour ajouter le C:\ps-test\Modules répertoire, tapez :

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

Pour ajouter un emplacement de module par défaut sur Linux ou MacOS, utilisez le format de commande suivant :

$Env:PSModulePath += ":<path>"

Par exemple, pour ajouter le /usr/local/Fabrikam/Modules répertoire à la valeur de la variable d’environnement PSModulePath , tapez :

$Env:PSModulePath += ":/usr/local/Fabrikam/Modules"

Sur Linux ou MacOS, le signe deux-points (:) dans la commande sépare le nouveau chemin d’accès qui l’précède dans la liste.

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

La valeur que vous définissez affecte uniquement la session active. Pour apporter la modification persistante, ajoutez la commande à votre profil PowerShell ou utilisez System dans Panneau de configuration pour modifier la valeur de la variable d’environnement PSModulePath dans le Registre.

En outre, pour apporter la modification persistante, vous pouvez également utiliser la méthode SetEnvironmentVariable de la classe System.Environment pour ajouter un chemin à 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.

Hidden

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.

Remplacé

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 les conflits de noms, utilisez le paramètre All de l’applet Get-Command de commande. À compter de PowerShell 3.0, Get-Command obtient uniquement les commandes qui s’exécutent lorsque 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 Préfixe de l’applet Import-Module de commande. Le paramètre Préfixe ajoute un préfixe aux noms des commandes importées afin qu’elles soient uniques dans la session. Le paramètre NoClobber n’importe aucune commande qui masque ou remplace les commandes existantes dans la session.

Vous pouvez également utiliser les paramètres Alias, Cmdlet, Function et Variable pour Import-Module sélectionner uniquement les commandes que vous souhaitez importer, et vous pouvez exclure des 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 Préfixe est prioritaire 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 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. 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 plus d’informations, notamment une explication des règles de priorité 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, notamment les applets de commande, les fournisseurs et les fonctions, ainsi que les éléments, tels que les variables, les alias et les 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 les commandes qui seront supprimées.

Pour rechercher 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

Les commandes qu’un module exporte doivent suivre les règles d’affectation de noms des commandes PowerShell. Si le module que vous importez exporte des applets de commande ou des fonctions qui ont des verbes non approuvés dans leurs noms, 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 obtenir plus d'informations ou tapez Get-Verb pour afficher la liste des verbes approuvés.

Ce message n'est qu'un avertissement. Le module entier 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 Import-Module de commande.

Modules intégrés et composants logiciels enfichables

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

À compter de PowerShell 3.0, pour les programmes hôtes qui implémentent l’API InitialSessionState.CreateDefault2 d’état de session 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.

Notes

Les sessions distantes, y compris les sessions démarrées à l’aide de l’applet New-PSSession de commande, sont des sessions de style plus ancien dans lesquelles les commandes intégrées sont empaquetées dans les composants logiciels enfichables.

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

  • CimCmdlets
  • Microsoft.PowerShell.Archive
  • Microsoft.PowerShell.Core
  • Microsoft.PowerShell.Diagnostics
  • Microsoft.PowerShell.Host
  • Microsoft.PowerShell.Management
  • Microsoft.PowerShell.Security
  • Microsoft.PowerShell.Utility
  • Microsoft.WSMan.Management
  • PackageManagement
  • PowerShellGet
  • PSDesiredStateConfiguration
  • PSDiagnostics
  • PSReadline

Événements de module de journalisation

À 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 PowerShell et les composants logiciels enfichables en définissant la propriété LogPipelineExecutionDetails des modules et des composants logiciels enfichables $Truesur . Vous pouvez également utiliser un paramètre 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 les articles de stratégie de journalisation et de groupe.

Voir aussi