Disconnect-PSSession

Syntax

Disconnect-PSSession
          [-Session] <PSSession[]>
          [-IdleTimeoutSec <Int32>]
          [-OutputBufferingMode <OutputBufferingMode>]
          [-ThrottleLimit <Int32>]
          [-WhatIf]
          [-Confirm]
          [<CommonParameters>]

Disconnect-PSSession
          [-IdleTimeoutSec <Int32>]
          [-OutputBufferingMode <OutputBufferingMode>]
          [-ThrottleLimit <Int32>]
          -Name <String[]>
          [-WhatIf]
          [-Confirm]
          [<CommonParameters>]

Disconnect-PSSession
          [-IdleTimeoutSec <Int32>]
          [-OutputBufferingMode <OutputBufferingMode>]
          [-ThrottleLimit <Int32>]
          [-Id] <Int32[]>
          [-WhatIf]
          [-Confirm]
          [<CommonParameters>]

Disconnect-PSSession
          [-IdleTimeoutSec <Int32>]
          [-OutputBufferingMode <OutputBufferingMode>]
          [-ThrottleLimit <Int32>]
          -InstanceId <Guid[]>
          [-WhatIf]
          [-Confirm]
          [<CommonParameters>]

Description

The Disconnect-PSSession cmdlet disconnects a Windows PowerShell session ( PSSession ), such as one started by using the New-PSSession cmdlet, from the current session. As a result, the PSSession is in a disconnected state. You can connect to the disconnected PSSession from the current session or from another session on the local computer or a different computer.

The Disconnect-PSSession cmdlet disconnects only open PSSessions that are connected to the current session. Disconnect-PSSession cannot disconnect broken or closed PSSession objects, or interactive PSSession objects started by using the Enter-PSSession cmdlet, and it cannot disconnect PSSession objects that are connected to other sessions.

To reconnect to a disconnected PSSession , use the Connect-PSSession or Receive-PSSession cmdlets.

When a PSSession is disconnected, the commands in the PSSession continue to run until they finish, unless the PSSession times out or the commands in the PSSession are blocked by a full output buffer. To change the idle time-out, use the IdleTimeoutSec parameter. To change the output buffering mode, use the OutputBufferingMode parameter. You can also use the InDisconnectedSession parameter of the Invoke-Command cmdlet to run a command in a disconnected session.

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

This cmdlet was introduced in Windows PowerShell 3.0.

Examples

Example 1: Disconnect a session

PS C:\> Disconnect-PSSession -Name UpdateSession

Id Name            ComputerName    State         ConfigurationName     Availability

-- ----            ------------    -----         -----------------     ------------

1  UpdateSession   Server01        Disconnected  Microsoft.PowerShell          None

This command disconnects the UpdateSession PSSession on the Server01 computer from the current session. The command uses the Name parameter to identify the PSSession .

The output shows that the attempt to disconnect was successful. The session state is Disconnected and the Availability is None, which indicates that the session is not busy and can be reconnected.

Example 2: Disconnect a session created in the current session

PS C:\> Get-PSSession -ComputerName Server12 -Name ITTask | Disconnect-PSSession -OutputBufferingMode Drop -IdleTimeoutSec 86400

Id Name            ComputerName    State         ConfigurationName     Availability

-- ----            ------------    -----         -----------------     ------------

1  ITTask          Server12        Disconnected  ITTasks               None

This command disconnects the ITTask PSSession on the Server12 computer from the current session. The ITTask session was created in the current session and connects to the Server12 computer. The command uses the Get-PSSession cmdlet to get the session and Disconnect-PSSession to disconnect it.

The Disconnect-PSSession command uses the OutputBufferingMode parameter to set the output mode to Drop. This setting makes sure that the script that is running in the session can continue to run even if the session output buffer is full. Because the script writes its output to a report on a file share, other output can be lost without consequence.

