Import-PSSession

Referência

Módulo:: Microsoft.PowerShell.Utility

Importações comanda de outra sessão para a sessão atual.

Syntax

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 , tais como cmdlets, funções e pseudónimos, de uma pssession num computador local ou remoto para a sessão atual. Pode importar qualquer comando que o Get-Command cmdlet possa encontrar na PSSession.

Utilize um Import-PSSession comando para importar comandos a partir de uma concha personalizada, como uma concha Microsoft Exchange Server, ou de uma sessão que inclua módulos Windows PowerShell e snap-ins ou outros elementos que não estejam na sessão atual.

Para importar comandos, primeiro use o New-PSSession cmdlet para criar uma pssessão. Em seguida, use o Import-PSSession cmdlet para importar os comandos. Por predefinição, Import-PSSession importa todos os comandos, exceto comandos que tenham os mesmos nomes que os comandos na sessão atual. Para importar todos os comandos, utilize o parâmetro AllowClobber .

Pode utilizar comandos importados tal como utilizaria qualquer comando na sessão. Quando se utiliza um comando importado, a parte importada do comando funciona implicitamente na sessão a partir da qual foi importada. No entanto, as operações remotas são totalmente tratadas por Windows PowerShell. Nem sequer precisas de estar atento a eles, exceto que tens de manter aberta a ligação à outra sessão (PSSession). Se o fechar, os comandos importados já não estão disponíveis.

Como os comandos importados podem demorar mais tempo a ser executados do que os comandos locais, Import-PSSession adiciona um parâmetro AsJob a cada comando importado. Este parâmetro permite-lhe executar o comando como um trabalho de fundo Windows PowerShell. Para obter mais informações, veja about_Jobs.

Quando utilizarImport-PSSession, Windows PowerShell adiciona os comandos importados a um módulo temporário que existe apenas na sua sessão e devolve um objeto que representa o módulo. Para criar um módulo persistente que pode utilizar em sessões futuras, utilize o Export-PSSession cmdlet.

O Import-PSSession cmdlet utiliza a característica implícita de remoting de Windows PowerShell. Quando importa comandos para a sessão atual, eles funcionam implicitamente na sessão original ou numa sessão semelhante no computador de origem.

A partir de Windows PowerShell 3.0, pode utilizar o Import-Module cmdlet para importar módulos de uma sessão remota para a sessão atual. Esta funcionalidade utiliza remoting implícito. É 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 PSSessão

$S = New-PSSession -ComputerName Server01
Import-PSSession -Session $S

Este comando importa todos os comandos de uma sessão PSSession no computador Server01 para a sessão atual, com exceção dos comandos que têm os mesmos nomes que os comandos na sessão atual.

Como este comando não utiliza o parâmetro CommandName , também importa todos os dados de formatação necessários para os comandos importados.

Exemplo 2: Comandos de importação que terminam com uma cadeia 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

Estes comandos importam os comandos com nomes que terminam em "teste" de uma PSSession para a sessão local, e depois mostram como usar um cmdlet importado.

O primeiro comando usa o New-PSSession cmdlet para criar uma pssessão. Poupa a pssession na $S variável.

O segundo comando usa o Import-PSSession cmdlet para importar comandos da PSSession para $S a sessão atual. Utiliza 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 quarto comandos usam os comandos importados na sessão atual. Como os comandos importados são adicionados à sessão atual, você usa a sintaxe local para executá-los. Não é necessário utilizar o Invoke-Command cmdlet para executar um comando importado.

Exemplo 3: Importar cmdlets de uma pssessão

$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 pode utilizar cmdlets importados tal como utilizaria os cmdlets locais.

Estes comandos importam os New-Test cmdlets e Get-Test os cmdlets de uma pssession no computador Server01 e o Set-Test cmdlet de uma pssessão no computador Server02.

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

Exemplo 4: Executar um comando importado como um trabalho de fundo

$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 gerir um comando importado como um trabalho de fundo.

Como os comandos importados podem demorar mais tempo a ser executados do que os comandos locais, Import-PSSession adiciona um parâmetro AsJob a cada comando importado. O parâmetro AsJob permite-lhe executar o comando como um trabalho de fundo.

O primeiro comando cria uma sessão de PSSessão no computador Server01 e guarda o objeto pssession na $S variável.

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

