Compartilhar via


Import-PSSession

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

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 cmdlet Import-PSSession 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 cmdlet Get-Command possa encontrar no PSSession.

Use um comando Import-PSSession 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 estão na sessão atual.

Para importar comandos, primeiro use o cmdlet New-PSSession para criar uma PSSession. Em seguida, use o cmdlet Import-PSSession para importar os comandos. Por padrão, Import-PSSession importa todos os comandos, 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 forma 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 tratadas inteiramente pelo Windows PowerShell. Você não precisa nem estar ciente deles, exceto que você deve manter a conexão com a outra sessão (PSSession) aberta. Se você fechá-lo, 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ê usa Import-PSSession, o 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 cmdlet Export-PSSession.

O cmdlet Import-PSSession 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 cmdlet Import-Module para importar módulos de uma sessão remota para a sessão atual. Esse recurso usa comunicação remota implícita. É equivalente ao uso 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 uma PSSession

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

Esse comando importa todos os comandos de uma PSSession no computador Server01 para a sessão atual, exceto para comandos que têm os mesmos nomes que os 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 cmdlet New-PSSession para criar uma PSSession. Ele salva a PSSession na variável $S.

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

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

Exemplo 3: Importar cmdlets de uma 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 você pode usar cmdlets importados da mesma forma que usaria cmdlets locais.

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

Mesmo que os cmdlets tenham sido importados de PSSessions diferentes, você pode canalizar um objeto de um cmdlet para outro sem erros.

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 executar o comando como um trabalho em segundo plano.

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

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

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

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

Exemplo 5: importar cmdlets e funções de um módulo do 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 uma PSSession no computador Server01 e salva-o na variável $S.

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

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

O terceiro comando usa o parâmetro Module de Import-PSSession para 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_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 exemplo mostra que Import-PSSession cria um módulo em um arquivo temporário em 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 cmdlet Import-PSSession para importar um cmdlet Get-Date e uma função SearchHelp para a sessão atual.

O cmdlet Import-PSSession 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 cmdlet Get-Date 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 oculto por um comando importado.

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

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

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

O quarto e o quinto comandos mostram como usar um nome qualificado para executar um comando oculto por um comando importado.

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

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

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" da PSSession no $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 você 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 Module de get-command para descobrir quais comandos foram importados para a sessão por um comando Import-PSSession.

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

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

O parâmetro Module usa um valor de cadeia de caracteres, que foi 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 do módulo, que retorna o nome do módulo.

O comando Get-Command é 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, o comando importado oculta ou substitui os comandos originais. Para obter mais informações, consulte about_Command_Precedence.

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

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ArgumentList

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

Por exemplo, para importar a variante do comando Get-Item na unidade de certificado (Cert:) na PSSession em $S, digite Import-PSSession -Session $S -Command Get-Item -ArgumentList cert:.

Tipo:Object[]
Aliases:Args
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 criado Import-PSSession.

Insira uma variável que contenha um certificado ou um comando ou expressão que obtém o certificado.

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

Tipo:X509Certificate2
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-CommandName

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

Por padrão, Import-PSSession importa todos os comandos da sessão, exceto os comandos que têm os mesmos nomes que os comandos na sessão atual. Isso impede que os comandos importados ocultam ou substituam comandos na 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 será importado, a menos que você use o parâmetro CommandName.

Tipo:String[]
Aliases:Name
Cargo:2
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-CommandType

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

  • Cognome. Os aliases do Windows PowerShell na sessão remota.
  • Todo. Os cmdlets e as funções na sessão remota.
  • Aplicação. Todos os arquivos que não sejam Windows-PowerShell arquivos nos caminhos listados na variável de ambiente Path ($env:path) na sessão remota, incluindo arquivos .txt, .exee .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. O Windows PowerShell funciona na sessão remota.
  • Roteiro. O script é bloqueado na sessão remota.
