Import-PSSession

Referência

Módulo:: Microsoft.PowerShell.Utility

Importa comandos de outra sessão para a sessão atual.

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

O Import-PSSession cmdlet importa comandos, como cmdlets, funções e aliases, de um PSSession em um computador local ou remoto para a sessão atual. Você pode importar qualquer comando que o Get-Command cmdlet possa encontrar no PSSession.

Use um Import-PSSession comando para importar comandos de um shell personalizado, como um shell Microsoft Exchange Server ou de uma sessão que inclua Windows PowerShell módulos e snap-ins ou outros elementos que não estão na sessão atual.

Para importar comandos, primeiro use o New-PSSession cmdlet para criar uma PSSession. Em seguida, use o Import-PSSession cmdlet para importar os comandos. Por padrão, importa todos os comandos, Import-PSSession exceto os comandos que têm os mesmos nomes que os comandos na sessão atual. Para importar todos os comandos, use o parâmetro AllowClobber.

Você pode usar comandos importados da mesma maneira que usaria qualquer comando na sessão. Quando você usa um comando importado, a parte importada do comando é executada implicitamente na sessão da qual ele foi importado. No entanto, as operações remotas são manipuladas inteiramente pelo Windows PowerShell. Você não precisa nem estar ciente delas, exceto de que a conexão com a outra sessão (PSSession) deve ser mantida aberta. Se ela for fechada, os comandos importados não estarão mais disponíveis.

Como os comandos importados podem levar mais tempo para serem executados do que os comandos locais, Import-PSSession adiciona um parâmetro AsJob a cada comando importado. Esse parâmetro permite que você execute o comando como um trabalho em segundo plano do Windows PowerShell. Para obter mais informações, consulte about_Jobs.

Quando você usaImport-PSSession, Windows PowerShell adiciona os comandos importados a um módulo temporário que existe apenas em sua sessão e retorna um objeto que representa o módulo. Para criar um módulo persistente que você pode usar em sessões futuras, use o Export-PSSession cmdlet.

O Import-PSSession cmdlet usa o recurso de comunicação remota implícita de Windows PowerShell. Quando você importa comandos para a sessão atual, eles são executados implicitamente na sessão original ou em uma sessão semelhante no computador de origem.

A partir do Windows PowerShell 3.0, você pode usar o Import-Module cmdlet para importar módulos de uma sessão remota para a sessão atual. Esse recurso usa a comunicação remota implícita. É equivalente a usar Import-PSSession para importar módulos selecionados de uma sessão remota para a sessão atual.

Exemplos

Exemplo 1: importar todos os comandos de um PSSession

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

Este comando importa todos os comandos de uma PSSession no computador Server01 para a sessão atual, com exceção de comandos que possuem os mesmos nomes de comandos na sessão atual.

Como esse comando não usa o parâmetro CommandName, ele também importa todos os dados de formatação necessários para os comandos importados.

Exemplo 2: Importar comandos que terminam com uma cadeia de caracteres 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

Esses comandos importam os comandos com nomes que terminam em "-test" de uma PSSession para a sessão local e mostram como usar um cmdlet importado.

O primeiro comando usa o New-PSSession cmdlet para criar um PSSession. Ele salva a PSSession na $S variável.

O segundo comando usa o Import-PSSession cmdlet para importar comandos do PSSession para $S a sessão atual. Ele usa o parâmetro CommandName para especificar comandos com o substantivo Test (Teste) e o parâmetro FormatTypeName para importar os dados de formatação para os comandos Test.

Os terceiro e o quarto comandos usam os comandos importados na sessão atual. Como comandos importados, na verdade, são adicionados à sessão atual, a sintaxe local é usada para executá-los. Você não precisa usar o Invoke-Command cmdlet para executar um comando importado.

Exemplo 3: importar cmdlets de um 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 exemplo mostra que é possível usar cmdlets importados da mesma maneira que cmdlets locais.

Esses comandos importam os cmdlets e Get-Test os New-Test cmdlets de um PSSession no computador Server01 e o Set-Test cmdlet de um PSSession no computador Server02.

Embora os cmdlets sejam importados de diferentes PSSessions, é possível direcionar um objeto de um cmdlet para outro sem erro.

Exemplo 4: executar um comando importado como um trabalho em 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 exemplo mostra como executar um comando importado como um trabalho em segundo plano.

Como os comandos importados podem levar mais tempo para serem executados do que os comandos locais, Import-PSSession adiciona um parâmetro AsJob a cada comando importado. O parâmetro AsJob permite que você execute o comando como um trabalho em segundo plano.

O primeiro comando cria uma PSSession no computador Server01 e salva o objeto PSSession na $S variável.