The command also uses the IdleTimeoutSec parameter to extend the idle time-out of the session to 24 hours. This setting allows time for this administrator or other administrators to reconnect to the session to verify that the script ran and troubleshoot if needed.

Example 3: Disconnecting sessions in an enterprise scenario

The technician starts by creating sessions on several remote computers and running a script in each session.The first command uses the New-PSSession cmdlet to create the ITTask session on three remote computers. The command saves the sessions in the $s variable. The second command uses the *FilePath* parameter of the Invoke-Command cmdlet to run a script in the sessions in the $s variable.

PS C:\> $s = New-PSSession -ComputerName Srv1, Srv2, Srv30 -Name ITTask



PS C:\> Invoke-Command $s -FilePath \\Server01\Scripts\Get-PatchStatus.ps1



The script running on the Srv1 computer generates unexpected errors. The technician contacts his manager and asks for assistance. The manager directs the technician to disconnect from the session so he can investigate.The second command uses the Get-PSSession cmdlet to get the ITTask session on the Srv1 computer and **Disconnect-PSSession** to disconnect it. This command does not affect the ITTask sessions on  the other computers.

PS C:\> Get-PSSession -Name ITTask -ComputerName Srv1 | Disconnect-PSSession

Id Name            ComputerName    State         ConfigurationName     Availability

-- ----            ------------    -----         -----------------     ------------

1 ITTask           Srv1            Disconnected  Microsoft.PowerShell          None



The third command uses the **Get-PSSession** cmdlet to get the ITTask sessions. The output shows that the ITTask sessions on the Srv2 and Srv30 computers were not affected by the command to disconnect.

PS C:\> Get-PSSession -ComputerName Srv1, Srv2, Srv30 -Name ITTask

Id Name            ComputerName    State         ConfigurationName     Availability

-- ----            ------------    -----         -----------------     ------------

 1 ITTask          Srv1            Disconnected  Microsoft.PowerShell          None

 2 ITTask          Srv2            Opened        Microsoft.PowerShell     Available

 3 ITTask          Srv30           Opened        Microsoft.PowerShell     Available



The manager logs on to his home computer, connects to his corporate network, starts Windows PowerShell, and uses the Get-PSSession cmdlet to get the ITTask session on the Srv1 computer. He uses the credentials of the technician to access the session.

PS C:\> Get-PSSession -ComputerName Srv1 -Name ITTask -Credential Domain01\User01

Id Name            ComputerName    State         ConfigurationName     Availability

-- ----            ------------    -----         -----------------     ------------

 1 ITTask          Srv1            Disconnected  Microsoft.PowerShell          None



Next, the manager uses the Connect-PSSession cmdlet to connect to the ITTask session on the Srv1 computer. The command saves the session in the $s variable.

PS C:\> $s = Connect-PSSession -ComputerName Srv1 -Name ITTask -Credential Domain01\User01



The manager uses the Invoke-Command cmdlet to run some diagnostic commands in the session in the $s variable. He recognizes that the script failed because it did not find a required directory. The manager uses the MkDir function to create the directory, and then he restarts the Get-PatchStatus.ps1 script and disconnects from the session.The manager reports his findings to the technician, suggests that he reconnect to the session to complete the tasks, and asks him to add a command to the Get-PatchStatus.ps1 script that creates the required directory if it does not exist.

PS C:\> Invoke-Command -Session $s {dir $home\Scripts\PatchStatusOutput.ps1}



PS C:\> Invoke-Command -Session $s {mkdir $home\Scripts\PatchStatusOutput}



PS C:\> Invoke-Command -Session $s -FilePath \\Server01\Scripts\Get-PatchStatus.ps1



PS C:\> Disconnect-PSSession -Session $s

This series of commands shows how Disconnect-PSSession might be used in an enterprise scenario. In this case, a new technician starts a script in a session on a remote computer and runs into a problem. The technician disconnects from the session so that a more experienced manager can connect to the session and resolve the problem.

