Receive-PSSession

Référence

Module:: Microsoft.PowerShell.Core

Obtient les résultats des commandes dans les sessions déconnectées

Syntaxe

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

Description

Cette applet de commande est disponible uniquement sur la plateforme Windows.

L’applet de commande Receive-PSSession obtient les résultats des commandes exécutées dans des sessions 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 lors de la déconnexion de la session. 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.

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

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 qui a été démarrée dans d’autres sessions ou sur d’autres ordinateurs.

Receive-PSSessionfonctionne sur les sessions PSS qui ont été déconnectées intentionnellement à l'aide de la cmdlet Disconnect-PSSession ou du paramètre Invoke-CommandInDisconnectedSession. Ou déconnecté 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.

Certains exemples utilisent le splatting pour réduire la longueur des lignes et améliorer la lisibilité. Pour plus d'informations, consultez À propos de la projection.

Exemples

Exemple 1 : Se connecter à une session PSSession

Cet exemple se connecte à une session sur un ordinateur distant et obtient les résultats des commandes qui s’exécutent dans une session.

Receive-PSSession -ComputerName Server01 -Name ITTask

Le Receive-PSSession spécifie l’ordinateur distant avec le paramètre ComputerName. Le paramètre Name identifie la session ITTask sur l’ordinateur Server01. L’exemple obtient les résultats des commandes qui étaient en cours d’exécution dans la session ITTask.

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

Exemple 2 : Obtenir les résultats de toutes les commandes sur les sessions déconnectées

Cet exemple obtient les résultats de toutes les commandes exécutées dans toutes les sessions déconnectées sur deux ordinateurs distants.

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.

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

Get-PSSession utilise le paramètre ComputerName pour spécifier les ordinateurs distants. Les objets sont envoyés dans le pipeline vers Receive-PSSession.

Exemple 3 : Obtenir les résultats d’un script en cours d’exécution dans une session

Cet exemple utilise l’applet de commande Receive-PSSession pour obtenir les résultats d’un script qui s’exécutait dans la session d’un ordinateur distant.

$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

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 demander à Receive-PSSession de renvoyer les résultats sous la forme d'un travail. Le paramètre JobName spécifie un nom pour le travail dans la session reconnectée. Le paramètre Credential exécute la commande Receive-PSSession à l’aide des autorisations d’un administrateur de domaine.

La sortie montre que Receive-PSSession a renvoyé les résultats en tant que travail dans la session en cours. Pour obtenir les résultats du travail, utilisez une commande Receive-Job

Exemple 4 : Obtenir les résultats après une panne réseau

Cet exemple utilise l’applet de commande Receive-PSSession pour obtenir les résultats d’un travail après qu’une panne réseau interrompt une connexion de session. 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.

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

L’applet de commande New-PSSession crée une session sur l’ordinateur Server01 et enregistre la session dans la variable $s. La variable $s affiche que l'état est ouvert et que la disponibilité est disponible. Ces valeurs indiquent que vous êtes connecté à la session et que vous pouvez exécuter des commandes dans la session.

L’applet de commande Invoke-Command exécute un script dans la session dans la variable $s. Le script commence à exécuter et à retourner des données, mais une panne réseau se produit qui interrompt la session. L’utilisateur doit quitter la session et redémarrer l’ordinateur local.

Lorsque l’ordinateur redémarre, l’utilisateur démarre PowerShell et exécute une commande Get-PSSession pour obtenir des sessions sur l’ordinateur Server01. La sortie indique que la session AD existe toujours sur l’ordinateur Server01. L'état indique que la session AD est déconnectée. La valeur Availability none indique que la session n’est connectée à aucune session cliente.

L’applet de commande Receive-PSSession se reconnecte à la session AD et obtient les résultats du script exécuté dans la session. La commande utilise le paramètre OutTarget pour demander les résultats dans un travail nommé ADJob. La commande retourne un objet de travail et la sortie indique que le script est toujours en cours d’exécution.

L’applet de commande Get-PSSession est utilisée pour vérifier l’état du travail. La sortie confirme que l'applet de commande Receive-PSSession s'est reconnectée à la session AD, qui est désormais ouverte et prête pour recevoir des commandes. Le script a repris son exécution et obtient les résultats du script.

