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

L’applet de commande receive-PSSession obtient les résultats des commandes exécutées dans les sessions Windows PowerShell (PSSession) qui ont été déconnectées. Si la session est actuellement connectée, receive-PSSession obtient les résultats des commandes en cours d’exécution lorsque la session a été déconnectée. Si la session est toujours déconnectée, receive-PSSession se connecte à la session, reprend toutes les commandes qui ont été suspendues et obtient les résultats des commandes en cours d’exécution dans la session.

Vous pouvez utiliser un receive-PSSession en plus ou au lieu d’une commande Connect-PSSession. Receive-PSSession peut se connecter à n’importe quelle session déconnectée ou reconnectée. Celles-ci incluent celles qui ont été démarrées dans d’autres sessions ou sur d’autres ordinateurs.

receive-PSSession fonctionne sur psSessions qui ont été déconnectés intentionnellement, par exemple à l’aide de l’applet de commande Disconnect-PSSession ou du paramètre InDisconnectedSession de l’applet de commande Invoke-Command, ou involontairement, par une interruption réseau.

Si vous utilisez l’applet de commande Receive-PSSession pour vous connecter à une session dans laquelle aucune commande n’est en cours d’exécution ou suspendue, Receive-PSSession se connecte à la session, mais ne retourne aucune sortie ou erreur.

Pour plus d’informations sur la fonctionnalité Sessions déconnectées, consultez about_Remote_Disconnected_Sessions.

Cette applet de commande a été introduite dans Windows PowerShell 3.0.

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

Cette commande utilise l’applet de commande Receive-PSSession pour se connecter à la session ITTask sur l’ordinateur Server01 et obtenir les résultats des commandes qui s’exécutaient dans la session.

Étant donné que la commande n’utilise pas le paramètre OutTarget, les résultats apparaissent sur la ligne de commande.

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

Cette commande obtient les résultats de toutes les commandes exécutées dans toutes les sessions déconnectées sur les ordinateurs Server01 et Server02.

Si une session n’a pas été déconnectée ou n’exécute pas de commandes, Receive-PSSession ne se connecte pas à la session et ne retourne aucune sortie ni erreur.

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

Cette commande utilise l’applet de commande Receive-PSSession pour obtenir les résultats d’un script qui s’exécutait dans la session ITTask sur l’ordinateur Server01.

La commande utilise les paramètres Nom_ordinateur et Name pour identifier la session déconnectée. Il utilise le paramètre OutTarget avec la valeur Job pour diriger Receive-PSSession pour retourner les résultats en tant que travail et le paramètre JobName pour spécifier un nom pour le travail dans la session reconnectée.

La commande utilise le paramètre Credential pour exécuter la commande Receive-PSSession à l’aide des autorisations d’un administrateur de domaine.

La sortie indique que Receive-PSSession renvoyé les résultats sous la forme d’un travail dans la session active. Pour obtenir les résultats du travail, utilisez une commande 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

Cet exemple utilise l’applet de commande receive-PSSession pour obtenir les résultats d’un travail après une panne réseau interrompt une connexion de session. Windows PowerShell tente automatiquement de reconnecter la session une fois par seconde pour les quatre minutes suivantes et abandonne l’effort uniquement si toutes les tentatives de l’intervalle de quatre minutes échouent.

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

Cet exemple utilise l’applet de commande Receive-PSSession pour se reconnecter aux sessions qui ont été intentionnellement déconnectées et obtenir les résultats des travaux qui s’exécutaient dans les sessions.

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

Cet exemple montre ce qui arrive à un travail en cours d’exécution dans une session déconnectée.

Cette applet de commande prend en charge les paramètres courants : -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction et -WarningVariable. Pour plus d’informations, consultez about_CommonParameters.

Vous pouvez diriger des objets de session, tels que ceux retournés par l’applet de commande Get-PSSession, vers cette applet de commande.

Vous pouvez diriger les ID de session vers cette applet de commande.

Vous pouvez diriger les ID d’instance des sessions de cette applet de commande.

Vous pouvez diriger les noms de session vers cette applet de commande.

Cette applet de commande retourne les résultats des commandes exécutées dans la session déconnectée, le cas échéant. Si la valeur ou la valeur par défaut du paramètre OutTarget est Job, receive-PSSession retourne un objet de travail. Sinon, elle retourne des objets qui représentent ces résultats de commande.

• receive-PSSession obtient les résultats uniquement des sessions qui ont été déconnectées. Seules les sessions connectées à des ordinateurs qui exécutent Windows PowerShell 3.0 ou version ultérieure peuvent être déconnectées et reconnectées.

• Si les commandes en cours d’exécution dans la session déconnectée n’ont pas généré de résultats ou si les résultats ont déjà été retournés à une autre session, receive-PSSession ne génère aucune sortie.

