Receive-Job

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

From the PowerShell reference 14 parameters Alias rcjb

What it does

from the PowerShell reference, CC BY 4.0

Gets the results of the PowerShell background jobs in the current session. The Receive-Job cmdlet gets the results of 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 PowerShell background job, the job starts, but the results don't appear immediately. Instead, the command returns an object that represents the background job. The job object contains useful information about the job, but it doesn't contain the results. This method lets you continue to work in the session while the job runs. For more information about background jobs in 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 aren't 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. Starting 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 it runs a Receive-Job command, either by using the Import-Module cmdlet or by getting a cmdlet in the module. For information about a particular custom job type, see the documentation of the custom job type feature.

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 [-Name] <string[]> [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [<CommonParameters>]

Receive-Job [-InstanceId] <guid[]> [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [<CommonParameters>]

Receive-Job [-Id] <int[]> [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [<CommonParameters>]

Get results for a particular job

$job = Start-Job -ScriptBlock {Get-Process}
Start-Sleep -Seconds 1
Receive-Job -Job $job

Identify

Use the Keep parameter

$job = Start-Job -ScriptBlock {Get-Service dhcp, fakeservice}
Start-Sleep -Seconds 1
$job | Receive-Job -Keep

Identify

Get results of several background jobs

# 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

Identify

Get results of background jobs on multiple remote computers

# 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 code 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.
$invokeCommandSplat = @{
Session = $s
ScriptBlock = {
Start-Job -Name $('MyJob-' +$Env:COMPUTERNAME) -ScriptBlock {
(Get-Date).ToString()
}
}
}
$j = Invoke-Command @invokeCommandSplat
# 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

Identify

Access child jobs

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

Identify

Its page in the reference: Receive-Job.

Parameters

14 in the PowerShell reference

-AutoRemoveJobIndicates that this cmdlet deletes the job after it returns the job results. If the job has more results, the job is still deleted, but Receive-Job displays a message. This parameter works only on custom job types. It's designed for instances of job types that save the job or the type outside of the session, such as instances of scheduled jobs. This parameter can't be used without the Wait parameter. This parameter was introduced in Windows PowerShell 3.0.

-ComputerNameSpecifies an array of names of computers. This parameter selects from among the job results that are stored on the local computer. It doesn't get data for jobs run on remote computers. To get job results that are stored on remote computers, use the Invoke-Command cmdlet to run a Receive-Job command remotely.

-ForceIndicates that this cmdlet continues waiting if jobs are in the Suspended or Disconnected state. By default, the Wait parameter of Receive-Job returns, or terminates the wait, when jobs are in one of the following states: - Completed - Failed - Stopped - Suspended - Disconnected. The Force parameter is valid only when the Wait parameter is also used in the command. This parameter was introduced in Windows PowerShell 3.0.

-IdSpecifies an array of IDs. This cmdlet gets the results of jobs with the specified IDs. The ID is an integer that uniquely identifies the job in the current session. it's easier to remember and type than the instance ID, but it's unique only in the current session. You can type one or more IDs separated by commas. To find the ID of a job, use Get-Job.

-InstanceIdSpecifies an array of instance IDs. This cmdlet gets the results of jobs with the specified instance IDs. An instance ID is a GUID that uniquely identifies the job on the computer. To find the instance ID of a job, use the Get-Job cmdlet.

-JobSpecifies the job for which results are being retrieved. Enter a variable that contains the job or a command that gets the job. You can also pipe a job object to Receive-Job.

-KeepIndicates that this cmdlet saves the aggregated stream data in the system, even after you have received them. By default, aggregated stream data is erased after viewed with Receive-Job. Closing the session, or removing the job with the Remove-Job cmdlet also deletes aggregated stream data.

-LocationSpecifies an array of locations. This cmdlet gets only the results of jobs in the specified locations.

-NameSpecifies an array of friendly names. This cmdlet gets the results of jobs that have the specified names. Wildcard characters are supported.

-NoRecurseIndicates that this cmdlet gets results only from the specified job. By default, Receive-Job also gets the results of all child jobs of the specified job.

-SessionSpecifies an array of sessions. This cmdlet gets the results of jobs that were run in the specified PowerShell session (PSSession). Enter a variable that contains the PSSession or a command that gets the PSSession, such as a Get-PSSession command.

-WaitIndicates that this cmdlet suppresses the command prompt until all job results are received. By default, Receive-Job immediately returns the available results. By default, the Wait parameter waits until the job is in one of the following states: - Completed - Failed - Stopped - Suspended - Disconnected To direct the Wait parameter to continue waiting if the job state is Suspended or Disconnected, use the Force parameter together with the Wait parameter. This parameter was introduced in Windows PowerShell 3.0.

-WriteEventsIndicates that this cmdlet reports changes in the job state while it waits for the job to finish. This parameter is valid only when the Wait parameter is used in the command and the Keep parameter is omitted. This parameter was introduced in Windows PowerShell 3.0.

-WriteJobInResultsIndicates that this cmdlet returns the job object followed by the results. This parameter is valid only when the Wait parameter is used in the command and the Keep parameter is omitted. This parameter was introduced in Windows PowerShell 3.0.

Receive-Job

What it does

Parameters

See also