Example 4: Correct the value of an idle time-out so it can be disconnected

The first command uses the New-PSSessionOption cmdlet to create a session option object. It uses the *IdleTimeout* parameter to set an idle time-out of 48 hours (172800000 milliseconds). The command saves the session option object in the $Timeout variable.

PS C:\> $Timeout = New-PSSessionOption -IdleTimeout 172800000



The second command uses the New-PSSession cmdlet to create the ITTask session on the Server01 computer. The command saves the session in the $s variable. The value of the *SessionOption* parameter is the 48-hour idle time-out in the $Timeout variable.

PS C:\> $s = New-PSSession -Computer Server01 -Name ITTask -SessionOption $Timeout



The third command disconnects the ITTask session in the $s variable. The command fails because the idle time-out value of the session exceeds the **MaxIdleTimeoutMs** quota in the session configuration. Because the idle time-out is not used until the session is disconnected, this violation can go undetected while the session is being used.

PS C:\> Disconnect-PSSession -Session $s

Disconnect-PSSession : The session ITTask cannot be disconnected because the specified

idle timeout value 172800(seconds) is either greater than the server maximum allowed

43200 (seconds) or less that the minimum allowed60(seconds).  Choose an idle time out

value that is within the allowed range and try again.



The fourth command uses the Invoke-Command cmdlet to run a Get-PSSessionConfiguration command for the Microsoft.PowerShell session configuration on the Server01 computer. The command uses the Format-List cmdlet to display all properties of the session configuration in a list.The output shows that the **MaxIdleTimeoutMS** property, which establishes the maximum permitted **IdleTimeout** value for sessions that use the session configuration, is 43200000 milliseconds (12 hours).

PS C:\> Invoke-Command -ComputerName Server01 {Get-PSSessionConfiguration Microsoft.PowerShell} | Format-List -Property *

Architecture                  : 64

Filename                      : %windir%\system32\pwrshplugin.dll

ResourceUri                   : http://schemas.microsoft.com/powershell/microsoft.powershell

MaxConcurrentCommandsPerShell : 1000

UseSharedProcess              : false

ProcessIdleTimeoutSec         : 0

xmlns                         : http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration

MaxConcurrentUsers            : 5

lang                          : en-US

SupportsOptions               : true

ExactMatch                    : true

RunAsUser                     :

IdleTimeoutms                 : 7200000

PSVersion                     : 3.0

OutputBufferingMode           : Block

AutoRestart                   : false

SecurityDescriptorSddl        : O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;SA;GXGW;;;WD)

MaxMemoryPerShellMB           : 1024

MaxIdleTimeoutms              : 2147483647

Uri                           : http://schemas.microsoft.com/powershell/microsoft.powershell

SDKVersion                    : 2

Name                          : microsoft.powershell

XmlRenderingType              : text

Capability                    : {Shell}

RunAsPassword                 :

MaxProcessesPerShell          : 15

ParentResourceUri             : http://schemas.microsoft.com/powershell/microsoft.powershell

Enabled                       : true

MaxShells                     : 25

MaxShellsPerUser              : 25

Permission                    : BUILTIN\Administrators AccessAllowed

PSComputerName                : localhost

RunspaceId                    : aea84310-6dbf-4c21-90ac-13980039925a

PSShowComputerName            : True





The fifth command gets the session option values of the session in the $s variable. The values of many session options are properties of the **ConnectionInfo** property of the **Runspace** property of the session.The output shows that the value of the **IdleTimeout** property of the session is 172800000 milliseconds (48 hours), which violates the **MaxIdleTimeoutMs** quota of 12 hours in the session configuration.To resolve this conflict, you can use the *ConfigurationName* parameter to select a different session configuration or use the *IdleTimeout* parameter to reduce the idle time-out of the session.

PS C:\> $s.Runspace.ConnectionInfo

