Import-PSSession

Módulo:

Microsoft.PowerShell.Utility

Importa en la sesión actual comandos de otra sesión.

Syntax

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

Description

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, utilice el cmdlet Import-PSSession para importar los comandos. De forma predeterminada, Import-PSSession importa todos los comandos salvo aquellos que tengan los mismos nombres que los comandos de la sesión actual. Para importar todos los comandos, utilice el parámetro AllowClobber.

Puede usar comandos importados del mismo modo que utilizaría cualquier comando de la sesión. Al usar un comando importado, la parte importada del comando se ejecuta de manera implícita en la sesión desde la que se importó. Sin embargo, Windows PowerShell controla completamente las operaciones remotas. Ni siquiera necesita estar al tanto de dichas operaciones, salvo en lo relativo a que debe mantener abierta la conexión con la otra sesión (PSSession). Si la cierra, dejarán de estar disponibles los comandos importados.

Puesto que los comandos importados pueden tardar más tiempo en ejecutarse que los comandos locales, Import-PSSession agrega un parámetro AsJob a cada comando importado. 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.

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

El cmdlet Import-PSSession 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 de una sesión remota a la sesión actual. Esta característica utiliza comunicación remota implícita. Es equivalente a utilizar Import-PSSession para importar en la sesión actual los módulos seleccionados de una sesión remota.

Ejemplos

Ejemplo 1: Importación de todos los comandos desde una PSSession

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

Este comando importa todos los comandos de una PSSession del equipo Server01 en la sesión actual, salvo aquellos comandos que tengan el mismo nombre que los comandos de la sesión actual.

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

Ejemplo 2: Importación de comandos que terminan con una cadena específica

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 en la sesión local los comandos con nombres que acaben en "-test" de una PSSession y, a continuación, 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 CommandNamepara especificar comandos con el sustantivo Test y el parámetro FormatTypeName para importar los datos de formato de los comandos Test.

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

Ejemplo 3: Importación de cmdlets desde una PSSession

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

Este ejemplo muestra que puede usar cmdlets importados del mismo modo que usaría cmdlets locales.

Estos comandos importación 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 importasen desde PSSessions diferentes, puede canalizar un objeto de un cmdlet a otro sin que se generen errores.

Ejemplo 4: Ejecución de un comando importado como trabajo en segundo plano

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

Este ejemplo muestra cómo ejecutar un comando importado como un trabajo en segundo plano.

Puesto que los comandos importados pueden tardar más tiempo en ejecutarse que los comandos locales, Import-PSSession agrega un parámetro AsJob a cada comando importado. 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 devuelve New-Test en la variable $batch.

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

Ejemplo 5: Importación de cmdlets y funciones desde un módulo de Windows PowerShell

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 en la sesión actual los cmdlets y las funciones desde un módulo de Windows PowerShell en un equipo remoto.

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 la PSSession de $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 en la sesión actual los cmdlets y las funciones del módulo.

Ejemplo 6: Create un módulo en un archivo temporal

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

Este ejemplo muestra que Import-PSSession crea un módulo en un archivo temporal en disco. También muestra que todos los comandos se convierten en funciones antes de ser importados 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 módulo de script (.psm1) en una ubicación temporal. La propiedad ExportedFunctions muestra que tanto el cmdlet Get-Date como la función SearchHelp se han importado como funciones.

Ejemplo 7: Ejecución de un comando oculto por un comando importado

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 que está oculto por un comando importado.

El primer comando importa un cmdlet de 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. El resultado muestra que la sesión incluye el cmdlet Get-Date original y una función Get-Date. La función Get-Date ejecuta el cmdlet Get-Date importado en la PSSession de $S.

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

Los comandos cuarto y quinto muestran cómo utilizar un nombre completo para ejecutar un comando que está oculto por un comando importado.

El cuarto comando obtiene el nombre del complemento de Windows PowerShell que agregó el cmdlet Get-Date original 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 prioridad de los comandos y los comandos ocultos, consulte about_Command_Precedence.

Ejemplo 8: Importación de comandos que tienen una cadena específica en sus nombres

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

Este comando importa comandos cuyos nombres incluyen "Item" de la 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 utilice Import-PSSession para ejecutar un comando en un equipo remoto equipo y tenga ya los datos de formato del comando de la sesión actual.

Ejemplo 9: Usar el parámetro Module para detectar qué comandos se importaron en la sesión

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 utilizar 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 de módulo, que devuelve el nombre del módulo.

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

Parámetros