Exemple 5 : Reconnexion à des sessions déconnectées

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.

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

L’applet de commande Invoke-Command exécute un script sur trois ordinateurs distants. Étant donné que le script rassemble et récapitule les données de plusieurs bases de données, le script prend souvent un certain temps pour se terminer. La commande utilise le paramètre InDisconnectedSession qui démarre les scripts, puis déconnecte immédiatement les sessions. Le paramètre SessionOption étend la valeur IdleTimeout de la session déconnectée. Les sessions déconnectées sont considérées comme inactives à partir du moment où elles sont déconnectées. Il est important de définir le délai d’inactivité pendant suffisamment longtemps pour que les commandes puissent être terminées et que vous puissiez vous reconnecter à la session. Vous pouvez définir le IdleTimeout uniquement lorsque vous créez le PSSession et que vous le modifiez uniquement lorsque vous vous déconnectez de celui-ci. Vous ne pouvez pas modifier la valeur IdleTimeout lorsque vous vous connectez à un PSSession ni pour recevoir ses résultats. Après avoir exécuté la commande, l’utilisateur quitte PowerShell et ferme l’ordinateur.

Le lendemain, l’utilisateur reprend Windows, démarre PowerShell et utilise Get-PSSession pour obtenir les sessions dans lesquelles les scripts étaient en cours d’exécution. La commande identifie les sessions par le nom de l’ordinateur, le nom de session et le nom de la configuration de session et enregistre les sessions dans la variable $s. La valeur de la variable $s s’affiche et indique que les sessions sont déconnectées, mais ne sont pas occupées.

L’applet de commande Receive-PSSession se connecte aux sessions de la variable $s et obtient leurs résultats. La commande enregistre les résultats dans la variable $Results. La variable $s s’affiche et indique que les sessions sont connectées et disponibles pour les commandes.

Le script entraîne l’affichage de la variable $Results dans la console PowerShell. Si l’un des résultats est inattendu, l’utilisateur peut exécuter des commandes dans les sessions pour examiner la cause racine.

Exemple 6 : Exécution d’un travail dans une session déconnectée

Cet exemple montre ce qui arrive à un travail exécuté dans une session déconnectée.

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

L’applet de commande New-PSSession crée la session de test sur l’ordinateur Server01. La commande enregistre la session dans la variable $s.

L’applet de commande Invoke-Command exécute une commande dans la session dans la variable $s. La commande utilise le paramètre AsJob pour exécuter la commande en tant que travail et crée l’objet de travail dans la session active. La commande retourne un objet de travail enregistré dans la variable $j. La variable $j affiche l’objet de travail.

L’objet de session dans la variable $s est envoyé vers le bas du pipeline pour Disconnect-PSSession et la session est déconnectée.

La variable $j est affichée et montre l'effet de la déconnexion de l'objet de tâche dans la variable $j. L'état du travail est maintenant Déconnecté.

La commande Receive-Job est exécutée sur le travail dans la variable $j. La sortie montre que le travail a commencé à renvoyer des résultats avant que la session et le travail ne soient déconnectés.

L’applet de commande Connect-PSSession est exécutée dans la même session cliente. La commande se reconnecte à la session de test sur l’ordinateur Server01 et enregistre la session dans la variable $s2.

L’applet de commande Receive-PSSession obtient les résultats du travail en cours d’exécution dans la session. Étant donné que la commande est exécutée dans la même session, Receive-PSSession retourne les résultats sous forme de travail par défaut et réutilise le même objet de travail. La commande enregistre le travail dans la variable $j2. Le cmdlet Receive-Job obtient les résultats de la tâche dans la variable $j.

Paramètres

-AllowRedirection

Indique que cette applet de commande autorise la redirection de cette connexion vers un AUTRE URI (Uniform Resource Identifier).

Lorsque vous utilisez le paramètre ConnectionURI, la destination distante peut retourner une instruction pour rediriger vers un AUTRE URI. Par défaut, PowerShell ne redirige pas les connexions, mais vous pouvez utiliser ce paramètre pour l’activer pour rediriger la connexion.

