Connect-PSSession

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.

   CommonParameters:
       -Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
       -OutBuffer, PipelineVariable and -OutVariable.

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.

Examples

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

Related PowerShell Cmdlets:

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.


 
Copyright © SS64.com 1999-2020
Some rights reserved