O segundo comando usa Import-PSSession para importar os cmdlets de teste do PSSession para $S a sessão atual.

O terceiro comando usa o parâmetro AsJob do cmdlet importado New-Test para executar um New-Test comando como um trabalho em segundo plano. O comando salva o objeto de trabalho que New-Test retorna na $batch variável.

O quarto comando usa o Receive-Job cmdlet para obter os resultados do trabalho na $batch variável.

Exemplo 5: importar cmdlets e funções de um módulo 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

Este exemplo mostra como importar os cmdlets e funções de um módulo do Windows PowerShell em um computador remoto para a sessão atual.

O primeiro comando cria um PSSession no computador Server01 e o salva na $S variável.

O segundo comando usa o Invoke-Command cmdlet para executar um Import-Module comando no PSSession em $S.

Normalmente, o módulo seria adicionado a todas as sessões por um Import-Module comando em um perfil Windows PowerShell, mas os perfis não são executados em PSSessions.

O terceiro comando usa o parâmetro Module para Import-PSSession importar os cmdlets e funções no módulo para a sessão atual.

Exemplo 6: criar um módulo em um arquivo temporário

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

Este exemplo mostra que Import-PSSession cria um módulo em um arquivo temporário no disco. Ele também mostra que todos os comandos são convertidos em funções antes de serem importados para a sessão atual.

O comando usa o Import-PSSession cmdlet para importar um Get-Date cmdlet e uma função SearchHelp para a sessão atual.

O Import-PSSession cmdlet retorna um objeto PSModuleInfo que representa o módulo temporário. O valor da propriedade Path mostra que Import-PSSession criou um arquivo de módulo de script (.psm1) em um local temporário. A propriedade ExportedFunctions mostra que o Get-Date cmdlet e a função SearchHelp foram importados como funções.

Exemplo 7: executar um comando oculto por um 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

Este exemplo mostra como executar um comando que está oculto por um comando importado.

O primeiro comando importa um Get-Date cmdlet do PSSession na $S variável. Como a sessão atual inclui um Get-Date cmdlet, o parâmetro AllowClobber é necessário no comando.

O segundo comando usa o parâmetro All do Get-Command cmdlet para obter todos os Get-Date comandos na sessão atual. A saída mostra que a sessão inclui o cmdlet original Get-Date e uma Get-Date função. A Get-Date função executa o cmdlet importado Get-Date no PSSession em $S.

O terceiro comando executa um Get-Date comando. Como as funções têm precedência sobre cmdlets, Windows PowerShell executa a função importadaGet-Date, que retorna uma data Julian.

Os quarto e quinto comandos mostram como usar um nome qualificado para executar um comando que está oculto por um comando importado.

O quarto comando obtém o nome do snap-in Windows PowerShell que adicionou o cmdlet original Get-Date à sessão atual.

O quinto comando usa o nome snap-in-qualified do Get-Date cmdlet para executar um Get-Date comando.

Para obter mais informações sobre precedência de comandos e comandos ocultos, consulte about_Command_Precedence.

Exemplo 8: importar comandos que têm uma cadeia de caracteres específica em seus nomes

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

Esse comando importa comandos cujos nomes incluem Item do PSSession em $S. Como o comando inclui o parâmetro CommandName , mas não o parâmetro FormatTypeData , apenas o comando é importado.

Use esse comando quando estiver usando Import-PSSession para executar um comando em um computador remoto e já tiver os dados de formatação para o comando na sessão atual.

Exemplo 9: usar o parâmetro Module para descobrir quais comandos foram importados para a sessão

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 mostra como usar o parâmetro Get-CommandModule para descobrir quais comandos foram importados para a sessão por um Import-PSSession comando.

O primeiro comando usa o Import-PSSession cmdlet para importar comandos cujos nomes incluem "bits" do PSSession na $S variável. O Import-PSSession comando retorna um módulo temporário e o comando salva o módulo na $m variável.

O segundo comando usa o Get-Command cmdlet para obter os comandos exportados pelo módulo na $M variável.

O parâmetro Module obtém um valor de cadeia de caracteres, que é projetado para o nome do módulo. No entanto, quando você envia um objeto de módulo, o Windows PowerShell usa o método ToString no objeto de módulo, que retorna o nome do módulo.

O Get-Command comando é o equivalente a Get-Command $M.Name".

Parâmetros

-AllowClobber

Indica que esse cmdlet importa os comandos especificados, mesmo que eles tenham os mesmos nomes que os comandos na sessão atual.

Se você importar um comando com o mesmo nome de um comando na sessão atual, os comandos importado ocultam ou substituem os originais. Para obter mais informações, confira about_Command_Precedence.