Vous pouvez également limiter le nombre de fois où la connexion est redirigée en modifiant la valeur d’option de session MaximumConnectionRedirectionCount. Utilisez le paramètre MaximumRedirection de l’applet de commande New-PSSessionOption ou définissez la propriété MaximumConnectionRedirectionCount de la variable de préférence $PSSessionOption. La valeur par défaut est 5.

Type:	SwitchParameter
Position:	Named
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-ApplicationName

Spécifie une application. Cette applet de commande se connecte uniquement aux sessions qui utilisent l’application spécifiée.

Entrez le segment de nom d’application de l’URI de connexion. Par exemple, dans l’URI de connexion suivant, WSMan est le nom de l’application : http://localhost:5985/WSMAN.

Le nom de l’application d’une session est stocké dans la propriété Runspace.ConnectionInfo.AppName de la session.

La valeur du paramètre est utilisée pour sélectionner et filtrer des sessions. Elle ne modifie pas l’application utilisée par la session.

Type:	String
Position:	Named
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	True
Accepter les caractères génériques:	False

-Authentication

Spécifie le mécanisme utilisé pour authentifier les informations d’identification de l’utilisateur dans la commande pour se reconnecter à une session déconnectée. Les valeurs acceptables pour ce paramètre sont les suivantes :

Par défaut
De base
Credssp
Digérer
Kerberos
Négocier
NegotiateWithImplicitCredential

La valeur par défaut est Default.

Pour plus d'informations sur les valeurs de ce paramètre, voir AuthenticationMechanism Enumeration.

Attention

L’authentification CredSSP (Credential Security Support Provider), dans laquelle les informations d’identification de l’utilisateur sont transmises à un ordinateur distant à authentifier, est conçue pour les commandes qui nécessitent une authentification sur plusieurs ressources, telles que l’accès à un partage réseau distant. Ce mécanisme augmente le risque de sécurité de l’opération à distance. Si l’ordinateur distant est compromis, les informations d’identification qui lui sont transmises peuvent être utilisées pour contrôler la session réseau.

Type:	AuthenticationMechanism
Valeurs acceptées:	Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:	Named
Valeur par défaut:	Default
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-CertificateThumbprint

Spécifie le certificat de clé publique numérique (X509) d’un compte d’utilisateur autorisé à se connecter à la session déconnectée. Entrez l’empreinte numérique du certificat.

Les certificats sont utilisés dans l’authentification basée sur les certificats client. Les certificats ne peuvent être mappés qu’à des comptes d’utilisateur locaux et ne fonctionnent pas avec des comptes de domaine.

Pour obtenir une empreinte numérique de certificat, utilisez une commande Get-Item ou Get-ChildItem dans le lecteur powerShell Cert:.

Type:	String
Position:	Named
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-ComputerName

Spécifie l’ordinateur sur lequel la session déconnectée est stockée. Les sessions sont stockées sur l'ordinateur situé côté serveur, ou du côté récepteur d'une connexion. La valeur par défaut est l’ordinateur local.

Tapez le nom NetBIOS, une adresse IP ou un nom de domaine complet (FQDN) d’un ordinateur. Les caractères génériques ne sont pas autorisés. Pour spécifier l’ordinateur local, tapez le nom de l’ordinateur, un point (.), $env:COMPUTERNAMEou localhost.

Type:	String
Alias:	Cn
Position:	0
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	True
Accepter les caractères génériques:	False

-ConfigurationName

Spécifie le nom d’une configuration de session. Cette applet de commande se connecte uniquement aux sessions qui utilisent la configuration de session spécifiée.

Entrez un nom de configuration ou l'URI complet de la ressource pour une configuration de session. Si vous ne spécifiez que le nom de la configuration, l'URI du schéma suivant est ajouté :

http://schemas.microsoft.com/powershell.

Le nom de configuration d’une session est stocké dans la propriété ConfigurationName de la session.

La valeur du paramètre est utilisée pour sélectionner et filtrer des sessions. Elle ne modifie pas la configuration de session utilisée par la session.

Pour plus d’informations sur les configurations de session, consultez about_Session_Configurations.

Type:	String
Position:	Named
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	True
Accepter les caractères génériques:	False

-Confirm

Vous invite à confirmer avant d’exécuter l’applet de commande.

