Receive-PSSession

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>
    -Name <String>
    [-ApplicationName <String>]
    [-ConfigurationName <String>]
    [-OutTarget <OutTarget>]
    [-JobName <String>]
    [-Credential <PSCredential>]
    [-Authentication <AuthenticationMechanism>]
    [-CertificateThumbprint <String>]
    [-Port <Int32>]
    [-UseSSL]
    [-SessionOption <PSSessionOption>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

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

Receive-PSSession
    [-ConnectionUri] <Uri>
    -Name <String>
    [-ConfigurationName <String>]
    [-AllowRedirection]
    [-OutTarget <OutTarget>]
    [-JobName <String>]
    [-Credential <PSCredential>]
    [-Authentication <AuthenticationMechanism>]
    [-CertificateThumbprint <String>]
    [-SessionOption <PSSessionOption>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Receive-PSSession
    [-ConnectionUri] <Uri>
    -InstanceId <Guid>
    [-ConfigurationName <String>]
    [-AllowRedirection]
    [-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>]

Este cmdlet só está disponível na plataforma Windows.

O cmdlet Receive-PSSession obtém os resultados dos comandos executados em sessões do PowerShell (PSSession) que foram desconectados. 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 se conecta à sessão, retoma todos os comandos que foram suspensos e obtém os resultados dos comandos em execução na sessão.

Este cmdlet foi introduzido no PowerShell 3.0.

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

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

Se você usar o cmdlet Receive-PSSession para se conectar a uma sessão na qual nenhum comando está em execução ou suspenso, Receive-PSSession se conecta à sessão, mas não retorna 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.

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 sendo executados na sessão ITTask.

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

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

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

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

Este exemplo usa o cmdlet Receive-PSSession 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 comando Receive-PSSession usando as permissões de um administrador de domínio.

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

Este exemplo usa o cmdlet Receive-PSSession 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 durante os 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 cmdlet New-PSSession cria uma sessão no computador Server01 e salva a sessão na variável $s. A variável $s exibe que o Estado está Aberto e a Disponibilidade está Disponível. Esses valores indicam que você está conectado à sessão e pode executar comandos na sessão.

O cmdlet Invoke-Command executa um script na sessão na variável $s. 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 tem que sair da sessão e reiniciar o computador local.

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

O cmdlet Receive-PSSession 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 cmdlet Get-PSSession é usado para verificar o estado do trabalho. A saída confirma que o cmdlet Receive-PSSession 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.

Este exemplo usa o cmdlet Receive-PSSession para se reconectar a sessões que foram intencionalmente desconectadas e obter os resultados de trabalhos que estavam sendo executados 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 cmdlet Invoke-Command executa um script em três computadores remotos. Como o script reúne e resume dados de vários bancos de dados, geralmente leva um tempo estendido para ser concluído. O comando usa o parâmetro InDisconnectedSession que inicia os scripts e, em seguida, desconecta imediatamente as sessões. O parâmetro SessionOption prolonga o tempo de inatividade 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 apenas quando criar o PSSession e mudá-lo apenas quando se desconectar dele. Não é possível alterar o valor de IdleTimeout ao se conectar a uma PSSession ou ao receber os 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 o nome da configuração da sessão e salva as sessões na variável $s. O valor da variável $s é exibido e mostra que as sessões estão desconectadas, mas não estão ocupadas.

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

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

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 cmdlet New-PSSession cria a sessão Test no computador Server01. O comando salva a sessão na variável $s.

O cmdlet Invoke-Command executa um comando na sessão na variável $s. 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 variável $j. A variável $j exibe o objeto de trabalho.

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

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

O Receive-Job é executado durante o trabalho na variável $j. A saída mostra que o trabalho começou a retornar resultados antes de a sessão e o trabalho serem desconectados.

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

O cmdlet Receive-PSSession 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 guarda o trabalho na variável $j2. O cmdlet Receive-Job obtém os resultados do trabalho na variável $j.

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

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

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

Você pode canalizar os Ids de instância das sessões deste cmdlet.

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

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

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

O PowerShell inclui os seguintes aliases para Receive-PSSession:

• Todas as plataformas:
  • rcsn

Este cmdlet só está disponível em plataformas Windows.

Receive-PSSession obtém resultados apenas de sessões que foram desconectadas. Somente 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 sendo executados 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 é Drop e o buffer de saída está cheio, o comando começa a excluir a saída. Receive-PSSession não consegue recuperar esta saída. Para obter mais informações sobre a opção de modo de buffer de saída, consulte os artigos de ajuda dos cmdlets New-PSSessionOption e New-PSTransportOption.

Não é possível alterar o valor do tempo limite de inatividade de uma PSSession quando se liga à PSSession ou recebe resultados. O parâmetro SessionOption de Receive-PSSession recebe um objeto SessionOption que contém um valor de IdleTimeout. No entanto, o valor de IdleTimeout do objeto SessionOption e o valor IdleTimeout da variável $PSSessionOption são ignorados quando ele se conecta a um PSSession ou recebendo resultados.

• Você pode definir e alterar o tempo limite ocioso de um PSSession ao criar o PSSession, usando os cmdlets New-PSSession ou 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. As sessões desconectadas são consideradas ociosas a partir do momento em que são desconectadas, mesmo que os 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 Invoke-Command, o objeto de 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 os resultados que não foram entregues ao objeto de trabalho original estão disponíveis na sessão reconectada.

Da mesma forma, se você iniciar um script em uma sessão e, em seguida, 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 parâmetro InDisconnectedSession do cmdlet Invoke-Command. Como esse parâmetro impede que os 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 cmdlet Invoke-Command para executar um comando Start-Job na sessão remota. Nesse caso, o objeto de trabalho é criado na sessão remota. Não é possível usar o cmdlet Receive-PSSession para obter os resultados do trabalho. Em vez disso, use o cmdlet Connect-PSSession para se conectar à sessão e, em seguida, use o cmdlet Invoke-Command para executar um comando Receive-Job 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 é Nenhuma.

• O valor da propriedade State depende da sessão atual. Um valor de Desconectado 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. Pode estar conectado a uma sessão diferente. Para determinar se pode conectar-se ou reconectar-se à sessão, use a propriedade Disponibilidade.
• Um valor de Disponibilidade Nenhum indica que pode se conectar à sessão. Um valor de Ocupado indica que não é possível conectar-se à PSSession porque já está ligada a outra sessão.
• Para obter mais informações sobre os valores da propriedade State de sessões, consulte RunspaceState.
• Para mais informações sobre os valores da propriedade Availability das sessões, consulte RunspaceAvailability.