The Connect-PSSession cmdlet reconnects to user-managed PowerShell sessions ( PSSessions ) that were disconnected. It works on sessions that are disconnected intentionally, such as by using Disconnect-PSSession or the InDisconnectedSession parameter of Invoke-Command , and those that were disconnected unintentionally, such as by a temporary network outage.
Syntax
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 -InstanceId Guid[] [-ConnectionUri] Uri[] [-AllowRedirection]
[-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}]
[-CertificateThumbprint String] [-ConfigurationName String] [-Credential PSCredential]
[-SessionOption PSSessionOption] [-ThrottleLimit Int32] [-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 -InstanceId Guid[] [-ComputerName] String[] [-ApplicationName String]
[-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}]
[-CertificateThumbprint String] [-ConfigurationName String] [-Credential PSCredential][-Port Int32]
[-SessionOption PSSessionOption] [-ThrottleLimit Int32] [-UseSSL] [-Confirm] [-WhatIf] [CommonParameters]
Connect-PSSession [-Id] Int32[] [-ThrottleLimit Int32] [-Confirm] [-WhatIf] [CommonParameters]
Connect-PSSession -InstanceId Guid[] [-ThrottleLimit Int32] [-Confirm] [-WhatIf] [CommonParameters]
Connect-PSSession -Name String[] [-ThrottleLimit Int32 [-Confirm]] [-WhatIf] [CommonParameters]
Connect-PSSession [-Session] PSSession[] [-ThrottleLimit Int32] [-Confirm] [-WhatIf] [CommonParameters]
Key
-AllowRedirection
Allow redirection of this connection to an alternate Uniform Resource Identifier (URI).
When you use -ConnectionURI, the remote destination can return an instruction to redirect to
a different URI. By default, PowerShell does not redirect connections.
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.
-ApplicationName string
The name of 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, 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.
-Authentication Authentication
The authentication mechanism to be used at the server. Possible values are:
Basic Send username and password in clear text.
Default Use the authentication method implemented by WS-Management protocol. This is the default.
Digest Challenge-response scheme using a server-specified data string for the challenge.
Kerberos Authenticate by using Kerberos certificates.
Negotiate Challenge-response that negotiates an authentication scheme.
e.g. Kerberos protocol or NTLM.
NegotiateWithImplicitCredential Use the credentials cached on the PSSession computer.
CredSSP Use Credential Security Service Provider (CredSSP) authentication, delegate
credentials to a remote computer. This increases the security risk, if the remote
computer is compromised, the credentials could be used to control the network session.
(Windows Vista or later versions.)
-CertificateThumbprint string
The certificate thumbprint of the digital public key certificate (X509) of a user account
that has permission to perform this action.
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 the Get-Item or Get-ChildItem command
in the PowerShell Cert: drive.
-ComputerName string
Specifies the computers on which the disconnected sessions are 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. Wildcard characters
are not permitted. To specify the local computer, type the computer name, localhost, or a dot (.)
-ConfigurationName string
Connect 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.
-Confirm
Prompt for confirmation before running the cmdlet.
-ConnectionURI Uri
Specifies a Uniform Resource Identifier (URI) that defines the connection endpoint for the
interactive 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
Valid values for the Transport segment of the URI are HTTP and HTTPS.
If you do not specify a ConnectionURI, you can use the UseSSL, ComputerName, Port, and
ApplicationName parameters to specify the URI values.
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 PowerShell remoting, specify port 5985 for HTTP or 5986 for HTTPS.
If the destination computer redirects the connection to a different URI, PowerShell will prevent
the redirection unless you use -AllowRedirection in the command.
-Credential PSCredential
A user account that has permission to connect to the disconnected session. default=current user.
e.g. "User64", "Domain01\User64", or "User@Domain.com". Or a PSCredential object, such as
returned by Get-Credential. When you type a user name, you will be prompted for a password.
-Id int
The IDs of the disconnected sessions. (from Get-PSSession)
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.
-InstanceId Guid
The instance IDs of the disconnected sessions.
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.
-Name string
Specifies the friendly names of the disconnected sessions.
-Port int
The network port on the remote computer that is used to reconnect to the session.
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, configure the WinRM listener on the remote computer to listen at that
port. Use the following commands to configure the listener:
1. `Remove-Item -Path WSMan:\Localhost\listener\listener* -Recurse`
2. `New-Item -Path WSMan:\Localhost\listener -Transport http -Address * -Port port-number`
Do not use the Port parameter unless you must. The port setting 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.
-Session PSSession
Specifies the disconnected sessions. Enter a variable that contains the PSSession objects or a command that
creates or gets the PSSession objects, such as a Get-PSSession command.
-SessionOption PSSessionOption
Set advanced options for the session. Enter a SessionOption object that you createusing New-PSSessionOption,
or a hash table in which the keys are session option names and the values aresession option values.
The default values for the options are determined by the value of the $PSSessionOption
preference variable, if it is set. Otherwise, the session uses the system defaults.
For information about the $PSSessionOption preference variable, see about_Preference_Variables.
-UseSSL
Use the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer.
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.
-ThrottleLimit Int32
Specifies the maximum number of concurrent connections that can be established to run this command. If you
omit this parameter or enter a value of 0, the default value, 32, is used.
The throttle limit applies only to the current command, not to the session or to the computer.
-UseSSL
Indicates that this cmdlet 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. The UseSSL parameter 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 that is used for the command, the command
fails.
-WhatIf
Show what would happen if the cmdlet runs. The cmdlet is not run.
Standard Aliases for Connect-PSSession: cnsn
Connect-PSSession can connect to any disconnected session that was started by the same user. These include 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 was introduced in Windows PowerShell 3.0.
Reconnect to a session:
PS C:> Connect-PSSession -ComputerName Server01 -Name ITTask
List, disconnect and then reconnect to a session:
PS C:> Get-PSSession PS C:> Get-PSSession | Disconnect-PSSession PS C:> Get-PSSession | Connect-PSSession
Create sessions on a remote computer and run a script in each,
start a background job in the session in the $s variable,
disconnect from the session in the $s variable
then from a different workstation - get the sessions on the Server64 computer,
and lastly connect to the ITTask session - saving the session
in the $s variable:
PS C:> $s = New-PSSession -ComputerName Server64 -Name ITTask -ConfigurationName ITTasks
PS C:> Invoke-Command -Session $s {Start-Job -FilePath \\Server30\Scripts\Backup-SQLDatabase.ps1}
PS C:> Disconnect-PSSession -Session $s -OutputBufferingMode Drop -IdleTimeoutSec 60*60*15
PS C:> Get-PSSession -ComputerName Server64 -Name ITTask
PS C:> $s = Connect-PSSession -ComputerName Server64 -Name ITTask
“The eyes are one of the most powerful tools a woman can have. With one look, she can relay the most intimate message. After the connection is made, words cease to exist” - Jennifer Salaiz
Exit-PSSession - End an interactive session with a remote computer.
Disconnect-PSSession - Disconnect from a session.
New-PSSession - Create a persistent connection to a local or remote computer.
Invoke-Command - Run a single command on local or remote computer.