PowerShell Logo Small

Receive-Job



This is the built-in help made by Microsoft for the command 'Receive-Job', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Gets the results of the Windows PowerShell background jobs in the current session.

SYNTAX


Receive-Job [-Job] <Job[]> [[-Location] [<String[]>]] [-AutoRemoveJob] [-Force] [-Keep] [-NoRecurse] [-Wait] [-WriteEvents] [-WriteJobInResults] [<CommonParameters>]
Receive-Job [-Job] <Job[]> [[-ComputerName] [<String[]>]] [-AutoRemoveJob] [-Force] [-Keep] [-NoRecurse] [-Wait] [-WriteEvents] [-WriteJobInResults] [<CommonParameters>]
Receive-Job [-Id] <Int32[]> [-AutoRemoveJob] [-Force] [-Keep] [-NoRecurse] [-Wait] [-WriteEvents] [-WriteJobInResults] [<CommonParameters>]
Receive-Job [-InstanceId] <Guid[]> [-AutoRemoveJob] [-Force] [-Keep] [-NoRecurse] [-Wait] [-WriteEvents] [-WriteJobInResults] [<CommonParameters>]
Receive-Job [-Job] <Job[]> [[-Session] [<PSSession[]>]] [-AutoRemoveJob] [-Force] [-Keep] [-NoRecurse] [-Wait] [-WriteEvents] [-WriteJobInResults] [<CommonParameters>]
Receive-Job [-Name] <String[]> [-AutoRemoveJob] [-Force] [-Keep] [-NoRecurse] [-Wait] [-WriteEvents] [-WriteJobInResults] [<CommonParameters>]



Search powershellhelp.space

DESCRIPTION


The Receive-Job cmdlet gets the results of Windows PowerShell background jobs, such as those started by using the Start-Job cmdlet or the AsJob parameter of any cmdlet. You
can get the results of all jobs or identify jobs by their name, ID, instance ID, computer name, location, or session, or by submitting a job object.


When you start a Windows PowerShell background job, the job starts, but the results do not appear immediately. Instead, the command returns an object that represents the
background job. The job object contains useful information about the job, but it does not contain the results. This method allows you to continue working in the session
while the job runs. For more information about background jobs in Windows PowerShell, see about_Jobs.


The Receive-Job cmdlet gets the results that have been generated by the time that the Receive-Job command is submitted. If the results are not yet complete, you can run
additional Receive-Job commands to get the remaining results.


By default, job results are deleted from the system when you receive them, but you can use the Keep parameter to save the results so that you can receive them again. To
delete the job results, run the Receive-Job command again (without the Keep parameter), close the session, or use the Remove-Job cmdlet to delete the job from the session.


Beginning in Windows PowerShell 3.0, Receive-Job also gets the results of custom job types, such as workflow jobs and instances of scheduled jobs. To enable Receive-Job to
get the results a custom job type, import the module that supports the custom job type into the session before running a Receive-Job command, either by using the
Import-Module cmdlet or by using or getting a cmdlet in the module. For information about a particular custom job type, see the documentation of the custom job type feature.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/p/?linkid=289603
Get-Job
Invoke-Command
Remove-Job
Resume-Job
Start-Job
Stop-Job
Suspend-Job
Wait-Job
about_Jobs
about_Job_Details
about_Remote_Jobs
about_Remote_Variables
about_Scopes

REMARKS

<

Examples


-------------------------- EXAMPLE 1 --------------------------

PS C:\>$job = Start-Job -ScriptBlock {Get-Process}
PS C:\>Receive-Job -Job $job



These commands use the Job parameter of Receive-Job to get the results of a particular job.

The first command uses the Start-Job cmdlet to start a job that runs a Get-Process command. The command uses the assignment operator (=) to save the resulting job object in
the $job variable.

The second command uses the Receive-Job cmdlet to get the results of the job. It uses the Job parameter to specify the job.






-------------------------- EXAMPLE 2 --------------------------

PS C:\>$job = Start-Job -ScriptBlock {Get-Process}
PS C:\>$job | Receive-Job



This example is the same as Example 2, except that the command uses a pipeline operator (|) to send the job object to Receive-Job. As a result, the command does not need a
Job parameter to specify the job.






-------------------------- EXAMPLE 3 --------------------------

The first command uses the Invoke-Command cmdlet to start a background job that runs a Get-Service command on three remote computers. The command uses the AsJob parameter to
run the command as a background job. The command saves the resulting job object in the $j variable.When you use the AsJob parameter of Invoke-Command to start a job, the job
object is created on the local computer, even though the job runs on the remote computers. As a result, you use local commands to manage the job.Also, when you use AsJob,
Windows PowerShell returns one job object that contains a child job for each job that was started. In this case, the job object contains three child jobs, one for each job
on each remote computer.
PS C:\>


PS C:\>$j = Invoke-Command -ComputerName Server01, Server02, Server03 -ScriptBlock {Get-Service} -AsJob

The second command uses the dot method to 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.
PS C:\>$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

The third command uses the Receive-Job cmdlet to get the results of the Job3 child job that ran on the Server02 computer. It uses the Name parameter to specify the name of
the child job and the Keep parameter to save the job results even after they are received.
PS C:\>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 Server02



These commands get the results of one of several background jobs run on remote computers.






-------------------------- EXAMPLE 4 --------------------------

The first command uses the New-PSSession cmdlet to create three user-managed sessions ("PSSessions), one on each of the servers specified in the command. It saves the
sessions in the $s variable.
PS C:\>$s = new-pssession -computername Server01, Server02, Server03

The second command uses the Invoke-Command cmdlet to run a Start-Job command in each of the PSSessions in the $s variable. The job runs a Get-Eventlog command that gets the
events in the System log. The command saves the results in the $j variable.Because the command used Invoke-Command to run the Start-Job command, the command actually started
three independent jobs on each of the three computers. As a result, the command returned three job objects representing three jobs run locally on three different computers.
PS C:\>$j = invoke-command -session $s -scriptblock {start-job -scriptblock {get-eventlog -logname system}}

The third command displays the three job objects in $j.
PS C:\>$j

Id Name State HasMoreData Location Command
-- ---- ----- ----------- -------- -------
1 Job1 Completed True Localhost get-eventlog system
2 Job2 Completed True Localhost get-eventlog system
3 Job3 Completed True Localhost get-eventlog system


The fourth command uses Invoke-Command to run a Receive-Job command in each of the sessions in $s and save the results in the $Results variable.Because $j is a local
variable, the script block uses the Using scope modifier to identify the $j variable. For more information about the Using scope modifier, see about_Remote_Variables
(http://go.microsoft.com/fwlink/?LinkID=252653).
PS C:\>$results = Invoke-Command -Session $s -ScriptBlock {Receive-Job -Job $Using:j}



This example shows how to get the results of background jobs run on three remote computers.