Receive-Job

Get the results of PowerShell background jobs in the current session.

Syntax
      Receive-Job [-Job] Job[] [[-ComputerName] string[]] [-Keep] [-NoRecurse] [CommonParameters]

      Receive-Job [[-InstanceId] Guid[]] [-Keep] [-NoRecurse] [CommonParameters]

      Receive-Job [-Job] Job[] [[-Location] string[]] [-Keep] [-NoRecurse] [CommonParameters]

      Receive-Job [[-Name] string[]] [-Keep] [-NoRecurse] [CommonParameters]

      Receive-Job [-Job] Job[] [[-Session] PSSession[]] [-Keep] [-NoRecurse] [CommonParameters]

      Receive-Job [-Id] Int32[] [-Keep] [-NoRecurse] [CommonParameters]

Key
   -ComputerNamestring[]
       Get the results of jobs that were run on the specified computers.
       Enter the computer names. The default is all jobs in the current session.

       This parameter selects from among the job results that are stored on the local computer.
       It does not get data from remote computers. To get job results that are stored on remote
       computers, use the Invoke-Command cmdlet to run a Receive-Job command remotely.

    -Id Int32[]
       Get the results of only jobs with the specified IDs.
       The default is all jobs in the current session.

       The ID is an integer that uniquely identifies the job within the current session.
       It is easier to remember and to type than the instance ID, but it is unique only
       within the current session. You can type one or more IDs (separated by commas).
       To find the ID of a job, type "Get-Job" without parameters.

   -InstanceId Guid[]
       Get the results of jobs with the specified instance IDs.
       The default is all jobs in the current session.

       An instance ID is a GUID that uniquely identifies the job on the computer.
       To find the instance ID of a job, use Get-Job.

   -Job Job[]
       The job for which results are being retrieved.
       This parameter is required in a Receive-Job command.
       Enter a variable that contains the job or a command that gets the job.
       You can also pipe a job object to Receive-Job.

   -Keep
       Save the job results in the system, even after you have received them.
       By default, the job results are deleted when they are retrieved. 

       To delete the results, use Receive-Job to receive them again without the
       Keep parameter, close the session, or use Remove-Job to delete the job from the session.

   -Location string[]
       Get only the results of jobs with the specified location.
       The default is all jobs in the current session.

   -Name string[]
       Get the results of jobs with the specified friendly name.
       The default is all jobs in the current session.

   -NoRecurse
       Get results only from the specified job.
       By default, Receive-Job also gets the results of all child jobs of the specified job.

   -Session PSSession[]
       Get 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.
       The default is all jobs in the current session.

   CommonParameters:
       -Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
       -OutBuffer -OutVariable.

Standard Aliases for Receive-Job: rcjb

Receive-Job gets the results of jobs started with Start-Job or the -AsJob parameter of any cmdlet.

When a PowerShell background job is started, the results do not appear immediately. Instead, the command returns an object representing the background job. The job object contains useful information about the job, but it does not contain the results.

To get the results of the command, use Receive-Job. Receive-Job 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, the -Keep parameter can use used to save the results. To delete the job results, receive them again (without -Keep), close the session, or use Remove-Job to delete the job from the session.

Examples

Get the results of a particular job:

PS C:\> $job = start-job -scriptblock {get-process}
PS C:\> receive-job -job $job
Alternatively with a pipeline:
PS C:\> $job | receive-job

Start a background job that runs Get-Service on server64 and server65:

PS C:\> $j = invoke-command -computername Server64, Server65 -scriptblock {get-service} -AsJob

List the two child jobs created by the above, then Receive the results of the second:

PS C:\> $j.childjobs
PS C:\> receive-job -name Job2 -keep

Create PSSessions on two servers, then use Invoke-Command to run a Start-Job command in each of the PSSessions:

PS C:\> $s = new-pssession -computername Server64, Server65
PS C:\> $j = invoke-command -session $s -scriptblock {start-job -scriptblock {get-eventlog -logname system}}
PS C:\> $j
PS C:\> $results = invoke-command -session $s -scriptblock {param($j) receive-job -job $j} -ArgumentList $j

Using Invoke-Command to run Start-Job, will start independent jobs on each of the computers. As a result, the command above returns two job objects representing jobs run locally on two different computers.

In the same way the final Invoke-Command above runs a Receive-Job command in each of the PSSessions and saves the results to $results.

Because $j is a local variable, the script block uses the "param" keyword to declare the variables in the command and the ArgumentList parameter to supply the value of $j.

“Don't tell people how to do things. Tell them what to do and let them surprise you with their results” ~ General George S. Patton

Related:

Get-Job - Get PowerShell background jobs that are running
Remove-Job - Delete a PowerShell background job


© Copyright SS64.com 1999-2013
Some rights reserved