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]
       -InstanceId <Guid>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-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
       -InstanceId <Guid>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Receive-PSSession
       -Name <String>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Description

The Receive-PSSession cmdlet gets the results of commands running in Windows 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.

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. These include those that were started in other sessions or on other computers.

Receive-PSSession works on PSSessions that were disconnected intentionally, such as by using the Disconnect-PSSession cmdlet or the InDisconnectedSession parameter of the Invoke-Command cmdlet, or unintentionally, such as 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.

This cmdlet was introduced in Windows PowerShell 3.0.

Examples

Example 1: Connect to a PSSession

PS C:\> Receive-PSSession -ComputerName Server01 -Name ITTask

This command uses the Receive-PSSession cmdlet to connect to the ITTask session on the Server01 computer and get the results of commands that were running in the session.

Because the command does not use the OutTarget parameter, the results appear at the command line.

Example 2: Get results of all commands on disconnected sessions

PS C:\> Get-PSSession -ComputerName Server01, Server02 | Receive-PSSession

This command gets the results of all commands running in all disconnected sessions on the Server01 and Server02 computers.

If any session was not disconnected or is not running commands, Receive-PSSession does not connect to the session and does not return any output or errors.

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

PS C:\> Receive-PSSession -ComputerName Server01 -Name ITTask -OutTarget Job -JobName ITTaskJob01 -Credential Domain01\Admin01
Id     Name            State         HasMoreData     Location
--     ----            -----         -----------     --------
16     ITTaskJob01     Running       True            Server01

This command uses the Receive-PSSession cmdlet to get the results of a script that was running in the ITTask session on the Server01 computer.

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 and the JobName parameter to specify a name for the job in the reconnected session.

The command uses the Credential parameter to run the Receive-PSSession command by 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

The first command uses the New-PSSession cmdlet to create a session on the Server01 computer. The command saves the session in the $s variable.The second command gets the session in the $s variable. Notice that the **State** is Opened and the **Availability** is Available. These values indicate that you are connected to the session and can run commands in the session.
PS C:\> $s = New-PSSession -ComputerName Server01 -Name AD -ConfigurationName ADEndpoint
PS C:\> $s

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

The third command uses the Invoke-Command cmdlet to run 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.
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

When the computer restarts, the user starts Windows 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 it is disconnected and the **Availability** value, None, indicates that it is not connected to any client sessions.
PS C:\> Get-PSSession -ComputerName Server01

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


The fifth command uses the **Receive-PSSession** cmdlet to reconnect to the AD session and get 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. The output indicates that the script is still running.
PS C:\> Receive-PSSession -ComputerName Server01 -Name AD -OutTarget Job -JobName AD
Job Id     Name      State         HasMoreData     Location
--     ----      -----         -----------     --------
16     ADJob     Running       True            Server01

The sixth command uses the Get-PSSession cmdlet to check the job state. The output confirms that, in addition to resuming script execution and getting the script results, the **Receive-PSSession** cmdlet reconnected to the AD session, which is now open and available for commands.
PS C:\> Get-PSSession -ComputerName Server01
Id Name    ComputerName    State         ConfigurationName     Availability
-- ----    ------------    -----         -----------------     ------------
 1 Backup  Server01        Disconnected  Microsoft.PowerShell          Busy
 8 AD      Server01        Opened        ADEndpoint                Available

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

Example 5: Reconnect to disconnected sessions

The first command uses the Invoke-Command cmdlet to run a script on the three remote computers. Because the scripts gathers and summarize data from multiple databases, it often takes the script an extended time to finish. The command uses the *InDisconnectedSession* parameter, which starts the scripts and then immediately disconnects the sessions.The command uses the *SessionOption* parameter to extend the **IdleTimeout** value of the disconnected session. Disconnected sessions are considered to be idle from the moment they are disconnected, so it is important to set the idle time-out for long enough that the commands can complete and you can reconnect to the session, if necessary. You can set the **IdleTimeout** only when you create the **PSSession** and change it only when you disconnect from it. You cannot change the **IdleTimeout** value when you connect to a **PSSession** or receiving its results.After running the command, the user exits Windows PowerShell and closes the computer .
PS C:\> Invoke-Command -InDisconnectedSession -ComputerName Server01, Server02, Server30 -FilePath \\Server12\Scripts\SharedScripts\Get-BugStatus.ps1 -Name BugStatus -SessionOption @{IdleTimeout = 86400000} -ConfigurationName ITTasks# Exit

