about_Job_Details

	Copy Code
TOPIC about_Job_Details SHORT DESCRIPTION Provides details about background jobs on local and remote computers. DETAILED DESCRIPTION This topic explains the concept of a background job and provides technical information about how background jobs work in Windows PowerShell. This topic is a supplement to the about_Jobs and about_Remote_Jobs topics. ABOUT BACKGROUND JOBS A background job runs a command or expression asynchronously. It might run a cmdlet, a function, a script, or any other command-based task. It is designed to run commands that take an extended period of time, but you can use it to run any command in the background. When a synchronous command runs, the Windows PowerShell command prompt is suppressed until the command is complete. But a background job does not suppress the Windows PowerShell prompt. A command to start a background job returns a job object. The prompt returns immediately so you can work on other tasks while the background job runs. However, when you start a background job, you do not get the results immediately even if the job runs very quickly. The job object that is returned contains useful information about the job, but it does not contain the job results. You must run a separate command to get the job results. You can also run commands to stop the job, to wait for the job to be completed, and to delete the job. To make the timing of a background job independent of other commands, each background job runs in its own Windows PowerShell environment (a "session"). However, this can be a temporary connection that is created only to run the job and is then destroyed, or it can be a persistent session (a PSSession) that you can use to run several related jobs or commands. USING THE JOB CMDLETS Use a Start-Job command to start a background job on a local computer. Start-Job returns a job object. You can also get objects representing the jobs that were started on the local computer by using the Get-Job cmdlet. To get the job results, use a Receive-Job command. If the job is not complete, Receive-Job returns partial results. You can also use the Wait-Job cmdlet to suppress the command prompt until one or all of the jobs that were started in the session are complete. To stop a background job, use the Stop-Job cmdlet. To delete a job, use the Remove-Job cmdlet. For more information about how the cmdlets work, see the Help topic for each cmdlet, and see about_Jobs. STARTING BACKGROUND JOBS ON REMOTE COMPUTERS You can create and manage background jobs on a local or remote computer. To run a background job remotely, use the AsJob parameter of a cmdlet such as Invoke-Command, or use the Invoke-Command cmdlet to run a Start-Job command remotely. You can also start a background job in an interactive session. For more information about remote background jobs, see about_Remote_Jobs. CHILD JOBS Each background job consists of a parent job and one or more child jobs. In jobs started by using Start-Job or the AsJob parameter of Invoke-Command, the parent job is an executive. It does not run any commands or return any results. The commands are actually run by the child jobs. (Jobs started by using other cmdlets might work differently.) The child jobs are stored in the ChildJobs property of the parent job object. The ChildJobs property can contain one or many child job objects. The child job objects have a name, ID, and instance ID that differ from the parent job so that you can manage the parent and child jobs individually or as a unit. To see the parent and child jobs in a job, use the Get-Job cmdlet to get the parent job, and then pipe the job to a Format-List command that displays the Name and ChildJobs properties of the objects, as shown in the following command. C:\PS> get-job \| format-list -property Name, ChildJobs Name : Job1 ChildJobs : {Job2} You can also use a Get-Job command on the child job, as shown in the following command: C:\PS> get-job job2 Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- 2 Job2 Completed True localhost get-process The configuration of the child job depends on the command that you use to start the job. -- When you use Start-Job to start a job on a local computer, the job consists of an executive parent job and a child job that runs the command. -- When you use the AsJob parameter of Invoke-Command to start a job on one or more computers, the job consists of an executive parent job and a child job for each job run on each computer. -- When you use Invoke-Command to run a Start-Job command on one or more remote computers, the result is the same as a local command run on each remote computer. The command returns a job object for each computer. The job object consists of an executive parent job and one child job that runs the command. The parent job represents all of the child jobs. When you manage a parent job, you also manage the associated child jobs. For example, if you stop a parent job, all child jobs are stopped. If you get the results of a parent job, you get the results of all child jobs. However, you can also manage child jobs individually. This is most useful when you want to investigate a problem with a job or get the results of only one of a number of child jobs started by using the AsJob parameter of Invoke-Command. (The backtick character [`] is the continuation character.) The following command uses the AsJob parameter of Invoke-Command to start background jobs on the local computer and two remote computers. The command saves the job in the $j variable. C:\PS> $j = invoke-command -computername localhost, Server01, Server02 ` -command {get-date} -AsJob When you display the Name and ChildJob properties of the job in $j, it shows that the command returned a job object with three child jobs, one for each computer. C:\PS> $j \| format-list name, childjobs Name : Job3 ChildJobs : {Job4, Job5, Job6} When you display the parent job, it shows that the job failed. C:\PS> $j Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- 1 Job3 Failed True localhost,server... get-date But when you run a Get-Job command on each of the child jobs, it shows that only one failed. PS C:\ps-test> get-job job4, job5, job6 Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- 4 Job4 Completed True localhost get-date 5 Job5 Failed False Server01 get-date 6 Job6 Completed True Server02 get-date To get the results of all child jobs, use the Receive-Job cmdlet to get the results of the parent job. But you can also get the results of a particular child job, as shown in the following command. C:\PS> receive-job -name job6 -keep \| format-table ComputerName, DateTime -auto ComputerName DateTime ------------ -------- Server02 Thursday, March 13, 2008 4:16:03 PM The child jobs feature of Windows PowerShell background jobs gives you more control over the jobs that you run. SEE ALSO about_Jobs about_Remote_Jobs about_Remote Invoke-Command Start-Job Get-Job Wait-Job Stop-Job Remove-Job New-PSSession Enter-PSSession Exit-PSSession

Copy Code

TOPIC
  about_Job_Details

SHORT DESCRIPTION
  Provides details about background jobs on local and remote computers.

DETAILED DESCRIPTION
   This topic explains the concept of a background job and provides technical
   information about how background jobs work in Windows PowerShell.

   This topic is a supplement to the about_Jobs and about_Remote_Jobs topics.


 ABOUT BACKGROUND JOBS
	A background job runs a command or expression asynchronously. It might run 
	a cmdlet, a function, a script, or any other command-based task. It is
	designed to run commands that take an extended period of time, but you
	can use it to run any command in the background.

	When a synchronous command runs, the Windows PowerShell command prompt is 
	suppressed until the command is complete. But a background job does not 
	suppress the Windows PowerShell prompt. A command to start a background job 
	returns a job object. The prompt returns immediately so you can work on 
	other tasks while the background job runs.
  
	However, when you start a background job, you do not get the results 
	immediately even if the job runs very quickly. The job object that is 
	returned contains useful information about the job, but it does not contain 
	the job results. You must run a separate command to get the job results. 
	You can also run commands to stop the job, to wait for the job to be 
	completed, and to delete the job.

	To make the timing of a background job independent of other commands, each 
	background job runs in its own Windows PowerShell environment 
	(a "session"). However, this can be a temporary connection that is created 
	only to run the job and is then destroyed, or it can be a persistent 
	session (a PSSession) that you can use to run several related jobs or 
	commands.


 USING THE JOB CMDLETS
	Use a Start-Job command to start a background job on a local computer. 
	Start-Job returns a job object. You can also get objects representing the 
	jobs that were started on the local computer by using the Get-Job cmdlet.

	To get the job results, use a Receive-Job command. If the job is not 
	complete, Receive-Job returns partial results. You can also use the 
	Wait-Job cmdlet to suppress the command prompt until one or all of the 
	jobs that were started in the session are complete.

	To stop a background job, use the Stop-Job cmdlet. To delete a job, use 
	the Remove-Job cmdlet.

	For more information about how the cmdlets work, see the Help topic for 
	each cmdlet, and see about_Jobs.

 
 STARTING BACKGROUND JOBS ON REMOTE COMPUTERS
	You can create and manage background jobs on a local or remote computer. To 
	run a background job remotely, use the AsJob parameter of a cmdlet such as 
	Invoke-Command, or use the Invoke-Command cmdlet to run a Start-Job 
	command remotely. You can also start a background job in an interactive 
	session.

	For more information about remote background jobs, see about_Remote_Jobs.


 CHILD JOBS
	Each background job consists of a parent job and one or more child jobs. In 
	jobs started by using Start-Job or the AsJob parameter of Invoke-Command, 
	the parent job is an executive. It does not run any commands or return any 
	results. The commands are actually run by the child jobs. (Jobs started by 
	using other cmdlets might work differently.)

	The child jobs are stored in the ChildJobs property of the parent job 
	object. The ChildJobs property can contain one or many child job objects. 
	The child job objects have a name, ID, and instance ID that differ 
	from the parent job so that you can manage the parent and child jobs 
	individually or as a unit.

	To see the parent and child jobs in a job, use the Get-Job cmdlet to get 
	the parent job, and then pipe the job to a Format-List command that displays 
	the Name and ChildJobs properties of the objects, as shown in the following 
	command.

		C:\PS> get-job | format-list -property Name, ChildJobs

		Name		: Job1
		ChildJobs	 : {Job2}


	You can also use a Get-Job command on the child job, as shown in the 
	following command:

		C:\PS> get-job job2

		Id	Name   State	HasMoreData   Location	Command
		--	----   -----	-----------   --------	-------
		2	 Job2   Completed  True		localhost   get-process


	The configuration of the child job depends on the command that you use to 
	start the job.

	 -- When you use Start-Job to start a job on a local computer, the job 
		consists of an executive parent job and a child job that runs the 
		command.

	 -- When you use the AsJob parameter of Invoke-Command to start a job on 
		one or more computers, the job consists of an executive parent job 
		and a child job for each job run on each computer.

	 -- When you use Invoke-Command to run a Start-Job command on one or more 
		remote computers, the result is the same as a local command run on 
		each remote computer. The command returns a job object for each 
		computer. The job object consists of an executive parent job and
		one child job that runs the command.

	The parent job represents all of the child jobs. When you manage a parent 
	job, you also manage the associated child jobs. For example, if you stop a 
	parent job, all child jobs are stopped. If you get the results of a parent 
	job, you get the results of all child jobs.

	However, you can also manage child jobs individually. This is most useful 
	when you want to investigate a problem with a job or get the results of 
	only one of a number of child jobs started by using the AsJob parameter of 
	Invoke-Command. (The backtick character [`] is the continuation character.)

	The following command uses the AsJob parameter of Invoke-Command to start 
	background jobs on the local computer and two remote computers. The command 
	saves the job in the $j variable.

		C:\PS> $j = invoke-command -computername localhost, Server01, Server02 `
			 -command {get-date} -AsJob

	When you display the Name and ChildJob properties of the job in $j, it 
	shows that the command returned a job object with three child jobs, one for 
	each computer.

		C:\PS> $j | format-list name, childjobs

		Name	: Job3
		ChildJobs : {Job4, Job5, Job6}


	When you display the parent job, it shows that the job failed.

		C:\PS> $j

		Id   Name	State   HasMoreData	 Location			 Command
		--   ----	-----   -----------	 --------			 -------
		1	Job3	Failed  True			localhost,server... get-date


	But when you run a Get-Job command on each of the child jobs, it shows 
	that only one failed.

		PS C:\ps-test> get-job job4, job5, job6

		Id   Name   State	HasMoreData	 Location		 Command
		--   ----   -----	-----------	 --------		 -------
		4	Job4   Completed  True			localhost		get-date
		5	Job5   Failed	 False		 Server01		 get-date
		6	Job6   Completed  True			Server02		 get-date



	To get the results of all child jobs, use the Receive-Job cmdlet to get 
	the results of the parent job. But you can also get the results of a 
	particular child job, as shown in the following command.

		C:\PS> receive-job -name job6 -keep | format-table ComputerName, DateTime -auto

		ComputerName DateTime
		------------ --------
		Server02	 Thursday, March 13, 2008 4:16:03 PM

	The child jobs feature of Windows PowerShell background jobs gives you 
	more control over the jobs that you run.


SEE ALSO
	about_Jobs
	about_Remote_Jobs
	about_Remote
	Invoke-Command
	Start-Job
	Get-Job
	Wait-Job
	Stop-Job
	Remove-Job
	New-PSSession
	Enter-PSSession
	Exit-PSSession