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>]

El cmdlet receive-PSSession de obtiene los resultados de los comandos que se ejecutan en sesiones de Windows PowerShell (PSSession) que se desconectaron. Si la sesión está conectada actualmente, Receive-PSSession obtiene los resultados de los comandos que se estaban ejecutando cuando se desconectaba la sesión. Si la sesión sigue desconectada, receive-PSSession se conecta a la sesión, reanuda los comandos suspendidos y obtiene los resultados de los comandos que se ejecutan en la sesión.

Puede usar un receive-PSSession de además de o en lugar de un comando Connect-PSSession. receive-PSSession puede conectarse a cualquier sesión desconectada o reconectada. Estos incluyen aquellos que se iniciaron en otras sesiones o en otros equipos.

receive-PSSession funciona en PSSessions que se desconectaron intencionadamente, como mediante el cmdlet Disconnect-PSSession o el inDisconnectedSession parámetro del cmdlet de Invoke-Command, o involuntariamente, como por una interrupción de la red.

Si usa el cmdlet Receive-PSSession para conectarse a una sesión en la que no se ejecutan ni suspenden comandos, Receive-PSSession se conecta a la sesión, pero no devuelve ningún resultado o error.

Para obtener más información sobre la característica Sesiones desconectadas, consulte about_Remote_Disconnected_Sessions.

Este cmdlet se introdujo en Windows PowerShell 3.0.

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

Este comando usa el cmdlet Receive-PSSession para conectarse a la sesión de ITTask en el equipo Server01 y obtener los resultados de los comandos que se estaban ejecutando en la sesión.

Dado que el comando no usa el parámetro OutTarget, los resultados aparecen en la línea de comandos.

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

Este comando obtiene los resultados de todos los comandos que se ejecutan en todas las sesiones desconectadas en los equipos Server01 y Server02.

Si alguna sesión no estaba desconectada o no ejecuta comandos, receive-PSSession no se conecta a la sesión y no devuelve ningún resultado o error.

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

Este comando usa el cmdlet Receive-PSSession para obtener los resultados de un script que se estaba ejecutando en la sesión de ITTask en el equipo Server01.

El comando usa los parámetros computerName y Name para identificar la sesión desconectada. Usa el parámetro OutTarget con un valor de Job para dirigir receive-PSSession para devolver los resultados como un trabajo y el parámetro JobName para especificar un nombre para el trabajo en la sesión reconectada.

El comando usa el parámetro Credential para ejecutar el comando Receive-PSSession mediante los permisos de un administrador de dominio.

La salida muestra que receive-PSSession devolvió los resultados como un trabajo en la sesión actual. Para obtener los resultados del trabajo, use un comando 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

En este ejemplo se usa el cmdlet Receive-PSSession para obtener los resultados de un trabajo después de que una interrupción de la red interrumpa una conexión de sesión. Windows PowerShell intenta volver a conectar automáticamente la sesión una vez cada segundo durante los próximos cuatro minutos y abandona el esfuerzo solo si se produce un error en todos los intentos del intervalo de cuatro minutos.

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

En este ejemplo se usa el cmdlet Receive-PSSession para volver a conectarse a las sesiones que se desconectaron intencionadamente y obtener los resultados de los trabajos que se estaban ejecutando en las sesiones.

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

En este ejemplo se muestra lo que sucede con un trabajo que se ejecuta en una sesión desconectada.

Este cmdlet admite los parámetros comunes: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction y -WarningVariable. Para obtener más información, vea about_CommonParameters.

Puede canalizar objetos de sesión, como los devueltos por el cmdlet Get-PSSession, a este cmdlet.

Puede canalizar identificadores de sesión a este cmdlet.

Puede canalizar los identificadores de instancia de las sesiones de este cmdlet.

Puede canalizar los nombres de sesión a este cmdlet.

Este cmdlet devuelve los resultados de los comandos que se ejecutaron en la sesión desconectada, si existe. Si el valor o el valor predeterminado del parámetro OutTarget es Job, Receive-PSSession devuelve un objeto de trabajo. De lo contrario, devuelve objetos que representan los resultados de ese comando.

• receive-PSSession obtiene resultados solo de las sesiones que se desconectaron. Solo las sesiones conectadas a equipos que ejecutan Windows PowerShell 3.0 o versiones posteriores solo se pueden desconectar y volver a conectar.

• Si los comandos que se estaban ejecutando en la sesión desconectada no generaron resultados o si los resultados ya se devolvieron a otra sesión, receive-PSSession no genera ninguna salida.

