Import-PSSession

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

El cmdlet import-PSSession importa comandos, como cmdlets, funciones y alias, desde una PSSession en un equipo local o remoto en la sesión actual. Puede importar cualquier comando que el cmdlet Get-Command pueda encontrar en PSSession.

Use un comando Import-PSSession para importar comandos desde un shell personalizado, como un shell de Microsoft Exchange Server, o desde una sesión que incluya módulos y complementos de Windows PowerShell u otros elementos que no estén en la sesión actual.

Para importar comandos, use primero el cmdlet New-PSSession para crear una PSSession. A continuación, use el cmdlet Import-PSSession para importar los comandos. De forma predeterminada, Import-PSSession importa todos los comandos, excepto los comandos que tienen los mismos nombres que los comandos de la sesión actual. Para importar todos los comandos, use el parámetro AllowClobber.

Puede usar comandos importados igual que usaría cualquier comando en la sesión. Cuando se usa un comando importado, la parte importada del comando se ejecuta implícitamente en la sesión desde la que se importó. Sin embargo, Windows PowerShell controla completamente las operaciones remotas. Ni siquiera es necesario tener en cuentalos, excepto que debe mantener abierta la conexión a la otra sesión (PSSession). Si lo cierra, los comandos importados ya no están disponibles.

Dado que los comandos importados pueden tardar más tiempo en ejecutarse que los comandos locales, Import-PSSession agrega un parámetro AsJob a todos los comandos importados. Este parámetro permite ejecutar el comando como un trabajo en segundo plano de Windows PowerShell. Para obtener más información, consulte about_Jobs.

Cuando se usa Import-PSSession, Windows PowerShell agrega los comandos importados a un módulo temporal que solo existe en la sesión y devuelve un objeto que representa el módulo. Para crear un módulo persistente que puede usar en sesiones futuras, use el cmdlet Export-PSSession.

El cmdlet import-PSSession de usa la característica de comunicación remota implícita de Windows PowerShell. Al importar comandos en la sesión actual, se ejecutan implícitamente en la sesión original o en una sesión similar en el equipo de origen.

A partir de Windows PowerShell 3.0, puede usar el cmdlet Import-Module para importar módulos desde una sesión remota a la sesión actual. Esta característica usa la comunicación remota implícita. Equivale a usar Import-PSSession para importar módulos seleccionados desde una sesión remota a la sesión actual.

PS C:\> $S = New-PSSession -ComputerName Server01
PS C:\> Import-PSSession -Session $S

Este comando importa todos los comandos de una PSSession en el equipo Server01 a la sesión actual, excepto los comandos que tienen los mismos nombres que los comandos de la sesión actual.

Dado que este comando no usa el parámetro CommandName, también importa todos los datos de formato necesarios para los comandos importados.

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

Estos comandos importan los comandos con nombres que terminan en "-test" de una PSSession en la sesión local y después muestran cómo usar un cmdlet importado.

El primer comando usa el cmdlet New-PSSession para crear una PSSession. Guarda la PSSession en la variable $S.

El segundo comando usa el cmdlet Import-PSSession para importar comandos de PSSession en $S a la sesión actual. Usa el parámetro commandName de para especificar comandos con el nombre Test y el parámetro FormatTypeName para importar los datos de formato para los comandos Test.

Los comandos tercero y cuarto usan los comandos importados en la sesión actual. Dado que los comandos importados se agregan realmente a la sesión actual, se usa la sintaxis local para ejecutarlos. No es necesario usar el cmdlet Invoke-Command para ejecutar un comando importado.

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

En este ejemplo se muestra que puede usar cmdlets importados como usaría cmdlets locales.

Estos comandos importan los cmdlets New-Test y Get-Test desde una PSSession en el equipo Server01 y el cmdlet Set-Test desde una PSSession en el equipo Server02.

Aunque los cmdlets se importaron desde diferentes PSSessions, puede canalizar un objeto de un cmdlet a otro sin errores.

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

En este ejemplo se muestra cómo ejecutar un comando importado como un trabajo en segundo plano.

Dado que los comandos importados pueden tardar más tiempo en ejecutarse que los comandos locales, Import-PSSession agrega un parámetro AsJob a todos los comandos importados. El parámetro AsJob le permite ejecutar el comando como un trabajo en segundo plano.

