Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

Receive-PSSession

Updated: October 17, 2013

Applies To: Windows PowerShell 4.0

Receive-PSSession

Gets results of commands in disconnected sessions

Aliases

The following abbreviations are aliases for this cmdlet:

  • rcsn

Syntax

Parameter Set: Session
Receive-PSSession [-Session] <PSSession> [-JobName <String> ] [-OutTarget <OutTarget> ] [-Confirm] [-WhatIf] [ <CommonParameters>]

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

Parameter Set: ComputerSessionName
Receive-PSSession [-ComputerName] <String> -Name <String> [-ApplicationName <String> ] [-Authentication <AuthenticationMechanism> ] [-CertificateThumbprint <String> ] [-ConfigurationName <String> ] [-Credential <PSCredential> ] [-JobName <String> ] [-OutTarget <OutTarget> ] [-Port <Int32> ] [-SessionOption <PSSessionOption> ] [-UseSSL] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: ConnectionUriInstanceId
Receive-PSSession [-ConnectionUri] <Uri> -InstanceId <Guid> [-AllowRedirection] [-Authentication <AuthenticationMechanism> ] [-CertificateThumbprint <String> ] [-ConfigurationName <String> ] [-Credential <PSCredential> ] [-JobName <String> ] [-OutTarget <OutTarget> ] [-SessionOption <PSSessionOption> ] [-Confirm] [-WhatIf] [ <CommonParameters>]

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

Parameter Set: Id
Receive-PSSession [-Id] <Int32> [-JobName <String> ] [-OutTarget <OutTarget> ] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: InstanceId
Receive-PSSession [-InstanceId] <Guid> [-JobName <String> ] [-OutTarget <OutTarget> ] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: SessionName
Receive-PSSession [-Name] <String> [-JobName <String> ] [-OutTarget <OutTarget> ] [-Confirm] [-WhatIf] [ <CommonParameters>]




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

Parameters

-Authentication<AuthenticationMechanism>

Specifies the mechanism that is used to authenticate the user's credentials in the command to reconnect to the disconnected session. Valid values are Default, Basic, Credssp, Digest, Kerberos, Negotiate, and NegotiateWithImplicitCredential. The default value is Default.

For information about the values of this parameter, see "AuthenticationMechanism enumeration" in MSDN.

CAUTION: Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. This mechanism increases the security risk of the remote operation. If the remote computer is compromised, the credentials that are passed to it can be used to control the network session.


Aliases

none

Required?

false

Position?

named

Default Value

Default

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-CertificateThumbprint<String>

Specifies the digital public key certificate (X509) of a user account that has permission to connect to the disconnected session. Enter the certificate thumbprint of the certificate.

Certificates are used in client certificate-based authentication. They can be mapped only to local user accounts; they do not work with domain accounts.

To get a certificate thumbprint, use a Get-Item or Get-ChildItem command in the Windows PowerShell Cert: drive.


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ComputerName<String>

Specifies the computer on which the disconnected session is stored. Sessions are stored on the computer that is at the "server-side" or receiving end of a connection. The default is the local computer.

Type the NetBIOS name, an IP address, or a fully qualified domain name of one computer. Wildcards are not permitted. To specify the local computer, type the computer name, "localhost", or a dot (.)


Aliases

Cn

Required?

true

Position?

1

Default Value

Local computer

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-Credential<PSCredential>

Specifies a user account that has permission to connect to the disconnected session. The default is the current user.

Type a user name, such as "User01" or "Domain01\User01". Or, enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.


Aliases

none

Required?

false

Position?

named

Default Value

Current user

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Id<Int32>

Specifies the ID of the disconnected session. The ID parameter works only when the disconnected session was previously connected to the current session.

This parameter is valid, but not effective, when the session is stored on the local computer, but was not connected to the current session.


Aliases

none

Required?

true

Position?

1

Default Value

None

Accept Pipeline Input?

True (ByPropertyName, ByValue)

Accept Wildcard Characters?

false

-InstanceId<Guid>

Specifies the instance ID of the disconnected session.

The instance ID is a GUID that uniquely identifies a PSSession on a local or remote computer.

The instance ID is stored in the InstanceID property of the PSSession.


Aliases

none

Required?

true

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-JobName<String>

Specifies a friendly name for the job that Receive-PSSession returns.

Receive-PSSession returns a job when the value of the OutTarget parameter is Job or the job that is running in the disconnected session was started in the current session.

If the job that is running in the disconnected session was started in the current session, Windows PowerShell reuses the original job object in the session and ignores the value of the JobName parameter.

If the job that is running in the disconnected session was started in a different session, Windows PowerShell creates a new job object. It uses a default name, but you can use this parameter to change the name.

If the default value or explicit value of the OutTarget parameter is not Job, the command succeeds, but the JobName parameter has no effect.


Aliases

none

Required?

false

Position?

named

Default Value

Job<n>

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Name<String>

Specifies the friendly name of the disconnected session.


Aliases

none

Required?

true

Position?

1

Default Value

None

Accept Pipeline Input?

True (ByPropertyName, ByValue)

Accept Wildcard Characters?

false

-OutTarget<OutTarget>

Determines how the session results are returned.

Valid values are:

-- Job: Returns the results asynchronously in a job object. You can use the JobName parameter to specify a name or new name for the job.

-- Host: Returns the results to the command line (synchronously). If the command is being resumed or the results consist of a large number of objects, the response might be delayed.

The default value of the OutTarget parameter is Host. However, if the command that is being received in disconnected session was started in the current session, the default value of the OutTarget parameter is the form in which the command was started. If the command was started as a job, it is returned as a job by default. Otherwise, it is returned to the host program by default.

