Importe des commandes à partir d'une autre session dans la session active.
Syntaxe
Import-PSSession [-Session] <PSSession> [[-CommandName] <string[]>] [[-FormatTypeName] <string[]>] [-AllowClobber] [-ArgumentList <Object[]>] [-CommandType {<Alias> | <Function> | <Filter> | <Cmdlet> | <ExternalScript> | <Application> | <Script> | <All>}] [-Module <string[]>] [-Prefix <string>] [<CommonParameters>]
Description
L'applet de commande Import-PSSession importe des commandes (telles que des applets de commande, des fonctions et des alias) à partir d'une session PSSession d'un ordinateur local ou distant dans la session active. Vous pouvez importer toutes les commandes trouvées par Get-Command dans la session PSSession.
Utilisez une commande Import-PSSession pour importer des commandes à partir d'un interpréteur de commandes personnalisé, tel qu'un interpréteur de commandes Microsoft Exchange Server, ou à partir d'une session incluant des composants logiciels enfichables et des modules Windows PowerShell, ou d'autres éléments ne figurant pas dans la session active.
Pour importer des commandes, utilisez tout d'abord l'applet de commande New-PSSession pour créer une session PSSession. Utilisez ensuite l'applet de commande Import-PSSession pour importer les commandes. Par défaut, Import-PSSession importe toutes les commandes, à l'exception de celles portant le même nom que des commandes de la session active. Pour importer toutes les commandes, utilisez le paramètre AllowClobber.
Vous pouvez utiliser les commandes importées comme vous utiliseriez les autres commandes de la session. Lorsque vous utilisez une commande importée, la partie importée de la commande s'exécute implicitement dans la session à partir de laquelle elle a été importée. Toutefois, les opérations distantes sont entièrement contrôlées par Windows PowerShell. Il n'est pas nécessaire que vous en ayez conscience, mais vous devez quand même garder la connexion à l'autre session (PSSession) ouverte. Si vous la fermez, les commandes importées ne sont plus disponibles.
Étant donné que l'exécution des commandes importées peut être plus longue que celle des commandes locales, Import-PSSession ajoute un paramètre AsJob à chaque commande importée. Ce paramètre vous permet d'exécuter une commande en tant que tâche en arrière-plan Windows PowerShell. Pour plus d'informations, consultez about_Jobs.
Lorsque vous utilisez Import-PSSession, Windows PowerShell ajoute les commandes importées à un module temporaire qui existe uniquement dans votre session, et retourne un objet qui représente le module. Pour créer un module permanent que vous pourrez utiliser dans les prochaines sessions, utilisez l'applet de commande Export-PSSession.
L'applet de commande Import-PSSession utilise la fonctionnalité de communication à distance implicite de Windows PowerShell. Lorsque vous importez des commandes dans la session active, elles s'exécutent implicitement dans la session d'origine ou dans une session similaire sur l'ordinateur d'origine.
Paramètres
-AllowClobber
Importe les commandes spécifiées, même si elles portent le même nom que des commandes de la session active.
Si vous importez une commande portant le même nom qu'une commande de la session active, la commande importée masque ou remplace les commandes d'origine. Pour plus d'informations, consultez about_Command_Precedence.
f
Par défaut, Import-PSSession n'importe pas les commandes portant le même nom que des commandes de la session active.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
False |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-ArgumentList <Object[]>
Importe la variante de la commande qui résulte de l'utilisation des arguments spécifiés (valeurs de paramètre).
Par exemple, pour importer la variante de la commande Get-Item du lecteur de certificat (Cert:) dans la session PSSession de $s, tapez « import-pssession -session $s -command Get-Item -argumentlist cert: ».
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
All command in the PSSession, except for commands with the same names as commands in the current session. |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-CommandName <string[]>
Importe uniquement les commandes possédant les modèles de noms ou les noms spécifiés. Les caractères génériques sont autorisés. Utilisez « CommandName » ou son alias, « Name ».
Par défaut, Import-PSSession importe toutes les commandes de la session, à l'exception de celles portant le même nom que des commandes de la session active. Cela évite que les commandes importées masquent ou remplacent des commandes de la session active. Pour importer toutes les commandes, y compris celles masquant ou remplaçant d'autres commandes, utilisez le paramètre AllowClobber.
Si vous utilisez le paramètre CommandName, les fichiers de mise en forme des commandes ne sont pas importés, à moins que vous n'utilisiez le paramètre FormatTypeName. De la même manière, si vous utilisez le paramètre FormatTypeName, aucune commande n'est importée, à moins que vous n'utilisiez le paramètre CommandName.
|
Obligatoire ? |
false |
|
Position ? |
3 |
|
Valeur par défaut |
All commands in the PSSession, except for commands with the same names as commands in the current session. |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
true |
-CommandType <CommandTypes>
Importe uniquement les types d'objets de commande spécifiés. La valeur par défaut est Cmdlet. Utilisez « CommandType » ou son alias, « Type ».
Les valeurs valides sont :
-- Alias : alias Windows PowerShell dans la session à distance.
-- All : applets de commande et fonctions dans la session à distance.
-- Application : tous les fichiers autres que les fichiers Windows PowerShell dans les chemins d'accès répertoriés dans la variable d'environnement Path (env:path $) de la session à distance, notamment les fichiers .txt, .exe et .DLL.
-- Cmdlet : applets de commande dans la session à distance. « Cmdlet » est la valeur par défaut.
-- ExternalScript : fichiers .ps1 dans les chemins d'accès répertoriés dans la variable d'environnement Path ($env:path) de la session à distance.
-- Filter and Function : fonctions Windows PowerShell dans la session à distance.
-- Script : blocs de script dans la session à distance.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
All command in the PSSession, except for commands with the same names as commands in the current session. |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-FormatTypeName <string[]>
Importe les instructions de mise en forme des types Microsoft .NET Framework spécifiés. Entrez les noms de types. Les caractères génériques sont autorisés.
La valeur de ce paramètre doit être le nom d'un type retourné par une commande Get-FormatData dans la session à partir de laquelle les commandes sont importées. Pour obtenir toutes les données de mise en forme de la session à distance, tapez *.
Si la commande n'inclut pas les paramètres CommandName ou FormatTypeName, Import-PSSession
importe des instructions de mise en forme pour tous les types .NET Framework retournés par une commande Get-FormatData dans la session à distance.
Si vous utilisez le paramètre FormatTypeName, aucune commande n'est importée, à moins que vous n'utilisiez le paramètre CommandName.
De même, si vous utilisez le paramètre CommandName, les fichiers de mise en forme des commandes ne sont pas importés, à moins que vous n'utilisiez le paramètre FormatTypeName.
|
Obligatoire ? |
false |
|
Position ? |
4 |
|
Valeur par défaut |
Types in the System.Management.Automation namespace |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
true |
-Module <string[]>
Importe uniquement les commandes dans les composants logiciels enfichables et les modules Windows PowerShell spécifiés. Entrez les noms des modules et des composants logiciels enfichables. Les caractères génériques ne sont pas autorisés.
Pour plus d'informations, consultez about_Pssnapins et Import-Module.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
All command in the PSSession, except for commands with the same names as commands in the current session. |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-Prefix <string>
Ajoute le préfixe spécifié aux noms des commandes importées.
Utilisez ce paramètre pour éviter des conflits de nom qui peuvent se produire lorsque différentes commandes de la session ont le même nom.
Par exemple, si vous spécifiez le préfixe « Remote », puis importez une applet de commande Get-Date, l'applet de commande est connue dans la session comme Get-RemoteDate, et n'est pas confondue avec l'applet de commande Get-Date d'origine.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
|
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-Session <PSSession>
Spécifie la session PSSession à partir de laquelle les applets de commande sont importées. Entrez une variable qui contient un objet session ou une commande qui obtient un objet session, telle qu'une commande New-PSSession ou Get-PSSession. Vous pouvez spécifier une seule session. Ce paramètre est obligatoire.
|
Obligatoire ? |
true |
|
Position ? |
1 |
|
Valeur par défaut |
aucun |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
<CommonParameters>
Cette applet de commande prend en charge les paramètres courants : -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer et -OutVariable. Pour plus d'informations, consultez about_Commonparameters.
Entrées et sorties
Le type d'entrée est le type des objets que vous pouvez diriger vers l'applet de commande. Le type de retour est le type des objets que l'applet de commande retourne.
|
Entrées |
Aucun Vous ne pouvez pas diriger d'objets vers cette applet de commande. |
|
Sorties |
System.Management.Automation.PSModuleInfo Import-PSSession retourne le mêm objet module que New-Module et Get-Module. Toutefois, le module importé est temporaire et existe uniquement dans la session active. Pour créer un module permanent sur le disque, utilisez l'applet de commande Export-PSSession. |
Remarques
Import-PSSession repose sur l'infrastructure de communication à distance Windows PowerShell. Pour utiliser cette applet de commande, l'ordinateur doit être configuré pour la communication à distance de la Gestion des services Web. Pour plus d'informations, consultez about_Remote et about_Remote_Requirements.
Vous ne pouvez pas utiliser Import-PSSession pour importer des variables ou des fournisseurs Windows PowerShell.
Lorsque vous importez des commandes portant le même nom que des commandes de la session active, les commandes importées peuvent masquer les alias, fonctions et applets de commande de la session et remplacer des fonctions et des variables dans la session. Pour plus d'informations, consultez about_Command_Precedence.
Import-PSSession convertit toutes les commandes en fonctions avant de les importer. Par conséquent, le comportement des commandes importées est un peu différent de celui qu'elles auraient si elles conservaient leur type de commande d'origine. Par exemple, si vous importez une applet de commande à partir d'une session PSSession puis importez une applet de commande portant le même nom à partir d'un module ou d'un composant logiciel enfichable, l'applet de commande importée à partir de la session PSSession s'exécute toujours par défaut, car les fonctions sont prioritaires sur les applets de commande. Inversement, si vous importez un alias dans une session qui dispose d'un alias du même nom, l'alias d'origine est toujours utilisé, car les alias sont prioritaires sur les fonctions. Pour plus d'informations, consultez about_Command_Precedence.
Import-PSSession utilise l'applet de commande Write-Progress pour afficher la progression de la commande. Vous pouvez consulter la barre de progression pendant que la commande s'exécute.
Pour rechercher les commandes à importer, Import-PSSession utilise l'applet de commande Invoke-Command pour exécuter une commande Get-Command dans la session PSSession. Pour recevoir les données de mise en forme des commandes, elle utilise l'applet de commande Get-FormatData. Vous pouvez voir les messages d'erreur de Invoke-Command, Get-Command, Get-FormatData lorsque vous exécutez une commande Import-PSSession. De plus, Import-PSSession ne peut pas importer de commandes d'une session PSSession qui n'inclut pas les applets de commande Get-Command, Get-FormatData, Select-Object et Get-Help.
Les commandes importées présentent les mêmes limitations que les autres commandes distantes, notamment l'impossibilité de démarrer un programme avec une interface utilisateur, telle que le Bloc-notes.
Étant donné que les profils Windows PowerShell ne sont pas exécutés dans PSSessions, les commandes qu'un profil ajoute à une session ne sont pas disponibles pour Import-PSSession. Pour importer des commandes à partir d'un profil, utilisez une commande Invoke-Command pour exécuter le profil manuellement dans la session PSSession avant d'importer les commandes.
Le module temporaire que Import-PSSession crée peut inclure un fichier de mise en forme, même si la commande n'importe pas de données de mise en forme. Si la commande n'importe pas de données de mise en forme, tous les fichiers de mise en forme créés ne contiendront pas de données de mise en forme.
Pour utiliser Import-PSSession, la stratégie d'exécution dans la session active ne peut pas être Restricted ou AllSigned, étant donné que le module que Import-PSSession crée contient des fichiers de script non signés interdits par ces stratégies. Pour utiliser Import-PSSession sans modifier la stratégie d'exécution pour l'ordinateur local, utilisez le paramètre Scope de Set-ExecutionPolicy pour définir une stratégie d'exécution moins restrictive pour un processus unique.
Exemple 1
C:\PS>$s = new-pssession -computername Server01 C:\PS> import-pssession -session $s Description ----------- Cette commande importe toutes les commandes d'une session PSSession de l'ordinateur Server01 dans la session active, à l'exception des commandes portant le même nom que des commandes de la session active. Étant donné que cette commande n'utilise pas le paramètre CommandName, elle importe également toute les données de mise en forme obligatoires pour les commandes importées.
Exemple 2
C:\PS>$s = new-pssession https://ps.testlabs.com/powershell C:\PS> import-pssession -session $s -commandname *-test -formatTypeName * C:\PS> new-test -name test1 C:\PS> get-test test1 | run-test Description ----------- Ces commandes importent les commandes dont les noms se terminent par « - test » à partir d'une PSSession dans la session locale, puis indiquent comment utiliser une applet de commande importée. La première commande utilise l'applet de commande New-PSSession pour créer une session PSSession. Elle enregistre la session PSSession dans la variable $s. La deuxième commande utilise l'applet de commande Import-PSSession pour importer les commandes à partir de la session PSSession de la variable $s dans la session active. Elle utilise le paramètre CommandName pour spécifier des commandes portant le nom Test et le paramètre FormatTypeName pour importer les données de mise en forme pour les commandes Test. Les troisième et quatrième commandes utilisent les commandes importées dans la session active. Étant donné que les commandes importées sont en fait ajoutées à la session active, vous utilisez la syntaxe locale pour les exécuter. Vous n'avez pas besoin d'utiliser l'applet de commande Invoke-Command pour exécuter une commande importée.
Exemple 3
C:\PS>$s1 = new-pssession -computername s1 C:\PS> $s2 = new-pssession -computername s2 C:\PS> import-pssession -session s1 -type cmdlet -name New-Test, Get-Test -FormatTypeName * C:\PS> import-pssession -session s2 -type cmdlet -name Set-Test -FormatTypeName * C:\PS> new-test Test1 | set-test -runtype full Description ----------- Cet exemple montre que vous pouvez utiliser les applets de commande importées de la même façon que les applets de commande locales. Ces commandes importent les applets de commande New-Test et Get-Test à partir d'une session PSSession sur l'ordinateur Server01 et l'applet de commande Set-Test à partir d'une session PSSession sur l'ordinateur Server02. Bien que les applets de commande aient été importées à partir de différentes sessions PSSession, vous pouvez diriger un objet d'une applet de commande vers une autre sans générer d'erreur.
Exemple 4
C:\PS>$s = new-pssession -computername Server01 C:\PS> import-pssession -session $s -commandname *-test* -formattypename * C:\PS> $batch = new-test -name Batch -asjob C:\PS> receive-job $batch Description ----------- Cet exemple montre comment exécuter une commande importée en tant que tâche en arrière-plan. Étant donné que l'exécution des commandes importées peut être plus longue que celle des commandes locales, Import-PSSession ajoute un paramètre AsJob à chaque commande importée. Le paramètre AsJob vous permet d'exécuter la commande sous la forme d'une tâche en arrière-plan. La première commande crée une session PSSession sur l'ordinateur Server01 et enregistre l'objet PSSession dans la variable $s. La deuxième commande utilise Import-PSSession pour importer les applets de commande Test à partir de la session PSSession de la variable $s dans la session active. La troisième commande utilise le paramètre AsJob de l'applet de commande New-Test importée pour exécuter une commande New-Test en tant que tâche en arrière-plan. Cette commande enregistre l'objet de traitement que New-Test retourne dans la variable $batch. La quatrième commande utilise l'applet de commande Receive-Job pour obtenir les résultats de la tâche dans la variable $batch.
Exemple 5
C:\PS>$s = new-pssession -comp Server01
C:\PS> invoke-command -session $s {import-module TestManagement}
C:\PS> import-pssession -session $s -module TestManagement
Description
-----------
Cet exemple montre comment importer les applets de commande et fonctions à partir d'un module Windows PowerShell de l'ordinateur distant dans la session active.
La première commande crée une session PSSession sur l'ordinateur Server01 et l'enregistre dans la variable $s.
La deuxième commande utilise l'applet de commande Invoke-Command pour exécuter une commande Import-Module dans la session PSSession de la variable $s.
En général, le module est ajouté à toutes les sessions par une commande Import-Module dans un profil Windows PowerShell, mais les profils ne sont pas exécutés dans les sessions PSSession.
La troisième commande utilise le paramètre Module de Import-PSSession pour importer les applets de commande et fonctions du module dans la session active.
Exemple 6
C:\PS>import-pssession $s -CommandName Get-Date, SearchHelp -formatTypeName * -AllowClobber
Name : tmp_79468106-4e1d-4d90-af97-1154f9317239_tcw1zunz.ttf
Path : C:\Users\User01\AppData\Local\Temp\tmp_79468106-4e1d-4d90-af97-1154f9317239_tcw1zunz.ttf\tmp_79468106-4e1d-4d90-af97-1154f9317239_
tcw1zunz.ttf.psm1
Description : Implicit remoting for http://server01.corp.fabrikam.com/wsman
Guid : 79468106-4e1d-4d90-af97-1154f9317239
Version : 1.0
ModuleBase : C:\Users\User01\AppData\Local\Temp\tmp_79468106-4e1d-4d90-af97-1154f9317239_tcw1zunz.ttf
ModuleType : Script
PrivateData : {ImplicitRemoting}
AccessMode : ReadWrite
ExportedAliases : {}
ExportedCmdlets : {}
ExportedFunctions : {[Get-Date, Get-Date], [SearchHelp, SearchHelp]}
ExportedVariables : {}
NestedModules : {}
Description
-----------
Cet exemple montre que Import-PSSession crée un module dans un fichier temporaire sur le disque. Il montre également que toutes les commandes sont converties en fonctions avant d'être importées dans la session active.
La commande utilise l'applet de commande Import-PSSession pour importer une applet de commande Get-Date et une fonction SearchHelp dans la session active.
L'applet de commande Import-PSSession retourne un objet PSModuleInfo qui représente le module temporaire. La valeur de la propriété Path montre que Import-PSSession a créé un fichier de module de script (.psm1) dans un emplacement temporaire. La propriété ExportedFunctions montre que l'applet de commande Get-Date et la fonction SearchHelp ont été importées comme fonctions.
Exemple 7
C:\PS>import-pssession $s -CommandName Get-Date -formatTypeName * -AllowClobber C:\PS> get-command get-date CommandType Name Definition ----------- ---- ---------- Function Get-Date ... Cmdlet Get-Date Get-Date [[-Date] <DateTime>] [-Year <Int32>] [-Month <Int32>] C:\PS> Get-Date 09074 C:\PS> (get-command -type cmdlet -name get-date).pssnapin.name Microsoft.PowerShell.Utility C:\PS> Microsoft.PowerShell.Utility\get-date Sunday, March 15, 2009 2:08:26 PM Description ----------- Cet exemple montre comment exécuter une commande masquée par une commande importée. La première commande importe une applet de commande Get-Date à partir de la session PSSession dans la variable $s. Étant donné que la session active inclut une applet de commande Get-Date, le paramètre AllowClobber est obligatoire dans la commande. La deuxième commande utilise l'applet de commande Get-Command pour obtenir les commandes Get-Date de la session active. La sortie montre que la session inclut l'applet de commande Get-Date d'origine et une fonction Get-Date. La fonction Get-Date exécute l'applet de commande Get-Date importée dans la session PSSession de $s. La troisième commande exécute une commande Get-Date. Étant donné que les fonctions sont prioritaires sur les applets de commande, Windows PowerShell exécute la fonction Get-Date importée, qui retourne une date julienne. Les quatrième et cinquième commandes montrent comment utiliser un nom qualifié pour exécuter une commande masquée par une commande importée. La quatrième commande obtient le nom du composant logiciel enfichable Windows PowerShell qui a ajouté l'applet de commande Get-Date d'origine à la session active. La cinquième commande utilise le nom de composant enfichable qualifié de l'applet de commande Get-Date pour exécuter une commande Get-Date. Pour plus d'informations sur la priorité des commandes et les commandes masquées, consultez about_Command_Precedence.
Exemple 8
C:\PS>import-pssession -session $s -commandName *Item* -AllowClobber Description ----------- Cette commande importe les commandes dont les noms incluent « Item » à partir de la session PSSession dans $s. Étant donné que la commande inclut le paramètre CommandName mais pas le paramètre FormatTypeData, seule la commande est importée. Utilisez cette commande lorsque vous utilisez Import-PSSession pour exécuter une commande sur un ordinateur distant et que vous disposez déjà des données de mise en forme pour la commande dans la session active.
Exemple 9
C:\PS>$m = import-pssession -session $s -CommandName *bits* -formattypename *bits* C:\PS> get-command -module $m CommandType Name ----------- ---- Function Add-BitsFile Function Complete-BitsTransfer Function Get-BitsTransfer Function Remove-BitsTransfer Function Resume-BitsTransfer Function Set-BitsTransfer Function Start-BitsTransfer Function Suspend-BitsTransfer Description ----------- Cette commande montre comment utiliser le paramètre Module de Get-Command pour rechercher les commandes qui ont été importées dans la session par une commande Import-PSSession. La première commande utilise l'applet de commande Import-PSSession pour importer les commandes dont les noms incluent des « parties » de la session PSSession dans la variable $s. La commande Import-PSSession retourne un module temporaire, puis enregistre le module dans la variable $m. La deuxième commande utilise l'applet de commande Get-Command pour obtenir les commandes exportées par le module dans la variable $m. Le paramètre Module prend une valeur de chaîne conçue pour le nom du module. Toutefois, lorsque vous envoyez un objet module, Windows PowerShell utilise la méthode ToString sur l'objet module, qui retourne le nom du module. La commande Get-Command est l'équivalent de « get-command $m.name ».
Voir aussi