Importa comandos de outra sessão na sessão atual.

Sintaxe

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>]

Descrição

O cmdlet Import-PSSession importa comandos (como cmdlets, funções e aliases) de uma PSSession em um computador local ou remoto na sessão atual. Você pode importar qualquer comando que Get-Command localizar na PSSession.

Use um comando Import-PSSession para importar comandos de um shell personalizado, como um shell Microsoft Exchange Server, ou de uma sessão que inclui 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, o Import-PSSession importa todos os comandos, salvo os comandos com nome idêntico ao de comandos da 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 pela sessão. Quando você usar um comando importado, a parte importada do comando é executada implicitamente na sessão da qual ele foi importado. Porém, os operações remotas são totalmente administradas pelo Windows PowerShell. Você não precisa nem mesmo estar ciente deles, mas deve manter a conexão com a outra sessão (PSSession) aberta. Se você fechá-la, os comandos importados não estarão mais disponíveis.

Como os comandos importados podem levar mais tempo para serem executados que comandos locais, Import-PSSession acrescenta um parâmetro AsJob a cada comando importado. Esse parâmetro permite executar o comando como 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 só existe na sua sessão e retorna um objeto que representa o módulo. Para criar um módulo persistente que você possa usar em sessões futuras, use o cmdlet Export-PSSession.

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

Parâmetros

-AllowClobber

Importa os comandos especificados, até mesmo se eles tiverem os mesmos nomes que os comandos da sessão atual.

Se você importar um comando cujo nome seja igual ao de um comando da sessão atual, o comando importado ocultará ou substituirá 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 da sessão atual.

Necessário?

false

Posição?

named

Valor padrão

False

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-ArgumentList <Object[]>

Importa a variante do comando resultante do uso dos argumentos especificados (valores de parâmetros).

Por exemplo, para importar a variante do comando Get-Item na unidade do certificado (Cert:) no PSSession em $s, digite "import-pssession -session $s -command Get-Item -argumentlist cert:".

Necessário?

false

Posição?

named

Valor padrão

All command in the PSSession, except for commands with the same names as commands in the current session.

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-CommandName <string[]>

Importa apenas os comandos com os padrões de nome ou com os nomes especificados. Os caracteres curinga são permitidos. Use "CommandName" ou seu alias, "Name".

Por padrão, o Import-PSSession importa todos os comandos da sessão, salvo os comandos com nome idêntico ao de comandos da sessão atual. Isso impede que comandos importados ocultem ou substituam comandos da sessão. Para importar todos os comandos, até mesmo os que ocultam ou substituem outros comandos, use o parâmetro AllowClobber.

Se você usar o parâmetro CommandName, não serão importados os arquivos de formatação para os comandos a menos que você use o parâmetro FormatTypeName. De maneira semelhante, se você usar o parâmetro FormatTypeName, nenhum comando será importado a menos que você use o parâmetro CommandName.

Necessário?

false

Posição?

3

Valor padrão

All commands in the PSSession, except for commands with the same names as commands in the current session.

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

true

-CommandType <CommandTypes>

Importa apenas os tipos especificados de objetos de comando. O valor padrão é Cmdlet. Use "CommandType" ou seu alias, "Type".

Os valores válidos são:

-- Alias: os aliases do Windows PowerShell na sessão remota.

-- All: os cmdlets e as funções na sessão remota.

-- Application: todos os arquivos que não sejam do Windows PowerShell nos caminhos listados na variável de ambiente Path ($env:path) da sessão remota, inclusive arquivos .txt, .exe e .dll.

-- Cmdlet: os cmdlets na sessão remota. "Cmdlet" é o padrão.

-- ExternalScript: os arquivos .ps1 nos caminhos listados na variável de ambiente Path ($env:path) da sessão remota.

-- Filter e Function: as funções do Windows PowerShell na sessão remota.

-- Script: os blocos de scripts na sessão remota.

Necessário?

false

Posição?

named

Valor padrão

All command in the PSSession, except for commands with the same names as commands in the current session.

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-FormatTypeName <string[]>

Importa instruções de formatação para os tipos do Microsoft .NET Framework especificados. Insira os nomes de tipos. Os caracteres curinga são permitidos.

O valor deste 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.

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

Necessário?

false

Posição?

4

Valor padrão

Types in the System.Management.Automation namespace

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

true

-Module <string[]>

Importa apenas os comandos nos snap-ins e módulos do Windows PowerShell especificados. Insira os nomes de snap-ins e módulos. Os caracteres curinga não são permitidos.

Para obter mais informações, consulte about_Pssnapins e Import-Module.

Necessário?

false

Posição?

named

Valor padrão

All command in the PSSession, except for commands with the same names as commands in the current session.

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-Prefix <string>

Adiciona o prefixo especificado aos substantivos nos nomes de comandos importados.

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

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

Necessário?

false

Posição?

named

Valor padrão

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-Session <PSSession>

