Connect-PSSession

重新连接到已断开连接的会话。

语法

Connect-PSSession
       -Name <String[]>
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       [-Session] <PSSession[]>
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       [-ComputerName] <String[]>
       [-ApplicationName <String>]
       [-ConfigurationName <String>]
       [-Name <String[]>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-Port <Int32>]
       [-UseSSL]
       [-SessionOption <PSSessionOption>]
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       [-ComputerName] <String[]>
       [-ApplicationName <String>]
       [-ConfigurationName <String>]
       -InstanceId <Guid[]>
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-Port <Int32>]
       [-UseSSL]
       [-SessionOption <PSSessionOption>]
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       [-ConfigurationName <String>]
       [-ConnectionUri] <Uri[]>
       [-AllowRedirection]
       [-Name <String[]>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-SessionOption <PSSessionOption>]
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       [-ConfigurationName <String>]
       [-ConnectionUri] <Uri[]>
       [-AllowRedirection]
       -InstanceId <Guid[]>
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-SessionOption <PSSessionOption>]
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       -InstanceId <Guid[]>
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       [-ThrottleLimit <Int32>]
       [-Id] <Int32[]>
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

说明

Connect-PSSession cmdlet 可重新连接到已断开连接的用户托管的 PowerShell 会话(PSSessions)。 它可用于有意断开连接的会话(例如通过使用 Disconnect-PSSession cmdlet 或 Invoke-Command cmdlet 的 InDisconnectedSession 参数)和无意断开连接的会话(例如由于临时网络故障)。

Connect-PSSession 可以连接到同一用户启动的任何断开连接的会话。 其中包括从其他计算机上的其他会话启动或断开连接的会话。

但是,Connect-PSSession 无法连接到中断或关闭的会话或者使用 Enter-PSSession cmdlet 启动的交互式会话。 此外,也无法将会话连接到由其他用户启动的会话,除非你能提供创建会话的用户的凭据。

有关断开连接会话功能的详细信息,请参阅 about_Remote_Disconnected_Sessions

此 cmdlet 是在 Windows PowerShell 3.0 中引入的。

示例

示例 1:重新连接到会话

Connect-PSSession -ComputerName Server01 -Name ITTask

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 4 ITTask          Server01        Opened        ITTasks                  Available

此命令重新连接到 Server01 计算机上的 ITTask 会话。

该输出显示此命令已成功。 该会话的 StateOpened,AvailabilityAvailable,指示你可以在该会话中运行命令。

示例 2:断开连接和重新连接的效果

Get-PSSession

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 Backups         Localhost       Opened        Microsoft.PowerShell     Available

Get-PSSession | Disconnect-PSSession

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 Backups         Localhost       Disconnected  Microsoft.PowerShell          None

Get-PSSession | Connect-PSSession

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 Backups         Localhost       Opened        Microsoft.PowerShell     Available

此示例显示了断开某一会话的连接又重新连接到该会话的效果。

第一个命令使用 Get-PSSession cmdlet。 在没有 ComputerName 参数的情况下,该命令仅获取已在当前会话中创建的会话。

输出显示命令获取本地计算机上的 Backups 会话。 该会话的 StateOpened,AvailabilityAvailable

第二个命令使用 Get-PSSession cmdlet 获取已在当前会话中创建的 PSSession 对象,并使用 Disconnect-PSSession cmdlet 断开会话的连接。 输出显示 Backups 会话已断开连接。 该会话的 StateDisconnected,AvailabilityNone

第三个命令使用 Get-PSSession cmdlet 获取已在当前会话中创建的 PSSession 对象,并使用 Connect-PSSession cmdlet 重新连接会话。 输出显示已重新连接 Backups 会话。 该会话的 StateOpened,AvailabilityAvailable

如果在未断开连接的会话上使用 Connect-PSSession cmdlet,该命令不会影响会话,也不会生成任何错误。

示例 3:企业方案中的一系列命令

此系列命令演示如何在企业方案中使用 Connect-PSSession cmdlet。 在此示例中,系统管理员将在远程计算机上的会话中启动长时间运行的作业。 启动该作业后,管理员将断开与该会话的连接,然后下班回家。 当晚晚些时候,管理员登录到她的主计算机,并验证作业是否运行,直到作业完成。

管理员首先在远程计算机上创建会话并在会话中运行脚本。第一个命令使用 New-PSSession cmdlet 在 Server01 远程计算机上创建 ITTask 会话。 该命令使用 ConfigurationName 参数来指定 ITTasks 会话配置。 该命令将会话保存在 $s 变量中。

第二个命令使用 Invoke-Command cmdlet 在 $s 变量中的会话中启动后台作业。 它使用 FilePath 参数在后台作业中运行脚本。

第三个命令使用 Disconnect-PSSession cmdlet 与 $s 变量中的会话断开连接。 该命令使用值为 Drop 的 OutputBufferingMode 参数以防止该脚本被阻止,因为必须将输出传递给该会话。 它使用 IdleTimeoutSec 参数将会话超时扩展到 15 小时。 完成该命令后,管理员锁定自己的计算机,然后晚上下班回家。

