Import-PSSession

Sintaxe

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 do Microsoft Exchange Server, ou de uma sessão que inclua módulos e snap-ins do Windows PowerShell ou outros elementos que não estejam na sessão atual.

Para importar comandos, primeiro use o New-PSSession cmdlet para criar um 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 dos 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 o 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ê usa Import-PSSessiono , o Windows PowerShell adiciona os comandos importados a um módulo temporário que existe apenas na 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 do 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

$S = New-PSSession -ComputerName Server01
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

$S = New-PSSession https://ps.testlabs.com/powershell
Import-PSSession -Session $S -CommandName *-test -FormatTypeName *
New-Test -Name Test1
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 o 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 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

$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

Este exemplo mostra que é possível usar cmdlets importados da mesma maneira que cmdlets locais.

Esses comandos importam os New-Test cmdlets and Get-Test 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

$S = New-PSSession -ComputerName Server01
Import-PSSession -Session $S -CommandName *-test* -FormatTypeName *
$batch = New-Test -Name Batch -AsJob
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 o adiciona um parâmetro AsJob a cada comando importado. O parâmetro AsJob permite executar o comando como um trabalho em segundo plano.

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

O segundo comando é usado 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 do Windows PowerShell

$S = New-PSSession -ComputerName Server01
Invoke-Command -Session $S {Import-Module TestManagement}
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 no $S.

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

O terceiro comando usa o parâmetro Module of Import-PSSession para importar os cmdlets e as 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 o cria Import-PSSession 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 no $S.

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

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 do Windows PowerShell que adicionou o cmdlet original Get-Date à sessão atual.

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

Para obter mais informações sobre precedência de comando 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 , somente 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 do 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 Module de Get-Command 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 salva o módulo na $m variável.

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

O parâmetro Module usa 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

-ArgumentList

-Certificate

-CommandName

-CommandType

-DisableNameChecking

-FormatTypeName

-FullyQualifiedModule

-Module

-Prefix

-Session

Entradas

None

Você não pode canalizar objetos para esse cmdlet.

Saídas

PSModuleInfo

Esse cmdlet retorna o mesmo objeto de módulo que New-Module os cmdlets Get-Module e os 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 use 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 um PSSession que não inclua os Get-Commandcmdlets , Get-FormatData, Select-Object, e Get-Help .
• 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 os perfis do Windows PowerShell não são executados em PSSessions, os comandos que um perfil adiciona a uma sessão não estão disponíveis para Import-PSSessiono . 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 cria pode incluir um arquivo de formatação, mesmo que Import-PSSession 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-PSSessiono , a diretiva 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 diretivas. Para usar Import-PSSession sem alterar a política de execução do computador local, use o parâmetro Scope de 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).

Links Relacionados

• Export-PSSession