Import-PSSession

Syntaxe

Import-PSSession
      [-Prefix <String>]
      [-DisableNameChecking]
      [[-CommandName] <String[]>]
      [-AllowClobber]
      [-ArgumentList <Object[]>]
      [-CommandType <CommandTypes>]
      [-Module <String[]>]
      [-FullyQualifiedModule <ModuleSpecification[]>]
      [[-FormatTypeName] <String[]>]
      [-Certificate <X509Certificate2>]
      [-Session] <PSSession>
      [<CommonParameters>]

Description

L’applet Import-PSSession de commande importe des commandes, telles que des applets de commande, des fonctions et des alias, à partir d’une session PSSession sur un ordinateur local ou distant dans la session active. Vous pouvez importer n’importe quelle commande que l’applet Get-Command de commande peut trouver dans la session PSSession.

Utilisez une Import-PSSession commande 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 qui inclut des modules Windows PowerShell et des composants logiciels enfichables ou d’autres éléments qui ne figurent pas dans la session active.

Pour importer des commandes, utilisez d’abord l’applet New-PSSession de commande pour créer une session PSSession. Utilisez ensuite l’applet Import-PSSession de commande pour importer les commandes. Par défaut, importe toutes les commandes à Import-PSSession l’exception des commandes qui ont le même nom que les commandes dans la session active. Pour importer toutes les commandes, utilisez le paramètre AllowClobber .

Vous pouvez utiliser des commandes importées comme vous utiliseriez n'importe quelle commande de la session. Quand 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 à distance sont gérées entièrement par Windows PowerShell. Vous ne devez même pas vous en rendre compte, sauf que vous devez conserver la connexion à l'autre session (PSSession) ouverte. Si vous la fermez, les commandes importées ne sont plus disponibles.

Étant donné que les commandes importées peuvent prendre plus de temps que les commandes locales, Import-PSSession ajoutez un paramètre AsJob à chaque commande importée. Ce paramètre vous permet d'exécuter la commande en tant que tâche en arrière-plan Windows PowerShell. Pour plus d’informations, consultez à propos des_tâches.

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 persistant que vous pouvez utiliser dans les sessions ultérieures, utilisez l’applet de Export-PSSession commande.

L’applet Import-PSSession de commande utilise la fonctionnalité de communication à distance implicite de Windows PowerShell. Quand 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.

À compter de Windows PowerShell 3.0, vous pouvez utiliser l’applet Import-Module de commande pour importer des modules à partir d’une session distante dans la session active. Cette fonctionnalité utilise la communication à distance implicite. Il équivaut à utiliser Import-PSSession pour importer des modules sélectionnés à partir d’une session distante dans la session active.

Exemples

Exemple 1 : Importer toutes les commandes à partir d’une session PSSession

$S = New-PSSession -ComputerName Server01
Import-PSSession -Session $S

Cette commande importe toutes les commandes d'une session PSSession sur l'ordinateur Server01 dans la session active, à l'exception des commandes qui ont le même nom que les commandes dans la session active.

Étant donné que cette commande n’utilise pas le paramètre CommandName , elle importe également toutes les données de mise en forme requises pour les commandes importées.

Exemple 2 : Importer des commandes qui se terminent par une chaîne spécifique

$S = New-PSSession https://ps.testlabs.com/powershell
Import-PSSession -Session $S -CommandName *-test -FormatTypeName *
New-Test -Name Test1
Get-Test test1 | Run-Test

Ces commandes importent les commandes dont les noms se terminent par « -test » à partir d'une session PSSession dans la session locale, puis indiquent comment utiliser une applet de commande importée.

La première commande utilise l’applet New-PSSession de commande pour créer une session PSSession. Il enregistre la session PSSession dans la $S variable.

La deuxième commande utilise l’applet Import-PSSession de commande pour importer des commandes à partir de la session PSSession dans $S la session active. Il utilise le paramètre CommandName pour spécifier des commandes avec le nom test et le paramètre FormatTypeName pour importer les données de mise en forme des commandes test.

