Importa los comandos de otra sesión en la sesión actual.
Sintaxis
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>]
Descripción
El cmdlet Import-PSSession importa en la sesión actual los comandos (por ejemplo, cmdlets, funciones y alias) de una PSSession en un equipo local o remoto. Se puede importar cualquier comando que Get-Command encuentre en la PSSession.
Utilice un comando Import-PSSession para importar los comandos de un shell personalizado, como un shell de Microsoft Exchange Server, o de una sesión que incluya módulos y complementos de Windows PowerShell u otros elementos que no se encuentren 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 los que tienen el mismo nombre que los comandos de la sesión actual. Para importar todos los comandos, utilice el parámetro AllowClobber.
Los comandos importados se pueden usar de la misma manera en que se utiliza cualquier comando en la sesión. Cuando se usa un comando importado, la parte importada del comando se ejecuta de forma implícita en la sesión desde la cual se importó. Sin embargo, Windows PowerShell administra completamente las operaciones remotas. El usuario ni siquiera necesita conocerlas; solo debe mantener abierta la conexión con la otra sesión (PSSession). Si la cierra, los comandos importados dejarán de estar 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 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, vea about_Jobs.
Cuando se usa Import-PSSession, Windows PowerShell agrega los comandos importados a un módulo temporal que solo existe en esa sesión y devuelve un objeto que representa el módulo. Para crear un módulo persistente que pueda utilizar en sesiones futuras, utilice el cmdlet Export-PSSession.
El cmdlet Import-PSSession usa la característica de comunicación remota de Windows PowerShell. Cuando se importan comandos en la sesión actual, estos se ejecutan de forma implícita en la sesión original o en una sesión similar en el equipo original.
Parámetros
-AllowClobber
Importa los comandos especificados, incluso si tienen el mismo nombre que los comandos de la sesión actual.
Si se importa un comando que tiene el mismo nombre que un comando de la sesión actual, el comando importado ocultará o reemplazará el comando original. Para obtener más información, vea about_Command_Precedence.
De forma predeterminada, Import-PSSession no importa los comandos que tienen el mismo nombre que los comandos de la sesión actual.
|
¿Requerido? |
false |
|
¿Posición? |
named |
|
Valor predeterminado |
False |
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
false |
-ArgumentList <Object[]>
Importa la variante del comando que resulta de usar 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:".
|
¿Requerido? |
false |
|
¿Posición? |
named |
|
Valor predeterminado |
All command in the PSSession, except for commands with the same names as commands in the current session. |
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
false |
-CommandName <string[]>
Importa solo los comandos con los nombres o patrones de nombre especificados. Se permite el uso de caracteres comodín. Utilice "CommandName" o su alias, "Name".
De forma predeterminada, Import-PSSession importa todos los comandos de la sesión, salvo los que tienen el mismo nombre que los comandos de la sesión actual. De este modo, se evita que los comandos importados oculten o reemplacen los comandos de la sesión. Para importar todos los comandos, incluidos los que ocultan o reemplazan otros comandos, utilice el parámetro AllowClobber.
Si utiliza el parámetro CommandName, no se importarán los archivos de formato de los comandos a menos que use el parámetro FormatTypeName. De forma similar, si utiliza el parámetro FormatTypeName, no se importará ningún comando a menos que use el parámetro CommandName.
|
¿Requerido? |
false |
|
¿Posición? |
3 |
|
Valor predeterminado |
All commands in the PSSession, except for commands with the same names as commands in the current session. |
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
true |
-CommandType <CommandTypes>
Importa únicamente los tipos de objetos de comando especificados. El valor predeterminado es Cmdlet. Use "CommandType" o su alias, "Type".
Los valores válidos son:
-- Alias: los alias de Windows PowerShell en la sesión remota.
-- All: los cmdlets y funciones de la sesión remota.
-- Application: todos los archivos que no sean archivos de Windows PowerShell en las rutas de acceso especificadas por 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 en las rutas de acceso especificadas por la variable de entorno Path ($env:path) en la sesión remota.
-- Filter y Function: las funciones de Windows PowerShell en la sesión remota.
-- Script: los bloques de script en la sesión remota.
|
¿Requerido? |
false |
|
¿Posición? |
named |
|
Valor predeterminado |
All command in the PSSession, except for commands with the same names as commands in the current session. |
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
false |
-FormatTypeName <string[]>
Importa las instrucciones de formato de los tipos de Microsoft .NET Framework especificados. Escriba los nombres de los tipos. Se permite el uso de 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 desde la que se importan los comandos. Para obtener todos los datos de formato de la sesión remota, escriba *.
Si el comando no incluye el parámetro CommandName o FormatTypeName, Import-PSSession
importará las instrucciones de formato de todos los tipos de .NET Framework devueltos por un comando Get-FormatData en la sesión remota.
Si utiliza el parámetro FormatTypeName, no se importará ningún comando a menos que use el parámetro CommandName.
De forma similar, si utiliza el parámetro CommandName, no se importarán los archivos de formato de los comandos a menos que use el parámetro FormatTypeName.
|
¿Requerido? |
false |
|
¿Posición? |
4 |
|
Valor predeterminado |
Types in the System.Management.Automation namespace |
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
true |
-Module <string[]>
Importa solo los comandos de los complementos y módulos especificados de Windows PowerShell. Escriba los nombres de los complementos y módulos. No se permite el uso de caracteres comodín.
Para obtener más información, vea about_Pssnapins e Import-Module.
|
¿Requerido? |
false |
|
¿Posición? |
named |
|
Valor predeterminado |
All command in the PSSession, except for commands with the same names as commands in the current session. |
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
false |
-Prefix <string>
Agrega el prefijo especificado a los sustantivos en los nombres de los comandos importados.
Utilice este parámetro para evitar conflictos entre nombres que podrían producirse cuando diferentes comandos de la sesión tienen el mismo nombre.
Por ejemplo, si especifica el prefijo "Remote" y, a continuación, importa un cmdlet Get-Date, el cmdlet se conocerá en la sesión como Get-RemoteDate y no se confundirá con el cmdlet Get-Date original.
|
¿Requerido? |
false |
|
¿Posición? |
named |
|
Valor predeterminado |
|
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
false |
-Session <PSSession>
Especifica la PSSession desde la que se importan los cmdlets. Escriba una variable que contenga el objeto de sesión o escriba un comando que lo obtenga, como un comando New-PSSession o Get-PSSession. Se puede especificar solamente una sesión. Este parámetro es obligatorio.
|
¿Requerido? |
true |
|
¿Posición? |
1 |
|
Valor predeterminado |
ninguno |
|
¿Aceptar canalización? |
false |
|
¿Aceptar caracteres comodín? |
false |
<CommonParameters>
Este cmdlet admite los parámetros comunes: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer y -OutVariable. Para obtener más información, vea about_Commonparameters.
Entradas y salidas
El tipo de entrada es el tipo de los objetos que se pueden canalizar al cmdlet. El tipo devuelto es el tipo de los objetos que el cmdlet devuelve.
|
Entradas |
Ninguno No puede canalizar objetos a este cmdlet. |
|
Salidas |
System.Management.Automation.PSModuleInfo Import-PSSession devuelve el mismo objeto de módulo que New-Module y Get-Module. Sin embargo, el módulo importado es temporal y existe únicamente en la sesión actual. Para crear un módulo permanente en el disco, utilice el cmdlet Export-PSSession. |
Notas
Import-PSSession se basa en la infraestructura de comunicación remota de Windows PowerShell. Para poder utilizar este cmdlet, el equipo debe estar configurado para la comunicación remota de WS-Management. Para obtener más información, vea about_Remote y about_Remote_Requirements.
No se puede usar Import-PSSession para importar variables ni proveedores de Windows PowerShell.
Si se importan comandos que tienen el mismo nombre que comandos de la sesión actual, los comandos importados puede ocultar los alias, las funciones y los cmdlets de la sesión y reemplazar las funciones y las variables de la sesión. Para obtener más información, vea about_Command_Precedence.
Import-PSSession convierte todos los comandos en funciones antes de importarlos. Como resultado, el comportamiento de los comandos importados difiere ligeramente del que tendrían si conservaran su tipo de comando original. Por ejemplo, si se importa un cmdlet de una PSSession y, a continuación, se importa un cmdlet con el mismo nombre de un módulo o complemento, el cmdlet que se importa de la PSSession siempre se ejecutará de forma predeterminada porque las funciones tienen prioridad sobre los cmdlets. A la inversa, si se importa un alias en una sesión que tiene un alias con el mismo nombre, siempre se utilizará el alias original porque los alias tienen prioridad sobre las funciones. Para obtener más información, vea about_Command_Precedence.
Import-PSSession utiliza el cmdlet Write-Progress para mostrar el progreso del comando. Es posible que se vea la barra de progreso durante la ejecución del comando.
Para obtener los comandos que se van a importar, Import-PSSession utiliza el cmdlet Invoke-Command para ejecutar un comando Get-Command en la PSSession. Para obtener los datos de formato de los comandos, utiliza el cmdlet Get-FormatData. Es posible que aparezcan mensajes de error de Invoke-Command, Get-Command y Get-FormatData al ejecutarse un comando Import-PSSession. Además, Import-PSSession no puede importar los comandos de una PSSession que no incluye los cmdlets Get-Command, Get-FormatData, Select-Object y Get-Help.
Los comandos importados tienen las mismas limitaciones que otros comandos remotos; por ejemplo, no pueden iniciar programas con una interfaz de usuario, como Bloc de notas.
Dado que los perfiles de Windows PowerShell no se ejecutan en sesiones PSSession, los comandos que un perfil agrega a una sesión no están disponibles para Import-PSSession. Si desea 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 Import-PSSession crea podría incluir un archivo de formato, incluso si el comando no importa los datos de formato. Si el comando no importa los datos de formato, los archivos de formato que se creen no incluirán datos de formato.
Para poder usar Import-PSSession, la directiva de ejecución de la sesión actual no puede ser Restricted ni AllSigned, porque el módulo que Import-PSSession crea contiene archivos de script no firmados que estas directivas prohíben. Para usar Import-PSSession sin cambiar la directiva de ejecución del equipo local, utilice el parámetro Scope de Set-ExecutionPolicy a fin de establecer una directiva de ejecución menos restrictiva para un proceso concreto.
Ejemplo 1
C:\PS>$s = new-pssession -computername Server01 C:\PS> import-pssession -session $s Descripción ----------- Este comando importa en la sesión actual todos los comandos de una PSSession en el equipo Server01, salvo los comandos que tienen 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 requeridos para los comandos importados.
Ejemplo 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 Descripción ----------- Estos comandos importan los comandos cuyo nombre termina en "-test" de una PSSession en la sesión local y, a continuación, muestran cómo utilizar un cmdlet importado. El primer comando utiliza 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 en la sesión actual los comandos de la PSSession almacenada en la variable $s. Utiliza el parámetro CommandName para especificar los comandos con el nombre Test y usa el parámetro FormatTypeName para importar los datos de formato de los comandos Test. El tercer y el cuarto comando utilizan los comandos importados en la sesión actual. Dado que los comandos importados en realidad se agregan a la sesión actual, se usa la sintaxis local para ejecutarlos. No es necesario utilizar el cmdlet Invoke-Command para ejecutar un comando importado.
Ejemplo 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 Descripción ----------- En este ejemplo, se muestra que los cmdlets importados pueden usarse de la misma manera que los 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 sesiones PSSession, se puede canalizar un objeto de un cmdlet a otro sin que se genere ningún error.
Ejemplo 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 Descripción ----------- 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 cada comando importado. El parámetro AsJob 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 en la sesión actual los cmdlets Test de la PSSession almacenada en la variable $s. El tercer comando usa el parámetro AsJob del cmdlet New-Test importado para ejecutar un comando New-Test como trabajo en segundo plano. El comando guarda en la variable $batch el objeto de trabajo que New-Test devuelve. El cuarto comando utiliza el cmdlet Receive-Job para obtener los resultados del trabajo almacenado en la variable $batch.
Ejemplo 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
Descripción
-----------
En este ejemplo, se muestra cómo importar en la sesión actual los cmdlets y funciones de 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 almacenada en $s.
Normalmente, un comando Import-Module en un perfil de Windows PowerShell agregaría el módulo a todas las sesiones, pero en las sesiones PSSession no se ejecutan perfiles.
El tercer comando usa el parámetro Module de Import-PSSession para importar en la sesión actual los cmdlets y funciones del módulo.
Ejemplo 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 : {}
Descripción
-----------
En este ejemplo, se muestra que Import-PSSession crea un módulo en un archivo temporal ubicado en el disco. También se 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 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.
Ejemplo 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 Descripción ----------- En este ejemplo, se muestra cómo ejecutar un comando ocultado por un comando importado. El primer comando importa un cmdlet Get-Date de la PSSession almacenada en la variable $s. Dado que la sesión actual incluye un cmdlet Get-Date, el parámetro AllowClobber es obligatorio en el comando. El segundo comando utiliza el cmdlet Get-Command para obtener 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 almacenada en la variable $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. El cuarto y el quinto comando muestran cómo utilizar un nombre completo para ejecutar un comando ocultado 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 cmdlet Get-Date que incluye el complemento para ejecutar un comando Get-Date. Para obtener más información sobre la precedencia de los comandos y los comandos ocultos, vea about_Command_Precedence.
Ejemplo 8
C:\PS>import-pssession -session $s -commandName *Item* -AllowClobber Descripción ----------- Este comando importa los comandos cuyo nombre incluye "Item" desde la PSSession almacenada en $s. Dado que el comando incluye el parámetro CommandName pero no el parámetro FormatTypeData, solo se importa el comando. Utilice este comando si usa Import-PSSession para ejecutar un comando en un equipo remoto y ya dispone de los datos de formato del comando en la sesión actual.
Ejemplo 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 Descripción ----------- Este comando muestra cómo utilizar el parámetro Module de Get-Command para determinar qué comandos se importaron en la sesión mediante un comando Import-PSSession. El primer comando utiliza el cmdlet Import-PSSession para importar los comandos cuyo nombre incluye "bits" desde la PSSession almacenada en la variable $s. El comando Import-PSSession devuelve un módulo temporal y lo guarda en la variable $m. El segundo comando usa el cmdlet Get-Command para obtener los comandos exportados por el módulo almacenado en la variable $m. El parámetro Module toma un valor de cadena, que se ha diseñado para el nombre del módulo. Sin embargo, cuando se envía un objeto de módulo, Windows PowerShell utiliza el método ToString en el objeto de módulo, el cual devuelve el nombre del módulo. El comando Get-Command equivale a "get-command $m.name".
Vea también