Get-PSSession

模块:

Microsoft.PowerShell.Core

获取本地和远程计算机上的 PowerShell 会话。

语法

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

Get-PSSession
   [-ComputerName] <String[]>
   [-ApplicationName <String>]
   [-ConfigurationName <String>]
   [-Name <String[]>]
   [-Credential <PSCredential>]
   [-Authentication <AuthenticationMechanism>]
   [-CertificateThumbprint <String>]
   [-Port <Int32>]
   [-UseSSL]
   [-ThrottleLimit <Int32>]
   [-State <SessionFilterState>]
   [-SessionOption <PSSessionOption>]
   [<CommonParameters>]

Get-PSSession
   [-ComputerName] <String[]>
   [-ApplicationName <String>]
   [-ConfigurationName <String>]
   -InstanceId <Guid[]>
   [-Credential <PSCredential>]
   [-Authentication <AuthenticationMechanism>]
   [-CertificateThumbprint <String>]
   [-Port <Int32>]
   [-UseSSL]
   [-ThrottleLimit <Int32>]
   [-State <SessionFilterState>]
   [-SessionOption <PSSessionOption>]
   [<CommonParameters>]

Get-PSSession
   [-ConnectionUri] <Uri[]>
   [-ConfigurationName <String>]
   [-AllowRedirection]
   [-Name <String[]>]
   [-Credential <PSCredential>]
   [-Authentication <AuthenticationMechanism>]
   [-CertificateThumbprint <String>]
   [-ThrottleLimit <Int32>]
   [-State <SessionFilterState>]
   [-SessionOption <PSSessionOption>]
   [<CommonParameters>]

Get-PSSession
   [-ConnectionUri] <Uri[]>
   [-ConfigurationName <String>]
   [-AllowRedirection]
   -InstanceId <Guid[]>
   [-Credential <PSCredential>]
   [-Authentication <AuthenticationMechanism>]
   [-CertificateThumbprint <String>]
   [-ThrottleLimit <Int32>]
   [-State <SessionFilterState>]
   [-SessionOption <PSSessionOption>]
   [<CommonParameters>]

Get-PSSession
   [-ConfigurationName <String>]
   -InstanceId <Guid[]>
   [-State <SessionFilterState>]
   -VMName <String[]>
   [<CommonParameters>]

Get-PSSession
   [-ConfigurationName <String>]
   [-Name <String[]>]
   [-State <SessionFilterState>]
   -ContainerId <String[]>
   [<CommonParameters>]

Get-PSSession
   [-ConfigurationName <String>]
   -InstanceId <Guid[]>
   [-State <SessionFilterState>]
   -ContainerId <String[]>
   [<CommonParameters>]

Get-PSSession
   [-ConfigurationName <String>]
   [-Name <String[]>]
   [-State <SessionFilterState>]
   -VMId <Guid[]>
   [<CommonParameters>]

Get-PSSession
   [-ConfigurationName <String>]
   -InstanceId <Guid[]>
   [-State <SessionFilterState>]
   -VMId <Guid[]>
   [<CommonParameters>]

Get-PSSession
   [-ConfigurationName <String>]
   [-Name <String[]>]
   [-State <SessionFilterState>]
   -VMName <String[]>
   [<CommonParameters>]

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

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

说明

Get-PSSession cmdlet 在本地和远程计算机上获取用户管理的 PowerShell 会话（PSSessions）。

从 Windows PowerShell 3.0 开始，会话存储在每个连接的远程端的计算机上。 可以使用 ComputerName 或 ConnectionUriGet-PSSession 参数来获取连接到本地计算机或远程计算机的会话，即使这些会话未在当前会话中创建。

如果没有参数，Get-PSSession 获取在当前会话中创建的所有会话。

使用筛选参数，包括 名称、ID、InstanceID、State、ApplicationName，以及 ConfigurationName 从 Get-PSSession 返回的会话中进行选择。

使用其余参数配置 Get-PSSession 命令在 ComputerName 或 ConnectionUri 参数时运行临时连接。

注意

在 Windows PowerShell 2.0 中，如果没有参数，Get-PSSession 获取在当前会话中创建的所有会话。 ComputerName 参数获取在当前会话中创建并连接到指定计算机的会话。

有关 PowerShell 会话的详细信息，请参阅 about_PSSessions。

示例

示例 1：获取在当前会话中创建的会话

Get-PSSession

此命令获取在当前会话中创建的所有 PSSessions。 它不会 在其他会话或其他计算机上创建的 PSSessions，即使它们连接到此计算机也是如此。

示例 2：获取连接到本地计算机的会话

Get-PSSession -ComputerName "localhost"