Type:	SwitchParameter
Alias:	cf
Position:	Named
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-ConnectionUri

Spécifie un URI qui définit le point de terminaison de connexion utilisé pour se reconnecter à la session déconnectée.

L’URI doit être complet. Le format de la chaîne est le suivant :

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

La valeur par défaut est la suivante :

http://localhost:5985/WSMAN

Si vous ne spécifiez pas d’URI de connexion, vous pouvez utiliser les paramètres UseSSL, ComputerName, Portet Paramètres applicationName pour spécifier les valeurs d’URI de connexion.

Les valeurs valides pour le segment Transport de l’URI sont HTTP et HTTPS. Si vous spécifiez un URI de connexion avec un segment de transport, mais que vous ne spécifiez pas de port, la session est créée avec des ports standard : 80 pour HTTP et 443 pour HTTPS. Pour utiliser les ports par défaut pour la communication à distance PowerShell, spécifiez le port 5985 pour HTTP ou 5986 pour HTTPS.

Si l’ordinateur de destination redirige la connexion vers un autre URI, PowerShell empêche la redirection, sauf si vous utilisez le paramètre AllowRedirection dans la commande.

Type:	Uri
Alias:	URI, CU
Position:	0
Valeur par défaut:	http://localhost:5985/WSMAN
Obligatoire:	True
Accepter l'entrée de pipeline:	True
Accepter les caractères génériques:	False

-Credential

Spécifie un compte d’utilisateur autorisé à se connecter à la session déconnectée. La valeur par défaut est l’utilisateur actuel.

Tapez un nom d’utilisateur, tel que User01 ou Domain01\User01, ou entrez un objet PSCredential généré par l’applet de commande Get-Credential. Si vous tapez un nom d’utilisateur, vous êtes invité à entrer le mot de passe.

Les informations d’identification sont stockées dans un objet PSCredential et le mot de passe est stocké en tant que SecureString.

Remarque

Pour plus d'informations sur la protection des données SecureString, reportez-vous à la section Niveau de sécurité de SecureString.

Type:	PSCredential
Position:	Named
Valeur par défaut:	Current user
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-Id

Spécifie l’ID d’une session déconnectée. Le paramètre ID fonctionne uniquement lorsque la session déconnectée a été précédemment connectée à la session active.

Ce paramètre est valide, mais pas effectif, lorsque la session est stockée sur l’ordinateur local, mais n’a pas été connectée à la session active.

Type:	Int32
Position:	0
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	True
Accepter les caractères génériques:	False

-InstanceId

Spécifie l’ID d’instance de la session déconnectée. L’ID d’instance est un GUID qui identifie de manière unique un psSession sur un ordinateur local ou distant. L’ID d’instance est stocké dans la propriété InstanceID du PSSession.

Type:	Guid
Position:	Named
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-JobName

Spécifie un nom convivial pour le travail que Receive-PSSession renvoie.

Receive-PSSession retourne un travail lorsque la valeur du paramètre OutTarget est Job ou le travail en cours d’exécution dans la session déconnectée a été démarré dans la session active.

Si le travail en cours d’exécution dans la session déconnectée a été démarré dans la session active, PowerShell réutilise l’objet de travail d’origine dans la session et ignore la valeur du paramètre JobName.

Si le travail en cours d’exécution dans la session déconnectée a été démarré dans une autre session, PowerShell crée un objet de travail. Il utilise un nom par défaut, mais vous pouvez utiliser ce paramètre pour modifier le nom.

Si la valeur par défaut ou la valeur explicite du paramètre OutTarget n’est pas Job, la commande réussit, mais le paramètre JobName n’a aucun effet.

Type:	String
Position:	Named
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-Name

Spécifie le nom convivial de la session déconnectée.

Type:	String
Position:	Named
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-OutTarget

Détermine la façon dont les résultats de la session sont renvoyés. Les valeurs acceptables pour ce paramètre sont les suivantes :

Travail. Retourne les résultats de manière asynchrone dans un objet de travail. Vous pouvez utiliser le paramètre JobName pour spécifier un nom ou un nouveau nom pour le travail.
Hôte. Retourne les résultats à la ligne de commande (de façon synchrone). Si la commande est reprise ou que les résultats se composent d’un grand nombre d’objets, la réponse peut être retardée.