当晚,管理员启动自己家中的计算机、登录到公司网络,然后启动 PowerShell。 第四个命令使用 Get-PSSession cmdlet 获取 Server01 计算机上的会话。 该命令查找 ITTask 会话。 第五个命令使用 Connect-PSSession cmdlet 连接到 ITTask 会话。 该命令将该会话保存在 $s 变量中。

第六个命令使用 Invoke-Command cmdlet 在 $s 变量中的会话中运行 Get-Job 命令。 输出显示作业已成功完成。第七个命令使用 Invoke-Command cmdlet 在会话中的 $s 变量的会话中运行 Receive-Job 命令。 该命令将结果保存在 $BackupSpecs 变量中。第八个命令使用 Invoke-Command cmdlet 在会话中运行另一个脚本。 该命令使用会话中 $BackupSpecs 变量的值作为脚本的输入。

$s = New-PSSession -ComputerName Server01 -Name ITTask -ConfigurationName ITTasks
Invoke-Command -Session $s -ScriptBlock {Start-Job -FilePath \\Server30\Scripts\Backup-SQLDatabase.ps1}

Id     Name            State         HasMoreData     Location             Command
--     ----            -----         -----------     --------             -------
2      Job2            Running       True            Server01             \\Server30\Scripts\Backup...

Disconnect-PSSession -Session $s -OutputBufferingMode Drop -IdleTimeoutSec 60*60*15

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 ITTask          Server01        Disconnected  ITTasks               None

Get-PSSession -ComputerName Server01 -Name ITTask

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 ITTask          Server01        Disconnected  ITTasks               None

$s = Connect-PSSession -ComputerName Server01 -Name ITTask

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 ITTask          Server01        Opened        ITTasks               Available

Invoke-Command -Session $s -ScriptBlock {Get-Job}

Id     Name            State         HasMoreData     Location             Command
--     ----            -----         -----------     --------             -------
2      Job2            Completed     True            Server01             \\Server30\Scripts\Backup...

Invoke-Command -Session $s -ScriptBlock {$BackupSpecs = Receive-Job -JobName Job2}
Invoke-Command -Session $s -ScriptBlock {\\Server30\Scripts\New-SQLDatabase.ps1 -InitData $BackupSpecs.Initialization}
Disconnect-PSSession -Session $s -OutputBufferingMode Drop -IdleTimeoutSec 60*60*15

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 ITTask          Server01        Disconnected  ITTasks               None

第九个命令与 $s 变量中的会话断开连接。管理员关闭 PowerShell 并关闭计算机。 她可以在第二天重新连接到会话,并检查工作计算机上的脚本状态。

参数

-AllowRedirection

指示此 cmdlet 允许将此连接重定向到备用 URI。

使用 ConnectionURI 参数时,远程目标将返回一个指令,以重定向到不同的 URI。 默认情况下,PowerShell 不会重定向连接,但你可以使用此参数允许它重定向连接。

也可以通过更改 MaximumConnectionRedirectionCount 会话选项值,限制重定向连接的次数。 使用 New-PSSessionOption cmdlet 的 MaximumRedirection 参数或设置 $PSSessionOption 首选项变量的 MaximumConnectionRedirectionCount 属性。 默认值为 5

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

-ApplicationName

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

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

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

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

-Authentication

指定在用于重新连接到断开连接的会话的命令中,用于对用户凭据进行身份验证的机制。 此参数的可接受值为:

  • Default
  • Basic
  • Credssp
  • Digest
  • Kerberos
  • Negotiate
  • NegotiateWithImplicitCredential

默认值为 Default

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

注意

在凭据安全支持提供程序 (CredSSP) 身份验证中,用户凭据传递到远程计算机中进行验证,这种验证用于要求对多个资源进行验证的命令(例如访问远程网络共享时使用的命令)。 此机制增加了远程操作的安全风险。 如果远程计算机的安全受到威胁,则传递给该计算机的凭据可用于控制网络会话。

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

-CertificateThumbprint

指定有权连接到断开连接的会话的用户帐户的数字公钥证书 (X509)。 输入证书的证书指纹。

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

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

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

-ComputerName

指定在其中存储断开连接的会话的计算机。 会话存储在位于连接的服务器端或接收端的计算机上。 默认为本地计算机。

键入计算机的 NetBIOS 名称、IP 地址或完全限定的域名。 不允许使用通配符。 若要指定本地计算机,请键入计算机名称 localhost 或点 (.)

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

-ConfigurationName

只连接到使用指定会话配置的会话。

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

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

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

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

-Confirm

提示你在运行 cmdlet 之前进行确认。

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

-ConnectionUri

为断开连接的会话指定连接终结点的 URI。

URI 必须完全限定。 此字符串的格式如下:

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

默认值如下:

http://localhost:5985/WSMAN

如果未指定连接 URI,可以使用 UseSSLPort 参数指定连接 URI 值。

URI 的 Transport 段的有效值为 HTTP 和 HTTPS。 如果使用传输段指定连接 URI,但不指定端口,将使用以下标准端口来创建会话:80 用于 HTTP,443 用于 HTTPS。 若要使用 PowerShell 远程处理的默认端口,请指定端口 5985 用于 HTTP,或端口 5986 用于 HTTPS。

