Connect-PSSession PowerShell Get-Help Output

This is the built-in help made by Microsoft for the command 'Connect-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

SYNTAX

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

Search powershellhelp.space

DESCRIPTION

The Connect-PSSession cmdlet reconnects to user-managed Windows PowerShell sessions ("PSSessions") that were disconnected. It works on sessions that are disconnected
intentionally, such as by using the Disconnect-PSSession cmdlet or the InDisconnectedSession parameter of the Invoke-Command cmdlet, and those that were disconnected
unintentionally, such as by a temporary network outage.

Connect-PSSession can connect to any disconnected session that was started by the same user, including those that were started by or disconnected from other sessions on
other computers.

However, Connect-PSSession cannot connect to broken or closed sessions, or interactive sessions started by using the Enter-PSSession cmdlet. Also you cannot connect sessions
to sessions started by other users, unless you can provide the credentials of the user who created the session.

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

This cmdlet is introduced in Windows PowerShell 3.0.

RELATED LINKS

REMARKS

Examples

Example 1

PS C:\>Connect-PSSession -ComputerName Server01 -Name ITTask
Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
4 ITTask Server01 Opened ITTasks Available

This command reconnects to the ITTask session on the Server01 computer.

The output shows that the command was successful. The State of the session is Opened and the Availability is Available, indicating that you can run commands in the session.

Example 2

PS C:\>Get-PSSession

Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
1 Backups Localhost Opened Microsoft.PowerShell Available

PS C:\> Get-PSSession | Disconnect-PSSession

Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
1 Backups Localhost Disconnected Microsoft.PowerShell None

PS C:\> Get-PSSession | Connect-PSSession

Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
1 Backups Localhost Opened Microsoft.PowerShell Available

This example shows the effect of disconnecting and then reconnecting to a session.

The first command uses the Get-PSSession cmdlet. Without the ComputerName parameter, the command gets only sessions that were created in the current session.

The output shows that the command gets the Backups session on the local computer. The State of the session is Opened and the Availability is Available.

The second command uses the Get-PSSession cmdlet to get the PSSessions that were created in the current session and the Disconnect-PSSession cmdlet to disconnect the
sessions. The output shows that the Backups session was disconnected. The State of the session is Disconnected and the Availability is None.

The third command uses the Get-PSSession cmdlet to get the PSSessions that were created in the current session and the Connect-PSSession cmdlet to reconnect the sessions.
The output shows that the Backups session was reconnected. The State of the session is Opened and the Availability is Available.

If you use the Connect-PSSession cmdlet on a session that is not disconnected, the command has no effect on the session and it does not generate any errors.

Example 3

The administrator begins by creating a sessions on a remote computer and running a script in the session.The first command uses the New-PSSession cmdlet to create the ITTask
session on the Server01 remote computer. The command uses the ConfigurationName parameter to specify the ITTasks session configuration. The command saves the sessions in the
$s variable.
PS C:\>$s = New-PSSession -ComputerName Server01 -Name ITTask -ConfigurationName ITTasks

The second command Invoke-Command cmdlet to start a background job in the session in the $s variable. It uses the FilePath parameter to run the script in the background job.
PS C:\>Invoke-Command -Session $s {Start-Job -FilePath \\Server30\Scripts\Backup-SQLDatabase.ps1}
Id Name State HasMoreData Location Command
-- ---- ----- ----------- -------- -------
2 Job2 Running True Server01 \\Server30\Scripts\Backup...

The third command uses the Disconnect-PSSession cmdlet to disconnect from the session in the $s variable. The command uses the OutputBufferingMode parameter with a value of
Drop to prevent the script from being blocked by having to deliver output to the session. It uses the IdleTimeoutSec parameter to extend the session timeout to 15 hours.When
the command completes, the administrator locks her computer and goes home for the evening.
PS C:\>Disconnect-PSSession -Session $s -OutputBufferingMode Drop -IdleTimeoutSec 60*60*15
Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
1 ITTask Server01 Disconnected ITTasks None

Later that evening, the administrator starts her home computer, logs on to the corporate network, and starts Windows PowerShell. The fourth command uses the Get-PSSession
cmdlet to get the sessions on the Server01 computer. The command finds the ITTask session.The fifth command uses the Connect-PSSession cmdlet to connect to the ITTask
session. The command saves the session in the $s variable.
PS C:\>Get-PSSession -ComputerName Server01 -Name ITTask

Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
1 ITTask Server01 Disconnected ITTasks None

PS C:\>$s = Connect-PSSession -ComputerName Server01 -Name ITTask

Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
1 ITTask Server01 Opened ITTasks Available

The sixth command uses the Invoke-Command cmdlet to run a Get-Job command in the session in the $s variable. The output shows that the job completed successfully.The seventh
command uses the Invoke-Command cmdlet to run a Receive-Job command in the session in the $s variable in the session. The command saves the results in the $BackupSpecs
variable.The eighth command uses the Invoke-Command cmdlet to runs another script in the session. The command uses the value of the $BackupSpecs variable in the session as
input to the script.

PS C:\>Invoke-Command -Session $s {Get-Job}

Id Name State HasMoreData Location Command
-- ---- ----- ----------- -------- -------
2 Job2 Completed True Server01 \\Server30\Scripts\Backup...

PS C:\>Invoke-Command -Session $s {$BackupSpecs = Receive-Job -JobName Job2}

PS C:\>Invoke-Command -Session $s {\\Server30\Scripts\New-SQLDatabase.ps1 -InitData $BackupSpecs.Initialization}

The ninth command disconnects from the session in the $s variable.The administrator closes Windows PowerShell and closes the computer. She can reconnect to the session on
the next day and check the script status from her work computer.
PS C:\>Disconnect-PSSession -Session $s -OutputBufferingMode Drop -IdleTimeoutSec 60*60*15
Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
1 ITTask Server01 Disconnected ITTasks None

This series of commands shows how the Connect-PSSession cmdlet might be used in an enterprise scenario. In this case, a system administrator starts a long-running job in a
session on a remote computer. After starting the job, the administrator disconnects from the session and goes home. Later that evening, the administrator logs on to her home
computer and verifies that the job ran to completion.