Windows PowerShell command on Get-command Receive-Job

NAME

Receive-Job

SYNOPSIS

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

SYNTAX

Receive-Job [-Job] [[-ComputerName] ] [-AutoRemoveJob] [-Force] [-Keep] [-NoRecurse] [-Wait]

[-WriteEvents] [-WriteJobInResults] []

Receive-Job [-Id] [-AutoRemoveJob] [-Force] [-Keep] [-NoRecurse] [-Wait] [-WriteEvents]

[-WriteJobInResults] []

Receive-Job [-InstanceId] [-AutoRemoveJob] [-Force] [-Keep] [-NoRecurse] [-Wait] [-WriteEvents]

[-WriteJobInResults] []

Receive-Job [-Job] [[-Location] ] [-AutoRemoveJob] [-Force] [-Keep] [-NoRecurse] [-Wait]

[-WriteEvents] [-WriteJobInResults] []

Receive-Job [-Job] [[-Session] ] [-AutoRemoveJob] [-Force] [-Keep] [-NoRecurse] [-Wait]

[-WriteEvents] [-WriteJobInResults] []

Receive-Job [-Name] [-AutoRemoveJob] [-Force] [-Keep] [-NoRecurse] [-Wait] [-WriteEvents]

[-WriteJobInResults] []

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 lets you continue to work 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.

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

PARAMETERS

-AutoRemoveJob []

Indicates 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 is 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 was introduced in Windows PowerShell 3.0. Required? false Position? named Default value False Accept pipeline input? False Accept wildcard characters? false

-ComputerName

Specifies an array of names of computers. This cmdlet gets the results of jobs that were run on the specified computers. Enter the computer names. Wildcard characters are supported. 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.

Required? false Position? 1 Default value None

Accept pipeline input? True (ByPropertyName)

Accept wildcard characters? false

-Force []

Indicates 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, or 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. Required? false Position? named Default value False Accept pipeline input? False Accept wildcard characters? false

-Id

Specifies an array of IDs. This cmdlet 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 in the current session. It is easier to remember and type than the instance ID, but it is unique only in 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.

Required? true Position? 0 Default value None

Accept pipeline input? True (ByPropertyName)

Accept wildcard characters? false

-InstanceId

Specifies an array of instance IDs. This cmdlet 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,

use the Get-Job cmdlet.

Required? true Position? 0 Default value None

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.

Enter 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? 0 Default value None

Accept pipeline input? True (ByPropertyName, ByValue)

Accept wildcard characters? false

-Keep []

Indicates that this cmdlet 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 specifying Keep parameter, close the

session, or use the Remove-Job cmdlet to delete the job from the session.

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

-Location

Specifies an array of locations. This cmdlet gets only the results of jobs in the specified locations. The default is all jobs in the current session. Required? false Position? 1 Default value None Accept pipeline input? False Accept wildcard characters? false

-Name

Specifies an array of friendly names. This cmdlet gets the results of jobs that have the specified names. Wildcard characters are supported. The default is all jobs in the current session. Required? true Position? 0 Default value None

Accept pipeline input? True (ByPropertyName)

Accept wildcard characters? false

-NoRecurse []

Indicates 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. Required? false Position? named Default value False Accept pipeline input? False Accept wildcard characters? false

-Session

Specifies an array of sessions. This cmdlet gets the results of jobs that were run in the specified Windows 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.

Required? false Position? 1 Default value None

Accept pipeline input? True (ByPropertyName)

Accept wildcard characters? false

-Wait []

Indicates 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, or 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. Required? false Position? named Default value False Accept pipeline input? False Accept wildcard characters? false

-WriteEvents []

Indicates 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. Required? false Position? named Default value False Accept pipeline input? False Accept wildcard characters? false

-WriteJobInResults []

Indicates 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. Required? false Position? named Default value False Accept pipeline input? False Accept wildcard characters? false This cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. For more information, see about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).

INPUTS

System.Management.Automation.Job You can pipe job objects to this cmdlet.

OUTPUTS

PSObject This cmdlet returns the results of the commands in the job.

NOTES

Example 1: Get results for a particular job

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: Get results for a particular job by using the pipeline

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

PS C:\>$job | Receive-Job

This example is the same as the previous example, 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: Get results of several background jobs

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:\>$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: Get results of background jobs on multiple remote computers

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.