Receive-PSSession

语法

Receive-PSSession
       [-Session] <PSSession>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Receive-PSSession
       [-Id] <Int32>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Receive-PSSession
       [-ComputerName] <String>
       [-ApplicationName <String>]
       [-ConfigurationName <String>]
       -Name <String>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-Port <Int32>]
       [-UseSSL]
       [-SessionOption <PSSessionOption>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Receive-PSSession
       [-ComputerName] <String>
       [-ApplicationName <String>]
       [-ConfigurationName <String>]
       -InstanceId <Guid>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-Port <Int32>]
       [-UseSSL]
       [-SessionOption <PSSessionOption>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Receive-PSSession
       [-ConfigurationName <String>]
       [-ConnectionUri] <Uri>
       [-AllowRedirection]
       -Name <String>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-SessionOption <PSSessionOption>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Receive-PSSession
       [-ConfigurationName <String>]
       [-ConnectionUri] <Uri>
       [-AllowRedirection]
       -InstanceId <Guid>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-SessionOption <PSSessionOption>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Receive-PSSession
       -InstanceId <Guid>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Receive-PSSession
       -Name <String>
       [-OutTarget <OutTarget>]
       [-JobName <String>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

说明

此 cmdlet 仅在 Windows 平台上可用。

Receive-PSSession cmdlet 获取在 PowerShell 会话（PSSession）中运行的命令的结果，这些命令已断开连接。 如果会话当前已连接，Receive-PSSession 获取会话断开连接时正在运行的命令的结果。 如果会话仍然断开连接，Receive-PSSession 连接到会话，恢复挂起的任何命令，并获取会话中运行的命令的结果。

PowerShell 3.0 中引入了此 cmdlet。

除了或而不是 Connect-PSSession 命令外，还可以使用 Receive-PSSession。 Receive-PSSession 可以连接到在其他会话或其他计算机上启动的任何断开连接或重新连接的会话。

Receive-PSSession 适用于有意使用 Disconnect-PSSession cmdlet 或 Invoke-CommandInDisconnectedSession 参数断开连接的 PSSession。 或者无意中因网络中断而断开连接。

如果使用 Receive-PSSession cmdlet 连接到没有运行或挂起命令的会话，Receive-PSSession 连接到会话，但不会返回任何输出或错误。

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

一些示例使用喷洒来减少行长并提高可读性。 有关详细信息，请参阅 about_Splatting。

示例

示例 1：连接到 PSSession

此示例连接到远程计算机上的会话，并获取在会话中运行的命令的结果。

Receive-PSSession -ComputerName Server01 -Name ITTask

Receive-PSSession 使用 ComputerName 参数指定远程计算机。 Name 参数标识 Server01 计算机上的 ITTask 会话。 该示例获取 ITTask 会话中运行的命令的结果。

由于该命令不使用 OutTarget 参数，因此结果将显示在命令行上。

示例 2：获取断开连接会话上所有命令的结果

此示例获取两台远程计算机上所有断开连接会话中运行的所有命令的结果。

如果任何会话未断开连接或未运行命令，Receive-PSSession 不会连接到会话，也不会返回任何输出或错误。

Get-PSSession -ComputerName Server01, Server02 | Receive-PSSession

Get-PSSession 使用 ComputerName 参数指定远程计算机。 对象将向下发送到管道以 Receive-PSSession。

示例 3：获取会话中运行的脚本的结果

此示例使用 Receive-PSSession cmdlet 获取远程计算机会话中运行的脚本的结果。

$parms = @{
  ComputerName = "Server01"
  Name = "ITTask"
  OutTarget = "Job"
  JobName = "ITTaskJob01"
  Credential = "Domain01\Admin01"
}
Receive-PSSession @parms

Id     Name            State         HasMoreData     Location
--     ----            -----         -----------     --------
16     ITTaskJob01     Running       True            Server01

该命令使用 ComputerName 和 Name 参数来标识断开连接的会话。 它使用具有 Job 值的 OutTarget 参数来指示 Receive-PSSession 将结果作为作业返回。 JobName 参数指定重新连接会话中作业的名称。 Credential 参数使用域管理员的权限运行 Receive-PSSession 命令。

输出显示，Receive-PSSession 在当前会话中以作业的形式返回结果。 若要获取作业结果，请使用 Receive-Job 命令

示例 4：在网络中断后获取结果

此示例使用 Receive-PSSession cmdlet 在网络中断中断会话连接后获取作业的结果。 PowerShell 在接下来的四分钟内自动尝试每秒重新连接会话一次，并且仅当四分钟间隔中的所有尝试失败时才放弃该工作。

PS> $s = New-PSSession -ComputerName Server01 -Name AD -ConfigurationName ADEndpoint
PS> $s

Id  Name   ComputerName    State        ConfigurationName     Availability
--  ----   ------------    -----        -----------------     ------------
8   AD      Server01       Opened       ADEndpoint               Available


PS> Invoke-Command -Session $s -FilePath \\Server12\Scripts\SharedScripts\New-ADResolve.ps1

Running "New-ADResolve.ps1"

# Network outage
# Restart local computer
# Network access is not re-established within 4 minutes


PS> Get-PSSession -ComputerName Server01

Id  Name   ComputerName    State          ConfigurationName      Availability
--  ----   ------------    -----          -----------------      ------------
1  Backup  Server01        Disconnected   Microsoft.PowerShell           None
8  AD      Server01        Disconnected   ADEndpoint                     None


PS> Receive-PSSession -ComputerName Server01 -Name AD -OutTarget Job -JobName AD

Job Id   Name      State         HasMoreData     Location
--       ----      -----         -----------     --------
16       ADJob     Running       True            Server01


PS> Get-PSSession -ComputerName Server01

Id  Name    ComputerName    State         ConfigurationName     Availability
--  ----    ------------    -----         -----------------     ------------
1  Backup   Server01        Disconnected  Microsoft.PowerShell          Busy
8  AD       Server01        Opened        ADEndpoint               Available

New-PSSession cmdlet 在 Server01 计算机上创建会话，并将会话保存在 $s 变量中。 $s 变量显示打开 状态，可用性 可用。 这些值指示已连接到会话，并且可以在会话中运行命令。

Invoke-Command cmdlet 在 $s 变量中的会话中运行脚本。 脚本开始运行并返回数据，但发生网络中断会中断会话。 用户必须退出会话并重启本地计算机。

计算机重启时，用户启动 PowerShell 并运行 Get-PSSession 命令，以获取 Server01 计算机上的会话。 输出显示 Server01 计算机上仍然存在 AD 会话。 状态 指示 AD 会话已断开连接。 可用性 值为 None，指示会话未连接到任何客户端会话。

Receive-PSSession cmdlet 重新连接到 AD 会话，并获取在会话中运行的脚本的结果。 该命令使用 OutTarget 参数在名为 ADJob的作业中请求结果。 该命令返回作业对象，输出指示脚本仍在运行。

Get-PSSession cmdlet 用于检查作业状态。 输出确认 Receive-PSSession cmdlet 已重新连接到 AD 会话，该会话现已打开并可用于命令。 并且，脚本恢复执行，并正在获取脚本结果。

示例 5：重新连接到断开连接的会话

此示例使用 Receive-PSSession cmdlet 重新连接到有意断开连接的会话，并获取在会话中运行的作业的结果。

PS> $parms = @{
      InDisconnectedSession = $True
      ComputerName = "Server01", "Server02", "Server30"
      FilePath = "\\Server12\Scripts\SharedScripts\Get-BugStatus.ps1"
      Name = "BugStatus"
      SessionOption = @{IdleTimeout = 86400000}
      ConfigurationName = "ITTasks"
    }
PS> Invoke-Command @parms
PS> Exit


PS> $s = Get-PSSession -ComputerName Server01, Server02, Server30 -Name BugStatus
PS> $s

Id  Name   ComputerName    State         ConfigurationName     Availability
--  ----   ------------    -----         -----------------     ------------
1  ITTask  Server01        Disconnected  ITTasks                       None
8  ITTask  Server02        Disconnected  ITTasks                       None
2  ITTask  Server30        Disconnected  ITTasks                       None


PS> $Results = Receive-PSSession -Session $s
PS> $s

Id  Name   ComputerName    State         ConfigurationName     Availability
--  ----   ------------    -----         -----------------     ------------
1  ITTask  Server01        Opened        ITTasks                  Available
8  ITTask  Server02        Opened        ITTasks                  Available
2  ITTask  Server30        Opened        ITTasks                  Available


PS> $Results

Bug Report - Domain 01
----------------------
ComputerName          BugCount          LastUpdated
--------------        ---------         ------------
Server01              121               Friday, December 30, 2011 5:03:34 PM

Invoke-Command cmdlet 在三台远程计算机上运行脚本。 由于脚本收集并汇总了来自多个数据库的数据，因此脚本通常需要较长时间才能完成。 该命令使用 InDisconnectedSession 参数来启动脚本，然后立即断开会话的连接。 SessionOption 参数扩展断开连接会话的 IdleTimeout 值。 断开连接的会话从断开连接的那一刻起被视为空闲。 必须设置足够长的时间空闲超时，以便命令可以完成，并且可以重新连接到会话。 仅当创建 PSSession 时，才能设置 IdleTimeout，并且仅在与 PSSession 断开连接时才更改它。 连接到 PSSession 或接收其结果时，无法更改 IdleTimeout 值。 运行此命令后，用户退出 PowerShell 并关闭计算机。

第二天，用户恢复 Windows，启动 PowerShell，并使用 Get-PSSession 获取运行脚本的会话。 该命令按计算机名称、会话名称和会话配置的名称标识会话，并将会话保存在 $s 变量中。 将显示 $s 变量的值，并显示会话已断开连接，但不会忙。

Receive-PSSession cmdlet 连接到 $s 变量中的会话并获取其结果。 该命令将结果保存在 $Results 变量中。 将显示 $s 变量，并显示会话已连接并可用于命令。

脚本结果 $Results 变量显示在 PowerShell 控制台中。 如果任何结果都意外，用户可以在会话中运行命令来调查根本原因。

示例 6：在断开连接的会话中运行作业

此示例显示了在断开连接的会话中运行的作业会发生什么情况。

PS> $s = New-PSSession -ComputerName Server01 -Name Test
PS> $j = Invoke-Command -Session $s { 1..1500 | Foreach-Object {"Return $_"; sleep 30}} -AsJob
PS> $j

Id     Name           State         HasMoreData     Location
--     ----           -----         -----------     --------
16     Job1           Running       True            Server01


PS> $s | Disconnect-PSSession

Id Name   ComputerName    State         ConfigurationName     Availability
-- ----   ------------    -----         -----------------     ------------
1  Test   Server01        Disconnected  Microsoft.PowerShell          None


PS> $j

Id     Name           State         HasMoreData     Location
--     ----           -----         -----------     --------
16     Job1           Disconnected  True            Server01


PS> Receive-Job $j -Keep

Return 1
Return 2


PS> $s2 = Connect-PSSession -ComputerName Server01 -Name Test
PS> $j2 = Receive-PSSession -ComputerName Server01 -Name Test
PS> Receive-Job $j

Return 3
Return 4

New-PSSession cmdlet 在 Server01 计算机上创建测试会话。 该命令将会话保存在 $s 变量中。

Invoke-Command cmdlet 在 $s 变量中的会话中运行命令。 该命令使用 AsJob 参数将命令作为作业运行，并在当前会话中创建作业对象。 该命令返回保存在 $j 变量中的作业对象。 $j 变量显示作业对象。

$s 变量中的会话对象将向下发送到管道，以 Disconnect-PSSession 会话断开连接。

将显示 $j 变量，并显示断开 $j 变量中作业对象断开连接的效果。 作业状态现在已断开连接。

Receive-Job 在 $j 变量中的作业上运行。 输出显示作业在会话之前开始返回输出，作业已断开连接。

Connect-PSSession cmdlet 在同一客户端会话中运行。 该命令重新连接到 Server01 计算机上的测试会话，并将会话保存在 $s2 变量中。

Receive-PSSession cmdlet 获取在会话中运行的作业的结果。 由于该命令在同一会话中运行，因此默认情况下 Receive-PSSession 以作业的形式返回结果，并重复使用相同的作业对象。 该命令将作业保存在 $j2 变量中。 Receive-Job cmdlet 获取 $j 变量中作业的结果。

参数

-AllowRedirection

-ApplicationName

-Authentication

-CertificateThumbprint

-ComputerName

-ConfigurationName

-Confirm

-ConnectionUri

-Credential

-Id

-InstanceId

-JobName

-Name

-OutTarget

-Port

-Session

-SessionOption

-UseSSL

-WhatIf

输入

PSSession

可以通过管道将会话对象传递给此 cmdlet，例如 Get-PSSession cmdlet 返回的对象。

Int32

可以通过管道将会话 ID 传递给此 cmdlet。

Guid

可以通过管道传递此 cmdlet 的会话实例 ID。

String

可以通过管道将会话名称传递给此 cmdlet。

输出

Job

如果 OutTarget 参数的值或默认值 Job，则 Receive-PSSession 返回作业对象。

PSObject

此 cmdlet 返回在断开连接的会话中运行的命令的结果（如果有）。

备注

PowerShell 包含以下 Receive-PSSession别名：

• 所有平台：
  • rcsn

此 cmdlet 仅在 Windows 平台上可用。

Receive-PSSession 仅从已断开连接的会话获取结果。 只有连接到或终止运行 PowerShell 3.0 或更高版本的计算机的会话才能断开连接并重新连接。

如果在断开连接的会话中运行的命令未生成结果，或者结果已返回到另一个会话，Receive-PSSession 不会生成任何输出。

会话的输出缓冲模式确定会话中的命令在会话断开连接时如何管理输出。 当会话的 OutputBufferingMode 选项为 Drop 且输出缓冲区已满时，命令将开始删除输出。 Receive-PSSession 无法恢复此输出。 有关输出缓冲模式选项的详细信息，请参阅有关 New-PSSessionOption 和 New-PSTransportOption cmdlet 的帮助文章。

连接到 PSSession 或接收结果时，无法更改 PSSession 的空闲超时值。 Receive-PSSession 的 SessionOption 参数采用具有 IdleTimeout 值的 SessionOption 对象。 但是，SessionOption 对象的 IdleTimeout 值，当 变量连接到 PSSession 或接收结果时，将忽略 IdleTimeout 值。

• 通过使用 New-PSSession 或 Invoke-Command cmdlet，以及断开与 PSSession的连接，可以在创建 PSSession时设置和更改 PSSession 的空闲超时。
• PSSession 的 IdleTimeout 属性对于断开连接的会话至关重要，因为它决定了在远程计算机上维护断开连接的会话的时间。 即使命令在断开连接的会话中运行，断开连接的会话也被视为空闲。

如果使用 Invoke-Command cmdlet 的 AsJob 参数在远程会话中启动作业，则会在当前会话中创建作业对象，即使作业在远程会话中运行也是如此。 如果断开远程会话的连接，则当前会话中的作业对象与作业断开连接。 作业对象包含返回给它的任何结果，但不会从断开连接的会话中的作业接收新结果。

如果其他客户端连接到包含正在运行的作业的会话，则原始会话中传递到原始作业对象的结果在新连接的会话中不可用。 重新连接会话中仅提供未传递到原始作业对象的结果。

同样，如果在会话中启动脚本，然后与会话断开连接，则脚本在断开连接之前传递到会话的任何结果都不适用于连接到会话的另一个客户端。

若要防止要断开连接的会话中数据丢失，请使用 Invoke-Command cmdlet 的 InDisconnectedSession 参数。 由于此参数可防止结果返回到当前会话，因此当重新连接会话时，所有结果都可用。

还可以通过使用 Invoke-Command cmdlet 在远程会话中运行 Start-Job 命令来防止数据丢失。 在这种情况下，作业对象是在远程会话中创建的。 不能使用 Receive-PSSession cmdlet 获取作业结果。 请改用 Connect-PSSession cmdlet 连接到会话，然后使用 Invoke-Command cmdlet 在会话中运行 Receive-Job 命令。

当包含正在运行的作业的会话断开连接并重新连接时，仅当作业断开连接并重新连接到同一会话时，才会重复使用原始作业对象，而要重新连接的命令不会指定新的作业名称。 如果会话重新连接到其他客户端会话或指定了新的作业名称，PowerShell 将为新会话创建新的作业对象。

断开 PSSession时，会话状态为“已断开连接”，可用性为“无”。

• State 属性的值相对于当前会话。 “已断开连接”值表示 PSSession 未连接到当前会话。 但是，这并不意味着 PSSession 已与所有会话断开连接。 它可能连接到其他会话。 若要确定是否可以连接或重新连接到会话，请使用 Availability 属性。
• “无”可用性 值表示可以连接到会话。 “忙碌”值表示无法连接到 PSSession，因为它已连接到另一个会话。
• 有关会话的 State 属性的值的详细信息，请参阅 RunspaceState。
• 有关会话 可用性 属性的值的详细信息，请参阅 RunspaceAvailability。

相关链接

• about_PSSessions
• about_Remote
• about_Remote_Disconnected_Sessions
• about_Session_Configurations
• Connect-PSSession
• Enter-PSSession
• Exit-PSSession
• Get-PSSession
• Invoke-Command
• New-PSSession
• New-PSSessionOption
• New-PSTransportOption
• Remove-PSSession