Compartilhar via

Export-PSSession

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

Exporta comandos de outra sessão e os salva em um módulo do PowerShell.

Sintaxe

Export-PSSession
      [-OutputModule] <String>
      [-Force]
      [-Encoding <Encoding>]
      [[-CommandName] <String[]>]
      [-AllowClobber]
      [-ArgumentList <Object[]>]
      [-CommandType <CommandTypes>]
      [-Module <String[]>]
      [-FullyQualifiedModule <ModuleSpecification[]>]
      [[-FormatTypeName] <String[]>]
      [-Certificate <X509Certificate2>]
      [-Session] <PSSession>
      [<CommonParameters>]

Description

O cmdlet Export-PSSession obtém cmdlets, funções, aliases e outros tipos de comando de outra sessão do PowerShell (PSSession) em um computador local ou remoto e os salva em um módulo do PowerShell. Para adicionar os comandos do módulo à sessão atual, use o cmdlet Import-Module.

Ao contrário de Import-PSSession, que importa comandos de outro PSSession para a sessão atual, Export-PSSession salva os comandos em um módulo. Os comandos não são importados para a sessão atual.

Para exportar comandos, use o cmdlet New-PSSession para criar uma PSSession que tenha os comandos que você deseja exportar. Em seguida, use o cmdlet Export-PSSession para exportar os comandos.

Para evitar conflitos de nome de comando, o padrão para Export-PSSession é exportar todos os comandos, exceto os comandos que existem na sessão atual. Você pode usar o parâmetro CommandName para especificar os comandos a serem exportados.

O cmdlet Export-PSSession usa o recurso de comunicação remota implícita do 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.

Exemplos

Exemplo 1: exportar comandos de uma PSSession

Este exemplo cria uma nova PSSession do computador local para o computador Server01. Todos os comandos, exceto aqueles que existem na sessão atual, são exportados para o módulo denominado Server01 no computador local. A exportação inclui os dados de formatação para os comandos.

$S = New-PSSession -ComputerName Server01
Export-PSSession -Session $S -OutputModule Server01

O comando New-PSSession cria uma PSSession no computador Server01. A PSSession é armazenada na variável $S. O comando Export-PSSession exporta os comandos da variável $S e os dados de formatação para o módulo Server01.

Exemplo 2: exportar os comandos Get e Set

Este exemplo exporta todos os comandos Get e Set de um servidor.

$S = New-PSSession -ConnectionUri https://exchange.microsoft.com/mailbox -Credential exchangeadmin01@hotmail.com -Authentication Negotiate
Export-PSSession -Session $S -Module exch* -CommandName Get-*, Set-* -FormatTypeName * -OutputModule $PSHOME\Modules\Exchange -Encoding ASCII

Esses comandos exportam os comandos Get e Set de um snap-in do Microsoft Exchange Server em um computador remoto para um módulo do Exchange no diretório $PSHOME\Modules no computador local. Colocar o módulo no diretório $PSHOME\Modules torna-o acessível a todos os usuários do computador.

Exemplo 3: exportar comandos de um computador remoto

Este exemplo exporta cmdlets de uma PSSession em um computador remoto e os salva em um módulo no computador local. Os cmdlets do módulo são adicionados à sessão atual para que possam ser usados.

$S = New-PSSession -ComputerName Server01 -Credential Server01\User01
Export-PSSession -Session $S -OutputModule TestCmdlets -Type Cmdlet -CommandName *test* -FormatTypeName *
Remove-PSSession $S
Import-Module TestCmdlets
Get-Help Test*
Test-Files

O comando New-PSSession cria uma PSSession no computador Server01 e salva-o na variável $S. O comando Export-PSSession exporta os cmdlets cujos nomes começam com Test from the PSSession in $S to the TestCmdlets module on the local computer.

O cmdlet Remove-PSSession exclui a PSSession em $S da sessão atual. Este comando mostra que a PSSession não precisa estar ativa para usar os comandos importados da sessão. O cmdlet Import-Module adiciona os cmdlets no módulo TestCmdlets à sessão atual. O comando pode ser executado em qualquer sessão a qualquer momento.

O cmdlet Get-Help obtém ajuda para cmdlets cujos nomes começam com Teste. Depois que os comandos em um módulo forem adicionados à sessão atual, você poderá usar os cmdlets Get-Help e Get-Command para saber mais sobre os comandos importados. O cmdlet Test-Files foi exportado do computador Server01 e adicionado à sessão. O cmdlet Test-Files é executado em uma sessão remota no computador do qual o comando foi importado. O PowerShell cria uma sessão com base em informações armazenadas no módulo TestCmdlets.

Exemplo 4: exportar e clobber comandos na sessão atual

Este exemplo exporta comandos armazenados em uma variável para a sessão atual.

Export-PSSession -Session $S -AllowClobber -OutputModule AllCommands

Esse comando Export-PSSession exporta todos os comandos e todos os dados de formatação da PSSession na variável $S para a sessão atual. O parâmetro AllowClobber inclui comandos com os mesmos nomes que os comandos na sessão atual.

Exemplo 5: Exportar comandos de uma PSSession fechada

