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
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
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
O segundo comando usa o parâmetro
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
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
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"}.
Não é possível especificar o parâmetro
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
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).