此命令获取连接到本地计算机的 PSSessions。 若要指示本地计算机，请键入计算机名称、localhost 或点（.）

该命令将返回本地计算机上的所有会话，即使这些会话是在不同会话或不同计算机上创建的。

示例 3：获取连接到计算机的会话

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

此命令获取连接到 Server02 计算机的 PSSessions。

该命令返回 Server02 上的所有会话，即使这些会话是在不同会话或不同计算机上创建的。

输出显示两个会话具有 Disconnected 状态和 Busy 可用性。 它们在不同的会话中创建，当前正在使用中。 在当前会话中创建 Opened 和 AvailableScheduledJobs 会话。

示例 4：保存此命令的结果

New-PSSession -ComputerName Server01, Server02, Server03
$s1, $s2, $s3 = Get-PSSession

此示例演示如何将 Get-PSSession 命令的结果保存在多个变量中。

第一个命令使用 New-PSSession cmdlet 在三台远程计算机上创建 PSSessions。

第二个命令使用 Get-PSSession cmdlet 获取三个 PSSessions。 然后，它将每个 PSSessions 保存在单独的变量中。

当 PowerShell 向变量数组分配对象数组时，它将第一个对象分配给第一个变量、第二个对象分配给第二个变量，依此类说。 如果对象多于变量，则会将所有剩余对象分配给数组中的最后一个变量。 如果变量多于对象，则不会使用额外的变量。

示例 5：使用实例 ID 删除会话

Get-PSSession | Format-Table -Property ComputerName, InstanceID
$s = Get-PSSession -InstanceID a786be29-a6bb-40da-80fb-782c67f7db0f
Remove-PSSession -Session $s

此示例演示如何使用其实例 ID 获取 PSSession，然后删除 PSSession。

第一个命令获取在当前会话中创建的所有 PSSessions。 它将 PSSessions 发送到 Format-Table cmdlet，该 cmdlet 显示每个 PSSession的 ComputerName 和 InstanceID 属性。

第二个命令使用 Get-PSSession cmdlet 获取特定的 PSSession，并将其保存在 $s 变量中。 该命令使用 InstanceID 参数来标识 PSSession。

第三个命令使用 Remove-PSSession cmdlet 删除 $s 变量中的 PSSession。

示例 6：获取具有特定名称的会话

此示例中的命令查找具有特定名称格式的会话，并使用特定的会话配置，然后连接到会话。 可以使用这样的命令来查找同事在其中启动任务并连接到完成任务的会话。

Get-PSSession -ComputerName Server02, Server12 -Name BackupJob* -ConfigurationName ITTasks -SessionOption @{OperationTimeout=240000}

Id Name            ComputerName    State         ConfigurationName     Availability
 -- ----            ------------    -----         -----------------     ------------
  3 BackupJob04     Server02        Disconnected        ITTasks                  None

$s = Get-PSSession -ComputerName Server02 -Name BackupJob04 -ConfigurationName ITTasks | Connect-PSSession
$s

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 5 BackupJob04     Server02        Opened        ITTasks                  Available

第一个命令获取 Server02 和 Server12 远程计算机上的会话，这些计算机的名称以 BackupJob 开头，并使用 ITTasks 会话配置。该命令使用 Name 参数来指定名称模式和 ConfigurationName 参数来指定会话配置。 SessionOption 参数的值是一个哈希表，用于将 OperationTimeout 的值设置为 240000 毫秒（4 分钟）。 此设置为命令提供了更多完成时间。ConfigurationName 和 SessionOption 参数用于配置每个计算机上运行 Get-PSSession cmdlet 的临时会话。输出显示命令返回 BackupJob04 会话。 会话已断开连接，可用性None，指示它未使用。

第二个命令使用 Get-PSSession cmdlet 访问 BackupJob04 会话，Connect-PSSession cmdlet 连接到会话。 该命令将会话保存在 $s 变量中。

第三个命令获取 $s 变量中的会话。 输出显示 Connect-PSSession 命令已成功。 会话处于 打开 状态，可供使用。

示例 7：使用会话 ID 获取会话

Get-PSSession -Id 2

此命令获取 ID 为 2的 PSSession。 由于 ID 属性的值仅在当前会话中是唯一的，因此 ID 参数仅对本地命令有效。

参数

-AllowRedirection

指示此 cmdlet 允许将此连接重定向到备用统一资源标识符（URI）。 默认情况下，PowerShell 不会重定向连接。

此参数配置创建的临时连接，以使用 ConnectionUri 参数运行 Get-PSSession 命令。

此参数是在 Windows PowerShell 3.0 中引入的。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-ApplicationName

