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>
    -Name <String>
    [-ApplicationName <String>]
    [-ConfigurationName <String>]
    [-OutTarget <OutTarget>]
    [-JobName <String>]
    [-Credential <PSCredential>]
    [-Authentication <AuthenticationMechanism>]
    [-CertificateThumbprint <String>]
    [-Port <Int32>]
    [-UseSSL]
    [-SessionOption <PSSessionOption>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

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

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

Receive-PSSession
    [-ConnectionUri] <Uri>
    -Name <String>
    [-ConfigurationName <String>]
    [-AllowRedirection]
    [-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>]

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

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

Receive-PSSession 适用于有意断开连接的 PSSession，例如，使用 Invoke-Command cmdlet 的 Disconnect-PSSession cmdlet 或 InDisconnectedSession 参数，或者无意间中断网络。

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

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

此 cmdlet 已在 Windows PowerShell 3.0 中引入。

PS C:\> Receive-PSSession -ComputerName Server01 -Name ITTask

此命令使用 Receive-PSSession cmdlet 连接到 Server01 计算机上的 ITTask 会话，并获取在会话中运行的命令的结果。

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

PS C:\> Get-PSSession -ComputerName Server01, Server02 | Receive-PSSession

此命令获取 Server01 和 Server02 计算机上所有断开连接会话中运行的所有命令的结果。

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

PS C:\> Receive-PSSession -ComputerName Server01 -Name ITTask -OutTarget Job -JobName ITTaskJob01 -Credential Domain01\Admin01
Id     Name            State         HasMoreData     Location
--     ----            -----         -----------     --------
16     ITTaskJob01     Running       True            Server01

此命令使用 Receive-PSSession cmdlet 获取在 Server01 计算机上的 ITTask 会话中运行的脚本的结果。

该命令使用 ComputerName 和 Name 参数来标识断开连接的会话。 它使用具有 Job 值的 OutTarget 参数来指示 Receive-PSSession 以作业的形式返回结果，JobName 参数在重新连接会话中指定作业的名称。

该命令使用 Credential 参数通过域管理员的权限运行 Receive-PSSession 命令。

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

The first command uses the New-PSSession cmdlet to create a session on the Server01 computer. The command saves the session in the $s variable.The second command gets the session in the $s variable. Notice that the **State** is Opened and the **Availability** is Available. These values indicate that you are connected to the session and can run commands in the session.
PS C:\> $s = New-PSSession -ComputerName Server01 -Name AD -ConfigurationName ADEndpoint
PS C:\> $s

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

The third command uses the Invoke-Command cmdlet to run a script in the session in the $s variable.The script begins to run and return data, but a network outage occurs that interrupts the session. The user has to exit the session and restart the local computer.
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

When the computer restarts, the user starts Windows PowerShell and runs a Get-PSSession command to get sessions on the Server01 computer. The output shows that the AD session still exists on the Server01 computer. The **State** indicates that it is disconnected and the **Availability** value, None, indicates that it is not connected to any client sessions.
PS C:\> Get-PSSession -ComputerName Server01

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


The fifth command uses the **Receive-PSSession** cmdlet to reconnect to the AD session and get the results of the script that ran in the session. The command uses the *OutTarget* parameter to request the results in a job named ADJob.The command returns a job object. The output indicates that the script is still running.
PS C:\> Receive-PSSession -ComputerName Server01 -Name AD -OutTarget Job -JobName AD
Job Id     Name      State         HasMoreData     Location
--     ----      -----         -----------     --------
16     ADJob     Running       True            Server01

The sixth command uses the Get-PSSession cmdlet to check the job state. The output confirms that, in addition to resuming script execution and getting the script results, the **Receive-PSSession** cmdlet reconnected to the AD session, which is now open and available for commands.
PS C:\> Get-PSSession -ComputerName Server01
Id Name    ComputerName    State         ConfigurationName     Availability
-- ----    ------------    -----         -----------------     ------------
 1 Backup  Server01        Disconnected  Microsoft.PowerShell          Busy
 8 AD      Server01        Opened        ADEndpoint                Available

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

The first command uses the Invoke-Command cmdlet to run a script on the three remote computers. Because the scripts gathers and summarize data from multiple databases, it often takes the script an extended time to finish. The command uses the *InDisconnectedSession* parameter, which starts the scripts and then immediately disconnects the sessions.The command uses the *SessionOption* parameter to extend the **IdleTimeout** value of the disconnected session. Disconnected sessions are considered to be idle from the moment they are disconnected, so it is important to set the idle time-out for long enough that the commands can complete and you can reconnect to the session, if necessary. You can set the **IdleTimeout** only when you create the **PSSession** and change it only when you disconnect from it. You cannot change the **IdleTimeout** value when you connect to a **PSSession** or receiving its results.After running the command, the user exits Windows PowerShell and closes the computer .
PS C:\> Invoke-Command -InDisconnectedSession -ComputerName Server01, Server02, Server30 -FilePath \\Server12\Scripts\SharedScripts\Get-BugStatus.ps1 -Name BugStatus -SessionOption @{IdleTimeout = 86400000} -ConfigurationName ITTasks# Exit

# Start Windows PowerShell on a different computer.

On the next day, the user resumes Windows and starts Windows PowerShell. The second command uses the Get-PSSession cmdlet to get the sessions in which the scripts were running. The command identifies the sessions by the computer name, session name, and the name of the session configuration and saves the sessions in the $s variable.The third command displays the value of the $s variable. The output shows that the sessions are disconnected, but not busy, as expected.
PS C:\> $s = Get-PSSession -ComputerName Server01, Server02, Server30 -Name BugStatus
 PS C:\> $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


The fourth command uses the **Receive-PSSession** cmdlet to connect to the sessions in the $s variable and get their results. The command saves the results in the $Results variable.Another display of the $s variable shows that the sessions are connected and available for commands.
PS C:\> $Results = Receive-PSSession -Session $s
PS C:\> $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


The fifth command displays the script results in the $Results variable. If any of the results are unexpected, the user can run commands in the sessions to investigate.
PS C:\> $Results
Bug Report - Domain 01
----------------------
ComputerName          BugCount          LastUpdated
--------------        ---------         ------------
Server01              121               Friday, December 30, 2011 5:03:34 PM

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

The first command uses the New-PSSession cmdlet to create the Test session on the Server01 computer. The command saves the session in the $s variable.
PS C:\> $s = New-PSSession -ComputerName Server01 -Name Test

The second command uses the Invoke-Command cmdlet to run a command in the session in the $s variable. The command uses the *AsJob* parameter to run the command as a job and to create the job object in the current session. The command returns a job object, which is saved in the $j variable.The third command displays the job object in the $j variable.
PS C:\> $j = Invoke-Command -Session $s { 1..1500 | Foreach-Object {"Return $_"; sleep 30}} -AsJob

PS C:\> $j
Id     Name           State         HasMoreData     Location
--     ----           -----         -----------     --------
16     Job1           Running       True            Server01

The fourth command disconnects the session in the $s variable.
PS C:\> $s | Disconnect-PSSession
Id Name   ComputerName    State         ConfigurationName     Availability
-- ----   ------------    -----         -----------------     ------------
1  Test   Server01        Disconnected  Microsoft.PowerShell  None

The fifth command shows the effect of disconnecting on the job object in the $j variable. The job state is now Disconnected.
PS C:\> $j
Id     Name           State         HasMoreData     Location
--     ----           -----         -----------     --------
16     Job1           Disconnected  True            Server01

The sixth command runs a Receive-Job command on the job in the $j variable. The output shows that the job began to return output before the session and the job were disconnected.
PS C:\> Receive-Job $j -Keep
Return 1
Return 2

The seventh command is run in the same client session. The command uses the Connect-PSSession cmdlet to reconnect to the Test session on the Server01 computer and saves the session in the $s2 variable.
PS C:\> $s2 = Connect-PSSession -ComputerName Server01 -Name Test

The eighth command uses the **Receive-PSSession** cmdlet to get the results of the job that was running in the session. Because the command is run in the same session, **Receive-PSSession** returns the results as a job by default and reuses the same job object. The command saves the job in the $j2 variable.The ninth command uses the **Receive-Job** cmdlet to get the results of the job in the $j variable.
PS C:\> $j2 = Receive-PSSession -ComputerName Server01 -Name Test

PS C:\> Receive-Job $j
Return 3
Return 4

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

此 cmdlet 支持通用参数：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 有关详细信息，请参阅 about_CommonParameters。

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

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

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

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

此 cmdlet 返回在断开连接的会话中运行的命令的结果（如果有）。 如果 OutTarget 参数的值或默认值为 Job，Receive-PSSession 返回作业对象。 否则，它将返回表示该命令结果的对象。

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

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

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

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

  使用 New-PSSession 或 Invoke-Command cmdlet，在创建 PSSession时 ，可以使用 New-PSSession 或 Invoke-Command cmdlet 设置和更改 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 命令。

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

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

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

  当可用性 的值为“无”时，表示可以连接到会话。 “忙碌”值表示无法连接到 PSSession，因为它已连接到另一个会话。

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

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