Compartilhar via


Receive-PSSession

Obtém resultados de comandos em sessões desconectadas

Sintaxe

Receive-PSSession
       [-Session] <PSSession>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Receive-PSSession
       [-Id] <Int32>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Receive-PSSession
       [-ComputerName] <String>
       [-ApplicationName <String>]
       [-ConfigurationName <String>]
       -Name <String>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-Port <Int32>]
       [-UseSSL]
       [-SessionOption <PSSessionOption>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Receive-PSSession
       [-ComputerName] <String>
       [-ApplicationName <String>]
       [-ConfigurationName <String>]
       -InstanceId <Guid>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-Port <Int32>]
       [-UseSSL]
       [-SessionOption <PSSessionOption>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Receive-PSSession
       [-ConfigurationName <String>]
       [-ConnectionUri] <Uri>
       [-AllowRedirection]
       -Name <String>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-SessionOption <PSSessionOption>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Receive-PSSession
       [-ConfigurationName <String>]
       [-ConnectionUri] <Uri>
       [-AllowRedirection]
       -InstanceId <Guid>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-SessionOption <PSSessionOption>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Receive-PSSession
       [-InstanceId] <Guid>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Receive-PSSession
       [-Name] <String>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Description

O Receive-PSSession cmdlet obtém os resultados dos comandos em execução nas sessões do PowerShell (PSSession) que foram desconectadas. Se a sessão estiver conectada no momento, Receive-PSSession obterá os resultados dos comandos que estavam em execução quando a sessão foi desconectada. Se a sessão ainda estiver desconectada, Receive-PSSession conecta-se à sessão, retoma todos os comandos que foram suspensos e obtém os resultados dos comandos em execução na sessão.

Esse cmdlet foi introduzido no PowerShell 3.0.

Você pode usar um Receive-PSSession além ou em vez de um Connect-PSSession comando. Receive-PSSession pode se conectar a qualquer sessão desconectada ou reconectada que tenha sido iniciada em outras sessões ou em outros computadores.

Receive-PSSession funciona em PSSessions que foram desconectados intencionalmente usando o Disconnect-PSSession cmdlet ou o Invoke-Command parâmetro InDisconnectedSession . Ou desconectado involuntariamente por uma interrupção de rede.

Se você usar o Receive-PSSession cmdlet para se conectar a uma sessão na qual nenhum comando está em execução ou suspenso, Receive-PSSession ele se conectará à sessão, mas não retornará nenhuma saída ou erros.

Para obter mais informações sobre o recurso Sessões desconectadas, consulte about_Remote_Disconnected_Sessions.

Alguns exemplos usam splatting para reduzir o comprimento da linha e melhorar a legibilidade. Para obter mais informações, consulte about_Splatting.

Exemplos

Exemplo 1: Conectar-se a um PSSession

Este exemplo se conecta a uma sessão em um computador remoto e obtém os resultados dos comandos que estão sendo executados em uma sessão.

Receive-PSSession -ComputerName Server01 -Name ITTask

O Receive-PSSession especifica o computador remoto com o parâmetro ComputerName . O parâmetro Name identifica a sessão ITTask no computador Server01. O exemplo obtém os resultados dos comandos que estavam em execução na sessão ITTask.

Como o comando não usa o parâmetro OutTarget , os resultados aparecem na linha de comando.

Exemplo 2: Obter resultados de todos os comandos em sessões desconectadas

Este exemplo obtém os resultados de todos os comandos em execução em todas as sessões desconectadas em dois computadores remotos.

Se alguma sessão não foi desconectada ou não está executando comandos, Receive-PSSession não se conecta à sessão e não retorna nenhuma saída ou erros.

Get-PSSession -ComputerName Server01, Server02 | Receive-PSSession

Get-PSSession usa o parâmetro ComputerName para especificar os computadores remotos. Os objetos são enviados pelo pipeline para Receive-PSSession.

Exemplo 3: Obter os resultados de um script em execução em uma sessão

Este exemplo usa o Receive-PSSession cmdlet para obter os resultados de um script que estava sendo executado na sessão de um computador remoto.

$parms = @{
  ComputerName = "Server01"
  Name = "ITTask"
  OutTarget = "Job"
  JobName = "ITTaskJob01"
  Credential = "Domain01\Admin01"
}
Receive-PSSession @parms

Id     Name            State         HasMoreData     Location
--     ----            -----         -----------     --------
16     ITTaskJob01     Running       True            Server01

O comando usa os parâmetros ComputerName e Name para identificar a sessão desconectada. Ele usa o parâmetro OutTarget com um valor de Job para direcionar Receive-PSSession para retornar os resultados como um trabalho. O parâmetro JobName especifica um nome para o trabalho na sessão reconectada. O parâmetro Credential executa o Receive-PSSession comando usando as permissões de um administrador de domínio.

A saída mostra que Receive-PSSession retornou os resultados como um trabalho na sessão atual. Para obter os resultados do trabalho, use um Receive-Job comando

Exemplo 4: Obter resultados após uma interrupção de rede

Este exemplo usa o Receive-PSSession cmdlet para obter os resultados de um trabalho depois que uma interrupção de rede interrompe uma conexão de sessão. O PowerShell tenta reconectar automaticamente a sessão uma vez por segundo pelos próximos quatro minutos e abandona o esforço somente se todas as tentativas no intervalo de quatro minutos falharem.

PS> $s = New-PSSession -ComputerName Server01 -Name AD -ConfigurationName ADEndpoint
PS> $s

Id  Name   ComputerName    State        ConfigurationName     Availability
--  ----   ------------    -----        -----------------     ------------
8   AD      Server01       Opened       ADEndpoint               Available


PS> Invoke-Command -Session $s -FilePath \\Server12\Scripts\SharedScripts\New-ADResolve.ps1

Running "New-ADResolve.ps1"

# Network outage
# Restart local computer
# Network access is not re-established within 4 minutes


PS> Get-PSSession -ComputerName Server01

Id  Name   ComputerName    State          ConfigurationName      Availability
--  ----   ------------    -----          -----------------      ------------
1  Backup  Server01        Disconnected   Microsoft.PowerShell           None
8  AD      Server01        Disconnected   ADEndpoint                     None


PS> Receive-PSSession -ComputerName Server01 -Name AD -OutTarget Job -JobName AD

Job Id   Name      State         HasMoreData     Location
--       ----      -----         -----------     --------
16       ADJob     Running       True            Server01


PS> Get-PSSession -ComputerName Server01

Id  Name    ComputerName    State         ConfigurationName     Availability
--  ----    ------------    -----         -----------------     ------------
1  Backup   Server01        Disconnected  Microsoft.PowerShell          Busy
8  AD       Server01        Opened        ADEndpoint               Available

O New-PSSession cmdlet cria uma sessão no computador Server01 e salva a $s sessão na variável. A $s variável exibe que o Estado é Aberto e a Disponibilidade está Disponível. Esses valores indicam que você está conectado à sessão e pode executar comandos na sessão.

O Invoke-Command cmdlet executa um script na sessão na $s variável. O script começa a ser executado e retorna dados, mas ocorre uma interrupção de rede que interrompe a sessão. O usuário precisa sair da sessão e reiniciar o computador local.

Quando o computador é reiniciado, o usuário inicia o PowerShell e executa um Get-PSSession comando para obter sessões no computador Server01. A saída mostra que a sessão do AD ainda existe no computador Server01. O Estado indica que a sessão do AD está desconectada. O valor de Disponibilidade de Nenhum indica que a sessão não está conectada a nenhuma sessão do cliente.

O Receive-PSSession cmdlet se reconecta à sessão do AD e obtém os resultados do script executado na sessão. O comando usa o parâmetro OutTarget para solicitar os resultados em um trabalho chamado ADJob. O comando retorna um objeto de trabalho e a saída indica que o script ainda está em execução.

O Get-PSSession cmdlet é usado para verificar o estado do trabalho. A saída confirma que o Receive-PSSession cmdlet se reconectou à sessão do AD , que agora está aberta e disponível para comandos. E o script retomou a execução e está obtendo os resultados do script.

Exemplo 5: Reconectar-se a sessões desconectadas

Este exemplo usa o Receive-PSSession cmdlet para se reconectar a sessões que foram intencionalmente desconectadas e obter os resultados dos trabalhos que estavam em execução nas sessões.

PS> $parms = @{
      InDisconnectedSession = $True
      ComputerName = "Server01", "Server02", "Server30"
      FilePath = "\\Server12\Scripts\SharedScripts\Get-BugStatus.ps1"
      Name = "BugStatus"
      SessionOption = @{IdleTimeout = 86400000}
      ConfigurationName = "ITTasks"
    }
PS> Invoke-Command @parms
PS> Exit


PS> $s = Get-PSSession -ComputerName Server01, Server02, Server30 -Name BugStatus
PS> $s

Id  Name   ComputerName    State         ConfigurationName     Availability
--  ----   ------------    -----         -----------------     ------------
1  ITTask  Server01        Disconnected  ITTasks                       None
8  ITTask  Server02        Disconnected  ITTasks                       None
2  ITTask  Server30        Disconnected  ITTasks                       None


PS> $Results = Receive-PSSession -Session $s
PS> $s

Id  Name   ComputerName    State         ConfigurationName     Availability
--  ----   ------------    -----         -----------------     ------------
1  ITTask  Server01        Opened        ITTasks                  Available
8  ITTask  Server02        Opened        ITTasks                  Available
2  ITTask  Server30        Opened        ITTasks                  Available


PS> $Results

Bug Report - Domain 01
----------------------
ComputerName          BugCount          LastUpdated
--------------        ---------         ------------
Server01              121               Friday, December 30, 2011 5:03:34 PM

O Invoke-Command cmdlet executa um script em três computadores remotos. Como o script coleta e resume dados de vários bancos de dados, geralmente leva muito tempo para ser concluído. O comando usa o parâmetro InDisconnectedSession que inicia os scripts e desconecta imediatamente as sessões. O parâmetro SessionOption estende o valor IdleTimeout da sessão desconectada. As sessões desconectadas são consideradas ociosas a partir do momento em que são desconectadas. É importante definir o tempo limite ocioso por tempo suficiente para que os comandos possam ser concluídos e você possa se reconectar à sessão. Você pode definir o IdleTimeout somente ao criar o PSSession e alterá-lo somente quando você se desconectar dele. Você não pode alterar o valor IdleTimeout ao se conectar a um PSSession ou receber seus resultados. Depois de executar o comando, o usuário sai do PowerShell e fecha o computador.

No dia seguinte, o usuário retoma o Windows, inicia o PowerShell e usa Get-PSSession para obter as sessões nas quais os scripts estavam sendo executados. O comando identifica as sessões pelo nome do computador, nome da sessão e nome da configuração da sessão e salva as $s sessões na variável. O valor da $s variável é exibido e mostra que as sessões estão desconectadas, mas não estão ocupadas.

O Receive-PSSession cmdlet se conecta às sessões na $s variável e obtém seus resultados. O comando salva os resultados na $Results variável. A $s variável é exibida e mostra que as sessões estão conectadas e disponíveis para comandos.

Os resultados do $Results script na variável são exibidos no console do PowerShell. Se algum dos resultados for inesperado, o usuário poderá executar comandos nas sessões para investigar a causa raiz.

Exemplo 6: Executando um trabalho em uma sessão desconectada

Este exemplo mostra o que acontece com um trabalho que está sendo executado em uma sessão desconectada.

PS> $s = New-PSSession -ComputerName Server01 -Name Test
PS> $j = Invoke-Command -Session $s { 1..1500 | Foreach-Object {"Return $_"; sleep 30}} -AsJob
PS> $j

Id     Name           State         HasMoreData     Location
--     ----           -----         -----------     --------
16     Job1           Running       True            Server01


PS> $s | Disconnect-PSSession

Id Name   ComputerName    State         ConfigurationName     Availability
-- ----   ------------    -----         -----------------     ------------
1  Test   Server01        Disconnected  Microsoft.PowerShell          None


PS> $j

Id     Name           State         HasMoreData     Location
--     ----           -----         -----------     --------
16     Job1           Disconnected  True            Server01


PS> Receive-Job $j -Keep

Return 1
Return 2


PS> $s2 = Connect-PSSession -ComputerName Server01 -Name Test
PS> $j2 = Receive-PSSession -ComputerName Server01 -Name Test
PS> Receive-Job $j

Return 3
Return 4

O New-PSSession cmdlet cria a sessão de teste no computador Server01. O comando salva a sessão na variável $s.

O Invoke-Command cmdlet executa um comando na sessão na $s variável. O comando usa o parâmetro AsJob para executar o comando como um trabalho e cria o objeto de trabalho na sessão atual. O comando retorna um objeto de trabalho salvo na $j variável. A $j variável exibe o objeto de trabalho.

O objeto de sessão na $s variável é enviado pelo pipeline e Disconnect-PSSession a sessão é desconectada.

A $j variável é exibida e mostra o efeito de desconectar o objeto de trabalho na $j variável. O estado do trabalho agora é Desconectado.

O Receive-Job é executado no trabalho na $j variável. A saída mostra que o trabalho começou a retornar a saída antes da sessão e o trabalho foi desconectado.

O Connect-PSSession cmdlet é executado na mesma sessão do cliente. O comando se reconecta à sessão de teste no computador Server01 e salva a $s2 sessão na variável.

O Receive-PSSession cmdlet obtém os resultados do trabalho que estava sendo executado na sessão. Como o comando é executado na mesma sessão, Receive-PSSession retorna os resultados como um trabalho por padrão e reutiliza o mesmo objeto de trabalho. O comando salva o $j2 trabalho na variável. O Receive-Job cmdlet obtém os resultados do trabalho na $j variável.

Parâmetros

-AllowRedirection

Indica que esse cmdlet permite o redirecionamento dessa conexão para um URI (Uniform Resource Identifier) alternativo.

Quando você usa o parâmetro ConnectionURI , o destino remoto pode retornar uma instrução para redirecionar para um URI diferente. Por padrão, o PowerShell não redireciona conexões, mas você pode usar esse parâmetro para habilitá-lo a redirecionar a conexão.

Você também pode limitar o número de vezes que a conexão é redirecionada alterando o valor da opção de sessão MaximumConnectionRedirectionCount . Use o parâmetro MaximumRedirection do New-PSSessionOption cmdlet ou defina a propriedade MaximumConnectionRedirectionCount da variável de $PSSessionOption preferência. O valor padrão é 5.

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

-ApplicationName

Especifica um aplicativo. Esse cmdlet se conecta apenas a sessões que usam o aplicativo especificado.

Insira o segmento de nome de aplicativo do URI de conexão. Por exemplo, no URI de conexão a seguir, WSMan é o nome do aplicativo: http://localhost:5985/WSMAN.

O nome do aplicativo de uma sessão é armazenado na propriedade Runspace.ConnectionInfo.AppName da sessão.

O valor do parâmetro é usado para selecionar e filtrar sessões. Ele não altera o aplicativo que a sessão usa.

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

-Authentication

Especifica o mecanismo usado para autenticar as credenciais do usuário no comando para se reconectar a uma sessão desconectada. Os valores aceitáveis para esse parâmetro são:

  • Padrão
  • Basic
  • Credssp
  • Digest
  • Kerberos
  • Negotiate
  • NegotiateWithImplicitCredential

O valor padrão é Default.

Para obter mais informações sobre os valores desse parâmetro, consulte Enumeração AuthenticationMechanism.

Cuidado

A autenticação do Provedor de Suporte à Segurança de Credenciais (CredSSP), na qual as credenciais do usuário são passadas para um computador remoto a ser autenticado, foi projetada para comandos que exigem autenticação em mais de um recurso, como acessar um compartilhamento de rede remoto. Esse mecanismo aumenta o risco de segurança da operação remota. Se o computador remoto estiver comprometido, as credenciais que são passadas a ele podem ser usadas para controlar a sessão de rede.

Tipo:AuthenticationMechanism
Valores aceitos:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Cargo:Named
Valor padrão:Default
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-CertificateThumbprint

Especifica o certificado de chave pública digital (X509) de uma conta de usuário com permissão para se conectar à sessão desconectada. Insira a impressão digital do certificado.

Os certificados são utilizados na autenticação baseada em certificado do cliente. Os certificados podem ser mapeados apenas para contas de usuário locais e não funcionam com contas de domínio.

Para obter uma impressão digital do certificado, use um Get-Item comando ou Get-ChildItem na unidade do PowerShell Cert: .

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

-ComputerName

Especifica o computador no qual a sessão desconectada está armazenada. As sessões são armazenadas no computador que está no lado do servidor ou na extremidade de recebimento de uma conexão. O padrão é o computador local.

Digite o nome NetBIOS, um endereço IP ou um FQDN (nome de domínio totalmente qualificado) de um computador. Caracteres curinga não são permitidos. Para especificar o computador local, digite o nome do computador, um ponto (.), $env:COMPUTERNAMEou localhost.

Tipo:String
Aliases:Cn
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-ConfigurationName

Especifica o nome de uma configuração de sessão. Esse cmdlet se conecta apenas a sessões que usam a configuração de sessão especificada.

Insira um nome de configuração ou o URI do recurso totalmente qualificado para uma configuração de sessão. Se você especificar apenas o nome da configuração, o seguinte URI de esquema será anexado:

http://schemas.microsoft.com/powershell.

O nome da configuração de uma sessão é armazenado na propriedade ConfigurationName da sessão.

O valor do parâmetro é usado para selecionar e filtrar sessões. Ele não altera a configuração da sessão que a sessão usa.

Para saber mais sobre configurações de sessão, confira about_Session_Configurations.

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

-Confirm

Solicita sua confirmação antes de executar o cmdlet.

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

-ConnectionUri

Especifica um URI que define o ponto de extremidade de conexão usado para se reconectar à sessão desconectada.

O URI deve ser totalmente qualificado. O formato da cadeia de caracteres é o seguinte:

<Transport>://<ComputerName>:<Port>/<ApplicationName>

O valor padrão é o seguinte:

http://localhost:5985/WSMAN

Se você não especificar um URI de conexão, poderá usar os parâmetros UseSSL, ComputerName, Port e ApplicationName para especificar os valores de URI de conexão.

Os valores válidos para o segmento Transport do URI são HTTP e HTTPS. Se você especificar um URI de conexão com um segmento de transporte, mas não especificar uma porta, a sessão será criada com portas padrão: 80 para HTTP e 443 para HTTPS. Para usar as portas padrão para comunicação remota do PowerShell, especifique a porta 5985 para HTTP ou 5986 para HTTPS.

Se o computador de destino redirecionar a conexão para um URI diferente, o PowerShell impedirá o redirecionamento, a menos que você use o parâmetro AllowRedirection no comando.

Tipo:Uri
Aliases:URI, CU
Cargo:0
Valor padrão:http://localhost:5985/WSMAN
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-Credential

Especifica uma conta de usuário que tem permissão para se conectar à sessão desconectada. O padrão é o usuário atual.

Digite um nome de usuário, como User01 ou Domain01\User01, ou insira um objeto PSCredential gerado pelo Get-Credential cmdlet. Se você digitar um nome de usuário, será solicitado que você insira a senha.

As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como um SecureString.

Observação

Para obter mais informações sobre a proteção de dados do SecureString , consulte Quão seguro é o SecureString?.

Tipo:PSCredential
Cargo:Named
Valor padrão:Current user
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Id

Especifica o ID de uma sessão desconectada. O parâmetro Id funciona somente quando a sessão desconectada foi conectada anteriormente à sessão atual.

Esse parâmetro é válido, mas não efetivo, quando a sessão é armazenada no computador local, mas não está conectada à sessão atual.

Tipo:Int32
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-InstanceId

Especifica a ID da instância da sessão desconectada. A ID da instância é um GUID que identifica exclusivamente um PSSession em um computador local ou remoto. A ID da instância é armazenada na propriedade InstanceID do PSSession.

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

-JobName

Especifica um nome amigável para o trabalho que Receive-PSSession retorna.

Receive-PSSession retorna um trabalho quando o valor do parâmetro OutTarget é Trabalho ou o trabalho que está sendo executado na sessão desconectada foi iniciado na sessão atual.

Se o trabalho que está sendo executado na sessão desconectada tiver sido iniciado na sessão atual, o PowerShell reutilizará o objeto de trabalho original na sessão e ignorará o valor do parâmetro JobName .

Se o trabalho em execução na sessão desconectada tiver sido iniciado em uma sessão diferente, o PowerShell criará um novo objeto de trabalho. Ele usa um nome padrão, mas você pode usar este parâmetro para alterar o nome.

Se o valor padrão ou explícito do parâmetro OutTarget não for Job, o comando será bem-sucedido, mas o parâmetro JobName não terá efeito.

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

-Name

Especifica o nome amigável da sessão desconectada.

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

-OutTarget

Determina como os resultados da sessão são retornados. Os valores aceitáveis para esse parâmetro são:

  • Trabalho. Retorna os resultados de forma assíncrona em um objeto de trabalho. Você pode usar o parâmetro JobName para especificar um nome ou um novo nome para o trabalho.
  • Anfitrião. Retorna os resultados para a linha de comando (de forma síncrona). Se o comando estiver sendo retomado ou os resultados consistirem de um grande número de objetos, a resposta poderá demorar.

O valor padrão do parâmetro OutTarget é Host. Se o comando que está sendo recebido em uma sessão desconectada foi iniciado na sessão atual, o valor padrão do parâmetro OutTarget será o formulário no qual o comando foi iniciado. Se o comando foi iniciado como um trabalho, por padrão, ele será retornado como um trabalho. Caso contrário, ele será retornado ao programa host por padrão.

Normalmente, o programa do host exibe objetos retornados na linha de comando sem atraso, mas esse comportamento pode variar.

Tipo:OutTarget
Valores aceitos:Default, Host, Job
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Port

Especifica a porta de rede do computador remoto usada para se reconectar à sessão. Para se conectar a um computador remoto, ele deve estar escutando na porta que a conexão usa. As portas padrão são 5985, que é a porta WinRM para HTTP, e 5986, que é a porta WinRM para HTTPS.

Antes de usar uma porta alternativa, você deve configurar o ouvinte do WinRM no computador remoto para escutar nessa porta. Para configurar o ouvinte, digite os dois comandos a seguir no prompt do PowerShell:

Remove-Item -Path WSMan:\Localhost\listener\listener* -Recurse

New-Item -Path WSMan:\Localhost\listener -Transport http -Address * -Port \<port-number\>

Não use o parâmetro Port , a menos que seja necessário. A porta definida no comando se aplica a todos os computadores ou sessões nos quais o comando é executado. Uma configuração de porta alternativa pode impedir que o comando seja executado em todos os computadores.

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

-Session

Especifica a sessão desconectada. Insira uma variável que contenha o PSSession ou um comando que crie ou obtenha o PSSession, como um Get-PSSession comando.

Tipo:PSSession
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-SessionOption

Especifica opções avançadas para a sessão. Insira um objeto SessionOption , como um que você cria usando o New-PSSessionOption cmdlet, ou uma tabela de hash na qual as chaves são nomes de opção de sessão e os valores são valores de opção de sessão.

Os valores padrão para as opções são determinados pelo valor da variável de $PSSessionOption preferência, se ela estiver definida. Caso contrário, os valores padrão são estabelecidos por opções definidas na configuração da sessão.

Os valores de opção de sessão têm precedência sobre os valores padrão para sessões definidas na $PSSessionOption variável de preferência e na configuração da sessão. No entanto, eles não têm precedência sobre os valores máximos, cotas ou limites definidos na configuração da sessão.

Para obter uma descrição das opções de sessão que inclui os valores padrão, consulte New-PSSessionOption. Para obter informações sobre a variável de preferência $PSSessionOption, consulte about_Preference_Variables. Para saber mais sobre configurações de sessão, confira about_Session_Configurations.

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

-UseSSL

Indica que esse cmdlet usa o protocolo SSL (Secure Sockets Layer) para se conectar à sessão desconectada. Por padrão, o SSL não é usado.

O WS-Management criptografa todo o conteúdo do PowerShell transmitido pela rede. UseSSL é uma proteção adicional que envia os dados por uma conexão HTTPS em vez de uma conexão HTTP.

Se você usar esse parâmetro e o SSL não estiver disponível na porta usada para o comando, o comando falhará.

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

-WhatIf

Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.

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

Entradas

PSSession

Você pode canalizar objetos de sessão para esse cmdlet, como objetos retornados pelo Get-PSSession cmdlet.

Int32

Você pode canalizar IDs de sessão para esse cmdlet.

Guid

Você pode canalizar as IDs de instância de sessões deste cmdlet.

String

Você pode canalizar nomes de sessão para esse cmdlet.

Saídas

Job

Se o valor ou o valor padrão do parâmetro OutTarget for Job, Receive-PSSession retornará um objeto de trabalho.

PSObject

Esse cmdlet retorna os resultados dos comandos executados na sessão desconectada, se houver.

Observações

O Windows PowerShell inclui os seguintes aliases para Receive-PSSession:

  • rcsn

Receive-PSSession Obtém resultados somente de sessões que foram desconectadas. Somente as sessões conectadas ou encerradas em computadores que executam o PowerShell 3.0 ou versões posteriores podem ser desconectadas e reconectadas.

Se os comandos que estavam em execução na sessão desconectada não geraram resultados ou se os resultados já foram retornados para outra sessão, Receive-PSSession não gera nenhuma saída.

O modo de buffer de saída de uma sessão determina como os comandos na sessão gerenciam a saída quando a sessão é desconectada. Quando o valor da opção OutputBufferingMode da sessão for Drop e o buffer de saída estiver cheio, o comando começará a excluir a saída. Receive-PSSession não é possível recuperar essa saída. Para obter mais informações sobre a opção de modo de buffer de saída, consulte os artigos de ajuda para os cmdlets New-PSSessionOption e New-PSTransportOption .

Você não pode alterar o valor de tempo limite ocioso de um PSSession quando você se conecta ao PSSession ou recebe resultados. O parâmetro SessionOption usa Receive-PSSession um objeto SessionOption que tem um valor IdleTimeout . No entanto, o valor IdleTimeout do objeto SessionOption e o valor IdleTimeout da variável são ignorados $PSSessionOption quando ela se conecta a um PSSession ou recebe resultados.

  • Você pode definir e alterar o tempo limite ocioso de um PSSession ao criar o PSSession, usando os New-PSSession cmdlets or Invoke-Command e ao se desconectar do PSSession.
  • A propriedade IdleTimeout de um PSSession é crítica para sessões desconectadas porque determina por quanto tempo uma sessão desconectada é mantida no computador remoto. Sessões desconectadas são consideradas ociosas desde o momento em que são desconectadas, ainda que comandos estejam em execução na sessão desconectada.

Se você iniciar um trabalho em uma sessão remota usando o parâmetro AsJob do cmdlet, o objeto de Invoke-Command trabalho será criado na sessão atual, mesmo que o trabalho seja executado na sessão remota. Se você desconectar a sessão remota, o objeto de trabalho na sessão atual será desconectado do trabalho. O objeto de trabalho contém todos os resultados que foram retornados a ele, mas não recebe novos resultados do trabalho na sessão desconectada.

Se um cliente diferente se conectar à sessão que contém o trabalho em execução, os resultados que foram entregues ao objeto de trabalho original na sessão original não estarão disponíveis na sessão recém-conectada. Somente resultados que não foram fornecidos ao objeto de trabalho original ficam disponíveis na sessão reconectada.

Da mesma forma, se você iniciar um script em uma sessão e depois se desconectar da sessão, todos os resultados que o script entregar à sessão antes de se desconectar não estarão disponíveis para outro cliente que se conecta à sessão.

Para evitar a perda de dados em sessões que você pretende desconectar, use o Invoke-Command parâmetro InDisconnectedSession do cmdlet. Como esse parâmetro impede que resultados sejam retornados à sessão atual, todos os resultados ficam disponíveis quando a sessão é reconectada.

Você também pode evitar a perda de dados usando o Invoke-Command cmdlet para executar um Start-Job comando na sessão remota. Nesse caso, o objeto de trabalho é criado na sessão remota. Você não pode usar o Receive-PSSession cmdlet para obter os resultados do trabalho. Em vez disso, use o Connect-PSSession cmdlet para se conectar à sessão e, em seguida, use o Invoke-Command cmdlet para executar um Receive-Job comando na sessão.

Quando uma sessão que contém um trabalho em execução é desconectada e, em seguida, reconectada, o objeto de trabalho original é reutilizado somente se o trabalho for desconectado e reconectado à mesma sessão e o comando para reconectar não especificar um novo nome de trabalho. Se a sessão for reconectada a uma sessão de cliente diferente ou um novo nome de trabalho for especificado, o PowerShell criará um novo objeto de trabalho para a nova sessão.

Quando você desconecta um PSSession, o estado da sessão é Desconectado e a disponibilidade é Nenhum.

  • O valor da propriedade State é relativo à sessão atual. Um valor de Disconnected significa que o PSSession não está conectado à sessão atual. No entanto, isso não significa que o PSSession esteja desconectado de todas as sessões . Ela pode ser conectada a uma sessão diferente. Para determinar se você pode se conectar ou reconectar à sessão, use a propriedade Disponibilidade .
  • Um valor de Disponibilidade de Nenhum indica que você pode se conectar à sessão. Um valor de Ocupado indica que você não pode se conectar ao PSSession porque ele está conectado a outra sessão.
  • Para obter mais informações sobre os valores da propriedade State das sessões, consulte RunspaceState.
  • Para obter mais informações sobre os valores da propriedade Availability das sessões, consulte RunspaceAvailability.