-AllowClobber

Indica que este cmdlet importa los comandos especificados, incluso si tienen los mismos nombres que los comandos de la sesión actual.

Si importa un comando con el mismo nombre que un comando de la sesión actual, el comando importado oculta o reemplaza los comandos originales. Para obtener más información, consulte about_Command_Precedence.

De forma predeterminada, Import-PSSession no importa comandos que tengan el mismo nombre que los comandos de la sesión actual.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ArgumentList

Especifica una matriz de comandos resultantes del uso de los argumentos especificados (valores de parámetro).

Por ejemplo, para importar la variante del comando Get-Item en la unidad de certificado (Cert:) de psSession en $S, escriba Import-PSSession -Session $S -Command Get-Item -ArgumentList cert:.

Type:	Object[]
Aliases:	Args
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Certificate

Especifica el certificado de cliente que se utiliza para firmar los archivos de formato (*.Format.ps1xml) o los archivos de módulo de script (. psm1) en el módulo temporal que crea Import-PSSession.

Introduzca una variable que contenga un certificado o un comando o una expresión que obtenga el certificado.

Para buscar un certificado, use el cmdlet Get-PfxCertificate o use el cmdlet Get-ChildItem en la unidad Certificate (Cert:). Si el certificado no es válido o no tiene autoridad suficiente, el comando genera un error.

Type:	X509Certificate2
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CommandName

Especifica comandos con los nombres o patrones de nombre especificados. Se permiten los caracteres comodín. Use CommandName o su alias, Name.

De forma predeterminada, Import-PSSession importa todos los comandos de la sesión, salvo aquellos que tengan los mismos nombres que los comandos de la sesión actual. Esto evita que los comandos importados oculten o reemplacen a los comandos de la sesión. Para importar todos los comandos, incluso aquellos que oculten o reemplacen a otros comandos, use el parámetro AllowClobber.

Si utiliza el parámetro CommandName, los archivos de formato de los comandos no se importan a menos que utilice el parámetro FormatTypeName. De forma similar, si utiliza el parámetro FormatTypeName, no se importa ningún comando salvo que use el parámetro CommandName.

Type:	String[]
Aliases:	Name
Position:	2
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CommandType

Especifica el tipo de objetos de comando. El valor predeterminado es Cmdlet. Use CommandType o su alias, Type. Los valores permitidos para este parámetro son los siguientes:

• Alias. Los alias de Windows PowerShell en la sesión remota.
• Todos. Los cmdlets y las funciones de la sesión remota.
• Aplicación. Todos los archivos que no sean de Windows PowerShell en las rutas de acceso que se enumeran en la variable de entorno Path ($env:path) en la sesión remota, incluidos los archivos .txt, .exe y .dll.
• Cmdlet. Los cmdlets de la sesión remota. "Cmdlet" es el valor predeterminado.
• ExternalScript. Los archivos .ps1 que se encuentren en las rutas de acceso que aparecen en la variable de entorno Path ($env:path) en la sesión remota.
• Filtro y función. Las funciones de Windows PowerShell en la sesión remota.
• Script. Los bloques de script en la sesión remota.

Type:	CommandTypes
Aliases:	Type
Accepted values:	Alias, Function, Filter, Cmdlet, ExternalScript, Application, Script, Workflow, Configuration, All
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-DisableNameChecking

Indica que este cmdlet suprime el mensaje que le advierte al importar un cmdlet o función cuyo nombre incluye un verbo no aprobado o un carácter prohibido.

De forma predeterminada, cuando un módulo que importa exporta cmdlets o funciones que tienen verbos no aprobados en sus nombres, el Windows PowerShell muestra el siguiente mensaje de advertencia:

"ADVERTENCIA: Algunos nombres de comandos importados incluyen verbos no aprobados que podrían hacer que sean menos reconocibles. Utilice el parámetro Verbose para obtener más detalle o escriba Get-Verb para ver la lista de verbos aprobados".

Este mensaje es sólo una advertencia. El módulo completo se importa de todos modos, incluidos los comandos que no cumplen las especificaciones. Aunque el mensaje se muestra a los usuarios del módulo, el autor del módulo debe corregir el problema de nomenclatura.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-FormatTypeName

Especifica instrucciones de formato para los tipos de Microsoft .NET Framework especificados. Escriba los nombres de tipos. Se permiten los caracteres comodín.

El valor de este parámetro debe ser el nombre de un tipo devuelto por un comando Get-FormatData en la sesión de la que se van a importar los comandos. Para obtener todos los datos de formato en la sesión remota, escriba *.