指定应用程序的名称。 此 cmdlet 仅连接到使用指定应用程序的会话。

输入连接 URI 的应用程序名称段。 例如，在以下连接 URI 中，应用程序名称为 WSMan：http://localhost:5985/WSMAN。 会话的应用程序名称存储在会话的 Runspace.ConnectionInfo.AppName 属性中。

此参数的值用于选择和筛选会话。 它不会更改会话使用的应用程序。

类型:	String
Position:	Named
默认值:	All sessions
必需:	False
接受管道输入:	True
接受通配符:	False

-Authentication

指定用于对运行 Get-PSSession 命令的会话的凭据进行身份验证的机制。

此参数配置创建的临时连接，以使用 ComputerName 或 ConnectionUri 参数运行 Get-PSSession 命令。

此参数的可接受值为：

• Default
• Basic
• CredSSP
• Digest
• Kerberos
• Negotiate
• NegotiateWithImplicitCredential。

默认值为 Default。

有关此参数的值的详细信息，请参阅 AuthenticationMechanism 枚举。

谨慎

凭据安全支持提供程序（CredSSP）身份验证（其中用户凭据传递到要进行身份验证的远程计算机）旨在用于需要对多个资源进行身份验证的命令，例如访问远程网络共享。 此机制会增加远程作的安全风险。 如果远程计算机遭到入侵，则传递给它的凭据可用于控制网络会话。

此参数是在 Windows PowerShell 3.0 中引入的。

类型:	AuthenticationMechanism
接受的值:	Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:	Named
默认值:	Default
必需:	False
接受管道输入:	False
接受通配符:	False

-CertificateThumbprint

指定用户帐户的数字公钥证书（X509），该证书有权创建运行 Get-PSSession 命令的会话。 输入证书的证书指纹。

此参数配置创建的临时连接，以使用 ComputerName 或 ConnectionUri 参数运行 Get-PSSession 命令。

证书用于基于客户端证书的身份验证。 它们只能映射到本地用户帐户;它们不适用于域帐户。

若要获取证书指纹，请使用 PowerShell Cert: 驱动器中的 Get-Item 或 Get-ChildItem 命令。

此参数是在 Windows PowerShell 3.0 中引入的。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ComputerName

指定计算机名称数组。 获取连接到指定计算机的会话。 不允许使用通配符。 没有默认值。

从 Windows PowerShell 3.0 开始，PSSession 对象存储在每个连接的远程端的计算机上。 若要获取指定计算机上的会话，PowerShell 会创建与每台计算机的临时连接，并运行 Get-PSSession 命令。

键入 NetBIOS 名称、IP 地址或一个或多个计算机的完全限定域名。 若要指定本地计算机，请键入计算机名称、localhost或点（.）。

注意

此参数仅从运行 Windows PowerShell 3.0 或更高版本的 PowerShell 的计算机获取会话。 早期版本不存储会话。

类型:	String[]
别名:	Cn
Position:	0
默认值:	None
必需:	True
接受管道输入:	True
接受通配符:	False

-ConfigurationName

指定配置的名称。 此 cmdlet 仅获取使用指定会话配置的会话。

输入会话配置的配置名称或完全限定的资源 URI。 如果仅指定配置名称，则前面有以下架构 URI：http://schemas.microsoft.com/powershell。 会话的配置名称存储在会话的 ConfigurationName 属性中。

此参数的值用于选择和筛选会话。 它不会更改会话使用的会话配置。

有关会话配置的详细信息，请参阅 about_Session_Configurations。

类型:	String
Position:	Named
默认值:	All sessions
必需:	False
接受管道输入:	True
接受通配符:	False

-ConnectionUri

指定一个 URI，用于定义运行 Get-PSSession 命令的临时会话的连接终结点。 URI 必须完全限定。

此参数配置创建的临时连接，以使用 ConnectionUri 参数运行 Get-PSSession 命令。

此字符串的格式为：

<Transport>://<ComputerName>:<Port\>/<ApplicationName>

默认值为：http://localhost:5985/WSMAN。

如果未指定 ConnectionUri，则可以使用 UseSSL、ComputerName、Port和 ApplicationName 参数来指定 ConnectionURI 值。 URI 的传输段的有效值为 HTTP 和 HTTPS。 如果使用传输段指定连接 URI，但未指定端口，则会使用标准端口创建会话：80 HTTP 和 HTTPS 443。 若要使用 PowerShell 远程处理的默认端口，请为 HTTP 指定端口 5985，或为 HTTPS 指定端口 5986。

如果目标计算机将连接重定向到其他 URI，则 PowerShell 会阻止重定向，除非在命令中使用 AllowRedirection 参数。