O terceiro comando usa o parâmetro AsJob do cmdlet importado New-Test para executar um New-Test comando como um trabalho de fundo. 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 a partir de um módulo 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 Windows PowerShell num computador remoto para a sessão atual.

O primeiro comando cria uma sessão PSSessão no computador Server01 e guarda-o na $S variável.

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

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

O terceiro comando utiliza o parâmetro módulo de importação dos Import-PSSession cmdlets e funções do módulo para a sessão atual.

Exemplo 6: Criar um módulo num ficheiro 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 num ficheiro temporário no disco. Também mostra que todos os comandos são convertidos em funções antes de serem importados para a sessão atual.

O comando utiliza o Import-PSSession cmdlet para importar uma Get-Date função cmdlet e uma função SearchHelp para a sessão atual.

O Import-PSSession cmdlet devolve um objeto PSModuleInfo que representa o módulo temporário. O valor da propriedade Path mostra que Import-PSSession criou um ficheiro de módulo de script (.psm1) numa localização temporária. A propriedade ExportedFunctions mostra que o Get-Date cmdlet e a função SearchHelp foram ambos importados como funções.

Exemplo 7: Executar um comando que é escondido por um comando importado

PS C:\> Import-PSSession $S -CommandName Get-Date -FormatTypeName * -AllowClobber

PS C:\> Get-Command Get-Date -All

CommandType   Name       Definition
-----------   ----       ----------
Function      Get-Date   ...
Cmdlet        Get-Date   Get-Date [[-Date] <DateTime>] [-Year <Int32>] [-Month <Int32>]

PS C:\> Get-Date
09074

PS C:\> (Get-Command -Type Cmdlet -Name Get-Date).PSSnapin.Name
Microsoft.PowerShell.Utility

PS C:\> Microsoft.PowerShell.Utility\Get-Date
Sunday, March 15, 2009 2:08:26 PM

Este exemplo mostra como executar um comando que é escondido por um comando importado.

O primeiro comando importa um Get-Date cmdlet da 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 utiliza 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 na PSSession em $S.

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

O quarto e quinto comandos mostram como usar um nome qualificado para executar um comando que é escondido por um comando importado.

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

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

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

Exemplo 8: Comandos de importação que têm uma cadeia 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 , apenas o comando é importado.

Utilize este comando quando estiver a utilizar Import-PSSession para executar um comando num computador remoto e já tem os dados de formatação para o comando na sessão atual.

Exemplo 9: Use o parâmetro módulo 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 módulo para Get-Command 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 devolve um módulo temporário, e o comando guarda o módulo na $m variável.

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

O parâmetro módulo tem um valor de cadeia, que é projetado para o nome do módulo. No entanto, quando submete um objeto de módulo, Windows PowerShell utiliza o método ToString no objeto do módulo, que devolve o nome do módulo.

O Get-Command comando é o equivalente a Get-Command $M.Name".

Parâmetros

-AllowClobber

Indica que este cmdlet importa os comandos especificados, mesmo que tenham os mesmos nomes que os comandos na sessão atual.

Se importar um comando com o mesmo nome que um comando na sessão atual, o comando importado esconde ou substitui os comandos originais. Para mais informações, consulte about_Command_Precedence.

Por predefinição, Import-PSSession não importa comandos com o mesmo nome que os comandos na sessão atual.

Type:	SwitchParameter
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-Certificado

Especifica o certificado de cliente que é usado para assinar os ficheiros de formato (*. Format.ps1xml) ou ficheiros de módulos de script (.psm1) no módulo temporário que Import-PSSession cria.

Introduza uma variável que contenha um certificado ou um comando ou expressão que obtenha o certificado.

Para encontrar um certificado, utilize o Get-PfxCertificate cmdlet ou utilize o Get-ChildItem cmdlet no Certificado (Cert:) Conduzir. Se o certificado não for válido ou não tiver autoridade suficiente, o comando falha.

Type:	X509Certificate2
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-DisableNameChecking

Indica que este cmdlet suprime a mensagem que o avisa quando importa um cmdlet ou função cujo nome inclui um verbo não aprovado ou um carácter proibido.

Por predefinição, quando um módulo que importa exporta cmdlets ou funções que não tenham verbos não aprovados nos seus nomes, o Windows PowerShell apresenta a seguinte mensagem de aviso:

