powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Receive-Job



NAME
Receive-Job

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

SYNTAX
Receive-Job [-Job] [[-ComputerName] ] [-Keep] [-NoRecurse] []

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

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

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

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

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


DESCRIPTION
The Receive-Job cmdlet gets the results of Windows Powershell background jobs. Use Receive-Job to get the results o
f jobs started by using the Start-Job cmdlet or the AsJob parameter of any cmdlet. You can get the results of all j
obs or identify jobs by their name, ID, instance ID, computer name, location, or session, or by submitting a job ob
ject.

When you start a Windows PowerShell background job, the job starts, but the results do not appear immediately. Inst
ead, the command returns an object that represents the background job. The job object contains useful information a
bout 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.

To get the results of the command, use the Receive-Job cmdlet. Receive-Job gets the results that have been generate
d by the time that the Receive-Job command is submitted. If the results are not yet complete, you can run additiona
l 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 sa
ve the results so that you can receive them again. To delete the job results, receive them again (without the Keep
parameter), close the session, or use the Remove-Job cmdlet to delete the job from the session.


PARAMETERS
-ComputerName
Gets 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 f
rom remote computers. To get job results that are stored on remote computers, use the Invoke-Command cmdlet to
run a Receive-Job command remotely.

Required? false
Position? 2
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Id
Gets the results of 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
type than the instance ID, but it is unique only within the current session. You can type one or more IDs (sepa
rated by commas). To find the ID of a job, type "Get-Job" without parameters.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-InstanceId
Gets 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, us
e the Get-Job cmdlet.

Required? false
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

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

Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false

-Keep []
Saves 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 the Remove-Job cmdlet to delete the job from the session.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Location
Gets only the results of jobs with the specified location. The default is all jobs in the current session.

Required? false
Position? 2
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Name
Gets the results of jobs with the specified friendly name. The default is all jobs in the current session.

Required? false
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-NoRecurse []
Gets results only from the specified job. By default, Receive-Job also gets the results of all child jobs of th
e specified job.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Session
Gets the results of jobs that were run in the specified Windows Powershell session (PSSession). Enter a variabl
e that contains the PSSession or a command that gets the PSSession, such as a Get-PSSession command. The defaul
t is all jobs in the current session.

Required? false
Position? 2
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
System.Management.Automation.Job
You can pipe job objects to Receive-Job.


OUTPUTS
PSObject
Receive-Job returns the results of the commands in the job.


NOTES





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

C:\PS>$job = start-job -scriptblock {get-process}

C:\PS> receive-job -job $job


Description
-----------
These commands use the Job parameter to get the results of a particular job. The first command uses the Start-Job c
mdlet to start a job that runs a "Get-Process" command. The command uses the assignment operator (=) to save the re
sulting 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 --------------------------

C:\PS>$job = start-job -scriptblock {get-process}

C:\PS> $job | receive-job


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

C:\PS>$j = invoke-command -computername Server01, Server02, Server03 -scriptblock {get-service} -AsJob

C:\PS> $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

C:\PS> 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


Description
-----------
These commands use the Name parameter of Receive-Job to get the results of one of several background jobs run on re
mote computers.

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 t
he 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.

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.

The third command uses the Receive-Job cmdlet to get the results of the Job3 child job that ran on the Server02 com
puter. It uses the Name parameter to specify the name of the child job and the Keep parameter to save the job resul
ts even after they are received.





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

C:\PS>$s = new-pssession -computername Server01, Server02, Server03

C:\PS> $j = invoke-command -session $s -scriptblock {start-job -scriptblock {get-eventlog -logname system}}

C:\PS> $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

C:\PS> $results = invoke-command -session $s -scriptblock {param($j) receive-job -job $j} -ArgumentList $j


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

The first command uses the New-PSSession cmdlet to create three PSSessions, one on each of the servers specified in
the command. It saves the PSSessions in the $s variable.

The second command uses the Invoke-Command cmdlet to run a Start-Job command in each of the PSSessions in the $s va
riable. The job runs a Get-Eventlog command that gets the events in the System log. The command saves the results i
n the $j variable.

Because the command used Invoke-Command to run the Start-Job command, the command actually started three independen
t 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.

The third command displays the three job objects in $j.

The fourth command uses Invoke-Command to run a Receive-Job command in each of the PSSessions in $s and save the re
sults in the $results variable.

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






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113372
about_Jobs
about_Job_Details
about_Remote_Jobs
Start-Job
Get-Job
Wait-Job
Stop-Job
Remove-Job
Invoke-Command