Get-PSSession

Gets the Windows PowerShell sessions (PSSessions) in the current session.

Syntax

Get-PSSession [[-ComputerName] <string[]>] [<CommonParameters>]

Get-PSSession [-Id] <Int32[]> [<CommonParameters>]

Get-PSSession [-InstanceId <Guid[]>] [<CommonParameters>]

Get-PSSession [-Name <string[]>] [<CommonParameters>]

Description

The Get-PSSession cmdlet gets the Windows PowerShell sessions (PSSessions) that were created in the current session.

Without parameters, Get-PSSession gets all of the PSSessions created in the current session. You can use the parameters of Get-PSSession to get the sessions that are connected to particular computers, or you can identify sessions by their names, IDs, or instance IDs.

For more information about Windows PowerShell sessions, see about_PSSessions.

Parameters

-ComputerName <string[]>

Gets only the PSSessions that are connected to the specified computers. Wildcards are permitted.

Type the NetBIOS name, an IP address, or a fully-qualified domain name of one or more computers. To specify the local computer, type the computer name, "localhost", or a dot (.).

Required?	false
Position?	1
Default Value	none
Accept Pipeline Input?	true (ByPropertyName)
Accept Wildcard Characters?	true

-Id <Int32[]>

Gets only the PSSessions with the specified IDs. Type one or more IDs (separated by commas), or use the range operator (..) to specify a range of IDs.

An ID is an integer that uniquely identifies the PSSession in the current session. It is easier to remember and type than the InstanceId, but it is unique only within the current session. To find the ID of a PSSession, use Get-PSSession without parameters.

Required?	true
Position?	1
Default Value	All sessions in the shell
Accept Pipeline Input?	true (ByPropertyName)
Accept Wildcard Characters?	false

-InstanceId <Guid[]>

Gets only the PSSessions with the specified instance IDs.

The instance ID is a GUID that uniquely identifies a PSSession on a local or remote computer. The InstanceID is unique, even when you have multiple sessions running in Windows PowerShell.

The InstanceID is stored in the InstanceID property of the object that represents a PSSession. To find the InstanceID of the PSSessions in the current session, type "get-pssession | Format-Table Name, ComputerName, InstanceId".

Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	true (ByPropertyName)
Accept Wildcard Characters?	true

-Name <string[]>

Gets only the PSSessions with the specified friendly names. Wildcards are permitted.

To find the names of the PSSessions in the current session, type "get-pssession" without parameters.

Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	true (ByPropertyName)
Accept Wildcard Characters?	true

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see about_CommonParameters.

Inputs and Outputs

The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns.

Inputs

None

You cannot pipe input to this cmdlet.

Outputs

System.Management.Automation.Runspaces.PSSession

Get-PSSession returns a PSSession object for each PSSession that it gets.

Notes

Get-PSSession gets the PSSessions that were created in the current session. It does not get the session that is created when you open Windows PowerShell, and it does not get PSSessions that were created in other sessions or on other computers, even if they connect to the local computer.

Example 1

C:\PS>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.

Example 2

C:\PS>$s = get-pssession -computername Server02

This command gets the PSSessions that are connected to the Server02 computer and saves them in the $p variable.

Example 3

C:\PS>new-pssession -computername Server01, Server02, Server03

C:\PS> $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.

Example 4

C:\PS>get-pssession | format-table -property computername, InstanceID

C:\PS> $s = get-pssession -InstanceID a786be29-a6bb-40da-80fb-782c67f7db0f

C:\PS> 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 on the local computer. 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.

Example 5

C:\PS>get-pssession -computername Serv*

This command gets all the PSSessions that connect to computers that have computer names that begin with "Serv".

Example 6

C:\PS>get-pssession -name Test*, Ux*

This command gets PSSessions that have names that begin with "Test" or "Ux".

Example 7

C:\PS>get-pssession 2

This command gets the PSSession with ID 2.