El primer comando crea una PSSession en el equipo Server01 y guarda el objeto PSSession en la variable $S.

El segundo comando usa Import-PSSession para importar los cmdlets test de PSSession en $S a la sesión actual.

El tercer comando usa el parámetro AsJob del cmdlet New-Test importado para ejecutar un comando New-Test como un trabajo en segundo plano. El comando guarda el objeto de trabajo que New-Test devuelve en la variable $batch.

El cuarto comando usa el cmdlet Receive-Job para obtener los resultados del trabajo en la variable $batch.

PS C:\> $S = New-PSSession -ComputerName Server01
PS C:\> Invoke-Command -Session $S {Import-Module TestManagement}
PS C:\> Import-PSSession -Session $S -Module TestManagement

En este ejemplo se muestra cómo importar los cmdlets y funciones desde un módulo de Windows PowerShell en un equipo remoto a la sesión actual.

El primer comando crea una PSSession en el equipo Server01 y la guarda en la variable $S.

El segundo comando usa el cmdlet Invoke-Command para ejecutar un comando Import-Module en PSSession en $S.

Normalmente, el módulo se agregaría a todas las sesiones mediante un comando Import-Module en un perfil de Windows PowerShell, pero los perfiles no se ejecutan en PSSessions.

El tercer comando usa el parámetro Module de import-PSSession para importar los cmdlets y funciones del módulo en la sesión actual.

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_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     : {}

En este ejemplo se muestra que import-PSSession crea un módulo en un archivo temporal en el disco. También muestra que todos los comandos se convierten en funciones antes de importarlos en la sesión actual.

El comando usa el cmdlet Import-PSSession para importar un cmdlet de Get-Date y una función SearchHelp en la sesión actual.

El cmdlet import-PSSession devuelve un objeto PSModuleInfo que representa el módulo temporal. El valor de la propiedad path muestra que import-PSSession creó un archivo de módulo de script (.psm1) en una ubicación temporal. La propiedad ExportedFunctions muestra que el cmdlet Get-Date y la función SearchHelp se importaron como funciones.

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

En este ejemplo se muestra cómo ejecutar un comando oculto por un comando importado.

El primer comando importa un cmdlet Get-Date desde PSSession en la variable $S. Dado que la sesión actual incluye un cmdlet Get-Date, el parámetro AllowClobber es necesario en el comando .

El segundo comando usa el parámetro All del cmdlet Get-Command para obtener todos los comandos Get-Date de la sesión actual. La salida muestra que la sesión incluye el cmdlet de Get-Date original y una función de Get-Date . La función Get-Date ejecuta el cmdlet Get-Date importado en psSession en $S.

El tercer comando ejecuta un comando Get-Date. Dado que las funciones tienen prioridad sobre los cmdlets, Windows PowerShell ejecuta la función Get-Date importada , que devuelve una fecha juliana.

Los comandos cuarto y quinto muestran cómo usar un nombre completo para ejecutar un comando oculto por un comando importado.

El cuarto comando obtiene el nombre del complemento de Windows PowerShell que agregó el cmdlet original Get-Date a la sesión actual.

El quinto comando usa el nombre completo del complemento del cmdlet Get-Date para ejecutar un comando Get-Date.

Para obtener más información sobre la precedencia de comandos y los comandos ocultos, consulte about_Command_Precedence.

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

Este comando importa comandos cuyos nombres incluyen "Item" de PSSession en $S. Dado que el comando incluye el parámetro CommandName, pero no el parámetro FormatTypeData, solo se importa el comando.

Use este comando cuando use Import-PSSession para ejecutar un comando en un equipo remoto y ya tiene los datos de formato del comando en la sesión actual.

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

Este comando muestra cómo usar el parámetro Module de Get-Command para averiguar qué comandos se importaron en la sesión mediante un comando import-PSSession.

El primer comando usa el cmdlet import-PSSession para importar comandos cuyos nombres incluyen "bits" de PSSession en la variable $S. El comando Import-PSSession devuelve un módulo temporal y el comando guarda el módulo en la variable $m.