Por padrão, Import-PSSession não importa comandos que tenham o mesmo nome que comandos na sessão atual.

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

-ArgumentList

Especifica uma matriz de comandos que resulta do uso dos argumentos especificados (valores de parâmetro).

Por exemplo, para importar a variante do Get-Item comando no certificado (Cert:) unidade no PSSession em $S, tipo 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 o certificado do cliente usado para assinar os arquivos de formato (*. Format.ps1xml) ou arquivos de módulo de script (.psm1) no módulo temporário que Import-PSSession cria.

Insira uma variável que contém um certificado, comando ou expressão que obtém os objetos.

Para localizar um certificado, use o Get-PfxCertificate cmdlet ou use o Get-ChildItem cmdlet no Certificado (Cert:) Dirigir. Se o certificado não for válido ou não tiver autoridade suficiente, o comando falhará.

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

-CommandName

Especifica comandos com os nomes ou padrões de nome especificados. Caracteres curinga são permitidos. Use CommandName ou seu alias, Name.

Por padrão, Import-PSSession importa todos os comandos da sessão, exceto para comandos que têm os mesmos nomes que comandos na sessão atual. Isso impede que os comandos importados ocultem ou substituam os comandos da sessão. Para importar todos os comandos, mesmo aqueles que ocultam ou substituem outros comandos, use o parâmetro AllowClobber.

Se você usar o parâmetro CommandName, os arquivos de formatação para os comandos não serão importados a menos que você use o parâmetro FormatTypeName. Da mesma forma, se você usar o parâmetro FormatTypeName, nenhum comando é importado, a menos que você use o parâmetro CommandName.

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

-CommandType

Especifica o tipo de objetos de comando. O valor padrão é Cmdlet. Use o CommandType ou seu alias, Type. Os valores aceitáveis para esse parâmetro são:

Alias. Os aliases do Windows PowerShell na sessão remota.
Todos. Os cmdlets e funções na sessão remota.
Console. Todos os arquivos diferentes de Windows-PowerShell arquivos nos caminhos listados na variável de ambiente Path ($env:path) na sessão remota, incluindo arquivos .txt, .exe e .dll.
Cmdlet. Os cmdlets na sessão remota. "Cmdlet" é o padrão.
ExternalScript. O .ps1 arquivos nos caminhos listados na variável de ambiente Path ($env:path) na sessão remota.
Filtrar e Função. As funções do Windows PowerShell na sessão remota.
Script. Os blocos de script na sessão 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 esse cmdlet suprime a mensagem que avisa quando você importa um cmdlet ou função cujo nome inclui um verbo não aprovado ou um caractere proibido.

Por padrão, quando um módulo que você importa exporta cmdlets ou funções que têm verbos não aprovados em seus nomes, o Windows PowerShell exibe a seguinte mensagem de aviso:

"AVISO: alguns nomes de comando importados incluem verbos não aprovados, o que pode torná-los menos detectáveis. Use o parâmetro Verbose para obter mais detalhes ou tipo Get-Verb para ver a lista de verbos aprovados."

A mensagem é apenas um aviso. O módulo completo ainda é importado, incluindo os comandos não autorizados. Embora a mensagem seja exibida para usuários do módulo, o problema de nomenclatura deve ser corrigido pelo autor do módulo.

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

-FormatTypeName

Especifica instruções de formatação para os tipos de .NET Framework da Microsoft especificados. Insira os nomes de tipo. Caracteres curinga são permitidos.

O valor desse parâmetro deve ser o nome de um tipo retornado por um Get-FormatData comando na sessão da qual os comandos estão sendo importados. Para obter todos os dados de formatação na sessão remota, digite *.

Se o comando não incluir o parâmetro CommandName ou FormatTypeName, Import-PSSession importará instruções de formatação para todos os tipos de .NET Framework retornados por um Get-FormatData comando na sessão remota.

Se você usar o parâmetro FormatTypeName, nenhum comando será importado, a menos que você use o parâmetro CommandName.

Da mesma forma, se você usar o parâmetro CommandName, os arquivos de formatação para os comandos não serão importados a menos que você use o parâmetro FormatTypeName.

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

-FullyQualifiedModule