如果目标计算机将连接重定向到另一个 URI,PowerShell 将阻止重定向,除非在命令中使用 AllowRedirection 参数。

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

-Credential

指定有权连接到断开连接的会话的用户帐户。 默认为当前用户。

键入用户名(如 User01Domain01\User01),或输入 Get-Credential cmdlet 生成的 PSCredential 对象。 如果键入用户名,系统会提示输入密码。

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

注意

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

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

-Id

指定断开连接的会话的 ID。 ID 参数只有在断开的会话之前连接到当前会话时才起作用。

如果会话存储在本地计算机上,但未连接到当前会话,则此参数是有效的,但并未生效。

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

-InstanceId

指定断开连接的会话的实例 ID。

实例 ID 是一个 GUID,用于唯一标识本地或远程计算机上的 PSSession

实例 ID 存储在 PSSession 的 InstanceID 属性中

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

-Name

指定断开连接的会话的友好名称。

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

-Port

指定远程计算机上用于重新连接到会话的网络端口。 若要连接到一台远程计算机,则必须在该连接所用的端口上侦听远程计算机。 默认端口为 HTTP 的 WinRM 端口 5985 和 HTTPS 的 WinRM 端口 5986

使用备用端口之前,你必须在远程计算机上配置 WinRM 侦听器,才能在该端口上进行侦听。 若要配置侦听器,请在 PowerShell 提示符下键入以下两个命令:

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

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

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

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

-Session

指定断开连接的会话。 输入包含 PSSession 对象的变量,或者用于创建或获取 PSSession 对象的命令,例如 Get-PSSession 命令。

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

-SessionOption

为该会话指定高级选项。 输入 SessionOption 对象(例如使用 New-PSSessionOption cmdlet 创建的对象),或输入哈希表,其中的键是会话选项名称,而值是会话选项值。

这些选项的默认值由 $PSSessionOption 首选项变量的值(如果已设置)确定。 否则,通过在会话配置中设置的选项创建默认值。

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

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

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

-ThrottleLimit

指定为运行此命令可建立的并发连接的最大数目。 如果省略此参数或输入 0 值,则使用默认值 32

节流限制仅适用于当前命令,而不适用于会话或计算机。

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

-UseSSL

指示此 cmdlet 使用安全套接字层 (SSL) 协议连接到断开连接的会话。 默认情况下,不使用 SSL。

WS-Management 对通过网络传输的所有 PowerShell 内容进行加密。 UseSSL 参数是一种额外的保护措施,它通过 HTTPS 连接而不是 HTTP 连接来发送数据。

如果使用此参数,但 SSL 在用于命令的端口上不可用,则命令将失败。

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

-WhatIf

显示运行该 cmdlet 时会发生什么情况。 cmdlet 未运行。

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

输入

PSSession

可以通过管道将会话 (PSSession) 传递给此 cmdlet。

输出

PSSession

此 cmdlet 返回一个对象,该对象表示其重新连接到的会话。

备注

Windows PowerShell 包含 Connect-PSSession 的以下别名:

  • cnsn

  • 此 cmdlet 仅在 Windows 平台上可用。

  • Connect-PSSession 仅重新连接到断开连接的会话,即 State 属性的值为 Disconnected 的会话。 只有连接到或结束于运行 Windows PowerShell 3.0 或更高版本的计算机的会话才能断开连接并重新连接。

  • 如果在未断开连接的会话上使用 Connect-PSSession,则该命令不会影响会话,也不会生成任何错误。

  • 断开连接的具有交互式令牌(使用 EnableNetworkAccess 参数创建的令牌)的环回会话只能通过创建该会话的计算机重新连接。 此限制可使计算机免遭恶意访问。

  • PSSession 的 State 属性值相对于当前会话。 因此,值 Disconnected 意味着 PSSession 未连接到当前会话。 但是,这并不意味着 PSSession 已与所有会话断开连接。 它可能连接到另一个会话。 若要确定是否可以连接或重新连接到该会话,请使用 Disconnected 属性。

    Availability 的值为 None,指示可连接到会话。 值 Busy 指示无法连接 PSSession,因为它已连接另一个会话。

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

    有关会话 Availability 属性的值的详细信息,请参阅 RunspaceAvailability 枚举

  • 连接到 PSSession 后,无法更改 PSSession 的空闲超时值。 Connect-PSSession 的 SessionOption 参数采用具有 IdleTimeout 值的 SessionOption 对象。 但是,在连接到 PSSession 时,将忽略 SessionOption 对象的 IdleTimeout 值和 $PSSessionOption 变量的 IdleTimeout 值

    可以在创建 PSSession(通过使用 New-PSSessionInvoke-Command cmdlet)以及断开与 PSSession 的连接时,设置和更改 PSSession 的空闲超时。

    PSSession 的 IdleTimeout 属性对于断开连接的会话至关重要,因为它确定在远程计算机上维护断开连接的会话的时间。 断开连接的会话从其断开连接的时刻起就被视为空闲,即使命令正在断开连接的会话中运行也是如此。