此参数是在 Windows PowerShell 3.0 中引入的。

此参数仅从运行 Windows PowerShell 3.0 或更高版本的 Windows PowerShell 的计算机获取会话。 早期版本不存储会话。

类型:	Uri[]
别名:	URI, CU
Position:	0
默认值:	Http://localhost:5985/WSMAN
必需:	True
接受管道输入:	True
接受通配符:	False

-ContainerId

指定容器 ID 数组。 此 cmdlet 启动与每个指定容器的交互式会话。 使用 docker ps 命令获取容器 ID 的列表。 有关详细信息，请参阅 docker ps 命令的帮助。

类型:	String[]
Position:	Named
默认值:	None
必需:	True
接受管道输入:	True
接受通配符:	False

-Credential

指定用户凭据。 此 cmdlet 使用指定用户的权限运行命令。 指定有权连接到远程计算机的用户帐户，并运行 Get-PSSession 命令。 默认值为当前用户。

键入用户名（如 User01 或 Domain01\User01），或输入由 Get-Credential cmdlet 生成的 PSCredential 对象。 如果键入用户名，系统会提示输入密码。

凭据存储在 PSCredential 对象中，密码存储为 SecureString。

注意

有关 SecureString 数据保护的详细信息，请参阅 SecureString 的安全性如何？。

此参数配置为使用 ComputerName 或 ConnectionUri 参数运行 Get-PSSession 命令创建的临时连接。

此参数是在 Windows PowerShell 3.0 中引入的。

类型:	PSCredential
Position:	Named
默认值:	Current user
必需:	False
接受管道输入:	False
接受通配符:	False

-Id

指定会话 ID 数组。 此 cmdlet 仅获取具有指定 ID 的会话。 键入一个或多个 ID，用逗号分隔，或使用范围运算符（..）指定一系列 ID。 不能将 ID 参数与 ComputerName 参数一起使用。

ID 是一个整数，用于唯一标识当前会话中的用户托管会话。 它比 InstanceId更容易记住和键入，但它仅在当前会话中是唯一的。 会话的 ID 存储在会话的 ID 属性中。

类型:	Int32[]
Position:	0
默认值:	All sessions
必需:	True
接受管道输入:	True
接受通配符:	False

-InstanceId

指定会话实例 ID 的数组。 此 cmdlet 仅获取具有指定实例 ID 的会话。

实例 ID 是唯一标识本地或远程计算机上的会话的 GUID。 即使 PowerShell 中运行多个会话，InstanceID 也是唯一的。

会话的实例 ID 存储在会话的 InstanceID 属性中。

类型:	Guid[]
Position:	Named
默认值:	All sessions
必需:	False
接受管道输入:	False
接受通配符:	False

-Name

指定会话名称数组。 此 cmdlet 仅获取具有指定友好名称的会话。 允许使用通配符。

会话的友好名称存储在会话的 Name 属性中。

类型:	String[]
Position:	Named
默认值:	All sessions
必需:	False
接受管道输入:	True
接受通配符:	True

-Port

指定用于运行 Get-PSSession 命令的临时连接的指定网络端口。 若要连接到远程计算机，远程计算机必须侦听连接使用的端口。 默认端口为 5985，即 HTTP 的 WinRM 端口，5986，即 HTTPS 的 WinRM 端口。

在使用备用端口之前，必须在远程计算机上配置 WinRM 侦听器以侦听该端口。 若要配置侦听器，请在 PowerShell 提示符处键入以下两个命令：

Remove-Item -Path WSMan:\Localhost\listener\listener* -Recurse

New-Item -Path WSMan:\Localhost\listener -Transport http -Address * -Port \<port-number\>

此参数配置为使用 ComputerName 或 ConnectionUri 参数运行 Get-PSSession 命令创建的临时连接。

除非必须，否则不要使用 Port 参数。 命令中设置的 端口 适用于运行命令的所有计算机或会话。 备用端口设置可能会阻止命令在所有计算机上运行。

此参数是在 Windows PowerShell 3.0 中引入的。

类型:	Int32
Position:	Named
默认值:	5985, 5986
必需:	False
接受管道输入:	False
接受通配符:	False

-SessionOption

指定会话的高级选项。 输入 SessionOption 对象，例如使用 New-PSSessionOption cmdlet 创建的会话选项，或键是会话选项名称的哈希表，值是会话选项值。

选项的默认值由 $PSSessionOption 首选项变量的值（如果已设置）确定。 否则，默认值由会话配置中设置的选项建立。