Tipo:CommandTypes
Aliases:Type
Valores aceitos:Alias, Function, Filter, Cmdlet, ExternalScript, Application, Script, Workflow, Configuration, All
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 digite Get-Verb para ver a lista de verbos aprovados."

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

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-FormatTypeName

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

O valor desse parâmetro deve ser o nome de um tipo retornado por um comando Get-FormatData 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 do .NET Framework retornados por um comando Get-FormatData 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.

Tipo:String[]
Cargo:3
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-FullyQualifiedModule

Especifica módulos com nomes especificados na forma de objetos ModuleSpecification (descritos na seção Comentários do construtor ModuleSpecification (Hashtable) na biblioteca MSDN). 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 necessários, mas Guid é opcional.

Não é possível especificar o parâmetro FullyQualifiedModule no mesmo comando que um parâmetro do Módulo ; os dois parâmetros são mutuamente exclusivos.

Tipo:ModuleSpecification[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Module

Especifica e matriz de comandos nos snap-ins e módulos do Windows PowerShell. Insira o snap-in e os nomes do módulo. Curingas 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.

Tipo:String[]
Aliases:PSSnapin
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Prefix

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

Use esse parâmetro para evitar conflitos de nome que podem ocorrer quando comandos diferentes na sessão tiverem o mesmo nome.

Por exemplo, se você especificar o prefixo Remote e importar um cmdlet de Get-Date, o cmdlet será conhecido na sessão como Get-RemoteDatee não será confundido com o cmdlet de get-date original.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Session

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

Tipo:PSSession
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Entradas

None

Você não pode redirecionar objetos para este 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 apenas na sessão atual. Para criar um módulo permanente em disco, use o cmdlet Export-PSSession.

Observações

  • Import-PSSession depende da infraestrutura de comunicação remota do Windows PowerShell. Para usar esse cmdlet, o computador deve ser configurado para WS-Management comunicação remota. Para obter mais informações, consulte about_Remote e about_Remote_Requirements.
  • Import-PSSession não importa variáveis nem provedores do Windows PowerShell.
  • Quando você importa comandos que têm os mesmos nomes que os comandos na sessão atual, os comandos importados podem ocultar aliases, funções e cmdlets na sessão e podem substituir funções e variáveis na sessão. Para evitar conflitos de nome, use o parâmetro prefixo . Para obter mais informações, consulte about_Command_Precedence.
  • Import-PSSession converte todos os comandos em funções antes de importá-los. Como resultado, os comandos importados se comportam um pouco diferente do que fariam se retivessem o tipo de comando original. Por exemplo, se você importar um cmdlet de uma PSSession e importar 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 as funções têm precedência sobre cmdlets. Por outro lado, se você importar um alias para uma sessão que tenha um alias com o mesmo nome, o alias original será sempre usado, pois os aliases têm precedência sobre as funções. Para obter mais informações, consulte about_Command_Precedence.
  • Import-PSSession usa o cmdlet Write-Progress para exibir o progresso do comando. Você pode ver a barra de progresso enquanto o comando está em execução.
  • Para localizar os comandos a serem importados, Import-PSSession usa o cmdlet Invoke-Command para executar um comando Get-Command no PSSession. Para obter dados de formatação para os comandos, ele usa o cmdlet Get-FormatData. Você pode ver mensagens de erro desses cmdlets ao executar um comando Import-PSSession. Além disso, Import-PSSession não pode importar comandos de uma PSSession que não inclua os cmdlets Get-Command, Get-FormatData, Select-Object e Get-Help.
  • Os comandos importados têm as mesmas limitações que outros comandos remotos, incluindo a incapacidade de iniciar um programa com uma interface do 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-PSSession. Para importar comandos de um perfil, use um comando Invoke-Command para executar o perfil na 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, todos os 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 sem sinal que são proibidos por essas políticas. Para usar Import-PSSession sem alterar a política de execução do computador local, use o parâmetro Scope de Set-ExecutionPolicy para definir uma política de 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 Prefixo. Para obter ajuda para um comando importado no Windows PowerShell 2.0, use o nome do comando original (não prefixado).