Les troisième et quatrième commandes utilisent les commandes importées dans la session active. Comme les commandes importées sont en réalité ajoutées à la session active, vous utilisez la syntaxe locale pour les exécuter. Vous n’avez pas besoin d’utiliser l’applet Invoke-Command de commande pour exécuter une commande importée.

Exemple 3 : Importer des applets de commande à partir d’une session PSSession

$S1 = New-PSSession -ComputerName s1
$S2 = New-PSSession -ComputerName s2
Import-PSSession -Session s1 -Type cmdlet -Name New-Test, Get-Test -FormatTypeName *
Import-PSSession -Session s2 -Type Cmdlet -Name Set-Test -FormatTypeName *
New-Test Test1 | Set-Test -RunType Full

Cet exemple montre que vous pouvez utiliser les applets de commande importées comme vous utiliseriez des applets de commande locales.

Ces commandes importent les New-Test applets de commande et Get-Test les applets de commande à partir d’une session PSSession sur l’ordinateur Server01 et de l’applet Set-Test de commande à partir d’une session PSSession sur l’ordinateur Server02.

Même si les applets de commande ont été importées à partir de différentes sessions PSSession, vous pouvez diriger un objet d'une applet de commande vers une autre sans erreur.

Exemple 4 : Exécuter une commande importée en tant que travail en arrière-plan

$S = New-PSSession -ComputerName Server01
Import-PSSession -Session $S -CommandName *-test* -FormatTypeName *
$batch = New-Test -Name Batch -AsJob
Receive-Job $batch

Cet exemple montre comment exécuter une commande importée en tant que tâche en arrière-plan.

Étant donné que les commandes importées peuvent prendre plus de temps que les commandes locales, Import-PSSession ajoutez un paramètre AsJob à chaque commande importée. Le paramètre AsJob vous permet d’exécuter la commande en tant que travail en arrière-plan.

La première commande crée une session PSSession sur l’ordinateur Server01 et enregistre l’objet PSSession dans la $S variable.

La deuxième commande utilise Import-PSSession pour importer les applets de commande test à partir de la session PSSession dans $S la session active.

La troisième commande utilise le paramètre AsJob de l’applet de commande importée New-Test pour exécuter une New-Test commande en tant que travail en arrière-plan. La commande enregistre l’objet de travail qui New-Test retourne dans la $batch variable.

La quatrième commande utilise l’applet Receive-Job de commande pour obtenir les résultats du travail dans la $batch variable.

Exemple 5 : Importer des applets de commande et des fonctions à partir d’un module Windows PowerShell

$S = New-PSSession -ComputerName Server01
Invoke-Command -Session $S {Import-Module TestManagement}
Import-PSSession -Session $S -Module TestManagement

Cet exemple montre comment importer les applets de commande et fonctions à partir d'un module Windows PowerShell sur un ordinateur distant dans la session active.

La première commande crée une session PSSession sur l’ordinateur Server01 et l’enregistre dans la $S variable.

La deuxième commande utilise l’applet Invoke-Command de commande pour exécuter une Import-Module commande dans la session PSSession dans $S.

En règle générale, le module est ajouté à toutes les sessions par une Import-Module commande dans un profil Windows PowerShell, mais les profils ne sont pas exécutés dans psSessions.

La troisième commande utilise le paramètre Module de l’importation des applets de Import-PSSession commande et des fonctions dans le module dans la session active.

Exemple 6 : Créer un module dans un fichier temporaire

PS C:\> 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_tcw1
zunz.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_tcw1
zunz.ttf
ModuleType        : Script
PrivateData       : {ImplicitRemoting}
AccessMode        : ReadWrite
ExportedAliases   : {}
ExportedCmdlets   : {}
ExportedFunctions : {[Get-Date, Get-Date], [SearchHelp, SearchHelp]}
ExportedVariables : {}
NestedModules     : {}