ConnectionUri                     : http://Server01/wsman

ComputerName                      : Server01

Scheme                            : http

Port                              : 80

AppName                           : /wsman

Credential                        :

ShellUri                          : http://schemas.microsoft.com/powershell/Microsoft.PowerShell

AuthenticationMechanism           : Default

CertificateThumbprint             :

MaximumConnectionRedirectionCount : 5

MaximumReceivedDataSizePerCommand :

MaximumReceivedObjectSize         : 209715200

UseCompression                    : True

NoMachineProfile                  : False

ProxyAccessType                   : None

ProxyAuthentication               : Negotiate

ProxyCredential                   :

SkipCACheck                       : False

SkipCNCheck                       : False

SkipRevocationCheck               : False

NoEncryption                      : False

UseUTF16                          : False

OutputBufferingMode               : Drop

IncludePortInSPN                  : False

Culture                           : en-US

UICulture                         : en-US

OpenTimeout                       : 180000

CancelTimeout                     : 60000

OperationTimeout                  : 180000

IdleTimeout                       : 172800000



The sixth command disconnects the session. It uses the *IdleTimeoutSec* parameter to set the idle time-out to the 12-hour maximum.

PS C:\> Disconnect-PSSession $s -IdleTimeoutSec 43200

Id Name            ComputerName    State         ConfigurationName     Availability

-- ----            ------------    -----         -----------------     ------------

 4 ITTask          Server01        Disconnected  Microsoft.PowerShell          None



The seventh command gets the value of the **IdleTimeout** property of the disconnected session, which is measured in milliseconds. The output confirms that the command was successful.

PS C:\> $s.Runspace.ConnectionInfo.IdleTimeout

43200000

This example shows how to correct the value of the IdleTimeout property of a session so that it can be disconnected.

The idle time-out property of a session is critical to disconnected sessions, because it determines how long a disconnected session is maintained before it is deleted. You can set the idle time-out option when you create a session and when you disconnect it. The default values for the idle time-out of a session are set in the $PSSessionOption preference variable on the local computer and in the session configuration on the remote computer. Values set for the session take precedence over values set in the session configuration, but session values cannot exceed quotas set in the session configuration, such as the MaxIdleTimeoutMs value.

Required Parameters

Optional Parameters

Inputs

System.Management.Automation.Runspaces.PSSession

You can pipe a session to this cmdlet.

Outputs

System.Management.Automation.Runspaces.PSSession

This cmdlet returns an object that represents the session that it disconnected.

Notes

• The Disconnect-PSSession cmdlet works only when the local and remote computers are running Windows PowerShell 3.0 or later versions of Windows PowerShell.
• If you use Disconnect-PSSession on a disconnected session, the command does not affect the session and it does not generate errors.
• Disconnected loopback sessions with interactive security tokens, which are created by using the EnableNetworkAccess parameter, can be reconnected only from the computer on which the session was created. This restriction protects the computer from malicious access.

• When you disconnect a PSSession , the session state is Disconnected and the availability is None .

  The value of the State property is relative to the current session. Therefore, a value of Disconnected means that the PSSession is not connected to the current session. However, it does not mean that the PSSession is disconnected from all sessions. It might be connected to a different session. To determine whether you can connect or reconnect to the session, use the Availability property.

  An Availability value of None indicates that you can connect to the session. A value of Busy indicates that you cannot connect to the PSSession because it is connected to another session.

  For more information about the values of the State property of sessions, see RunspaceState Enumeration in the MSDN library.

  For more information about the values of the Availability property of sessions, see RunspaceAvailability Enumeration in the MSDN library.

Related Links

• Connect-PSSession
• Enter-PSSession
• Exit-PSSession
• Get-PSSession
• Get-PSSessionConfiguration
• New-PSSession
• New-PSSessionOption
• New-PSTransportOption
• Receive-PSSession
• Register-PSSessionConfiguration
• Remove-PSSession