"AVISO: Alguns nomes de comando importados incluem verbos não aprovados que podem torná-los menos detetáveis. Utilize o parâmetro Verbose para obter mais detalhes ou escrever 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 apresentada aos utilizadores do módulo, o problema de nomeação deve ser corrigido pelo autor do módulo.

Type:	SwitchParameter
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-FormatoTypeName

Especifica instruções de formatação para os tipos de .NET Framework microsoft especificados. Introduza os nomes do tipo. Wildcards são permitidos.

O valor deste parâmetro deve ser o nome de um tipo que é devolvido por um Get-FormatData comando na sessão a partir da qual os comandos estão a ser importados. Para obter todos os dados de formatação na sessão remota, escreva *.

Se o comando não incluir nem o ponto de Nome de Comando ou FormatoTypeName, Import-PSSession importa instruções de formatação para todos os tipos .NET Framework devolvidos por um Get-FormatData comando na sessão remota.

Se utilizar o parâmetro FormatoTypeName , não são importados comandos a não ser que utilize o parâmetro CommandName .

Da mesma forma, se utilizar o parâmetro CommandName , os ficheiros de formatação para os comandos não são importados a menos que utilize o parâmetro FormatTypeName .

Type:	String[]
Position:	3
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-Lista de Argumentos

Especifica uma matriz de comandos que resulta da utilização dos argumentos especificados (valores dos parâmetros).

Por exemplo, importar a variante do Get-Item comando no certificado (Cert:) conduzir na PSSession em $S, tipo Import-PSSession -Session $S -Command Get-Item -ArgumentList cert:.

Type:	Object[]
Aliases:	Args
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-Módulo

Especifica e conjunto de comandos no Windows PowerShell snap-ins e módulos. Introduza os nomes do snap-in e do módulo. Wildcards não são permitidos.

Import-PSSession não pode importar fornecedores de um snap-in.

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

Type:	String[]
Aliases:	PSSnapin
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-Nome de comando

Especifica comandos com os nomes especificados ou padrões de nome. Wildcards são permitidos. Use o Nome de Comando ou o seu pseudónimo, Nome.

Por predefinição, Import-PSSession importa todos os comandos da sessão, com exceção dos comandos que têm os mesmos nomes que os comandos na sessão atual. Isto impede que os comandos importados escondam ou substituam comandos na sessão. Para importar todos os comandos, mesmo aqueles que escondem ou substituem outros comandos, utilize o parâmetro AllowClobber .

Se utilizar o parâmetro CommandName , os ficheiros de formatação para os comandos não são importados a menos que utilize o parâmetro FormatTypeName . Da mesma forma, se utilizar o parâmetro FormatTypeName , não são importados comandos a menos que utilize o parâmetro CommandName .

Type:	String[]
Aliases:	Name
Position:	2
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-Perfeitamente Qualificado

