Get-PSSession
Gets the Windows PowerShell sessions on local and remote computers.
Get-PSSession [-Name [<String[]>]] [<CommonParameters>]
Get-PSSession [-ConnectionUri*] <Uri[]> [-AllowRedirection] [-Authentication {Default | Basic | Negotiate |NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-CertificateThumbprint [<String>]][-ConfigurationName [<String>]] [-Credential [<PSCredential>]] [-Name [<String[]>]] [-SessionOption[<PSSessionOption>]] [-State {All | Opened | Disconnected | Closed | Broken}] [-ThrottleLimit [<Int32>]][<CommonParameters>]
Get-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>]] [-State {All | Opened | Disconnected | Closed | Broken}] [-ThrottleLimit[<Int32>]] [-UseSSL] [<CommonParameters>]
Get-PSSession [-ComputerName*] <String[]> [-ApplicationName [<String>]] [-Authentication {Default | Basic |Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-CertificateThumbprint [<String>]][-ConfigurationName [<String>]] [-Credential [<PSCredential>]] [-Port [<Int32>]] [-SessionOption[<PSSessionOption>]] [-State {All | Opened | Disconnected | Closed | Broken}] [-ThrottleLimit [<Int32>]] [-UseSSL]-InstanceId* <Guid[]> [<CommonParameters>]
Get-PSSession [-ConnectionUri*] <Uri[]> [-AllowRedirection] [-Authentication {Default | Basic | Negotiate |NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-CertificateThumbprint [<String>]][-ConfigurationName [<String>]] [-Credential [<PSCredential>]] [-SessionOption [<PSSessionOption>]] [-State {All |Opened | Disconnected | Closed | Broken}] [-ThrottleLimit [<Int32>]] -InstanceId* <Guid[]> [<CommonParameters>]
Get-PSSession [-Id*] <Int32[]> [<CommonParameters>]
Get-PSSession [-InstanceId* <Guid[]>] [<CommonParameters>]
The Get-PSSession cmdlet gets the user-managed Windows PowerShell sessions (PSSessions) on local and remote computers.
Starting in Windows PowerShell 3.0, sessions are stored on the computers at the remote end of each connection. You can use the ComputerName or ConnectionUri parameters of Get-PSSession to get the sessions that connect to the local computer or remote computers, even if they were not created in the current session.
Without parameters, Get-PSSession gets all sessions that were created in the current session.
Use the filtering parameters, including Name, ID, InstanceID, State, ApplicationName, and ConfigurationName to select from among the sessions that Get-PSSession returns.
Use the remaining parameters to configure the temporary connection in which the Get-PSSession command runs when you use the ComputerName or ConnectionUri parameters.
NOTE: In Windows PowerShell 2.0, without parameters, Get-PSSession gets all sessions that were created in the current session. The ComputerName parameter gets sessions that were created in the current session and connect to the specified computer.
For more information about Windows PowerShell sessions, see about_PSSessions (http://go.microsoft.com/fwlink/?LinkID=135181).
Parameters |
---|
-Authentication [<AuthenticationMechanism>]
|
-CertificateThumbprint [<String>]
|
-ComputerName <String[]>
|
-Credential [<PSCredential>]
|
-Id <Int32[]>
|
-InstanceId <Guid[]>
|
-Name [<String[]>]
|
-Port [<Int32>]
|
-State [<SessionFilterState>]
|
-ThrottleLimit [<Int32>]
|
-UseSSL [<SwitchParameter>]
|
-AllowRedirection [<SwitchParameter>]
|
-ApplicationName [<String>]
|
-ConfigurationName [<String>]
|
-ConnectionUri <Uri[]>
|
-SessionOption [<PSSessionOption>]
|
<CommonParameters>
|
Inputs
None
You cannot pipe input to this cmdlet.
Outputs
System.Management.Automation.Runspaces.PSSession
Examples
- Get sessions created in the current session:
PS C:> Get-PSSession
This command gets all of the PSSessions that were created in the current session. It does not get PSSessions that were created in other sessions or on other computers, even if they connect to this computer.
- Get sessions connected to the local computer:
PS C:> Get-PSSession -ComputerName "localhost"
This command gets the PSSessions that are connected to the local computer. To indicate the local computer, type the computer name, localhost, or a dot (.)
The command returns all of the sessions on the local computer, even if they were created in different sessions or on different computers.
- Get sessions connected to a computer:
PS C:> Get-PSSession -ComputerName "Server02" Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 2 Session3 Server02 Disconnected ITTasks Busy 1 ScheduledJobs Server02 Opened Microsoft.PowerShell Available 3 Test Server02 Disconnected Microsoft.PowerShell Busy
This command gets the PSSessions that are connected to the Server02 computer.
The command returns all of the sessions on Server02, even if they were created in different sessions or on different computers.
The output shows that two of the sessions have a Disconnected state and a Busy availability. They were created in different sessions and are currently in use. The ScheduledJobs session, which is Opened and Available, was created in the current session.
- Save results of this command:
PS C:> New-PSSession -ComputerName Server01, Server02, Server03 PS C:> $s1, $s2, $s3 = Get-PSSession
This example shows how to save the results of a Get-PSSession command in multiple variables.
The first command uses the New-PSSession cmdlet to create PSSessions on three remote computers.
The second command uses a Get-PSSession cmdlet to get the three PSSessions. It then saves each of the PSSessions in a separate variable.
When Windows PowerShell assigns an array of objects to an array of variables, it assigns the first object to the first variable, the second object to the second variable, and so on. If there are more objects than variables, it assigns all remaining objects to the last variable in the array. If there are more variables than objects, the extra variables are not used.
- Delete a session by using an instance ID:
PS C:> Get-PSSession | Format-Table -Property ComputerName, InstanceID PS C:> $s = Get-PSSession -InstanceID a786be29-a6bb-40da-80fb-782c67f7db0f PS C:> Remove-PSSession -Session $s
This example shows how to get a PSSession by using its instance ID, and then to delete the PSSession.
The first command gets all of the PSSessions that were created in the current session. It sends the PSSessions to the Format-Table cmdlet, which displays the ComputerName and InstanceID properties of each PSSession.
The second command uses the Get-PSSession cmdlet to get a particular PSSession and to save it in the $s variable. The command uses the InstanceID parameter to identify the PSSession.
The third command uses the Remove-PSSession cmdlet to delete the PSSession in the $s variable.
- Get a session that has a particular name:
- The first command gets sessions on the Server02 and Server12 remote computers that have names that begin with BackupJob and use the ITTasks session configuration.The command uses the Name parameter to specify the name pattern and the ConfigurationName parameter to specify the session configuration:
PS C:> Get-PSSession -ComputerName Server02, Server12 -Name BackupJob* -ConfigurationName ITTasks -SessionOption @{OperationTimeout=240000} Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 3 BackupJob04 Server02 Disconnected ITTasks None
The value of the SessionOption parameter is a hash table that sets the value of the OperationTimeout to 240000 milliseconds (4 minutes). This setting gives the command more time to complete.The ConfigurationName and SessionOption parameters are used to configure the temporary sessions in which the Get-PSSession cmdlet runs on each computer.The output shows that the command returns the BackupJob04 session. The session is disconnected and the Availability is None, which indicates that it is not in use.
- The second command uses the Get-PSSession cmdlet to get to the BackupJob04 session and the Connect-PSSession cmdlet to connect to the session:
PS C:> $s = Get-PSSession -ComputerName Server02 -Name BackupJob04 -ConfigurationName ITTasks | Connect-PSSession
The command saves the session in the $s variable.
- The third command gets the session in the $s variable:
PS C:> $s Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 5 BackupJob04 Server02 Opened ITTasks Available
The output shows that the Connect-PSSession command was successful. The session is in the Opened state and is available for use.The commands in this example find a session that has a particular name format and uses a particular session configuration and then connect to the session. You can use a command like this one to find a session in which a colleague started a task and connect to finish the task.
- The first command gets sessions on the Server02 and Server12 remote computers that have names that begin with BackupJob and use the ITTasks session configuration.The command uses the Name parameter to specify the name pattern and the ConfigurationName parameter to specify the session configuration:
- Get a session by using its ID:
PS C:> Get-PSSession -Id 2
This command gets the PSSession with ID 2. Because the value of the ID property is unique only in the current session, the Id parameter is valid only for local commands.
Additional Notes
This cmdlet gets user-managed sessions PSSession objects" such as those that are created by using the New-PSSession, Enter-PSSession, and Invoke-Command cmdlets. It does not get the system-managed session that is created when you start Windows PowerShell. Starting in Windows PowerShell 3.0, PSSession objects are stored on the computer that is at the server-side or receiving end of a connection. To get the sessions that are stored on the local computer or a remote computer, Windows PowerShell establishes a temporary session to the specified computer and runs query commands in the session. To get sessions that connect to a remote computer, use the ComputerName or ConnectionUri parameters to specify the remote computer. To filter the sessions that Get-PSSession gets, use the Name, ID, InstanceID, and State parameters. Use the remaining parameters to configure the temporary session that Get-PSSession uses. When you use the ComputerName or ConnectionUri parameters, Get-PSSession gets only sessions from computers running Windows PowerShell 3.0 and later versions of Windows PowerShell. The value of the State property of a PSSession 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 PSSession from the current 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 (http:// msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.runspaces.runspacestate(v=VS.85). aspx) in the MSDN library. For more information about the values of the Availability property of sessions, see RunspaceAvailability Enumeration (http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.runspaces.run spaceavailability(v=vs.85).aspx).
Related Links
Connect-PSSession
Disconnect-PSSession
Receive-PSSession
Enter-PSSession
Exit-PSSession
Invoke-Command
New-PSSession
Remove-PSSession