Receive-Job
Obtient les résultats des travaux en arrière-plan PowerShell dans la session active.
Syntaxe
Receive-Job
[-Job] <Job[]>
[[-Location] <String[]>]
[-Keep]
[-NoRecurse]
[-Force]
[-Wait]
[-AutoRemoveJob]
[-WriteEvents]
[-WriteJobInResults]
[<CommonParameters>]Receive-Job
[-Job] <Job[]>
[[-ComputerName] <String[]>]
[-Keep]
[-NoRecurse]
[-Force]
[-Wait]
[-AutoRemoveJob]
[-WriteEvents]
[-WriteJobInResults]
[<CommonParameters>]Receive-Job
[-Job] <Job[]>
[[-Session] <PSSession[]>]
[-Keep]
[-NoRecurse]
[-Force]
[-Wait]
[-AutoRemoveJob]
[-WriteEvents]
[-WriteJobInResults]
[<CommonParameters>]Receive-Job
[-Keep]
[-NoRecurse]
[-Force]
[-Wait]
[-AutoRemoveJob]
[-WriteEvents]
[-WriteJobInResults]
[-Name] <String[]>
[<CommonParameters>]Receive-Job
[-Keep]
[-NoRecurse]
[-Force]
[-Wait]
[-AutoRemoveJob]
[-WriteEvents]
[-WriteJobInResults]
[-InstanceId] <Guid[]>
[<CommonParameters>]Receive-Job
[-Keep]
[-NoRecurse]
[-Force]
[-Wait]
[-AutoRemoveJob]
[-WriteEvents]
[-WriteJobInResults]
[-Id] <Int32[]>
[<CommonParameters>]Description
L’applet de commande Receive-Job obtient les résultats des travaux en arrière-plan PowerShell, tels que ceux démarrés à l’aide de l’applet de commande Start-Job ou du paramètre AsJob d’une applet de commande.
Vous pouvez obtenir les résultats de tous les travaux ou identifier les travaux par leur nom, ID, ID d’instance, nom d’ordinateur, emplacement ou session, ou en envoyant un objet de travail.
Lorsque vous démarrez un travail en arrière-plan PowerShell, le travail démarre, mais les résultats ne s’affichent pas immédiatement. Au lieu de cela, la commande retourne un objet qui représente le travail en arrière-plan. L’objet de travail contient des informations utiles sur le travail, mais il ne contient pas les résultats. Cette méthode vous permet de continuer à travailler dans la session pendant l’exécution du travail. Pour plus d’informations sur les travaux en arrière-plan dans PowerShell, consultez about_Jobs.
L’applet de commande Receive-Job obtient les résultats générés au moment où la commande Receive-Job est envoyée.
Si les résultats ne sont pas encore terminés, vous pouvez exécuter des commandes Receive-Job supplémentaires pour obtenir les résultats restants.
Par défaut, les résultats du travail sont supprimés du système lorsque vous les recevez, mais vous pouvez utiliser le paramètre Keep pour enregistrer les résultats afin de pouvoir les recevoir à nouveau.
Pour supprimer les résultats du travail, réexécutez la commande Receive-Job sans le paramètre Conserver, fermez la session ou utilisez l’applet de commande Remove-Job pour supprimer le travail de la session.
À compter de Windows PowerShell 3.0, Receive-Job obtient également les résultats des types de travaux personnalisés, tels que les travaux de flux de travail et les instances de travaux planifiés.
Pour permettre Receive-Job d’obtenir les résultats d’un type de travail personnalisé, importez le module qui prend en charge le type de travail personnalisé dans la session avant d’exécuter une commande Receive-Job, soit à l’aide de l’applet de commande Import-Module, soit en utilisant ou en obtenant une applet de commande dans le module.
Pour plus d’informations sur un type de travail personnalisé particulier, consultez la documentation de la fonctionnalité de type de travail personnalisé.
Exemples
Exemple 1 : Obtenir les résultats d’un travail particulier
$job = Start-Job -ScriptBlock {Get-Process}
Receive-Job -Job $jobCes commandes utilisent le paramètre Job de Receive-Job pour obtenir les résultats d’un travail particulier.
La première commande démarre un travail avec Start-Job et stocke l’objet de travail dans la variable $job.
La deuxième commande utilise l’applet de commande Receive-Job pour obtenir les résultats du travail.
Il utilise le paramètre Job pour spécifier le travail.
Exemple 2 : Utiliser le paramètre Keep
$job = Start-Job -ScriptBlock {Get-Service dhcp, fakeservice}
$job | Receive-Job -Keep
Cannot find any service with service name 'fakeservice'.
+ CategoryInfo : ObjectNotFound: (fakeservice:String) [Get-Service], ServiceCommandException
+ FullyQualifiedErrorId : NoServiceFoundForGivenName,Microsoft.PowerShell.Commands.GetServiceCommand
+ PSComputerName : localhost
Status Name DisplayName
------ ---- -----------
Running dhcp DHCP Client
$job | Receive-Job -Keep
Cannot find any service with service name 'fakeservice'.
+ CategoryInfo : ObjectNotFound: (fakeservice:String) [Get-Service], ServiceCommandException
+ FullyQualifiedErrorId : NoServiceFoundForGivenName,Microsoft.PowerShell.Commands.GetServiceCommand
+ PSComputerName : localhost
Status Name DisplayName
------ ---- -----------
Running dhcp DHCP ClientCet exemple stocke un travail dans la variable $job et canalise le travail vers l’applet de commande Receive-Job. Le paramètre -Keep est également utilisé pour permettre à toutes les données de flux agrégées d’être récupérées à nouveau après la première vue.
Exemple 3 : Obtenir les résultats de plusieurs travaux en arrière-plan
Lorsque vous utilisez le paramètre AsJob de Invoke-Command pour démarrer un travail, l’objet de travail est créé sur l’ordinateur local, même si le travail s’exécute sur les ordinateurs distants.
Par conséquent, vous utilisez des commandes locales pour gérer le travail.
En outre, lorsque vous utilisez AsJob, PowerShell retourne un objet de travail qui contient un travail enfant pour chaque travail démarré. Dans ce cas, l’objet de travail contient trois travaux enfants, un pour chaque travail sur chaque ordinateur distant.
# Use the Invoke-Command cmdlet with the -AsJob parameter to start a background job that runs a Get-Service command on three remote computers.
# Store the resulting job object in the $j variable
$j = Invoke-Command -ComputerName Server01, Server02, Server03 -ScriptBlock {Get-Service} -AsJob
# Display the value of the **ChildJobs** property of the job object in $j.
# The display shows that the command created three child jobs, one for the job on each remote computer.
# You could also use the -IncludeChildJobs parameter of the Get-Job cmdlet.
$j.ChildJobs
Id Name State HasMoreData Location Command
-- ---- ----- ----------- -------- -------
2 Job2 Completed True Server01 Get-Service
3 Job3 Completed True Server02 Get-Service
4 Job4 Completed True Server03 Get-Service
# Use the Receive-Job cmdlet to get the results of just the Job3 child job that ran on the Server02 computer.
# Use the *Keep* parameter to allow you to view the aggregated stream data more than once.
Receive-Job -Name Job3 -Keep
Status Name DisplayName PSComputerName
------ ----------- ----------- --------------
Running AeLookupSvc Application Experience Server02
Stopped ALG Application Layer Gateway Service Server02
Running Appinfo Application Information Server02
Running AppMgmt Application Management Server02Exemple 4 : Obtenir les résultats des travaux en arrière-plan sur plusieurs ordinateurs distants
# Use the New-PSSession cmdlet to create three user-managed PSSessions on three servers, and save the sessions in the $s variable.
$s = New-PSSession -ComputerName Server01, Server02, Server03
# Use Invoke-Command run a Start-Job command in each of the PSSessions in the $s variable.
# The creates a new job with a custom name to each server
# The job outputs the datetime from each server
# Save the job objects in the $j variable.
$j = Invoke-Command -Session $s -ScriptBlock {Start-Job -Name $('MyJob-' +$env:COMPUTERNAME) -ScriptBlock {(Get-Date).ToString()}}
# To confirm that these job objects are from the remote machines, run Get-Job to show no local jobs running.
Get-Job
# Display the three job objects in $j.
# Note that the Localhost location is not the local computer, but instead localhost as it relates to the job on each Server.
$j
Id Name State HasMoreData Location Command
-- ---- ----- ----------- -------- -------
1 MyJob-Server01 Completed True Localhost (Get-Date).ToString()
2 MyJob-Server02 Completed True Localhost (Get-Date).ToString()
3 MyJob-Server03 Completed True Localhost (Get-Date).ToString()
# Use Invoke-Command to run a Receive-Job command in each of the sessions in the $s variable and save the results in the $results variable.
# The Receive-Job command must be run in each session because the jobs were run locally on each server.
$results = Invoke-Command -Session $s -ScriptBlock {Receive-Job -Name $('MyJob-' +$env:COMPUTERNAME)}
3/22/2021 7:41:47 PM
3/22/2021 7:41:47 PM
3/22/2021 9:41:47 PMCet exemple montre comment obtenir les résultats des travaux en arrière-plan exécutés sur trois ordinateurs distants.
Contrairement à l’exemple précédent, l’utilisation de Invoke-Command pour exécuter la commande Start-Job a réellement démarré trois travaux indépendants sur chacun des trois ordinateurs. Par conséquent, la commande a retourné trois objets de travail représentant trois travaux exécutés localement sur trois ordinateurs différents.
Exemple 5 : Accéder aux travaux enfants
Le paramètre -Keep conserve l’état des flux agrégés d’un travail afin qu’il puisse être consulté à nouveau. Sans ce paramètre, toutes les données de flux agrégés sont effacées lorsque le travail est reçu. Pour plus d’informations, consultez about_Job_Details
Note
Les flux agrégés incluent les flux de tous les travaux enfants. Vous pouvez toujours atteindre les flux de données individuels via l’objet de travail et les objets de travail enfants.
Start-Job -Name TestJob -ScriptBlock {dir C:\, Z:\}
# Without the Keep parameter, aggregated child job data is displayed once.
# Then destroyed.
Receive-Job -Name TestJob
Directory: C:\
Mode LastWriteTime Length Name
---- ------------- ------ ----
d-r--- 1/24/2019 7:11 AM Program Files
d-r--- 2/13/2019 8:32 AM Program Files (x86)
d-r--- 10/3/2018 11:47 AM Users
d----- 2/7/2019 1:52 AM Windows
Cannot find drive. A drive with the name 'Z' does not exist.
+ CategoryInfo : ObjectNotFound: (Z:String) [Get-ChildItem], DriveNotFoundException
+ FullyQualifiedErrorId : DriveNotFound,Microsoft.PowerShell.Commands.GetChildItemCommand
+ PSComputerName : localhost
# It would seem that the child job data is gone.
Receive-Job -Name TestJob
# Using the object model, you can still retrieve child job data and streams.
$job = Get-Job -Name TestJob
$job.ChildJobs[0].Error
Cannot find drive. A drive with the name 'Z' does not exist.
+ CategoryInfo : ObjectNotFound: (Z:String) [Get-ChildItem], DriveNotFoundException
+ FullyQualifiedErrorId : DriveNotFound,Microsoft.PowerShell.Commands.GetChildItemCommand
+ PSComputerName : localhostParamètres
-AutoRemoveJob
Indique que cette applet de commande supprime le travail après qu’il retourne les résultats du travail.
Si le travail a plus de résultats, le travail est toujours supprimé, mais Receive-Job affiche un message.
Ce paramètre fonctionne uniquement sur les types de travaux personnalisés. Il est conçu pour les instances de types de travaux qui enregistrent le travail ou le type en dehors de la session, comme les instances de travaux planifiés.
Ce paramètre ne peut pas être utilisé sans le paramètre Wait.
Ce paramètre a été introduit dans Windows PowerShell 3.0.
| 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 |
-ComputerName
Spécifie un tableau de noms d’ordinateurs.
Ce paramètre sélectionne parmi les résultats du travail stockés sur l’ordinateur local.
Il n’obtient pas de données pour les travaux exécutés sur des ordinateurs distants.
Pour obtenir les résultats du travail stockés sur des ordinateurs distants, utilisez l’applet de commande Invoke-Command pour exécuter une commande Receive-Job à distance.
| Type: | String[] |
| Alias: | Cn |
| Position: | 1 |
| Valeur par défaut: | All computers available |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | True |
-Force
Indique que cette applet de commande continue d’attendre si les travaux se trouvent dans l’état Suspendu ou déconnecté. Par défaut, le paramètre Wait de Receive-Job retourne ou met fin à l’attente lorsque les travaux se trouvent dans l’un des états suivants :
- Terminé
- Raté
- Arrêté
- Suspendu
- Coupé.
Le paramètre
Ce paramètre a été introduit dans Windows PowerShell 3.0.
| 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 |
-Id
Spécifie un tableau d’ID. Cette applet de commande obtient les résultats des travaux avec les ID spécifiés.
L’ID est un entier qui identifie de façon unique le travail dans la session active.
Il est plus facile de mémoriser et de taper que l’ID d’instance, mais il est unique uniquement dans la session active. Vous pouvez taper un ou plusieurs ID séparés par des virgules.
Pour rechercher l’ID d’un travail, utilisez Get-Job.
| 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 un tableau d’ID d’instance. Cette applet de commande obtient les résultats des travaux avec les ID d’instance spécifiés.
Un ID d’instance est un GUID qui identifie de façon unique le travail sur l’ordinateur.
Pour rechercher l’ID d’instance d’un travail, utilisez l’applet de commande Get-Job.
| Type: | Guid[] |
| Position: | 0 |
| Valeur par défaut: | All instances |
| Obligatoire: | True |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | False |
-Job
Spécifie le travail pour lequel les résultats sont récupérés.
Entrez une variable qui contient le travail ou une commande qui obtient le travail.
Vous pouvez également diriger un objet de travail vers Receive-Job.
| Type: | Job[] |
| Position: | 0 |
| Valeur par défaut: | None |
| Obligatoire: | True |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | False |
-Keep
Indique que cette applet de commande enregistre les données de flux agrégés dans le système, même après les avoir reçues. Par défaut, les données de flux agrégés sont effacées après avoir été consultées avec Receive-Job.
La fermeture de la session ou la suppression du travail avec l’applet de commande Remove-Job supprime également les données de flux agrégés.
| 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 |
-Location
Spécifie un tableau d’emplacements. Cette applet de commande obtient uniquement les résultats des travaux dans les emplacements spécifiés.
| Type: | String[] |
| Position: | 1 |
| Valeur par défaut: | All locations |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-Name
Spécifie un tableau de noms conviviaux. Cette applet de commande obtient les résultats des travaux qui ont les noms spécifiés. Les caractères génériques sont pris en charge.
| Type: | String[] |
| Position: | 0 |
| Valeur par défaut: | None |
| Obligatoire: | True |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | True |
-NoRecurse
Indique que cette applet de commande obtient uniquement les résultats du travail spécifié.
Par défaut, Receive-Job obtient également les résultats de tous les travaux enfants du travail spécifié.
| 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 |
-Session
Spécifie un tableau de sessions.
Cette applet de commande obtient les résultats des travaux qui ont été exécutés dans la session PowerShell spécifiée (PSSession).
Entrez une variable qui contient le PSSession
| Type: | PSSession[] |
| Position: | 1 |
| Valeur par défaut: | All sessions |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | False |
-Wait
Indique que cette applet de commande supprime l’invite de commandes jusqu’à ce que tous les résultats du travail soient reçus.
Par défaut, Receive-Job retourne immédiatement les résultats disponibles.
Par défaut, le paramètre Wait attend que le travail se trouve dans l’un des états suivants :
- Terminé
- Raté
- Arrêté
- Suspendu
- Coupé.
Pour diriger le paramètre
Ce paramètre a été introduit dans Windows PowerShell 3.0.
| Type: | SwitchParameter |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-WriteEvents
Indique que cette applet de commande signale les modifications apportées à l’état du travail pendant qu’elle attend la fin du travail.
Ce paramètre est valide uniquement lorsque le paramètre Wait est utilisé dans la commande et que le paramètre Keep est omis.
Ce paramètre a été introduit dans Windows PowerShell 3.0.
| 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 |
-WriteJobInResults
Indique que cette applet de commande retourne l’objet de travail suivi des résultats.
Ce paramètre est valide uniquement lorsque le paramètre Wait est utilisé dans la commande et que le paramètre Keep est omis.
Ce paramètre a été introduit dans Windows PowerShell 3.0.
| 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 |
Entrées
Vous pouvez diriger les objets de travail vers cette applet de commande.
Sorties
PSObject
Cette applet de commande retourne les résultats des commandes dans le travail.