Receive-PSSession

Gets results of commands in disconnected sessions PowerShell reference

From the PowerShell reference 19 parameters Alias rcsn

What it does

from the PowerShell reference, CC BY 4.0

Gets results of commands in disconnected sessions 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.

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

Connect to a PSSession

Receive-PSSession -ComputerName Server01 -Name ITTaskIdentify

Get results of all commands on disconnected sessions

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

Get the results of a script running in a session

$parms = @{
ComputerName = "Server01"
Name = "ITTask"
OutTarget = "Job"
JobName = "ITTaskJob01"
Credential = "Domain01\Admin01"
}
Receive-PSSession @parms

Identify

Get results after a network outage

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

Identify

Trips 1 Sigma rule: lowUnusually Long PowerShell CommandLine by oscd.community, Natalia Shornikova

Reconnect to disconnected 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

Identify

Trips 1 Sigma rule: lowUnusually Long PowerShell CommandLine by oscd.community, Natalia Shornikova

Running a job 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

Identify

Its page in the reference: Receive-PSSession.

Parameters

19 in the PowerShell reference

Show its 19 parameters

-AllowRedirectionIndicates that this cmdlet 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, PowerShell doesn't redirect connections, but you can use this parameter to enable 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.

-ApplicationNameSpecifies an application. This cmdlet 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, WSMan is the application name: http://localhost:5985/WSMAN. The application name of a session is stored in the Runspace.ConnectionInfo.AppName property of the session. The parameter's value is used to select and filter sessions. It doesn't change the application that the session uses.

-AuthenticationSpecifies the mechanism that's used to authenticate the user credentials in the command to reconnect to a disconnected session. The acceptable values for this parameter are: - Default - Basic - Credssp - Digest - Kerberos - Negotiate - NegotiateWithImplicitCredential The default value is Default. For more information about the values of this parameter, see AuthenticationMechanism Enumeration. CAUTION: Credential Security Support Provider (CredSSP) authentication, in which the user 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.

-CertificateThumbprintSpecifies 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. Certificates can be mapped only to local user accounts, and don't work with domain accounts. To get a certificate thumbprint, use a Get-Item or Get-ChildItem command in the PowerShell Cert: drive.

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

-ConfigurationNameSpecifies the name of a session configuration. This cmdlet 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 parameter's value is used to select and filter sessions. It doesn't change the session configuration that the session uses. For more information about session configurations, see about_Session_Configurations.

-ConnectionUriSpecifies a URI that defines the connection endpoint that is used to reconnect to the disconnected session. The URI must be fully qualified. The string's format is as follows: <Transport>://<ComputerName>:<Port>/<ApplicationName> The default value is as follows: http://localhost:5985/WSMAN If you don't 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 don't specify a port, the session is created with standard ports: 80 for HTTP and 443 for HTTPS. To use the default ports for PowerShell remoting, specify port 5985 for HTTP or 5986 for HTTPS. If the destination computer redirects the connection to a different URI, PowerShell prevents the redirection unless you use the AllowRedirection parameter in the command.

-CredentialSpecifies a user account that has permission to connect to the disconnected session. The default is the current user. Credentials are stored in a PSCredential object and the password is stored as a SecureString. NOTE: For more information about SecureString data protection, see How secure is SecureString?.

-IdSpecifies the ID of a 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 wasn't connected to the current session.

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

-JobNameSpecifies 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's running in the disconnected session was started in the current session. If the job that's running in the disconnected session was started in the current session, PowerShell reuses the original job object in the session and ignores the value of the JobName parameter. If the job that's running in the disconnected session was started in a different session, 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 isn't Job, the command succeeds, but the JobName parameter has no effect.

-NameSpecifies the friendly name of the disconnected session.

-OutTargetDetermines how the session results are returned. The acceptable values for this parameter 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. If the command that's being received in a 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, by default, it's returned as a job. Otherwise, it's 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.

-PortSpecifies the remote computer's network port that's used to reconnect to the session. To connect to a remote computer, it must be listening on the port that the connection uses. The default ports are 5985, which is the WinRM port for HTTP, and 5986, which is the WinRM port for HTTPS. Before using an alternate port, you must configure the WinRM listener on the remote computer to listen on that port. To configure the listener, type the following two commands at the PowerShell prompt: Remove-Item -Path WSMan:\Localhost\listener\listener* -Recurse New-Item -Path WSMan:\Localhost\listener -Transport http -Address * -Port <port-number> Don't use the Port parameter unless it's necessary. The port that's 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.

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

-SessionOptionSpecifies 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's 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 don't take precedence over maximum values, quotas, or limits set in the session configuration. For a description of the session options that includes the default values, see New-PSSessionOption. For information about the $PSSessionOption preference variable, see about_Preference_Variables. For more information about session configurations, see about_Session_Configurations.

-UseSSLIndicates that this cmdlet uses the Secure Sockets Layer (SSL) protocol to connect to the disconnected session. By default, SSL isn't used. WS-Management encrypts all 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 and SSL isn't available on the port that's used for the command, the command fails.

-ConfirmPrompts you for confirmation before running the cmdlet.

-WhatIfShows what would happen if the cmdlet runs. The cmdlet isn't run.

Receive-PSSession

What it does

Parameters

See also