Si el comando no incluye el parámetro CommandName o FormatTypeName , Import-PSSession importa instrucciones de formato para todos los tipos de .NET Framework devueltos por un comando Get-FormatData en la sesión remota.

Si utiliza el parámetro FormatTypeName, los comandos no se importan a menos que utilice el parámetro CommandName.

De forma similar, si utiliza el parámetro CommandName, los archivos de formato para los comandos no se importan a menos que utilice el parámetro FormatTypeName.

Type:	String[]
Position:	3
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-FullyQualifiedModule

Especifica los módulos con nombres que se especifican en forma de objetos ModuleSpecification (descritos en la sección Comentarios del Constructor ModuleSpecification (Hashtable) en MSDN Library). Por ejemplo, el parámetro FullyQualifiedModule acepta un nombre de módulo especificado en el formato @{ModuleName = "modulename"; ModuleVersion = "version_number"} o @{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}. ModuleName y ModuleVersion son necesarios, pero Guid es opcional.

No se puede especificar el parámetro FullyQualifiedModule en el mismo comando que un parámetro Module ; los dos parámetros son mutuamente excluyentes.

Type:	ModuleSpecification[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Module

Especifica y matriz de comandos en los complementos y módulos de Windows PowerShell. Escriba los nombres de módulo y complemento. No se permiten caracteres comodín.

Import-PSSession no puede importar proveedores desde un complemento.

Para obtener más información, consulte about_PSSnapins y about_Modules.

Type:	String[]
Aliases:	PSSnapin
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Prefix

Especifica un prefijo para los nombres de los comandos importados.

Utilice este parámetro para evitar conflictos de nombres que se pueden producir cuando distintos comandos de la sesión tienen el mismo nombre.

Por ejemplo, si especifica el prefijo Remote e importa un cmdlet de Get-Date, el cmdlet se conoce en la sesión como Get-RemoteDate y no se confunde con el cmdlet Get-Date original.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Session

Especifica la PSSession desde la que se importan los cmdlets. Escriba una variable que contenga un objeto de sesión o un comando que obtenga un objeto de sesión, como un comando New-PSSession o Get-PSSession. Sólo puede especificar una sesión. Este parámetro es obligatorio.

Type:	PSSession
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

Entradas

None

No se pueden canalizar objetos a este cmdlet.

Salidas

PSModuleInfo

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

Notas

• Import-PSSession se basa en la infraestructura de comunicación remota Windows PowerShell. Para usar este cmdlet, el equipo debe estar configurado para la comunicación remota de WS-Management. Para obtener más información, consulte about_Remote y about_Remote_Requirements.
• Import-PSSession no importa variables ni proveedores de Windows PowerShell.
• Cuando se importan comandos con los mismos nombres que los comandos de la sesión actual, los comandos importados pueden ocultar alias, funciones y cmdlets de la sesión y pueden reemplazar las funciones y variables de la sesión. Para evitar conflictos de nombres, utilice el parámetro Prefix. 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 manera un poco distinta a como lo harían si conservasen 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 desde un módulo o un complemento, el cmdlet importado desde la PSSession se ejecuta siempre de forma predeterminada porque las funciones tienen prioridad frente a los cmdlets. Por el contrario, si importa un alias a una sesión que tenga un alias con el mismo nombre, el alias original se utiliza siempre, porque 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. Puede ver 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 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 desde 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 para 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 los comandos de un perfil, utilice un comando Invoke-Command para ejecutar manualmente el perfil en la PSSession antes de importar los comandos.
• El módulo temporal que crea Import-PSSession puede incluir un archivo de formato, incluso si el comando Importar datos de formato. Si el comando no importa datos de formato, ninguno de los archivos de formato creados contendrá datos de formato.
• Para usar Import-PSSession, la directiva de ejecución en la sesión actual no puede ser Restricted ni AllSigned, porque el módulo temporal que crea Import-PSSession contiene archivos de script sin firmar que estas directivas prohíben. 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 único proceso.
• En los temas de ayuda de Windows PowerShell 2.0 sobre comandos que se importan desde otra sesión no incluyen el prefijo que se asigna mediante el parámetro Prefix. Para obtener ayuda sobre un comando importado en Windows PowerShell 2.0, utilice el nombre de comando original (sin prefijo).

Vínculos relacionados

• Export-PSSession
• New-PSSession
• about_Command_Precedence
• about_PSSessions
• about_Jobs