La valeur par défaut du paramètre OutTarget est Host. Si la commande reçue dans une session déconnectée a été démarrée dans la session active, la valeur par défaut du paramètre OutTarget est le formulaire dans lequel la commande a été démarrée. Si la commande a été démarrée en tant que tâche, par défaut, elle est retournée en tant que tâche. Sinon, elle est retournée au programme hôte par défaut.

En règle générale, le programme hôte affiche les objets retournés à la ligne de commande sans délai, mais ce comportement peut varier.

Type:	OutTarget
Valeurs acceptées:	Default, Host, Job
Position:	Named
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-Port

Spécifie le port réseau de l’ordinateur distant utilisé pour se reconnecter à la session. Pour se connecter à un ordinateur distant, celui-ci doit être en écoute sur le port utilisé pour la connexion. Les ports par défaut sont 5985, qui est le port WinRM pour HTTP et 5986, qui est le port WinRM pour HTTPS.

Avant d’utiliser un autre port, vous devez configurer l’écouteur WinRM sur l’ordinateur distant pour écouter sur ce port. Pour configurer l’écouteur, tapez les deux commandes suivantes à l’invite PowerShell :

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

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

N’utilisez pas le paramètre Port, sauf s’il est nécessaire. Le port défini dans la commande s’applique à tous les ordinateurs ou sessions sur lesquels la commande s’exécute. Un autre paramètre de port peut empêcher l’exécution de la commande sur tous les ordinateurs.

Type:	Int32
Position:	Named
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-Session

Spécifie la session déconnectée. Entrez une variable qui contient la PSSession ou une commande qui crée ou obtient la PSSession, telle qu'une commande Get-PSSession.

Type:	PSSession
Position:	0
Valeur par défaut:	None
Obligatoire:	True
Accepter l'entrée de pipeline:	True
Accepter les caractères génériques:	False

-SessionOption

Spécifie les options avancées de la session. Entrez un objet SessionOption, tel qu’un objet que vous créez à l’aide de l’applet de commande New-PSSessionOption, ou une table de hachage dans laquelle les clés sont des noms d’options de session et les valeurs sont des valeurs d’option de session.

Les valeurs par défaut des options sont déterminées par la valeur de la variable de préférence $PSSessionOption, si elle est définie. Sinon, les valeurs par défaut sont établies par les options définies dans la configuration de session.

Les valeurs d’option de session sont prioritaires sur les valeurs par défaut pour les sessions définies dans la variable de préférence $PSSessionOption et dans la configuration de session. Toutefois, elles ne sont pas prioritaires sur les valeurs maximales, les quotas ou les limites définies dans la configuration de session.

Pour obtenir une description des options de session qui incluent les valeurs par défaut, consultez New-PSSessionOption. Pour plus d’informations sur la variable de préférence $PSSessionOption, consultez about_Preference_Variables. Pour plus d’informations sur les configurations de session, consultez about_Session_Configurations.

Type:	PSSessionOption
Position:	Named
Valeur par défaut:	None
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-UseSSL

Indique que cette applet de commande utilise le protocole SSL (Secure Sockets Layer) pour se connecter à la session déconnectée. Par défaut, SSL n’est pas utilisé.

WS-Management chiffre tout le contenu PowerShell transmis sur le réseau. UseSSL est une protection supplémentaire qui envoie les données sur une connexion HTTPS au lieu d’une connexion HTTP.

Si vous utilisez ce paramètre et SSL n’est pas disponible sur le port utilisé pour la commande, la commande échoue.

Type:	SwitchParameter
Position:	Named
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

-WhatIf

Affiche ce qui se passerait si l’applet de commande s’exécute. L’applet de commande n’est pas exécutée.

Type:	SwitchParameter
Alias:	wi
Position:	Named
Valeur par défaut:	False
Obligatoire:	False
Accepter l'entrée de pipeline:	False
Accepter les caractères génériques:	False

Entrées

PSSession

Vous pouvez diriger les objets de session vers cette applet de commande, comme les objets retournés par l’applet de commande Get-PSSession.

Int32

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

Guid

Vous pouvez acheminer les IDs d'instance des sessions avec ce cmdlet.

String

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