El segundo comando usa el cmdlet Get-Command para obtener los comandos exportados por el módulo en la variable $M.

El parámetro module toma un valor de cadena, que está diseñado para el nombre del módulo. Sin embargo, al enviar un objeto de módulo, Windows PowerShell usa el método ToString en el objeto module, que devuelve el nombre del módulo.

El comando Get-Command es el equivalente de Get-Command $M.Name".

Este cmdlet admite los parámetros comunes: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction y -WarningVariable. Para obtener más información, vea about_CommonParameters.

No se pueden canalizar objetos a este cmdlet.

import-PSSession devuelve el mismo objeto de módulo que devuelven los cmdlets New-Module y Get-Module. Sin embargo, el módulo importado es temporal y solo existe en la sesión actual. Para crear un módulo permanente en el disco, use el cmdlet Export-PSSession.

• import-PSSession se basa en la infraestructura de comunicación remota de Windows PowerShell. Para usar este cmdlet, el equipo debe configurarse para WS-Management comunicación remota. Para obtener más información, consulte about_Remote y about_Remote_Requirements.
• import-PSSession no importa variables ni proveedores de Windows PowerShell.
• Al importar comandos que tienen los mismos nombres que los comandos de la sesión actual, los comandos importados pueden ocultar alias, funciones y cmdlets en la sesión y pueden reemplazar funciones y variables en la sesión. Para evitar conflictos de nombres, use el parámetro prefijo. Para obtener más información, consulte about_Command_Precedence.
• Import-PSSession convierte todos los comandos en funciones antes de importarlos. Como resultado, los comandos importados se comportan de forma un poco diferente de lo que harían si conservaran su tipo de comando original. Por ejemplo, si importa un cmdlet desde una PSSession y, a continuación, importa un cmdlet con el mismo nombre de un módulo o complemento, el cmdlet que se importa desde PSSession siempre se ejecuta de forma predeterminada porque las funciones tienen prioridad sobre los cmdlets. Por el contrario, si importa un alias en una sesión que tiene un alias con el mismo nombre, siempre se usa el alias original, ya que los alias tienen prioridad sobre las funciones. Para obtener más información, consulte about_Command_Precedence.
• Import-PSSession usa el cmdlet Write-Progress para mostrar el progreso del comando. Es posible que vea la barra de progreso mientras se ejecuta el comando.
• Para buscar los comandos que se van a importar, import-PSSession usa el cmdlet Invoke-Command para ejecutar un comando de Get-Command en PSSession. Para obtener datos de formato para los comandos, usa el cmdlet Get-FormatData. Es posible que vea mensajes de error de estos cmdlets al ejecutar un comando import-PSSession. Además, import-PSSession no puede importar comandos de una PSSession que no incluya los cmdlets Get-Command, Get-FormatData, Select-Object y Get-Help.
• Los comandos importados tienen las mismas limitaciones que otros comandos remotos, incluida la incapacidad de iniciar un programa con una interfaz de usuario, como el Bloc de notas.
• Dado que los perfiles de Windows PowerShell no se ejecutan en PSSessions, los comandos que agrega un perfil a una sesión no están disponibles para Import-PSSession. Para importar comandos desde un perfil, use un comando Invoke-Command para ejecutar el perfil en PSSession manualmente antes de importar comandos.
• El módulo temporal que import-PSSession crea podría incluir un archivo de formato, incluso si el comando no importa datos de formato. Si el comando no importa datos de formato, los archivos de formato creados no contendrán datos de formato.
• Para usar Import-PSSession, la directiva de ejecución de la sesión actual no puede ser Restringida ni AllSigned, ya que el módulo temporal que import-PSSession crea contiene archivos de script sin firmar que están prohibidos por estas directivas. Para usar import-PSSession sin cambiar la directiva de ejecución del equipo local, use el parámetro Scope de Set-ExecutionPolicy para establecer una directiva de ejecución menos restrictiva para un solo proceso.
• En Windows PowerShell 2.0, los temas de ayuda de los comandos que se importan desde otra sesión no incluyen el prefijo que se asigna mediante el parámetro Prefix. Para obtener ayuda para un comando importado en Windows PowerShell 2.0, use el nombre del comando original (sin prefijo).