Especifica módulos com nomes especificados na forma de objetos ModuleSpecification (descritos na seção Comentários do Construtor ModuleSpecification (Hashtable) no SDK do PowerShell. Por exemplo, o parâmetro FullyQualifiedModule aceita um nome de módulo especificado no formato:

@{ModuleName = "modulename"; ModuleVersion = "version_number"} ou
@{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}.

ModuleName e ModuleVersion são obrigatórios, mas Guid é opcional.

Não é possível especificar o parâmetro FullyQualifiedModule no mesmo comando que um parâmetro module . Os dois parâmetros são mutuamente exclusivos.

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

-Module

Especifica e matriz de comandos nos Windows PowerShell snap-ins e módulos. Digite os nomes de módulos e snap-ins. Caracteres curinga não são permitidos.

Import-PSSession não pode importar provedores de um snap-in.

Para obter mais informações, consulte about_PSSnapins e about_Modules.

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

-Prefix

Especifica um prefixo para os substantivos nos nomes dos comandos importados.

Use este parâmetro para evitar conflitos de nome que podem ocorrer quando diferentes membros da sessão têm o mesmo nome.

Por exemplo, se você especificar o prefixo Remoto e importar um Get-Date cmdlet, o cmdlet será conhecido na sessão como Get-RemoteDate, e ele não será confundido com o cmdlet original Get-Date .

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

-Session

Especifica a PSSession da qual os cmdlets são importados. Insira uma variável que contém um objeto de sessão ou um comando que obtém um objeto de sessão, como um New-PSSession ou Get-PSSession um comando. Você pode especificar somente uma sessão. Este parâmetro é necessário.

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

Entradas

None

Não é possível transferir objetos para esse cmdlet.

Saídas

PSModuleInfo

Import-PSSession retorna o mesmo objeto de módulo que New-Module e Get-Module cmdlets retornam. No entanto, o módulo importado é temporário e existe somente na sessão atual. Para criar um módulo permanente no disco, use o Export-PSSession cmdlet.

Observações

Import-PSSession depende da infraestrutura de comunicação remota do PowerShell. Para usar esse cmdlet, o computador deve ser configurado para comunicação remota do WS-Management. Para obter mais informações, consulte about_Remote e about_Remote_Requirements.
Import-PSSession não importa variáveis ou provedores do PowerShell.
Quando você importa comandos que têm os mesmos nomes que comandos na sessão atual, os comandos importados podem ocultar aliases, funções e cmdlets na sessão e eles podem substituir funções e variáveis na sessão. Para evitar conflitos de nome, use o parâmetro Prefix. Para obter mais informações, confira about_Command_Precedence.
Import-PSSession converte todos os comandos em funções antes de importá-los. Como resultado, comandos importados possuem um comportamento um pouco diferente de quando mantém tipo de comando original. Por exemplo, se você importar um cmdlet de uma PSSession e um cmdlet com o mesmo nome de um módulo ou snap-in, o cmdlet é importado da PSSession sempre será executado por padrão porque funções têm precedência sobre cmdlets. Por outro lado, se você importar um alias para uma sessão com um alias com o mesmo nome, o alias original sempre é usado, pois aliases têm precedência sobre funções. Para obter mais informações, confira about_Command_Precedence.
Import-PSSession usa o Write-Progress cmdlet para exibir o progresso do comando. Você pode ver a barra de progresso enquanto o comando é executado.
Para localizar os comandos a serem importados, Import-PSSession usa o Invoke-Command cmdlet para executar um Get-Command comando no PSSession. Para obter dados de formatação para os comandos, ele usa o Get-FormatData cmdlet. Você pode ver mensagens de erro desses cmdlets ao executar um Import-PSSession comando. Além disso, Import-PSSession não é possível importar comandos de uma PSSession que não inclua os Get-Commandcmdlets e Get-Help , e , Get-FormatDataportanto, Select-Object
Comandos importados têm as mesmas limitações que outros comandos remotos, inclusive a incapacidade de iniciar um programa com uma interface de usuário, como o Bloco de notas.
Como Windows PowerShell perfis não são executados em PSSessionsions, os comandos que um perfil adiciona a uma sessão não estão disponíveis para Import-PSSession. Para importar comandos de um perfil, use um Invoke-Command comando para executar o perfil no PSSession manualmente antes de importar comandos.
O módulo temporário que Import-PSSession cria pode incluir um arquivo de formatação, mesmo que o comando não importe dados de formatação. Se o comando não importar dados de formatação, quaisquer arquivos de formatação criados não conterão dados de formatação.
Para usar Import-PSSession, a política de execução na sessão atual não pode ser Restrita ou AllSigned, pois o módulo temporário que Import-PSSession cria contém arquivos de script não assinados que são proibidos por essas políticas. Para usar Import-PSSession sem alterar a política de execução para o computador local, use o parâmetro Escopo para definir uma política de Set-ExecutionPolicy execução menos restritiva para um único processo.
No Windows PowerShell 2.0, os tópicos de ajuda para comandos importados de outra sessão não incluem o prefixo que você atribui usando o parâmetro Prefix. Para obter ajuda sobre um comando importado no Windows PowerShell 2.0, use o nome original do comando (sem prefixo).

Export-PSSession