Especifica a PSSession da qual os cmdlets são importados. Insira uma variável que contenha um objeto de sessão ou um comando que obtenha um objeto de sessão, como o comando New-PSSession ou Get-PSSession. Você pode especificar só uma sessão. Esse parâmetro é obrigatório.

Necessário?

true

Posição?

1

Valor padrão

nenhum

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

<CommonParameters>

Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.

Entradas e saídas

O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.

Entradas

None

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

Saídas

System.Management.Automation.PSModuleInfo

Import-PSSession retorna o mesmo objeto do módulo que New-Module e Get-Module retornam. Porém, o módulo importado é temporário e existe só na sessão atual. Para criar um módulo permanente em disco, use o cmdlet Export-PSSession.

Observações

Import-PSSession depende da infraestrutura remota do Windows PowerShell. Para usar esse cmdlet, o computador deve ser configurado para comunicação remota de WS-Management. Para obter mais informações, consulte about_Remote and about_Remote_Requirements.

Você não pode usar Import-PSSession para importar variáveis ou provedores do Windows PowerShell.

Quando você importa comandos que têm os mesmos nomes que os comandos da sessão atual, os comandos importados podem ocultar aliases, funções e cmdlets na sessão, além de substituir funções e variáveis na sessão. 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 tivessem retido seus tipos de comando originais. Por exemplo, se você importar um cmdlet de uma PSSession e depois importar um cmdlet com o mesmo nome de um módulo ou snap-in, o cmdlet importado da PSSession sempre é executado por padrão porque as funções têm precedência sobre os cmdlets. Por outro lado, se você importar um alias em uma sessão que tenha um alias com o mesmo nome, o alias original sempre será usado, porque 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 andamento do comando. Você poderá ver a barra de andamento enquanto o comando estiver sendo executado.

Para localizar os comandos a serem importados, Import-PSSession usa o cmdlet Invoke-Command para executar um comando Get-Command na PSSession. Para obter dados de formatação para os comandos, ele usa o cmdlet Get-FormatData. Talvez você encontre mensagens de erro de Invoke-Command, Get-Command e Get-FormatData 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 de 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 acrescenta 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 poderia incluir um arquivo de formatação, até mesmo se o comando não importar dados de formatação. Se o comando não importar dados de formatação, qualquer arquivo de formatação criado não conterá dados de formatação.

Para usar Import-PSSession, a diretiva de execução na sessão atual não pode ser Restricted ou AllSigned, pois o módulo 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 diretiva de execução para o computador local, use o parâmetro Scope de Set-ExecutionPolicy para definir uma diretiva de execução menos restritiva para um único processo.

Exemplo 1

C:\PS>$s = new-pssession -computername Server01

C:\PS> import-pssession -session $s

Descrição
-----------
Esse comando importa todos os comandos de uma PSSession no computador Server01 para a sessão atual, salvo os comandos com nome idêntico ao de comandos da 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

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

Descrição
-----------
Esses comandos importam os comandos com nomes que terminam em "-test" de uma PSSession na sessão local e, depois, 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 Test e o parâmetro FormatTypeName para importar os dados de formatação para os comandos Test.

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






Exemplo 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

Descrição
-----------
Esse exemplo mostra que você pode usar cmdlets importados da mesma maneira 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. 

Embora os cmdlets sejam importados de PSSessions diferentes, você pode canalizar um objeto de um cmdlet para outro sem erro.






Exemplo 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

Descrição
-----------
Esse exemplo mostra como executar um comando importado como trabalho em segundo plano. 

Como os comandos importados podem levar mais tempo para serem executados que comandos locais, Import-PSSession acrescenta 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 variável $s.

O segundo comando usa Import-PSSession para importar os cmdlets Test 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 retornou na variável $batch.

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






Exemplo 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

Descrição
-----------
Esse exemplo mostra como importar os cmdlets e as funções de um módulo do Windows PowerShell em um computador remoto na sessão atual.

O primeiro comando cria uma PSSession no computador Server01 e salva-a na variável $s. 

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

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

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






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

Descrição
-----------
Esse 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 na sessão atual.

O comando usa o cmdlet Import-PSSession para importar um cmdlet Get-Date e uma função SearchHelp na 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

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

Descrição
-----------
Esse exemplo mostra como executar um comando ocultado 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 é obrigatório no comando.

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

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

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

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

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

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






Exemplo 8

C:\PS>import-pssession -session $s -commandName *Item* -AllowClobber

Descrição
-----------
Esse comando importa comandos cujos nomes incluam "Item" da 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 para o comando na sessão atual.






Exemplo 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

Descrição
-----------
Esse comando mostra como usar o parâmetro Module de Get-Command para descobrir quais comandos foram importados na sessão por um comando Import-PSSession.

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

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

O parâmetro Module utiliza um valor de cadeia de caracteres, que foi criado para o nome do módulo. Porém, quando você envia um objeto de módulo, o Windows PowerShell usa o método ToString no objeto de módulo, o qual retorna o nome do módulo. 

O comando Get-Command é o equivalente de "get-command $m.name".






See Also




Sumário