Este exemplo mostra como executar os comandos exportados com opções especiais quando a PSSession que criou os comandos exportados for fechada.

Se a sessão remota original for fechada quando um módulo for importado, o módulo usará qualquer sessão remota aberta que se conecte ao computador de origem. Se não houver nenhuma sessão atual no computador de origem, o módulo restabelecerá uma sessão.

Para executar comandos exportados com opções especiais em uma sessão remota, você deve criar uma sessão remota com essas opções antes de importar o módulo. Usar o cmdlet New-PSSession com o parâmetro SessionOption

$Options = New-PSSessionOption -NoMachineProfile
$S = New-PSSession -ComputerName Server01 -SessionOption $Options
Export-PSSession -Session $S -OutputModule Server01
Remove-PSSession $S
New-PSSession -ComputerName Server01 -SessionOption $Options
Import-Module Server01

O cmdlet New-PSSessionOption cria um objeto PSSessionOption e salva o objeto na variável $Options. O comando New-PSSession cria uma PSSession no computador Server01. O parâmetro SessionOption usa o objeto armazenado em $Options. A sessão é armazenada na variável $S.

O cmdlet Export-PSSession exporta comandos da PSSession em $S para o módulo Server01. O cmdlet Remove-PSSession exclui a PSSession na variável $S.

O cmdlet New-PSSession cria uma nova PSSession que se conecta ao computador Server01. O parâmetro SessionOption usa o objeto armazenado em $Options. O cmdlet Import-Module importa os comandos do módulo Server01. Os comandos no módulo são executados no PSSession no computador Server01.

Parâmetros

-AllowClobber

Exporta os comandos especificados, mesmo que eles tenham os mesmos nomes que os comandos na sessão atual.

Se você exportar um comando com o mesmo nome de um comando na sessão atual, o comando exportado oculta ou substitui os comandos originais. Para obter mais informações, consulte about_Command_Precedence.

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

-ArgumentList

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

Por exemplo, para exportar a variante do comando Get-Item na unidade certificado (Cert:) na PSSession em $S, digite Export-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 que Export-PSSession cria. 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

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

Por padrão, Export-PSSession exporta todos os comandos da PSSession, exceto os comandos que têm os mesmos nomes que os comandos na sessão atual. Isso impede que os comandos sejam ocultos ou substituídos por comandos na sessão atual. Para exportar 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 exportados, a menos que você use o parâmetro FormatTypeName. Da mesma forma, se você usar o parâmetro FormatTypeName, nenhum comando será exportado, a menos que você use o parâmetro CommandName.

Tipo:String[]
Aliases:Name
Cargo:2
Valor padrão:All commands in the session.
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:True

-CommandType

Exporta apenas os tipos especificados de objetos de comando. Use commandType ou seu alias, Type.

Os valores aceitáveis para esse parâmetro são os seguintes:

  • Alias: todos os aliases do PowerShell na sessão atual.
  • All: todos os tipos de comando. É o equivalente a Get-Command -Name *.
  • Application: todos os arquivos que não sejam arquivos do PowerShell em caminhos listados na variável de ambiente Path ($env:path), incluindo arquivos .txt, .exee .dll.
  • Cmdlet: os cmdlets na sessão atual. O cmdlet é o padrão.
  • Configuration: uma configuração do PowerShell. Para obter mais informações, consulte about_Session_Configurations.
  • ExternalScript: todos os arquivos .ps1 nos caminhos listados na variável de ambiente Path ($env:path).
  • Filter e Function: todas as funções do PowerShell.
  • Script blocos de script na sessão atual.
  • Workflow um fluxo de trabalho do PowerShell. Para obter mais informações, consulte about_Workflows.

Esses valores são definidos como uma enumeração baseada em sinalizador. Você pode combinar vários valores 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 binária-OR. Passar valores como uma matriz é a opção mais simples e também permite que você use a conclusão da guia nos valores.

Tipo:CommandTypes
Aliases:Type
Valores aceitos:Alias, All, Application, Cmdlet, Configuration, ExternalScript, Filter, Function, Script, Workflow
Cargo:Named
Valor padrão:All commands in the session.
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Encoding

Especifica o tipo de codificação para o arquivo de destino. O valor padrão é utf8NoBOM.

Os valores aceitáveis para esse parâmetro são os seguintes:

  • ascii: usa a codificação para o conjunto de caracteres ASCII (7 bits).
  • ansi: usa a codificação para a página de código ANSI da cultura atual. Essa opção foi adicionada ao PowerShell 7.4.
  • bigendianunicode: codifica no formato UTF-16 usando a ordem de bytes big-endian.
  • bigendianutf32: codifica no formato UTF-32 usando a ordem de bytes big-endian.
  • oem: usa a codificação padrão para programas de MS-DOS e console.
  • unicode: codifica no formato UTF-16 usando a ordem de bytes little-endian.
  • utf7: codifica no formato UTF-7.
  • utf8: codifica no formato UTF-8.
  • utf8BOM: codifica no formato UTF-8 com Marca de Ordem de Byte (BOM)
  • utf8NoBOM: codifica no formato UTF-8 sem Marca de Ordem de Bytes (BOM)
  • utf32: codifica no formato UTF-32.