会话选项值优先于在 $PSSessionOption 首选项变量和会话配置中设置的会话的默认值。 但是，它们不优先于会话配置中设置的最大值、配额或限制。

有关会话选项的说明（包括默认值）请参阅 New-PSSessionOption。 有关 $PSSessionOption 首选项变量的信息，请参阅 about_Preference_Variables。 有关会话配置的详细信息，请参阅 about_Session_Configurations。

类型:	PSSessionOption
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-State

指定会话状态。 此 cmdlet 仅获取处于指定状态的会话。 此参数的可接受值为：All、Opened、Disconnected、Closed和 Broken。 默认值为 All。

会话状态值相对于当前会话。 未在当前会话中创建且未连接到当前会话的会话的状态为 Disconnected，即使会话连接到其他会话也是如此。

会话的状态存储在会话的 State 属性中。

此参数是在 Windows PowerShell 3.0 中引入的。

类型:	SessionFilterState
接受的值:	All, Opened, Disconnected, Closed, Broken
Position:	Named
默认值:	All
必需:	False
接受管道输入:	False
接受通配符:	False

-ThrottleLimit

指定可以建立的最大并发连接数，以运行 Get-PSSession 命令。 如果省略此参数或输入值 0 （零），则使用默认值 32。 限制限制仅适用于当前命令，不适用于会话或计算机。

此参数是在 Windows PowerShell 3.0 中引入的。

类型:	Int32
Position:	Named
默认值:	32
必需:	False
接受管道输入:	False
接受通配符:	False

-UseSSL

指示此 cmdlet 使用安全套接字层 （SSL） 协议建立运行 Get-PSSession 命令的连接。 默认情况下，不使用 SSL。 如果使用此参数，但 SSL 在用于命令的端口上不可用，则命令将失败。

此参数配置创建的临时连接，以使用 ComputerName 参数运行 Get-PSSession 命令。

此参数是在 Windows PowerShell 3.0 中引入的。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-VMId

指定虚拟机的 ID 数组。 此 cmdlet 启动与每个指定虚拟机的交互式会话。 若要查看可用的虚拟机，请使用以下命令：

Get-VM | Select-Object -Property Name, ID

类型:	Guid[]
别名:	VMGuid
Position:	Named
默认值:	None
必需:	True
接受管道输入:	True
接受通配符:	False

-VMName

指定虚拟机的名称数组。 此 cmdlet 启动与每个指定虚拟机的交互式会话。 若要查看可用的虚拟机，请使用 Get-VM cmdlet。

类型:	String[]
Position:	Named
默认值:	None
必需:	True
接受管道输入:	True
接受通配符:	False

输入

None

不能通过管道将对象传递给此 cmdlet。

输出

PSSession

备注

PowerShell 包含以下 Get-PSSession别名：

• 所有平台：

  • gsn

• 此 cmdlet 获取用户管理的会话 PSSession 对象“，例如使用 New-PSSession、Enter-PSSession和 Invoke-Command cmdlet 创建的会话。 它不会获取启动 PowerShell 时创建的系统托管会话。

• 从 Windows PowerShell 3.0 开始，PSSession 对象存储在位于服务器端或接收连接的末尾的计算机上。 若要获取存储在本地计算机或远程计算机上的会话，PowerShell 会建立到指定计算机的临时会话，并在会话中运行查询命令。

• 若要获取连接到远程计算机的会话，请使用 ComputerName 或 ConnectionUri 参数来指定远程计算机。 若要筛选 Get-PSSession 获取的会话，请使用 名称、ID、InstanceID和 State 参数。 使用其余参数配置 Get-PSSession 使用的临时会话。

• 使用 ComputerName 或 ConnectionUri 参数时，Get-PSSession 仅从运行 Windows PowerShell 3.0 及更高版本的 PowerShell 的计算机获取会话。

• PSSession 的 State 属性的值相对于当前会话。 因此，断开连接 值表示 PSSession 未连接到当前会话。 但是，这并不意味着 PSSession 已与所有会话断开连接。 它可能连接到其他会话。 若要确定是否可以从当前会话连接到 PSSession，请使用 Availability 属性。

可用性 值 None 指示可以连接到会话。 忙碌 的值指示无法连接到 PSSession，因为它已连接到另一个会话。

有关会话的 State 属性的值的详细信息，请参阅 RunspaceState 枚举。

有关会话 可用性 属性的值的详细信息，请参阅 RunspaceAvailability 枚举。

相关链接

• Connect-PSSession
• Disconnect-PSSession
• Receive-PSSession
• Enter-PSSession
• Exit-PSSession
• Invoke-Command
• New-PSSession
• Remove-PSSession
• about_PSSessions
• about_Remote