• Le mode de mise en mémoire tampon de sortie d’une session détermine comment les commandes de la session gèrent la sortie lorsque la session est déconnectée. Lorsque la valeur de l’option OutputBufferingMode de la session est Drop et que la mémoire tampon de sortie est pleine, la commande commence à supprimer la sortie. receive-PSSession ne peut pas récupérer cette sortie. Pour plus d’informations sur l’option mode de mise en mémoire tampon de sortie, consultez les rubriques d’aide relatives aux applets de commande New-PSSessionOption et New-PSTransportOption.

• Vous ne pouvez pas modifier la valeur de délai d’inactivité d’une PSSession lorsque vous vous connectez au PSSession ou recevez des résultats. Le paramètre sessionOption de Receive-PSSession prend un objet SessionOption qui a une valeur IdleTimeout. Toutefois, la valeur IdleTimeout de l’objet SessionOption et la valeur IdleTimeout de la variable $PSSessionOption sont ignorées lorsqu’elle se connecte à un PSSession ou reçoit des résultats.

  Vous pouvez définir et modifier le délai d’inactivité d’une PSSession lorsque vous créez le PSSession, à l’aide des applets de commande New-PSSession ou Invoke-Command, et lorsque vous vous déconnectez desPSSession .

  La propriété IdleTimeout d’un PSSession est essentielle pour les sessions déconnectées, car elle détermine la durée pendant laquelle une session déconnectée est conservée sur l’ordinateur distant. Les sessions déconnectées sont considérées comme inactives à partir du moment où elles sont déconnectées, même si les commandes s’exécutent dans la session déconnectée.

• Si vous démarrez un travail de démarrage dans une session distante à l’aide du paramètre AsJob de l’applet de commande Invoke-Command , l’objet de travail est créé dans la session active, même si le travail s’exécute dans la session distante. Si vous déconnectez la session distante, l’objet de travail de la session active est maintenant déconnecté du travail. L’objet de travail contient toujours les résultats retournés à celui-ci, mais il ne reçoit pas de nouveaux résultats du travail dans la session déconnectée.

  Si un autre client se connecte à la session qui contient le travail en cours d’exécution, les résultats remis à l’objet de travail d’origine dans la session d’origine ne sont pas disponibles dans la session nouvellement connectée. Seuls les résultats qui n’ont pas été remis à l’objet de travail d’origine sont disponibles dans la session reconnectée.

  De même, si vous démarrez un script dans une session, puis déconnectez-vous de la session, les résultats que le script remet à la session avant la déconnexion ne sont pas disponibles pour un autre client qui se connecte à la session.

  Pour éviter la perte de données dans les sessions que vous envisagez de déconnecter, utilisez le paramètre InDisconnectedSession de l’applet de commande Invoke-Command . Étant donné que ce paramètre empêche les résultats d’être retournés à la session active, tous les résultats sont disponibles lorsque la session est reconnectée.

  Vous pouvez également empêcher la perte de données à l’aide de l’applet de commande Invoke-Command pour exécuter une commande Start-Job dans la session à distance. Dans ce cas, l’objet de travail est créé dans la session distante. Vous ne pouvez pas utiliser l’applet de commande receive-PSSession pour obtenir les résultats du travail. Utilisez plutôt l’applet de commande Connect-PSSession pour vous connecter à la session, puis utilisez l’applet de commande Invoke-Command pour exécuter une commande Receive-Job dans la session.

• Lorsqu’une session qui contient un travail en cours d’exécution est déconnectée, puis reconnectée, l’objet de travail d’origine est réutilisé uniquement si le travail est déconnecté et reconnecté à la même session, et que la commande à reconnecter ne spécifie pas de nouveau nom de travail. Si la session est reconnectée à une autre session cliente ou qu’un nouveau nom de travail est spécifié, Windows PowerShell crée un objet de travail pour la nouvelle session.

• Lorsque vous déconnectez une PSSession, l’état de session est Déconnecté et la disponibilité est nulle.

  La valeur de la propriété State est relative à la session active. Par conséquent, une valeur de Disconnected signifie que le PSSession n’est pas connecté à la session active. Toutefois, cela ne signifie pas que le PSSession est déconnecté de toutes les sessions. Il peut être connecté à une autre session. Pour déterminer si vous pouvez vous connecter ou vous reconnecter à la session, utilisez la propriété Availability.

  La valeur de disponibilité None indique que vous pouvez vous connecter à la session. La valeur Busy indique que vous ne pouvez pas vous connecter au PSSession , car elle est connectée à une autre session.

  Pour plus d’informations sur les valeurs de la propriété State des sessions, consultez 'énumération RunspaceState dans la bibliothèque MSDN.

  Pour plus d’informations sur les valeurs de la propriété Availability des sessions, consultez 'énumération RunspaceAvailability.