Typically, the host program displays returned objects at the command line without delay, but this behavior can vary.


Aliases

none

Required?

false

Position?

named

Default Value

Host

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Port<Int32>

Specifies the network port on the remote computer that is used to reconnect to the session. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS).

Before using an alternate port, you must configure the WinRM listener on the remote computer to listen at that port. To configure the listener, type the following two commands at the Windows PowerShell prompt:

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

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

Do not use the Port parameter unless you must. The port that is set in the command applies to all computers or sessions on which the command runs. An alternate port setting might prevent the command from running on all computers.


Aliases

none

Required?

false

Position?

named

Default Value

5985, 5986

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Session<PSSession>

Specifies the disconnected session. Enter a variable that contains the PSSession or a command that creates or gets the PSSession, such as a Get-PSSession command.


Aliases

none

Required?

true

Position?

1

Default Value

none

Accept Pipeline Input?

True (ByPropertyName, ByValue)

Accept Wildcard Characters?

false

-UseSSL

Uses the Secure Sockets Layer (SSL) protocol to connect to the disconnected session. By default, SSL is not used.

WS-Management encrypts all Windows PowerShell content transmitted over the network. UseSSL is an additional protection that sends the data across an HTTPS connection instead of an HTTP connection.

If you use this parameter, but SSL is not available on the port used for the command, the command fails.


Aliases

none

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-AllowRedirection

Allows redirection of this connection to an alternate Uniform Resource Identifier (URI).

When you use the ConnectionURI parameter, the remote destination can return an instruction to redirect to a different URI. By default, Windows PowerShell does not redirect connections, but you can use this parameter to allow it to redirect the connection.

You can also limit the number of times the connection is redirected by changing the MaximumConnectionRedirectionCount session option value. Use the MaximumRedirection parameter of the New-PSSessionOption cmdlet or set the MaximumConnectionRedirectionCount property of the $PSSessionOption preference variable. The default value is 5.


Aliases

none

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ApplicationName<String>

Connects only to sessions that use the specified application.

Enter the application name segment of the connection URI. For example, in the following connection URI, the application name is WSMan: http://localhost:5985/WSMAN. The application name of a session is stored in the Runspace.ConnectionInfo.AppName property of the session.

The value of this parameter is used to select and filter sessions. It does not change the application that the session uses.


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-ConfigurationName<String>

Connects only to sessions that use the specified session configuration.

Enter a configuration name or the fully qualified resource URI for a session configuration. If you specify only the configuration name, the following schema URI is prepended: http://schemas.microsoft.com/powershell. The configuration name of a session is stored in the ConfigurationName property of the session.

The value of this parameter is used to select and filter sessions. It does not change the session configuration that the session uses.

For more information about session configurations, see about_Session_Configurations .


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-ConnectionUri<Uri>

Specifies a Uniform Resource Identifier (URI) that defines the connection endpoint that is used to reconnect to the disconnected session.

The URI must be fully qualified. The format of this string is as follows:

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

The default value is as follows:

http://localhost:5985/WSMAN

If you do not specify a connection URI, you can use the UseSSL, ComputerName, Port, and ApplicationName parameters to specify the connection URI values.

Valid values for the Transport segment of the URI are HTTP and HTTPS. If you specify a connection URI with a Transport segment, but do not specify a port, the session is created with standards ports: 80 for HTTP and 443 for HTTPS. To use the default ports for Windows PowerShell remoting, specify port 5985 for HTTP or 5986 for HTTPS.

If the destination computer redirects the connection to a different URI, Windows PowerShell prevents the redirection unless you use the AllowRedirection parameter in the command.


Aliases

URI,CU

Required?

true

Position?

1

Default Value

http://localhost:5985/WSMAN

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-SessionOption<PSSessionOption>

Sets advanced options for the session. Enter a SessionOption object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values.

The default values for the options are determined by the value of the $PSSessionOption preference variable, if it is set. Otherwise, the default values are established by options set in the session configuration.

The session option values take precedence over default values for sessions set in the $PSSessionOption preference variable and in the session configuration. However, they do not take precedence over maximum values, quotas or limits set in the session configuration.

For a description of the session options, including the default values, see New-PSSessionOption. For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152).


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Confirm

Prompts you for confirmation before running the cmdlet.


Required?

false

Position?

named

Default Value

false

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.


Required?

false

Position?

named

Default Value

false

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see  about_CommonParameters (http://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

  • System.Management.Automation.Runspaces.PSSession

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


  • System.Int32

    You can pipe session IDs to Receive-PSSession.


  • System.Guid

    You can pipe the instance IDs of sessions to Receive-PSSession.


  • System.String

    You can pipe session names to Receive-PSSession.


Outputs

The output type is the type of the objects that the cmdlet emits.

  • System.Management.Automation.Job or PSObject

    Receive-PSSession gets 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 (terminate at) computers running Windows PowerShell 3.0 or later 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 begins 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 timeout 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 connecting to a PSSession or receiving results.

    You can set and change the idle timeout 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 MSDN at http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.runspaces.runspacestate(v=VS.85).aspx.

    For more information about the values of the Availability property of sessions, see RunspaceAvailability Enumeration at http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.runspaces.runspaceavailability(v=vs.85).aspx.

Examples

Example 1

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.


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

Example 2

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.


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

Example 3

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


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

Example 4

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.


 

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

Example 5

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.


 

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…

Example 5

This example shows what happens to a job that is running 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.


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…

Related topics



Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.