• El modo de almacenamiento en búfer de salida de una sesión determina cómo los comandos de la sesión administran la salida cuando se desconecta la sesión. Cuando el valor de la opción OutputBufferingMode de la sesión es Drop y el búfer de salida está lleno, el comando procede a eliminar la salida. receive-PSSession no puede recuperar esta salida. Para obtener más información sobre la opción de modo de almacenamiento en búfer de salida, consulte los temas de ayuda de los cmdlets New-PSSessionOption y New-PSTransportOption.

• No se puede cambiar el valor de tiempo de espera de inactividad de un PSSession de cuando se conecta al psSession de o recibe resultados. El parámetro SessionOption de receive-PSSession toma un objeto SessionOption que tiene un valor IdleTimeout. Sin embargo, el IdleTimeout valor del objeto sessionOption de y el IdleTimeout valor de la variable $PSSessionOption se omiten cuando se conecta a un PSSession o recibe resultados.

  Puede establecer y cambiar el tiempo de espera de inactividad de un psSession de al crear el PSSession, mediante el New-PSSession o cmdlets invoke-Command y cuando se desconecta del PSSession.

  La propiedad IdleTimeout de un PSSession es fundamental para las sesiones desconectadas, ya que determina cuánto tiempo se mantiene una sesión desconectada en el equipo remoto. Las sesiones desconectadas se consideran inactivas desde el momento en que se desconectan, incluso si los comandos se ejecutan en la sesión desconectada.

• Si inicia un trabajo de inicio en una sesión remota mediante el parámetro AsJob del cmdlet Invoke-Command, el objeto de trabajo se crea en la sesión actual, aunque el trabajo se ejecute en la sesión remota. Si desconecta la sesión remota, el objeto de trabajo de la sesión actual ahora está desconectado del trabajo. El objeto de trabajo todavía contiene los resultados devueltos a él, pero no recibe nuevos resultados del trabajo en la sesión desconectada.

  Si un cliente diferente se conecta a la sesión que contiene el trabajo en ejecución, los resultados que se entregaron al objeto de trabajo original en la sesión original no están disponibles en la sesión recién conectada. Solo los resultados que no se entregaron al objeto de trabajo original están disponibles en la sesión reconectada.

  Del mismo modo, si inicia un script en una sesión y, a continuación, se desconecta de la sesión, los resultados que el script entrega a la sesión antes de desconectar no están disponibles para otro cliente que se conecta a la sesión.

  Para evitar la pérdida de datos en sesiones que se van a desconectar, use el parámetro InDisconnectedSession del cmdlet Invoke-Command. Dado que este parámetro impide que los resultados se devuelvan a la sesión actual, todos los resultados están disponibles cuando se vuelve a conectar la sesión.

  También puede evitar la pérdida de datos mediante el cmdlet invoke-Command de para ejecutar un comando Start-Job en la sesión remota. En este caso, el objeto de trabajo se crea en la sesión remota. No puede usar el cmdlet Receive-PSSession para obtener los resultados del trabajo. En su lugar, use el cmdlet Connect-PSSession para conectarse a la sesión y, a continuación, use el cmdlet Invoke-Command para ejecutar un comando Receive-Job en la sesión.

• Cuando se desconecta una sesión que contiene un trabajo en ejecución y, a continuación, se vuelve a conectar, el objeto de trabajo original solo se reutiliza si el trabajo está desconectado y se vuelve a conectar a la misma sesión, y el comando para volver a conectarse no especifica un nuevo nombre de trabajo. Si se vuelve a conectar la sesión a otra sesión de cliente o se especifica un nuevo nombre de trabajo, Windows PowerShell crea un nuevo objeto de trabajo para la nueva sesión.

• Cuando se desconecta un PSSession, el estado de sesión es Desconectado y la disponibilidad es None.

  El valor de la propiedad Estado es relativo a la sesión actual. Por lo tanto, un valor de Disconnected significa que el psSession no está conectado a la sesión actual. Sin embargo, no significa que el psSession se desconecta de todas las sesiones. Puede estar conectado a otra sesión. Para determinar si puede conectarse o reconectarse a la sesión, utilice la propiedad Disponibilidad.

  Un valor de Disponibilidad de Ninguno indica que puede conectarse a la sesión. Un valor de Busy indica que no se puede conectar al de PSSession de porque está conectado a otra sesión.

  Para obtener más información sobre los valores de la propiedad state de de sesiones, vea RunspaceState Enumeration en MSDN Library.

  Para obtener más información sobre los valores de la propiedad availability de sesiones, vea RunspaceAvailability Enumeration.