Especifica módulos com nomes especificados sob a forma de objetos depecificação de módulos (descritos na secção observações do Construtor de Especificação de Módulos (Hashtable) no PowerShell SDK. Por exemplo, o parâmetroModule Totalmente Qualificado aceita um nome de módulo especificado no formato:

@{ModuleName = "modulename"; ModuleVersion = "version_number"} ou
@{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}.

MóduloName e Modusversão são necessários , mas Guid é opcional.

Não é possível especificar o parâmetro Demodule Totalmente Qualificado no mesmo comando que um parâmetro do Módulo . Os dois parâmetros são mutuamente exclusivos.

Type:	ModuleSpecification[]
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-Prefixo

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

Utilize este parâmetro para evitar conflitos de nomes que possam ocorrer quando diferentes comandos na sessão têm o mesmo nome.

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

Type:	String
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-Sessão

Especifica a pssessão a partir da qual os cmdlets são importados. Introduza uma variável que contenha um objeto de sessão ou um comando que obtém um objeto de sessão, como um ou Get-PSSession um New-PSSession comando. Pode especificar apenas uma sessão. Este parâmetro é necessário.

Type:	PSSession
Position:	0
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-Tipo de Comando

Especifica o tipo de objetos de comando. O valor predefinido é Cmdlet. Utilize o CommandType ou o seu pseudónimo, Escreva. Os valores aceitáveis para este parâmetro são:

Alias: Os Windows PowerShell pseudónimos na sessão remota.
All: Os cmdlets e funções na sessão remota.
Application: Todos os ficheiros que não Windows-PowerShell ficheiros nos caminhos listados na variável ambiente Path ($env:path) na sessão remota, incluindo .txt, .exe e .dll ficheiros.
Cmdlet: Os cmdlets na sessão remota. "Comandante" é o padrão.
ExternalScript: O .ps1 ficheiros nos caminhos listados na variável ambiente Path ($env:path) na sessão remota.
Filtere Function: O Windows PowerShell funciona na sessão remota.
Script: O script bloqueia na sessão remota.

Estes valores são definidos como uma enumeração baseada em bandeiras. Pode combinar vários valores para definir várias bandeiras usando este parâmetro. Os valores podem ser passados para o parâmetro CommandType como uma matriz de valores ou como uma cadeia separada por vírgula desses valores. O cmdlet combina os valores utilizando uma operação binária-OR. Passar valores como matriz é a opção mais simples e também permite-lhe utilizar a conclusão do separador sobre os valores.

Type:	CommandTypes
Aliases:	Type
Accepted values:	Alias, Function, Filter, Cmdlet, ExternalScript, Application, Script, Workflow, Configuration, All
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Entradas

Nenhuma

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

Saídas

PSModuleInfo

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

Notas

Import-PSSession depende da infraestrutura de remoing PowerShell. Para utilizar este cmdlet, o computador deve ser configurado para WS-Management de remote. Para mais informações, consulte about_Remote e about_Remote_Requirements.
Import-PSSession não importa variáveis ou fornecedores PowerShell.
Quando importa comandos com os mesmos nomes que os comandos na sessão em curso, os comandos importados podem ocultar pseudónimos, funções e cmdlets na sessão e podem substituir funções e variáveis na sessão. Para evitar conflitos de nome, utilize o parâmetro Prefix . Para mais informações, consulte about_Command_Precedence.
Import-PSSession converte todos os comandos em funções antes de os importar. Como resultado, os comandos importados comportam-se de forma um pouco diferente do que fariam se mantivessem o seu tipo de comando original. Por exemplo, se importar um cmdlet de uma PSSession e, em seguida, importar um cmdlet com o mesmo nome de um módulo ou snap-in, o cmdlet que é importado da PSSession sempre funciona por defeito porque as funções têm precedência sobre os cmdlets. Inversamente, se importa um pseudónimo para uma sessão que tem um pseudónimo com o mesmo nome, o pseudónimo original é sempre usado, porque os pseudónimos têm precedência sobre funções. Para mais informações, consulte about_Command_Precedence.
Import-PSSession usa o Write-Progress cmdlet para mostrar o progresso do comando. Pode ver a barra de progresso enquanto o comando está em funcionamento.
Para encontrar os comandos para importar, Import-PSSession usa o Invoke-Command cmdlet para executar um Get-Command comando na PSSession. Para obter dados de formatação para os comandos, utiliza o Get-FormatData cmdlet. Pode ver mensagens de erro destes cmdlets quando 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-Command, Get-FormatData``Select-Objecte Get-Help cmdlets.
Os comandos importados têm as mesmas limitações que outros comandos remotos, incluindo a incapacidade de iniciar um programa com uma interface de utilizador, como Bloco de notas.
Como Windows PowerShell perfis não são executados em sessões de PSS, os comandos que um perfil adiciona a uma sessão não estão disponíveis para Import-PSSession. Para importar comandos a partir de um perfil, utilize um Invoke-Command comando para executar o perfil na PSSession manualmente antes de importar comandos.
O módulo temporário que Import-PSSession cria pode incluir um ficheiro de formatação, mesmo que o comando não importe dados de formatação. Se o comando não importar dados de formatação, quaisquer ficheiros de formatação que sejam criados não conterão dados de formatação.
Para utilizar Import-PSSession, a política de execução na sessão em curso não pode ser restrita ou allSigned, porque o módulo temporário que Import-PSSession cria contém ficheiros de script não assinados que são proibidos por estas políticas. Para utilizar Import-PSSession sem alterar a política de execução do computador local, utilize o parâmetro Scope para definir uma política de Set-ExecutionPolicy execução menos restritiva para um único processo.
Em Windows PowerShell 2.0, os tópicos de ajuda para comandos importados de outra sessão não incluem o prefixo que atribui utilizando o parâmetro Prefix. Para obter ajuda para um comando importado em Windows PowerShell 2.0, utilize o nome de comando original (não prefixado).

Export-PSSession