Cet exemple montre comment Import-PSSession créer un module dans un fichier temporaire sur le disque. Il montre également que toutes les commandes sont converties en fonctions avant leur importation dans la session active.

La commande utilise l’applet Import-PSSession de commande pour importer une Get-Date applet de commande et une fonction SearchHelp dans la session active.

L’applet Import-PSSession de commande retourne un objet PSModuleInfo qui représente le module temporaire. La valeur de la propriété Path montre qu’un Import-PSSession fichier de module de script (.psm1) a été créé dans un emplacement temporaire. La propriété ExportFunctions indique que l’applet de commande et la Get-Date fonction SearchHelp ont tous deux été importés en tant que fonctions.

Exemple 7 : Exécuter une commande masquée par une commande importée

PS C:\> Import-PSSession $S -CommandName Get-Date -FormatTypeName * -AllowClobber

PS C:\> Get-Command Get-Date -All

CommandType   Name       Definition
-----------   ----       ----------
Function      Get-Date   ...
Cmdlet        Get-Date   Get-Date [[-Date] <DateTime>] [-Year <Int32>] [-Month <Int32>]

PS C:\> Get-Date
09074

PS C:\> (Get-Command -Type Cmdlet -Name Get-Date).PSSnapin.Name
Microsoft.PowerShell.Utility

PS C:\> Microsoft.PowerShell.Utility\Get-Date
Sunday, March 15, 2009 2:08:26 PM

Cet exemple montre comment exécuter une commande qui est masquée par une commande importée.

La première commande importe une Get-Date applet de commande à partir de la session PSSession dans la $S variable. Étant donné que la session active inclut une Get-Date applet de commande, le paramètre AllowClobber est requis dans la commande.

La deuxième commande utilise le paramètre All de l’applet Get-Command de commande pour obtenir toutes les Get-Date commandes de la session active. La sortie indique que la session inclut l’applet de commande d’origine Get-Date et une Get-Date fonction. La Get-Date fonction exécute l’applet de commande importée Get-Date dans psSession dans $S.

La troisième commande exécute une Get-Date commande. Étant donné que les fonctions sont prioritaires sur les applets de commande, Windows PowerShell exécute la fonction importée Get-Date , qui retourne une date julian.

Les quatrième et cinquième commandes montrent comment utiliser un nom qualifié pour exécuter une commande qui est 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 d’origine Get-Date à la session active.

La cinquième commande utilise le nom qualifié enfichable de l’applet Get-Date de commande pour exécuter une Get-Date commande.

Pour plus d’informations sur la priorité des commandes et les commandes masquées, consultez about_Command_Precedence.

Exemple 8 : Importer des commandes qui ont une chaîne spécifique dans leurs noms

PS C:\> Import-PSSession -Session $S -CommandName **Item** -AllowClobber

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 de la commande dans la session active.

Exemple 9 : Utiliser le paramètre Module pour découvrir les commandes qui ont été importées dans la session

PS C:\> $M = Import-PSSession -Session $S -CommandName *bits* -FormatTypeName *bits*
PS C:\> 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

Cette commande montre comment utiliser le paramètre Module pour Get-Command savoir quelles commandes ont été importées dans la session par une Import-PSSession commande.

La première commande utilise l’applet Import-PSSession de commande pour importer des commandes dont les noms incluent des « bits » à partir de la session PSSession dans la $S variable. La Import-PSSession commande retourne un module temporaire et la commande enregistre le module dans la $m variable.

La deuxième commande utilise l’applet Get-Command de commande pour obtenir les commandes exportées par le module dans la $M variable.

Le paramètre Module prend une valeur de chaîne, qui est conçue pour le nom du module. Toutefois, lorsque vous envoyez un objet de module, Windows PowerShell utilise la méthode ToString sur l’objet module, qui retourne le nom du module.