Sorties

Job

Si la valeur ou la valeur par défaut du paramètre OutTarget est Job, Receive-PSSession retourne un objet de travail.

PSObject

Cette applet de commande retourne les résultats des commandes exécutées dans la session déconnectée, le cas échéant.

Notes

PowerShell inclut les alias suivants pour Receive-PSSession:

Toutes les plateformes :
- rcsn

Cette applet de commande est disponible uniquement sur les plateformes Windows.

Receive-PSSession obtient uniquement les résultats des sessions qui ont été déconnectées. Seules les sessions connectées ou arrêtées sur les ordinateurs qui exécutent PowerShell 3.0 ou versions ultérieures 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 la façon dont 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 pouvez pas récupérer cette sortie. Pour plus d'informations sur l'option de mode de mise en mémoire tampon de la sortie, consultez les articles d'aide des cmdlets New-PSSessionOption et New-PSTransportOption.

Vous ne pouvez pas modifier la valeur du délai d'inactivité d'une PSSession lorsque vous vous connectez à la PSSession ou que vous recevez des résultats. Le paramètre SessionOption de Receive-PSSession prend un objet SessionOption qui a une valeur IdleTimeout. Toutefois, les valeurs IdleTimeout de l’objet SessionOption et IdleTimeout de la variable $PSSessionOption sont ignorées lorsqu'elles se connectent à un PSSession ou lors de la réception des résultats.

Vous pouvez définir et modifier le délai d’inactivité d’un PSSession lors de la création du PSSession, à l’aide des applets de commande New-PSSession ou Invoke-Command, et lorsque vous vous déconnectez du PSSession.
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 une tâche dans une session distante à l’aide du paramètre AsJob de l’applet de commande Invoke-Command, l’objet de tâche est créé dans la session active, même si la tâche s’exécute dans la session distante. Si vous déconnectez la session distante, l’objet de travail de la session active est déconnecté du travail. L’objet de travail contient les résultats retournés à celui-ci, mais 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é, 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. Une valeur de Disconnected signifie que le PSSession n'est pas connecté à la session en cours. Cependant, 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 Occupé indique que vous ne pouvez pas vous connecter au PSSession parce qu'il est connecté à une autre session.
Pour plus d'informations sur les valeurs de la propriété State des sessions, voir RunspaceState.
Pour en savoir plus sur les valeurs de la propriété Availability des sessions, consultez RunspaceAvailability.

Partager via

Receive-PSSession

Syntaxe

Description

Exemples

Exemple 1 : Se connecter à une session PSSession

Exemple 2 : Obtenir les résultats de toutes les commandes sur les sessions déconnectées

Exemple 3 : Obtenir les résultats d’un script en cours d’exécution dans une session

Exemple 4 : Obtenir les résultats après une panne réseau

Exemple 5 : Reconnexion à des sessions déconnectées

Exemple 6 : Exécution d’un travail dans une session déconnectée

Paramètres

-AllowRedirection

-ApplicationName

-Authentication

-CertificateThumbprint

-ComputerName

-ConfigurationName

-Confirm

-ConnectionUri

-Credential

-Id

-InstanceId

-JobName

-Name

-OutTarget

-Port

-Session

-SessionOption

-UseSSL

-WhatIf

Entrées

Sorties

Notes

Ressources supplémentaires

Partager via

Receive-PSSession

Syntaxe

Description

Exemples

Exemple 1 : Se connecter à une session PSSession

Exemple 2 : Obtenir les résultats de toutes les commandes sur les sessions déconnectées

Exemple 3 : Obtenir les résultats d’un script en cours d’exécution dans une session

Exemple 4 : Obtenir les résultats après une panne réseau

Exemple 5 : Reconnexion à des sessions déconnectées

Exemple 6 : Exécution d’un travail dans une session déconnectée

Paramètres

-AllowRedirection

-ApplicationName

-Authentication

-CertificateThumbprint

-ComputerName

-ConfigurationName

-Confirm

-ConnectionUri

-Credential

-Id

-InstanceId

-JobName

-Name

-OutTarget

-Port

-Session

-SessionOption

-UseSSL

-WhatIf

Entrées

Sorties

Notes

Liens associés

Ressources supplémentaires