A partir do PowerShell 6.2, o parâmetro de codificação de também permite IDs numéricas de páginas de código registradas (como -Encoding 1251) ou nomes de cadeia de caracteres de páginas de código registradas (como -Encoding "windows-1251"). Para obter mais informações, consulte a documentação do .NET para Encoding.CodePage.

A partir do PowerShell 7.4, você pode usar o valor Ansi para o parâmetro de codificação para passar a ID numérica para a página de código ANSI da cultura atual sem precisar especificá-la manualmente.

Nota

UTF-7 * não é mais recomendável usar. A partir do PowerShell 7.1, um aviso será gravado se você especificar utf7 para o parâmetro de codificação.

Tipo:Encoding
Valores aceitos:ASCII, BigEndianUnicode, BigEndianUTF32, OEM, Unicode, UTF7, UTF8, UTF8BOM, UTF8NoBOM, UTF32
Cargo:Named
Valor padrão:UTF8NoBOM
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Force

Substitui um ou mais arquivos de saída existentes, mesmo que o arquivo tenha o atributo somente leitura.

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

-FormatTypeName

Exporta instruções de formatação somente para os tipos especificados do Microsoft .NET Framework. Insira os nomes de tipo. Por padrão, Export-PSSession exporta instruções de formatação para todos os tipos do .NET Framework que não estão no namespace System.Management.Automation.

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 você usar o parâmetro FormatTypeName, nenhum comando será exportado, a menos que você use o parâmetro CommandName.

Se você usar o parâmetro CommandName, os arquivos de formatação para os comandos não serão exportados, 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

O valor pode ser um nome de módulo, uma especificação de módulo completa 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 é uma especificação de nome ou módulo, o PowerShell pesquisa o PSModulePath para o módulo especificado.

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

  • ModuleName - necessário especifica o nome do módulo.
  • GUID - opcional especifica o GUID do módulo.
  • Também é necessário para 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 necessá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 do Módulo. os dois parâmetros são mutuamente exclusivos.

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

-Module

Exporta apenas os comandos nos snap-ins e módulos especificados do PowerShell. Insira o snap-in e os nomes do módulo. Curingas não são permitidos.

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

Tipo:String[]
Aliases:PSSnapin
Cargo:Named
Valor padrão:All commands in the session.
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-OutputModule

Especifica um caminho e um nome opcionais para o módulo criado por Export-PSSession. O caminho padrão é $HOME\Documents\WindowsPowerShell\Modules. Esse parâmetro é necessário.

Se o subdiretório do módulo ou qualquer um dos arquivos que Export-PSSession criar já existirem, o comando falhará. Para substituir arquivos existentes, use o parâmetro Force.

Tipo:String
Aliases:PSPath, ModuleName
Cargo:1
Valor padrão:$HOME\Documents\WindowsPowerShell\Modules
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Session

Especifica a PSSession da qual os comandos são exportados. 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 Get-PSSession. 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

FileInfo

Esse cmdlet retorna uma lista de arquivos que compõem o módulo que ele criou.

Observações

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

Você não pode usar Export-PSSession para exportar um provedor do PowerShell.

Os comandos exportados são executados implicitamente na PSSession da qual foram exportados. Os detalhes da execução dos comandos remotamente são tratados inteiramente pelo PowerShell. Você pode executar os comandos exportados da mesma forma que executaria comandos locais.

Export-ModuleMember captura e salva informações sobre a PSSession no módulo exportado. Se a PSSession da qual os comandos foram exportados for fechada quando você importar o módulo e não houver PSSessions ativas no mesmo computador, os comandos no módulo tentarão recriar a PSSession. Se as tentativas de recriar a PSSession falharem, os comandos exportados não serão executados.

As informações de sessão que Export-ModuleMember capturam e salvam no módulo não incluem opções de sessão, como as especificadas na variável de preferência $PSSessionOption ou usando o parâmetro SessionOption dos cmdlets New-PSSession, Enter-PSSessionou Invoke-Command. Se a PSSession original for fechada quando você importar o módulo, o módulo usará outro PSSession para o mesmo computador, se houver um disponível. Para habilitar os comandos importados a serem executados em uma sessão configurada corretamente, crie uma PSSession com as opções desejadas antes de importar o módulo.

Para localizar os comandos a serem exportados, Export-PSSession usa o cmdlet Invoke-Command para executar um comando Get-Command no PSSession. Para obter e salvar dados de formatação para os comandos, ele usa os cmdlets Get-FormatData e Export-FormatData. Você pode ver mensagens de erro de Invoke-Command, Get-Command, Get-FormatDatae Export-FormatData ao executar um comando Export-PSSession. Além disso, Export-PSSession não pode exportar comandos de uma sessão que não inclua os cmdlets Get-Command, Get-FormatData, Select-Objecte Get-Help.

Export-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.

Os comandos exportados 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 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 Export-PSSession. Para exportar comandos de um perfil, use um comando Invoke-Command para executar o perfil na PSSession manualmente antes de exportar comandos.

O módulo que Export-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.