PowerShell Logo Small

Connect-PSSession



This is the built-in help made by Microsoft for the command 'Connect-PSSession', in PowerShell version 3 - as retrieved from Windows version 'Microsoft Windows Server 2012 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

Reconnects to disconnected sessions

SYNTAX


Connect-PSSession [-ThrottleLimit <Int32>] -Name <String[]> [-Confirm] [-WhatIf] [<CommonParameters>]
Connect-PSSession [-ConnectionUri] <Uri[]> [-AllowRedirection] [-Authentication <AuthenticationMechanism>] [-CertificateThumbprint <String>]
[-ConfigurationName <String>] [-Credential <PSCredential>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <Int32>] -InstanceId <Guid[]>
[-Confirm] [-WhatIf] [<CommonParameters>]
Connect-PSSession [-ComputerName] <String[]> [-ApplicationName <String>] [-Authentication <AuthenticationMechanism>] [-CertificateThumbprint
<String>] [-ConfigurationName <String>] [-Credential <PSCredential>] [-Name <String[]>] [-Port <Int32>] [-SessionOption <PSSessionOption>]
[-ThrottleLimit <Int32>] [-UseSSL] [-Confirm] [-WhatIf] [<CommonParameters>]
Connect-PSSession [-ApplicationName <String>] [-Authentication <AuthenticationMechanism>] [-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 <AuthenticationMechanism>] [-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

Online Version: http://go.microsoft.com/fwlink/?LinkID=210604
Connect-PSSession
Disconnect-PSSession
Enter-PSSession
Exit-PSSession
Get-PSSession
Get-PSSessionConfiguration
New-PSSession
New-PSSessionOption
New-PSTransportOption
Receive-PSSession
Register-PSSessionConfiguration
Remove-PSSession
about_PSSessions
about_Remote
about_Remote_Disconnected_Sessions
about_Session_Configurations

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.