Receive-PSSession

Syntax

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

This cmdlet is only available on the Windows platform.

The Receive-PSSession cmdlet gets the results of commands running in PowerShell sessions (PSSession) that were disconnected. If the session is currently connected, Receive-PSSession gets the results of commands that were running when the session was disconnected. If the session is still disconnected, Receive-PSSession connects to the session, resumes any commands that were suspended, and gets the results of commands running in the session.

This cmdlet was introduced in PowerShell 3.0.

You can use a Receive-PSSession in addition to or instead of a Connect-PSSession command. Receive-PSSession can connect to any disconnected or reconnected session that was started in other sessions or on other computers.

Receive-PSSession works on PSSessions that were disconnected intentionally using the Disconnect-PSSession cmdlet or the Invoke-Command InDisconnectedSession parameter. Or disconnected unintentionally by a network interruption.

If you use the Receive-PSSession cmdlet to connect to a session in which no commands are running or suspended, Receive-PSSession connects to the session, but returns no output or errors.

For more information about the Disconnected Sessions feature, see about_Remote_Disconnected_Sessions.

Some examples use splatting to reduce the line length and improve readability. For more information, see about_Splatting.

Examples

Example 1: Connect to a PSSession

This example connects to a session on a remote computer and gets the results of commands that are running in a session.

Receive-PSSession -ComputerName Server01 -Name ITTask

The Receive-PSSession specifies the remote computer with the ComputerName parameter. The Name parameter identifies the ITTask session on the Server01 computer. The example gets the results of commands that were running in the ITTask session.

Because the command doesn't use the OutTarget parameter, the results appear on the command line.

Example 2: Get results of all commands on disconnected sessions

This example gets the results of all commands running in all disconnected sessions on two remote computers.

If any session wasn't disconnected or isn't running commands, Receive-PSSession doesn't connect to the session and doesn't return any output or errors.

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

Get-PSSession uses the ComputerName parameter to specify the remote computers. The objects are sent down the pipeline to Receive-PSSession.

Example 3: Get the results of a script running in a session

This example uses the Receive-PSSession cmdlet to get the results of a script that was running in a remote computer's session.

$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

The command uses the ComputerName and Name parameters to identify the disconnected session. It uses the OutTarget parameter with a value of Job to direct Receive-PSSession to return the results as a job. The JobName parameter specifies a name for the job in the reconnected session. The Credential parameter runs the Receive-PSSession command using the permissions of a domain administrator.

The output shows that Receive-PSSession returned the results as a job in the current session. To get the job results, use a Receive-Job command

Example 4: Get results after a network outage

This example uses the Receive-PSSession cmdlet to get the results of a job after a network outage disrupts a session connection. PowerShell automatically attempts to reconnect the session once per second for the next four minutes and abandons the effort only if all attempts in the four-minute interval fail.

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

The New-PSSession cmdlet creates a session on the Server01 computer and saves the session in the $s variable. The $s variable displays that the State is Opened and the Availability is Available. These values indicate that you're connected to the session and can run commands in the session.

The Invoke-Command cmdlet runs a script in the session in the $s variable. The script begins to run and return data, but a network outage occurs that interrupts the session. The user has to exit the session and restart the local computer.

When the computer restarts, the user starts PowerShell and runs a Get-PSSession command to get sessions on the Server01 computer. The output shows that the AD session still exists on the Server01 computer. The State indicates that the AD session is disconnected. The Availability value of None, indicates that the session isn't connected to any client sessions.

The Receive-PSSession cmdlet reconnects to the AD session and gets the results of the script that ran in the session. The command uses the OutTarget parameter to request the results in a job named ADJob. The command returns a job object and the output indicates that the script is still running.

The Get-PSSession cmdlet is used to check the job state. The output confirms that the Receive-PSSession cmdlet reconnected to the AD session, which is now open and available for commands. And, the script resumed execution and is getting the script results.

Example 5: Reconnect to disconnected sessions

This example uses the Receive-PSSession cmdlet to reconnect to sessions that were intentionally disconnected and get the results of jobs that were running in the sessions.

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

The Invoke-Command cmdlet runs a script on three remote computers. Because the script gathers and summarizes data from multiple databases, it often takes the script an extended time to finish. The command uses the InDisconnectedSession parameter that starts the scripts and then immediately disconnects the sessions. The SessionOption parameter extends the IdleTimeout value of the disconnected session. Disconnected sessions are considered idle from the moment they're disconnected. It's important to set the idle time-out for long enough so that the commands can complete and you can reconnect to the session. You can set the IdleTimeout only when you create the PSSession and change it only when you disconnect from it. You can't change the IdleTimeout value when you connect to a PSSession or receiving its results. After running the command, the user exits PowerShell and closes the computer.

The next day, the user resumes Windows, starts PowerShell, and uses Get-PSSession to get the sessions in which the scripts were running. The command identifies the sessions by the computer name, session name, and the name of the session configuration and saves the sessions in the $s variable. The value of the $s variable is displayed and shows that the sessions are disconnected, but aren't busy.

The Receive-PSSession cmdlet connects to the sessions in the $s variable and gets their results. The command saves the results in the $Results variable. The $s variable is displayed and shows that the sessions are connected and available for commands.

The script results in the $Results variable are displayed in the PowerShell console. If any of the results are unexpected, the user can run commands in the sessions to investigate the root cause.

Example 6: Running a job in a disconnected session

This example shows what happens to a job that's running in a disconnected session.

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

The New-PSSession cmdlet creates the Test session on the Server01 computer. The command saves the session in the $s variable.