# Start Windows PowerShell on a different computer.

On the next day, the user resumes Windows and starts Windows PowerShell. The second command uses the Get-PSSession cmdlet 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 third command displays the value of the $s variable. The output shows that the sessions are disconnected, but not busy, as expected.
PS C:\> $s = Get-PSSession -ComputerName Server01, Server02, Server30 -Name BugStatus
 PS C:\> $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


The fourth command uses the **Receive-PSSession** cmdlet to connect to the sessions in the $s variable and get their results. The command saves the results in the $Results variable.Another display of the $s variable shows that the sessions are connected and available for commands.
PS C:\> $Results = Receive-PSSession -Session $s
PS C:\> $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


The fifth command displays the script results in the $Results variable. If any of the results are unexpected, the user can run commands in the sessions to investigate.
PS C:\> $Results
Bug Report - Domain 01
----------------------
ComputerName          BugCount          LastUpdated
--------------        ---------         ------------
Server01              121               Friday, December 30, 2011 5:03:34 PM

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.

Example 6: Running a job in a disconnected session

The first command uses the New-PSSession cmdlet to create the Test session on the Server01 computer. The command saves the session in the $s variable.
PS C:\> $s = New-PSSession -ComputerName Server01 -Name Test

The second command uses the Invoke-Command cmdlet to run a command in the session in the $s variable. The command uses the *AsJob* parameter to run the command as a job and to create the job object in the current session. The command returns a job object, which is saved in the $j variable.The third command displays the job object in the $j variable.
PS C:\> $j = Invoke-Command -Session $s { 1..1500 | Foreach-Object {"Return $_"; sleep 30}} -AsJob

PS C:\> $j
Id     Name           State         HasMoreData     Location
--     ----           -----         -----------     --------
16     Job1           Running       True            Server01

The fourth command disconnects the session in the $s variable.
PS C:\> $s | Disconnect-PSSession
Id Name   ComputerName    State         ConfigurationName     Availability
-- ----   ------------    -----         -----------------     ------------
1  Test   Server01        Disconnected  Microsoft.PowerShell  None

The fifth command shows the effect of disconnecting on the job object in the $j variable. The job state is now Disconnected.
PS C:\> $j
Id     Name           State         HasMoreData     Location
--     ----           -----         -----------     --------
16     Job1           Disconnected  True            Server01

The sixth command runs a Receive-Job command 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.
PS C:\> Receive-Job $j -Keep
Return 1
Return 2

The seventh command is run in the same client session. The command uses the Connect-PSSession cmdlet to reconnect to the Test session on the Server01 computer and saves the session in the $s2 variable.
PS C:\> $s2 = Connect-PSSession -ComputerName Server01 -Name Test

The eighth command uses the **Receive-PSSession** cmdlet to get 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 ninth command uses the **Receive-Job** cmdlet to get the results of the job in the $j variable.
PS C:\> $j2 = Receive-PSSession -ComputerName Server01 -Name Test

PS C:\> Receive-Job $j
Return 3
Return 4

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

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, such as those returned by the Get-PSSession cmdlet, to this 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

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

• If the commands that were running in the disconnected session did not generate results or if the results were already returned to another session, Receive-PSSession does not generate any output.

• The output buffering mode of a session 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 cannot recover this output. For more information about the output buffering mode option, see the help topics for the New-PSSessionOption and New-PSTransportOption cmdlets.

• You cannot 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 now disconnected from the job. The job object still contains any results that were returned to it, but it does not 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 are not 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 are not 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 cannot 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 does not specify a new job name. If the session is reconnected to a different client session or a new job name is specified, Windows 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. Therefore, a value of Disconnected means that the PSSession is not connected to the current session. However, it does not 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 cannot connect to the PSSession because it is connected to another session.

  For more information about the values of the State property of sessions, see RunspaceState Enumeration in the MSDN library.

  For more information about the values of the Availability property of sessions, see RunspaceAvailability Enumeration.

Related Links

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