La Get-Command commande est l’équivalent de Get-Command $M.Name».

Paramètres

-AllowClobber

-ArgumentList

-Certificate

-CommandName

-CommandType

-DisableNameChecking

-FormatTypeName

-FullyQualifiedModule

-Module

-Prefix

-Session

Entrées

None

Vous ne pouvez pas diriger les objets vers cette applet de commande.

Sorties

PSModuleInfo

Cette applet de commande retourne le même objet de module que celui retourné New-Module par Get-Module les applets de commande. 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 Export-PSSession commande.

Notes

Windows PowerShell inclut les alias suivants pour Import-PSSession:

• ipsn

• Import-PSSession s’appuie sur l’infrastructure de communication à distance PowerShell. Pour utiliser cette applet de commande, l'ordinateur doit être configuré pour la communication à distance WS-Management. Pour plus d’informations, consultez about_Remote et about_Remote_Requirements.

• Import-PSSession n’importe pas de variables ni de fournisseurs PowerShell.

• Quand vous importez des commandes qui ont le même nom que les commandes dans la session active, les commandes importées peuvent masquer des alias, des fonctions et des applets de commande dans la session, et peuvent remplacer des fonctions et variables dans la session. Pour éviter les conflits de noms, utilisez le paramètre Préfixe . Pour plus d’informations, consultez about_Command_Precedence.

• Import-PSSession convertit toutes les commandes en fonctions avant de les importer. Par conséquent, les commandes importées se comportent un peu différemment que si elles avaient conservé leur type de commande d'origine. Par exemple, si vous importez une applet de commande à partir d'une session PSSession, puis une applet de commande avec le même nom à partir d'un module ou d'un composant logiciel enfichable, l'applet de commande qui est importée à partir de la session PSSession s'exécute toujours par défaut, car les fonctions sont prioritaires sur les applets de commande. À l'inverse, si vous importez un alias dans une session qui a un alias avec le 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 Write-Progress de commande pour afficher la progression de la commande. Vous pouvez voir la barre de progression pendant l'exécution de la commande.

• Pour rechercher les commandes à importer, Import-PSSession utilise l’applet Invoke-Command de commande pour exécuter une Get-Command commande dans la session PSSession. Pour obtenir des données de mise en forme pour les commandes, elle utilise l’applet Get-FormatData de commande. Vous pouvez voir des messages d’erreur à partir de ces applets de commande lorsque vous exécutez une Import-PSSession commande. En outre, Import-PSSession ne peut pas importer de commandes à partir d’une session PSSession qui n’inclut pas les applets de commande , Get-FormatDataet Select-ObjectGet-Help les Get-Commandapplets de commande.

• Les commandes importées présentent les mêmes restrictions que d'autres commandes à distance, notamment l'impossibilité de démarrer un programme avec une interface utilisateur, tel que le Bloc-notes.

• Étant donné que les profils Windows PowerShell ne sont pas exécutés dans les sessions PSSession, les commandes qu’un profil ajoute à une session ne sont pas disponibles .Import-PSSession Pour importer des commandes à partir d’un profil, utilisez une Invoke-Command commande pour exécuter le profil dans la session PSSession manuellement avant d’importer des commandes.

• Le module temporaire qui 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, les fichiers de mise en forme éventuellement créés ne contiennent 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 restreinte ou AllSigned, car le module temporaire qui Import-PSSession crée contient des fichiers de script non signés qui sont 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 façon à définir une stratégie d’exécution moins restrictive pour un seul processus.

• Dans Windows PowerShell 2.0, les rubriques d’aide pour les commandes importées à partir d’une autre session n’incluent pas le préfixe que vous affectez à l’aide du paramètre Préfixe . Pour obtenir de l'aide pour une commande importée dans Windows PowerShell 2.0, utilisez le nom de commande (sans préfixe) d'origine.

Liens associés

• Export-PSSession