The Invoke-Command cmdlet runs a command in the session in the $s variable. The command uses the AsJob parameter to run the command as a job and creates the job object in the current session. The command returns a job object that's saved in the $j variable. The $j variable displays the job object.

The session object in the $s variable is sent down the pipeline to Disconnect-PSSession and the session is disconnected.

The $j variable is displayed and shows the effect of disconnecting the job object in the $j variable. The job state is now Disconnected.

The Receive-Job is run on the job in the $j variable. The output shows that the job began to return output before the session and the job were disconnected.

The Connect-PSSession cmdlet is run in the same client session. The command reconnects to the Test session on the Server01 computer and saves the session in the $s2 variable.

The Receive-PSSession cmdlet gets the results of the job that was running in the session. Because the command is run in the same session, Receive-PSSession returns the results as a job by default and reuses the same job object. The command saves the job in the $j2 variable. The Receive-Job cmdlet gets the results of the job in the $j variable.

Parameters

-AllowRedirection

-ApplicationName

-Authentication

-CertificateThumbprint

-ComputerName

-ConfigurationName

-Confirm

-ConnectionUri

-Credential

-Id

-InstanceId

-JobName

-Name

-OutTarget

-Port

-Session

-SessionOption

-UseSSL

-WhatIf

Inputs

PSSession

You can pipe session objects to this cmdlet, such as objects returned by the Get-PSSession cmdlet.

Int32

You can pipe session Ids to this cmdlet.

Guid

You can pipe the instance Ids of sessions this cmdlet.

String

You can pipe session names to this cmdlet.

Outputs

System.Management.Automation.Job or PSObject

This cmdlet returns the results of commands that ran in the disconnected session, if any. If the value or default value of the OutTarget parameter is Job, Receive-PSSession returns a job object. Otherwise, it returns objects that represent that command results.

Notes

This cmdlet is only available on Windows platforms.

Receive-PSSession gets results only from sessions that were disconnected. Only sessions that are connected to, or terminate at, computers that run PowerShell 3.0 or later versions can be disconnected and reconnected.

If the commands that were running in the disconnected session didn't generate results or if the results were already returned to another session, Receive-PSSession doesn't generate any output.

A session's output buffering mode determines how commands in the session manage output when the session is disconnected. When the value of the OutputBufferingMode option of the session is Drop and the output buffer is full, the command starts to delete output. Receive-PSSession can't recover this output. For more information about the output buffering mode option, see the help articles for the New-PSSessionOption and New-PSTransportOption cmdlets.

You can't change the idle time-out value of a PSSession when you connect to the PSSession or receive results. The SessionOption parameter of Receive-PSSession takes a SessionOption object that has an IdleTimeout value. However, the IdleTimeout value of the SessionOption object and the IdleTimeout value of the $PSSessionOption variable are ignored when it connects to a PSSession or receiving results.

• You can set and change the idle time-out of a PSSession when you create the PSSession, by using the New-PSSession or Invoke-Command cmdlets, and when you disconnect from the PSSession.
• The IdleTimeout property of a PSSession is critical to disconnected sessions because it determines how long a disconnected session is maintained on the remote computer. Disconnected sessions are considered to be idle from the moment that they are disconnected, even if commands are running in the disconnected session.

If you start a start a job in a remote session by using the AsJob parameter of the Invoke-Command cmdlet, the job object is created in the current session, even though the job runs in the remote session. If you disconnect the remote session, the job object in the current session is disconnected from the job. The job object contains any results that were returned to it, but doesn't receive new results from the job in the disconnected session.

If a different client connects to the session that contains the running job, the results that were delivered to the original job object in the original session aren't available in the newly connected session. Only results that were not delivered to the original job object are available in the reconnected session.

Similarly, if you start a script in a session and then disconnect from the session, any results that the script delivers to the session before disconnecting aren't available to another client that connects to the session.

To prevent data loss in sessions that you intend to disconnect, use the InDisconnectedSession parameter of the Invoke-Command cmdlet. Because this parameter prevents results from being returned to the current session, all results are available when the session is reconnected.

You can also prevent data loss by using the Invoke-Command cmdlet to run a Start-Job command in the remote session. In this case, the job object is created in the remote session. You can't use the Receive-PSSession cmdlet to get the job results. Instead, use the Connect-PSSession cmdlet to connect to the session and then use the Invoke-Command cmdlet to run a Receive-Job command in the session.

When a session that contains a running job is disconnected and then reconnected, the original job object is reused only if the job is disconnected and reconnected to the same session, and the command to reconnect doesn't specify a new job name. If the session is reconnected to a different client session or a new job name is specified, PowerShell creates a new job object for the new session.

When you disconnect a PSSession, the session state is Disconnected and the availability is None.

• The value of the State property is relative to the current session. A value of Disconnected means that the PSSession isn't connected to the current session. However, it doesn't mean that the PSSession is disconnected from all sessions. It might be connected to a different session. To determine whether you can connect or reconnect to the session, use the Availability property.
• An Availability value of None indicates that you can connect to the session. A value of Busy indicates that you can't connect to the PSSession because it's connected to another session.
• For more information about the values of the State property of sessions, see RunspaceState.
• For more information about the values of the Availability property of sessions, see RunspaceAvailability.

Related Links

• about_PSSessions
• about_Remote
• about_Remote_Disconnected_Sessions
• about_Session_Configurations
• Connect-PSSession
• Enter-PSSession
• Exit-PSSession
• Get-PSSession
• Invoke-Command
• New-PSSession
• New-PSSessionOption
• New-PSTransportOption
• Remove-PSSession