Partilhar via

Import-PSSession

  • Referência
Módulo:
Microsoft.PowerShell.Utility

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 Import-PSSession cmdlet importa comandos , como cmdlets, funções e aliases, de uma 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 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 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ê nem precisa 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 executar o comando como um trabalho em segundo plano do Windows PowerShell. Para obter mais informações, veja about_Jobs.

Quando você usa Import-PSSessiono , 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ê possa 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. Este recurso usa 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 uma 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, 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

$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, em seguida, mostram como usar um cmdlet importado.

O primeiro comando usa o New-PSSession cmdlet para criar uma 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 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 realmente adicionados à sessão atual, você usa a sintaxe local para executá-los. Não é necessário usar o Invoke-Command cmdlet para executar um comando importado.

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

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

Embora os cmdlets tenham sido importados de PSSessions diferentes, você pode canalizar 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 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 $S variável.

O segundo comando é usado Import-PSSession para importar os cmdlets Test do PSSession in $S para 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 uma PSSession no computador Server01 e a 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 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_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 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, o Windows PowerShell executa a função importada Get-Date , que retorna uma data juliana.

O quarto e 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 original Get-Date à sessão atual.

O quinto comando usa o nome qualificado do snap-in 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

Este comando importa comandos cujos nomes incluem 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 este 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: Use 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" da 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 Get-Command $M.Namea ".

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

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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 na unidade de certificado (Cert:) no PSSession em $S, digite Import-PSSession -Session $S -Command Get-Item -ArgumentList cert:.

Tipo:Object[]
Aliases:Args
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Certificate

Especifica o certificado de 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 contenha um certificado ou um comando ou expressão que obtenha o certificado.

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

Tipo:X509Certificate2
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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 dos comandos da sessão atual. Isso impede que comandos importados ocultem 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
Position:2
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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:

  • Alias: Os aliases do Windows PowerShell na sessão remota.
  • All: Os cmdlets e funções na sessão remota.
  • Application: Todos os arquivos diferentes dos arquivos do Windows-PowerShell 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: Os arquivos .ps1 nos caminhos listados na variável de ambiente Path ($env:path) na sessão remota.
  • Filter e Function: O Windows PowerShell funciona na sessão remota.
  • Script: O script bloqueia na sessão remota.

Esses valores são definidos como uma enumeração baseada em sinalizador. Você pode combinar vários valores juntos para definir vários sinalizadores usando esse parâmetro. Os valores podem ser passados para o parâmetro CommandType como uma matriz de valores ou como uma cadeia de caracteres separada por vírgulas desses valores. O cmdlet combinará os valores usando uma operação binary-OR. Passar valores como uma matriz é a opção mais simples e também permite que você use o preenchimento de tabulação nos valores.

Tipo:CommandTypes
Aliases:Type
Valores aceites:Alias, Function, Filter, Cmdlet, ExternalScript, Application, Script, Workflow, Configuration, All
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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 importado exporta cmdlets ou funções com verbos não aprovados em seus nomes, o Windows PowerShell exibe a seguinte mensagem de aviso:

"AVISO: Alguns nomes de comandos importados incluem verbos não aprovados que podem torná-los menos detetá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 conformes. Embora a mensagem seja exibida para os usuários do módulo, o problema de nomenclatura deve ser corrigido pelo autor do módulo.

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-FormatTypeName

Especifica instruções de formatação para os tipos especificados do Microsoft .NET Framework. Insira os nomes dos tipos. Curingas 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 do .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 .

Tipo:String[]
Position:3
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-FullyQualifiedModule

O valor pode ser um nome de módulo, uma especificação de módulo completo ou um caminho para um arquivo de módulo.

Quando o valor é um caminho, o caminho pode ser totalmente qualificado ou relativo. Um caminho relativo é resolvido em relação ao script que contém a instrução using.

Quando o valor é um nome ou especificação de módulo, o PowerShell procura o módulo especificado no PSModulePath .

Uma especificação de módulo é uma hashtable que tem as seguintes chaves.

  • ModuleName - Obrigatório Especifica o nome do módulo.
  • GUID - Opcional Especifica o GUID do módulo.
  • Também é necessário especificar pelo menos uma das três chaves abaixo.
    • ModuleVersion - Especifica uma versão mínima aceitável do módulo.
    • MaximumVersion - Especifica a versão máxima aceitável do módulo.
    • RequiredVersion - Especifica uma versão exata e obrigatória do módulo. Isso não pode ser usado com as outras chaves de versão.

Não é possível especificar o parâmetro FullyQualifiedModule no mesmo comando que um parâmetro Module . Os dois parâmetros excluem-se mutuamente.

Tipo:ModuleSpecification[]
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Module

Especifica e matriz de comandos nos snap-ins e módulos do Windows PowerShell. Insira os nomes do snap-in e do módulo. Curingas não são permitidos.

Import-PSSession Não é possível importar provedores de um snap-in.

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

Tipo:String[]
Aliases:PSSnapin
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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 têm o mesmo nome.

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

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Session

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 um New-PSSession comando or Get-PSSession . Você pode especificar apenas uma sessão. Este parâmetro é obrigatório.

Tipo:PSSession
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

None

Não é possível canalizar objetos para este cmdlet.

Saídas

PSModuleInfo

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

Notas

  • Import-PSSession depende da infraestrutura 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 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 Prefix . 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 de forma um pouco diferente do que se mantivessem seu tipo de comando original. Por exemplo, se você importar um cmdlet de um PSSession e, em seguida, importar um cmdlet com o mesmo nome de um módulo ou snap-in, o cmdlet importado do PSSession sempre será executado por padrão porque as funções têm precedência sobre os 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, porque os aliases têm precedência sobre as funções. Para obter mais informações, consulte 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 está em execução.
  • 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 uma PSSession que não inclua os Get-Commandcmdlets , 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 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-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 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, os arquivos de formatação criados não conterão dados de formatação.
  • Para usar Import-PSSessiono , a política de execução na sessão atual não pode ser Restrita ou AllSigned, porque 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 diretiva de execução para o computador local, use o parâmetro Scope de para definir uma diretiva 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 para um comando importado no Windows PowerShell 2.0, use o nome do comando original (não prefixado).