PowerShell Logo Small

Receive-PSSession



This is the built-in help made by Microsoft for the command 'Receive-PSSession', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Gets results of commands in disconnected sessions

SYNTAX


Receive-PSSession [-Session] <PSSession> [-JobName [<String>]] [-OutTarget {Default | Host | Job}] [-Confirm] [-WhatIf] [<CommonParameters>]
Receive-PSSession [-ComputerName] <String> [-ApplicationName [<String>]] [-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest |
Kerberos}] [-CertificateThumbprint [<String>]] [-ConfigurationName [<String>]] [-Credential [<PSCredential>]] [-JobName [<String>]] [-OutTarget {Default | Host | Job}]
[-Port [<Int32>]] [-SessionOption [<PSSessionOption>]] [-UseSSL] -Name <String> [-Confirm] [-WhatIf] [<CommonParameters>]
Receive-PSSession [-ComputerName] <String> [-ApplicationName [<String>]] [-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest |
Kerberos}] [-CertificateThumbprint [<String>]] [-ConfigurationName [<String>]] [-Credential [<PSCredential>]] [-JobName [<String>]] [-OutTarget {Default | Host | Job}]
[-Port [<Int32>]] [-SessionOption [<PSSessionOption>]] [-UseSSL] -InstanceId <Guid> [-Confirm] [-WhatIf] [<CommonParameters>]
Receive-PSSession [-ConnectionUri] <Uri> [-AllowRedirection] [-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}]
[-CertificateThumbprint [<String>]] [-ConfigurationName [<String>]] [-Credential [<PSCredential>]] [-JobName [<String>]] [-OutTarget {Default | Host | Job}] [-SessionOption
[<PSSessionOption>]] -Name <String> [-Confirm] [-WhatIf] [<CommonParameters>]
Receive-PSSession [-ConnectionUri] <Uri> [-AllowRedirection] [-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}]
[-CertificateThumbprint [<String>]] [-ConfigurationName [<String>]] [-Credential [<PSCredential>]] [-JobName [<String>]] [-OutTarget {Default | Host | Job}] [-SessionOption
[<PSSessionOption>]] -InstanceId <Guid> [-Confirm] [-WhatIf] [<CommonParameters>]
Receive-PSSession [-Id] <Int32> [-JobName [<String>]] [-OutTarget {Default | Host | Job}] [-Confirm] [-WhatIf] [<CommonParameters>]
Receive-PSSession [-InstanceId] <Guid> [-JobName [<String>]] [-OutTarget {Default | Host | Job}] [-Confirm] [-WhatIf] [<CommonParameters>]
Receive-PSSession [-Name] <String> [-JobName [<String>]] [-OutTarget {Default | Host | Job}] [-Confirm] [-WhatIf] [<CommonParameters>]



Search powershellhelp.space

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 in place of a Connect-PSSession command. Receive-PSSession can connect to any disconnected or reconnected session,
including 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 is introduced in Windows PowerShell 3.0.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/p/?linkid=289604
Connect-PSSession
Enter-PSSession
Exit-PSSession
Get-PSSession
Invoke-Command
New-PSSession
New-PSSessionOption
Receive-PSSession
Remove-PSSession
about_PSSessions
about_Remote
about_Remote_Disconnected_Sessions
about_Session_Configurations

REMARKS

<

Examples


Example 1

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

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

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 with 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

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 C:\>Invoke-Command -Session $s -FilePath \\Server12\Scripts\SharedScripts\New-ADResolve.ps1
Running "New-ADResolve.ps1" ….exit

# 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 once each second for the next four minutes and abandons the effort only if all attempts in the four-minute interval fail.






Example 5

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 complete. 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's important to set the idle timeout for a long enough period 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
connecting 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 5

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 1Return 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.