diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md index d572715b47d4..e18e93184bb7 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -1,7 +1,7 @@ --- description: Provides details about background jobs on local and remote computers. Locale: en-US -ms.date: 10/16/2020 +ms.date: 03/24/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_job_details?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Job_Details @@ -9,6 +9,7 @@ title: about_Job_Details # about_Job_Details ## Short description + Provides details about background jobs on local and remote computers. ## Detailed description @@ -16,33 +17,31 @@ Provides details about background jobs on local and remote computers. This topic explains the concept of a background job and provides technical information about how background jobs work in PowerShell. -This topic is a supplement to the [about_Jobs](about_Jobs.md), -[about_Thread_Jobs](/powershell/module/microsoft.powershell.core/about/about_Thread_Jobs), -and [about_Remote_Jobs](about_Remote_Jobs.md) topics. +This topic is a supplement to the [about_Jobs][03], [about_Thread_Jobs][06], +and [about_Remote_Jobs][04] 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 +cmdlet, a function, a script, or any other command-based task. It's 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 PowerShell command prompt is suppressed -until the command is complete. But a background job does not suppress the +until the command is complete. But a background job doesn't suppress the 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. +However, when you start a background job, you don't get the results immediately +even if the job runs very quickly. The job object that's returned contains +useful information about the job, but it doesn't 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 PowerShell session. However, this can be a -temporary connection that is created only to run the job and is then destroyed, +temporary connection that's created only to run the job and is then destroyed, or it can be a persistent **PSSession** that you can use to run several related jobs or commands. @@ -52,16 +51,16 @@ 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 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 get the job results, use a `Receive-Job` command. If the job isn't 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](about_Jobs.md). +cmdlet, and see [about_Jobs][03]. ### Starting background jobs on remote computers @@ -72,13 +71,13 @@ command remotely. You can also start a background job in an interactive session. For more information about remote background jobs, see -[about_Remote_Jobs](about_Remote_Jobs.md). +[about_Remote_Jobs][04]. ### Child jobs Each background job consists of a parent job and one or more child jobs. In jobs started 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 +the parent job is an executive. It doesn't run any commands or return any results. The commands are actually run by the child jobs. Jobs started using other cmdlets might work differently. @@ -93,8 +92,10 @@ parameter of the `Get-Job` cmdlet. The **IncludeChildJob** parameter was introduced in Windows PowerShell 3.0. ```powershell -PS> Get-Job -IncludeChildJob +Get-Job -IncludeChildJob +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 RemoteJob Failed True localhost Get-Process @@ -107,8 +108,10 @@ value, use the **ChildJobState** parameter of the `Get-Job` cmdlet. The **ChildJobState** parameter was introduced in Windows PowerShell 3.0. ```powershell -PS> Get-Job -ChildJobState Failed +Get-Job -ChildJobState Failed +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 RemoteJob Failed True localhost Get-Process @@ -119,8 +122,10 @@ To get the child jobs of a job on all versions of PowerShell, use the **ChildJob** property of the parent job. ```powershell -PS> (Get-Job Job1).ChildJobs +(Get-Job Job1).ChildJobs +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 Job2 Completed True Server01 Get-Process @@ -131,8 +136,10 @@ You can also use a `Get-Job` command on the child job, as shown in the following command: ```powershell -PS> Get-Job Job3 +Get-Job Job3 +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 3 Job3 Failed False localhost Get-Process @@ -169,8 +176,12 @@ background jobs on the local computer and two remote computers. The command saves the job in the `$j` variable. ```powershell -PS> $j = Invoke-Command -ComputerName localhost, Server01, Server02 ` --Command {Get-Date} -AsJob +$invokeCommandSplat = @{ + ComputerName = 'localhost', 'Server01', 'Server02' + ScriptBlock = {Get-Date} + AsJob = $true +} +$j = Invoke-Command @invokeCommandSplat ``` When you display the Name and **ChildJob** properties of the job in `$j`, it @@ -178,8 +189,10 @@ shows that the command returned a job object with three child jobs, one for each computer. ```powershell -PS> $j | Format-List Name, ChildJobs +$j | Format-List Name, ChildJobs +``` +```Output Name : Job3 ChildJobs : {Job4, Job5, Job6} ``` @@ -187,8 +200,10 @@ ChildJobs : {Job4, Job5, Job6} When you display the parent job, it shows that the job failed. ```powershell -PS> $j +$j +``` +```Output Id Name PSJobTypeName State HasMoreData Location -- ---- ------------- ----- ----------- -------- 3 Job3 RemotingJob Failed False localhost,Server... @@ -198,8 +213,10 @@ But when you run a `Get-Job` command that gets the child jobs, the output shows that only one child job failed. ```powershell -PS> Get-Job -IncludeChildJobs +Get-Job -IncludeChildJobs +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 3 Job3 RemotingJob Failed False localhost,Server... @@ -208,13 +225,16 @@ Id Name PSJobTypeName State HasMoreData Location Command 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. +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. ```powershell -PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, ->> DateTime -AutoSize +Receive-Job -Name Job6 -Keep | + Format-Table ComputerName, DateTime -AutoSize +``` + +```Output ComputerName DateTime ------------ -------- Server02 Thursday, March 13, 2008 4:16:03 PM @@ -226,17 +246,15 @@ more control over the jobs that you run. ### Job types PowerShell supports different types of jobs for different tasks. Beginning in -Windows PowerShell 3.0, developers can write "job source adapters" that add -new job types to PowerShell and include the job source adapters in modules. -When you import the module, you can use the new job type in your session. - -For example, the PSScheduledJob module adds scheduled jobs and the PSWorkflow +Windows PowerShell 3.0, developers can write "job source adapters" that add new +job types to PowerShell and include the job source adapters in modules. When +you import the module, you can use the new job type in your session. For +example, the PSScheduledJob module adds scheduled jobs and the PSWorkflow module adds workflow jobs. Custom jobs types might differ significantly from standard PowerShell -background jobs. For example, scheduled jobs are saved on disk; they do not -exist only in a particular session. Workflow jobs can be suspended and -resumed. +background jobs. For example, scheduled jobs are saved on disk; they don't +exist only in a particular session. Workflow jobs can be suspended and resumed. The cmdlets that you use to manage custom jobs depend on the job type. For some, you use the standard job cmdlets, such as `Get-Job` and `Start-Job`. @@ -249,39 +267,50 @@ different job objects for different types of jobs. The value of the **PSJobTypeName** property of the job objects that `Get-Job` returns indicates the job type. -The following table lists the job types that come with PowerShell. - -| Job Type | Description | -| -------------- | -------------------------------------------------------- | -| BackgroundJob | Started using the `Start-Job` cmdlet. | -| RemoteJob | Started using the **AsJob** parameter of the | -| | `Invoke-Command` cmdlet. | -| PSWorkflowJob | Started using the **AsJob** parameter of a workflow. | -| PSScheduledJob | An instance of a scheduled job started by a job trigger. | -| CIMJob | Started using the **AsJob** parameter of a cmdlet from a | -| | CDXML module. | -| WMIJob | Started using the **AsJob** parameter of a cmdlet from a | -| | WMI module. | -| PSEventJob | Created using`Register-ObjectEvent` and specifying an | -| | action with the **Action** parameter. | +The following list describes the built-in PowerShell job types. + +- **BackgroundJob** - Started using the `Start-Job` cmdlet. +- **RemoteJob** - Started using the **AsJob** parameter of the `Invoke-Command` + cmdlet. +- **CIMJob** - Started using the **AsJob** parameter of a cmdlet from a CDXML + module. +- **WMIJob** - Started using the **AsJob** parameter of a cmdlet from a WMI + module. +- **PSEventJob** - Created using`Register-ObjectEvent` and specifying an action + with the **Action** parameter. > [!NOTE] > Before using the `Get-Job` cmdlet to get jobs of a particular type, verify > that the module that adds the job type is imported into the current session. -> Otherwise, `Get-Job` does not get jobs of that type. +> Otherwise, `Get-Job` can't get jobs of that type. + +Windows PowerShell 5.1 includes the following additional job types. + +- **PSWorkflowJob** - Started using the **AsJob** parameter of a workflow. +- **PSScheduledJob** - An instance of a scheduled job started by a job trigger. + +These job types are only available in Windows PowerShell 5.1. The modules that +add these job types aren't compatible with PowerShell 6.0 and later. + +For more information, see the following articles: + +- [about_Scheduled_Jobs][01] +- [about_Workflows][02] ## Examples The following commands create a local background job, a remote background job, a workflow job, and a scheduled job. Then, it uses the `Get-Job` cmdlet to get -the jobs. `Get-Job` does not get the scheduled job, but it gets any started +the jobs. `Get-Job` doesn't get the scheduled job, but it gets any started instances of the scheduled job. Start a background job on the local computer. ```powershell -PS> Start-Job -Name LocalData {Get-Process} +Start-Job -Name LocalData {Get-Process} +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 LocalData BackgroundJob Running True localhost Get-Process @@ -290,9 +319,16 @@ Id Name PSJobTypeName State HasMoreData Location Command Start a background job that runs on a remote computer. ```powershell -PS> Invoke-Command -ComputerName Server01 {Get-Process} ` --AsJob -JobName RemoteData +$invokeCommandSplat = @{ + ComputerName = 'Server01' + AsJob = $true + JobName = 'RemoteData' + ScriptBlock = {Get-Process} +} +Invoke-Command @invokeCommandSplat +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 RemoteData RemoteJob Running True Server01 Get-Process @@ -301,9 +337,15 @@ Id Name PSJobTypeName State HasMoreData Location Command Create a scheduled job ```powershell -PS> Register-ScheduledJob -Name ScheduledJob -ScriptBlock ` - {Get-Process} -Trigger (New-JobTrigger -Once -At "3 PM") +$registerScheduledJobSplat = @{ + Name = 'ScheduledJob' + ScriptBlock = {Get-Process} + Trigger = (New-JobTrigger -Once -At "3 PM") +} +Register-ScheduledJob @registerScheduledJobSplat +``` +```Output Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 ScheduledJob 1 Get-Process True @@ -312,26 +354,29 @@ Id Name JobTriggers Command Enabled Create a workflow. ```powershell -PS> workflow Test-Workflow {Get-Process} +workflow Test-Workflow {Get-Process} ``` Run the workflow as a job. ```powershell +Test-Workflow -AsJob -JobName TestWFJob +``` -PS> Test-Workflow -AsJob -JobName TestWFJob - +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process ``` -Get the jobs. The `Get-Job` command does not get scheduled jobs, but it gets +Get the jobs. The `Get-Job` command doesn't get scheduled jobs, but it gets instances of the scheduled job that are started. ```powershell -PS> Get-Job +Get-Job +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 LocalData BackgroundJob Completed True localhost Get-Process @@ -343,8 +388,10 @@ Id Name PSJobTypeName State HasMoreData Location Command To get scheduled jobs, use the `Get-ScheduledJob` cmdlet. ```powershell -PS> Get-ScheduledJob +Get-ScheduledJob +``` +```Output Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- 1 ScheduledJob 1 Get-Process True @@ -352,16 +399,33 @@ Id Name JobTriggers Command Enabled ## See also -- [about_Jobs](about_Jobs.md) -- [about_Remote](about_Remote.md) -- [about_Remote_Jobs](about_Remote_Jobs.md) -- [about_Thread_Jobs](/powershell/module/microsoft.powershell.core/about/about_Thread_Jobs) -- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command) -- [Get-Job](xref:Microsoft.PowerShell.Core.Get-Job) -- [Remove-Job](xref:Microsoft.PowerShell.Core.Remove-Job) -- [Start-Job](xref:Microsoft.PowerShell.Core.Start-Job) -- [Stop-Job](xref:Microsoft.PowerShell.Core.Stop-Job) -- [Wait-Job](xref:Microsoft.PowerShell.Core.Wait-Job) -- [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession) -- [Exit-PSSession](xref:Microsoft.PowerShell.Core.Exit-PSSession) -- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) +- [about_Jobs][03] +- [about_Remote][05] +- [about_Remote_Jobs][04] +- [about_Thread_Jobs][06] +- [Invoke-Command][10] +- [Get-Job][09] +- [Remove-Job][12] +- [Start-Job][13] +- [Stop-Job][14] +- [Wait-Job][15] +- [Enter-PSSession][07] +- [Exit-PSSession][08] +- [New-PSSession][11] + + +[01]: /powershell/module/psscheduledjob/about/about_scheduled_jobs?view=powershell-5.1&preserve-view=true +[02]: /powershell/module/psworkflow/about/about_workflows?view=powershell-5.1&preserve-view=true +[03]: about_Jobs.md +[04]: about_Remote_Jobs.md +[05]: about_Remote.md +[06]: /powershell/module/microsoft.powershell.core/about/about_Thread_Jobs +[07]: xref:Microsoft.PowerShell.Core.Enter-PSSession +[08]: xref:Microsoft.PowerShell.Core.Exit-PSSession +[09]: xref:Microsoft.PowerShell.Core.Get-Job +[10]: xref:Microsoft.PowerShell.Core.Invoke-Command +[11]: xref:Microsoft.PowerShell.Core.New-PSSession +[12]: xref:Microsoft.PowerShell.Core.Remove-Job +[13]: xref:Microsoft.PowerShell.Core.Start-Job +[14]: xref:Microsoft.PowerShell.Core.Stop-Job +[15]: xref:Microsoft.PowerShell.Core.Wait-Job diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Job_Details.md index 65cb9c53743d..e851ef1825ba 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -1,7 +1,7 @@ --- description: Provides details about background jobs on local and remote computers. Locale: en-US -ms.date: 10/16/2020 +ms.date: 03/24/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_job_details?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Job_Details @@ -9,6 +9,7 @@ title: about_Job_Details # about_Job_Details ## Short description + Provides details about background jobs on local and remote computers. ## Detailed description @@ -16,33 +17,31 @@ Provides details about background jobs on local and remote computers. This topic explains the concept of a background job and provides technical information about how background jobs work in PowerShell. -This topic is a supplement to the [about_Jobs](about_Jobs.md), -[about_Thread_Jobs](about_Thread_Jobs.md), and -[about_Remote_Jobs](about_Remote_Jobs.md) topics. +This topic is a supplement to the [about_Jobs][03], [about_Thread_Jobs][06], +and [about_Remote_Jobs][04] 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 +cmdlet, a function, a script, or any other command-based task. It's 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 PowerShell command prompt is suppressed -until the command is complete. But a background job does not suppress the +until the command is complete. But a background job doesn't suppress the 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. +However, when you start a background job, you don't get the results immediately +even if the job runs very quickly. The job object that's returned contains +useful information about the job, but it doesn't 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 PowerShell session. However, this can be a -temporary connection that is created only to run the job and is then destroyed, +temporary connection that's created only to run the job and is then destroyed, or it can be a persistent **PSSession** that you can use to run several related jobs or commands. @@ -52,16 +51,16 @@ 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 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 get the job results, use a `Receive-Job` command. If the job isn't 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](about_Jobs.md). +cmdlet, and see [about_Jobs][03]. ### Starting background jobs on remote computers @@ -72,13 +71,13 @@ command remotely. You can also start a background job in an interactive session. For more information about remote background jobs, see -[about_Remote_Jobs](about_Remote_Jobs.md). +[about_Remote_Jobs][04]. ### Child jobs Each background job consists of a parent job and one or more child jobs. In jobs started 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 +the parent job is an executive. It doesn't run any commands or return any results. The commands are actually run by the child jobs. Jobs started using other cmdlets might work differently. @@ -93,8 +92,10 @@ parameter of the `Get-Job` cmdlet. The **IncludeChildJob** parameter was introduced in Windows PowerShell 3.0. ```powershell -PS> Get-Job -IncludeChildJob +Get-Job -IncludeChildJob +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 RemoteJob Failed True localhost Get-Process @@ -107,8 +108,10 @@ value, use the **ChildJobState** parameter of the `Get-Job` cmdlet. The **ChildJobState** parameter was introduced in Windows PowerShell 3.0. ```powershell -PS> Get-Job -ChildJobState Failed +Get-Job -ChildJobState Failed +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 RemoteJob Failed True localhost Get-Process @@ -119,8 +122,10 @@ To get the child jobs of a job on all versions of PowerShell, use the **ChildJob** property of the parent job. ```powershell -PS> (Get-Job Job1).ChildJobs +(Get-Job Job1).ChildJobs +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 Job2 Completed True Server01 Get-Process @@ -131,8 +136,10 @@ You can also use a `Get-Job` command on the child job, as shown in the following command: ```powershell -PS> Get-Job Job3 +Get-Job Job3 +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 3 Job3 Failed False localhost Get-Process @@ -169,8 +176,12 @@ background jobs on the local computer and two remote computers. The command saves the job in the `$j` variable. ```powershell -PS> $j = Invoke-Command -ComputerName localhost, Server01, Server02 ` --Command {Get-Date} -AsJob +$invokeCommandSplat = @{ + ComputerName = 'localhost', 'Server01', 'Server02' + ScriptBlock = {Get-Date} + AsJob = $true +} +$j = Invoke-Command @invokeCommandSplat ``` When you display the Name and **ChildJob** properties of the job in `$j`, it @@ -178,8 +189,10 @@ shows that the command returned a job object with three child jobs, one for each computer. ```powershell -PS> $j | Format-List Name, ChildJobs +$j | Format-List Name, ChildJobs +``` +```Output Name : Job3 ChildJobs : {Job4, Job5, Job6} ``` @@ -187,8 +200,10 @@ ChildJobs : {Job4, Job5, Job6} When you display the parent job, it shows that the job failed. ```powershell -PS> $j +$j +``` +```Output Id Name PSJobTypeName State HasMoreData Location -- ---- ------------- ----- ----------- -------- 3 Job3 RemotingJob Failed False localhost,Server... @@ -198,8 +213,10 @@ But when you run a `Get-Job` command that gets the child jobs, the output shows that only one child job failed. ```powershell -PS> Get-Job -IncludeChildJobs +Get-Job -IncludeChildJobs +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 3 Job3 RemotingJob Failed False localhost,Server... @@ -208,13 +225,16 @@ Id Name PSJobTypeName State HasMoreData Location Command 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. +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. ```powershell -PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, ->> DateTime -AutoSize +Receive-Job -Name Job6 -Keep | + Format-Table ComputerName, DateTime -AutoSize +``` + +```Output ComputerName DateTime ------------ -------- Server02 Thursday, March 13, 2008 4:16:03 PM @@ -226,17 +246,15 @@ more control over the jobs that you run. ### Job types PowerShell supports different types of jobs for different tasks. Beginning in -Windows PowerShell 3.0, developers can write "job source adapters" that add -new job types to PowerShell and include the job source adapters in modules. -When you import the module, you can use the new job type in your session. - -For example, the PSScheduledJob module adds scheduled jobs and the PSWorkflow +Windows PowerShell 3.0, developers can write "job source adapters" that add new +job types to PowerShell and include the job source adapters in modules. When +you import the module, you can use the new job type in your session. For +example, the PSScheduledJob module adds scheduled jobs and the PSWorkflow module adds workflow jobs. Custom jobs types might differ significantly from standard PowerShell -background jobs. For example, scheduled jobs are saved on disk; they do not -exist only in a particular session. Workflow jobs can be suspended and -resumed. +background jobs. For example, scheduled jobs are saved on disk; they don't +exist only in a particular session. Workflow jobs can be suspended and resumed. The cmdlets that you use to manage custom jobs depend on the job type. For some, you use the standard job cmdlets, such as `Get-Job` and `Start-Job`. @@ -249,32 +267,41 @@ different job objects for different types of jobs. The value of the **PSJobTypeName** property of the job objects that `Get-Job` returns indicates the job type. -The following table lists the job types that come with PowerShell. - -| Job Type | Description | -| -------------- | -------------------------------------------------------- | -| BackgroundJob | Started using the `Start-Job` cmdlet. | -| RemoteJob | Started using the **AsJob** parameter of the | -| | `Invoke-Command` cmdlet. | -| PSWorkflowJob | Started using the **AsJob** parameter of a workflow. | -| PSScheduledJob | An instance of a scheduled job started by a job trigger. | -| CIMJob | Started using the **AsJob** parameter of a cmdlet from a | -| | CDXML module. | -| WMIJob | Started using the **AsJob** parameter of a cmdlet from a | -| | WMI module. | -| PSEventJob | Created using`Register-ObjectEvent` and specifying an | -| | action with the **Action** parameter. | +The following list describes the built-in PowerShell job types. + +- **BackgroundJob** - Started using the `Start-Job` cmdlet. +- **RemoteJob** - Started using the **AsJob** parameter of the `Invoke-Command` + cmdlet. +- **CIMJob** - Started using the **AsJob** parameter of a cmdlet from a CDXML + module. +- **WMIJob** - Started using the **AsJob** parameter of a cmdlet from a WMI + module. +- **PSEventJob** - Created using`Register-ObjectEvent` and specifying an action + with the **Action** parameter. > [!NOTE] > Before using the `Get-Job` cmdlet to get jobs of a particular type, verify > that the module that adds the job type is imported into the current session. -> Otherwise, `Get-Job` does not get jobs of that type. +> Otherwise, `Get-Job` can't get jobs of that type. + +Windows PowerShell 5.1 includes the following additional job types. + +- **PSWorkflowJob** - Started using the **AsJob** parameter of a workflow. +- **PSScheduledJob** - An instance of a scheduled job started by a job trigger. + +These job types are only available in Windows PowerShell 5.1. The modules that +add these job types aren't compatible with PowerShell 6.0 and later. + +For more information, see the following articles: + +- [about_Scheduled_Jobs][01] +- [about_Workflows][02] ## Examples The following commands create a local background job, a remote background job, a workflow job, and a scheduled job. Then, it uses the `Get-Job` cmdlet to get -the jobs. `Get-Job` does not get the scheduled job, but it gets any started +the jobs. `Get-Job` doesn't get the scheduled job, but it gets any started instances of the scheduled job. Start a background job on the local computer. @@ -290,78 +317,50 @@ Id Name PSJobTypeName State HasMoreData Location Command Start a background job that runs on a remote computer. ```powershell -PS> Invoke-Command -ComputerName Server01 {Get-Process} ` --AsJob -JobName RemoteData +$invokeCommandSplat = @{ + ComputerName = 'Server01' + AsJob = $true + JobName = 'RemoteData' + ScriptBlock = {Get-Process} +} +Invoke-Command @invokeCommandSplat +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 RemoteData RemoteJob Running True Server01 Get-Process ``` -Create a scheduled job - -```powershell -PS> Register-ScheduledJob -Name ScheduledJob -ScriptBlock ` - {Get-Process} -Trigger (New-JobTrigger -Once -At "3 PM") - -Id Name JobTriggers Command Enabled --- ---- ----------- ------- ------- -1 ScheduledJob 1 Get-Process True -``` - -Create a workflow. - -```powershell -PS> workflow Test-Workflow {Get-Process} -``` - -Run the workflow as a job. - -```powershell - -PS> Test-Workflow -AsJob -JobName TestWFJob - -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process -``` - -Get the jobs. The `Get-Job` command does not get scheduled jobs, but it gets -instances of the scheduled job that are started. - -```powershell -PS> Get-Job - -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 LocalData BackgroundJob Completed True localhost Get-Process -4 RemoteData RemoteJob Completed True Server01 Get-Process -6 TestWFJob PSWorkflowJob Completed True localhost WorkflowJob -8 ScheduledJob PSScheduledJob Completed True localhost Get-Process -``` - -To get scheduled jobs, use the `Get-ScheduledJob` cmdlet. - -```powershell -PS> Get-ScheduledJob - -Id Name JobTriggers Command Enabled --- ---- ----------- ------- ------- -1 ScheduledJob 1 Get-Process True -``` - ## See also -- [about_Jobs](about_Jobs.md) -- [about_Remote](about_Remote.md) -- [about_Remote_Jobs](about_Remote_Jobs.md) -- [about_Thread_Jobs](about_Thread_Jobs.md) -- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command) -- [Get-Job](xref:Microsoft.PowerShell.Core.Get-Job) -- [Remove-Job](xref:Microsoft.PowerShell.Core.Remove-Job) -- [Start-Job](xref:Microsoft.PowerShell.Core.Start-Job) -- [Stop-Job](xref:Microsoft.PowerShell.Core.Stop-Job) -- [Wait-Job](xref:Microsoft.PowerShell.Core.Wait-Job) -- [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession) -- [Exit-PSSession](xref:Microsoft.PowerShell.Core.Exit-PSSession) -- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) +- [about_Jobs][03] +- [about_Remote][05] +- [about_Remote_Jobs][04] +- [about_Thread_Jobs][06] +- [Invoke-Command][10] +- [Get-Job][09] +- [Remove-Job][12] +- [Start-Job][13] +- [Stop-Job][14] +- [Wait-Job][15] +- [Enter-PSSession][07] +- [Exit-PSSession][08] +- [New-PSSession][11] + + +[01]: /powershell/module/psscheduledjob/about/about_scheduled_jobs?view=powershell-5.1&preserve-view=true +[02]: /powershell/module/psworkflow/about/about_workflows?view=powershell-5.1&preserve-view=true +[03]: about_Jobs.md +[04]: about_Remote_Jobs.md +[05]: about_Remote.md +[06]: about_Thread_Jobs.md +[07]: xref:Microsoft.PowerShell.Core.Enter-PSSession +[08]: xref:Microsoft.PowerShell.Core.Exit-PSSession +[09]: xref:Microsoft.PowerShell.Core.Get-Job +[10]: xref:Microsoft.PowerShell.Core.Invoke-Command +[11]: xref:Microsoft.PowerShell.Core.New-PSSession +[12]: xref:Microsoft.PowerShell.Core.Remove-Job +[13]: xref:Microsoft.PowerShell.Core.Start-Job +[14]: xref:Microsoft.PowerShell.Core.Stop-Job +[15]: xref:Microsoft.PowerShell.Core.Wait-Job diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Job_Details.md index be3253aa7d58..8534801df59a 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -1,7 +1,7 @@ --- description: Provides details about background jobs on local and remote computers. Locale: en-US -ms.date: 10/16/2020 +ms.date: 03/24/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_job_details?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Job_Details @@ -17,33 +17,31 @@ Provides details about background jobs on local and remote computers. This topic explains the concept of a background job and provides technical information about how background jobs work in PowerShell. -This topic is a supplement to the [about_Jobs](about_Jobs.md), -[about_Thread_Jobs](about_Thread_Jobs.md), and -[about_Remote_Jobs](about_Remote_Jobs.md) topics. +This topic is a supplement to the [about_Jobs][03], [about_Thread_Jobs][06], +and [about_Remote_Jobs][04] 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 +cmdlet, a function, a script, or any other command-based task. It's 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 PowerShell command prompt is suppressed -until the command is complete. But a background job does not suppress the +until the command is complete. But a background job doesn't suppress the 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. +However, when you start a background job, you don't get the results immediately +even if the job runs very quickly. The job object that's returned contains +useful information about the job, but it doesn't 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 PowerShell session. However, this can be a -temporary connection that is created only to run the job and is then destroyed, +temporary connection that's created only to run the job and is then destroyed, or it can be a persistent **PSSession** that you can use to run several related jobs or commands. @@ -53,16 +51,16 @@ 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 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 get the job results, use a `Receive-Job` command. If the job isn't 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](about_Jobs.md). +cmdlet, and see [about_Jobs][03]. ### Starting background jobs on remote computers @@ -73,13 +71,13 @@ command remotely. You can also start a background job in an interactive session. For more information about remote background jobs, see -[about_Remote_Jobs](about_Remote_Jobs.md). +[about_Remote_Jobs][04]. ### Child jobs Each background job consists of a parent job and one or more child jobs. In jobs started 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 +the parent job is an executive. It doesn't run any commands or return any results. The commands are actually run by the child jobs. Jobs started using other cmdlets might work differently. @@ -94,8 +92,10 @@ parameter of the `Get-Job` cmdlet. The **IncludeChildJob** parameter was introduced in Windows PowerShell 3.0. ```powershell -PS> Get-Job -IncludeChildJob +Get-Job -IncludeChildJob +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 RemoteJob Failed True localhost Get-Process @@ -108,8 +108,10 @@ value, use the **ChildJobState** parameter of the `Get-Job` cmdlet. The **ChildJobState** parameter was introduced in Windows PowerShell 3.0. ```powershell -PS> Get-Job -ChildJobState Failed +Get-Job -ChildJobState Failed +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 RemoteJob Failed True localhost Get-Process @@ -120,8 +122,10 @@ To get the child jobs of a job on all versions of PowerShell, use the **ChildJob** property of the parent job. ```powershell -PS> (Get-Job Job1).ChildJobs +(Get-Job Job1).ChildJobs +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 Job2 Completed True Server01 Get-Process @@ -132,8 +136,10 @@ You can also use a `Get-Job` command on the child job, as shown in the following command: ```powershell -PS> Get-Job Job3 +Get-Job Job3 +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 3 Job3 Failed False localhost Get-Process @@ -170,8 +176,12 @@ background jobs on the local computer and two remote computers. The command saves the job in the `$j` variable. ```powershell -PS> $j = Invoke-Command -ComputerName localhost, Server01, Server02 ` --Command {Get-Date} -AsJob +$invokeCommandSplat = @{ + ComputerName = 'localhost', 'Server01', 'Server02' + ScriptBlock = {Get-Date} + AsJob = $true +} +$j = Invoke-Command @invokeCommandSplat ``` When you display the Name and **ChildJob** properties of the job in `$j`, it @@ -179,8 +189,10 @@ shows that the command returned a job object with three child jobs, one for each computer. ```powershell -PS> $j | Format-List Name, ChildJobs +$j | Format-List Name, ChildJobs +``` +```Output Name : Job3 ChildJobs : {Job4, Job5, Job6} ``` @@ -188,8 +200,10 @@ ChildJobs : {Job4, Job5, Job6} When you display the parent job, it shows that the job failed. ```powershell -PS> $j +$j +``` +```Output Id Name PSJobTypeName State HasMoreData Location -- ---- ------------- ----- ----------- -------- 3 Job3 RemotingJob Failed False localhost,Server... @@ -199,8 +213,10 @@ But when you run a `Get-Job` command that gets the child jobs, the output shows that only one child job failed. ```powershell -PS> Get-Job -IncludeChildJobs +Get-Job -IncludeChildJobs +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 3 Job3 RemotingJob Failed False localhost,Server... @@ -209,13 +225,16 @@ Id Name PSJobTypeName State HasMoreData Location Command 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. +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. ```powershell -PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, ->> DateTime -AutoSize +Receive-Job -Name Job6 -Keep | + Format-Table ComputerName, DateTime -AutoSize +``` + +```Output ComputerName DateTime ------------ -------- Server02 Thursday, March 13, 2008 4:16:03 PM @@ -227,17 +246,15 @@ more control over the jobs that you run. ### Job types PowerShell supports different types of jobs for different tasks. Beginning in -Windows PowerShell 3.0, developers can write "job source adapters" that add -new job types to PowerShell and include the job source adapters in modules. -When you import the module, you can use the new job type in your session. - -For example, the PSScheduledJob module adds scheduled jobs and the PSWorkflow +Windows PowerShell 3.0, developers can write "job source adapters" that add new +job types to PowerShell and include the job source adapters in modules. When +you import the module, you can use the new job type in your session. For +example, the PSScheduledJob module adds scheduled jobs and the PSWorkflow module adds workflow jobs. Custom jobs types might differ significantly from standard PowerShell -background jobs. For example, scheduled jobs are saved on disk; they do not -exist only in a particular session. Workflow jobs can be suspended and -resumed. +background jobs. For example, scheduled jobs are saved on disk; they don't +exist only in a particular session. Workflow jobs can be suspended and resumed. The cmdlets that you use to manage custom jobs depend on the job type. For some, you use the standard job cmdlets, such as `Get-Job` and `Start-Job`. @@ -250,32 +267,41 @@ different job objects for different types of jobs. The value of the **PSJobTypeName** property of the job objects that `Get-Job` returns indicates the job type. -The following table lists the job types that come with PowerShell. - -| Job Type | Description | -| -------------- | -------------------------------------------------------- | -| BackgroundJob | Started using the `Start-Job` cmdlet. | -| RemoteJob | Started using the **AsJob** parameter of the | -| | `Invoke-Command` cmdlet. | -| PSWorkflowJob | Started using the **AsJob** parameter of a workflow. | -| PSScheduledJob | An instance of a scheduled job started by a job trigger. | -| CIMJob | Started using the **AsJob** parameter of a cmdlet from a | -| | CDXML module. | -| WMIJob | Started using the **AsJob** parameter of a cmdlet from a | -| | WMI module. | -| PSEventJob | Created using`Register-ObjectEvent` and specifying an | -| | action with the **Action** parameter. | +The following list describes the built-in PowerShell job types. + +- **BackgroundJob** - Started using the `Start-Job` cmdlet. +- **RemoteJob** - Started using the **AsJob** parameter of the `Invoke-Command` + cmdlet. +- **CIMJob** - Started using the **AsJob** parameter of a cmdlet from a CDXML + module. +- **WMIJob** - Started using the **AsJob** parameter of a cmdlet from a WMI + module. +- **PSEventJob** - Created using`Register-ObjectEvent` and specifying an action + with the **Action** parameter. > [!NOTE] > Before using the `Get-Job` cmdlet to get jobs of a particular type, verify > that the module that adds the job type is imported into the current session. -> Otherwise, `Get-Job` does not get jobs of that type. +> Otherwise, `Get-Job` can't get jobs of that type. + +Windows PowerShell 5.1 includes the following additional job types. + +- **PSWorkflowJob** - Started using the **AsJob** parameter of a workflow. +- **PSScheduledJob** - An instance of a scheduled job started by a job trigger. + +These job types are only available in Windows PowerShell 5.1. The modules that +add these job types aren't compatible with PowerShell 6.0 and later. + +For more information, see the following articles: + +- [about_Scheduled_Jobs][01] +- [about_Workflows][02] ## Examples The following commands create a local background job, a remote background job, a workflow job, and a scheduled job. Then, it uses the `Get-Job` cmdlet to get -the jobs. `Get-Job` does not get the scheduled job, but it gets any started +the jobs. `Get-Job` doesn't get the scheduled job, but it gets any started instances of the scheduled job. Start a background job on the local computer. @@ -291,78 +317,50 @@ Id Name PSJobTypeName State HasMoreData Location Command Start a background job that runs on a remote computer. ```powershell -PS> Invoke-Command -ComputerName Server01 {Get-Process} ` --AsJob -JobName RemoteData +$invokeCommandSplat = @{ + ComputerName = 'Server01' + AsJob = $true + JobName = 'RemoteData' + ScriptBlock = {Get-Process} +} +Invoke-Command @invokeCommandSplat +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 RemoteData RemoteJob Running True Server01 Get-Process ``` -Create a scheduled job - -```powershell -PS> Register-ScheduledJob -Name ScheduledJob -ScriptBlock ` - {Get-Process} -Trigger (New-JobTrigger -Once -At "3 PM") - -Id Name JobTriggers Command Enabled --- ---- ----------- ------- ------- -1 ScheduledJob 1 Get-Process True -``` - -Create a workflow. - -```powershell -PS> workflow Test-Workflow {Get-Process} -``` - -Run the workflow as a job. - -```powershell - -PS> Test-Workflow -AsJob -JobName TestWFJob - -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process -``` - -Get the jobs. The `Get-Job` command does not get scheduled jobs, but it gets -instances of the scheduled job that are started. - -```powershell -PS> Get-Job - -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 LocalData BackgroundJob Completed True localhost Get-Process -4 RemoteData RemoteJob Completed True Server01 Get-Process -6 TestWFJob PSWorkflowJob Completed True localhost WorkflowJob -8 ScheduledJob PSScheduledJob Completed True localhost Get-Process -``` - -To get scheduled jobs, use the `Get-ScheduledJob` cmdlet. - -```powershell -PS> Get-ScheduledJob - -Id Name JobTriggers Command Enabled --- ---- ----------- ------- ------- -1 ScheduledJob 1 Get-Process True -``` - ## See also -- [about_Jobs](about_Jobs.md) -- [about_Remote](about_Remote.md) -- [about_Remote_Jobs](about_Remote_Jobs.md) -- [about_Thread_Jobs](about_Thread_Jobs.md) -- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command) -- [Get-Job](xref:Microsoft.PowerShell.Core.Get-Job) -- [Remove-Job](xref:Microsoft.PowerShell.Core.Remove-Job) -- [Start-Job](xref:Microsoft.PowerShell.Core.Start-Job) -- [Stop-Job](xref:Microsoft.PowerShell.Core.Stop-Job) -- [Wait-Job](xref:Microsoft.PowerShell.Core.Wait-Job) -- [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession) -- [Exit-PSSession](xref:Microsoft.PowerShell.Core.Exit-PSSession) -- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) +- [about_Jobs][03] +- [about_Remote][05] +- [about_Remote_Jobs][04] +- [about_Thread_Jobs][06] +- [Invoke-Command][10] +- [Get-Job][09] +- [Remove-Job][12] +- [Start-Job][13] +- [Stop-Job][14] +- [Wait-Job][15] +- [Enter-PSSession][07] +- [Exit-PSSession][08] +- [New-PSSession][11] + + +[01]: /powershell/module/psscheduledjob/about/about_scheduled_jobs?view=powershell-5.1&preserve-view=true +[02]: /powershell/module/psworkflow/about/about_workflows?view=powershell-5.1&preserve-view=true +[03]: about_Jobs.md +[04]: about_Remote_Jobs.md +[05]: about_Remote.md +[06]: about_Thread_Jobs.md +[07]: xref:Microsoft.PowerShell.Core.Enter-PSSession +[08]: xref:Microsoft.PowerShell.Core.Exit-PSSession +[09]: xref:Microsoft.PowerShell.Core.Get-Job +[10]: xref:Microsoft.PowerShell.Core.Invoke-Command +[11]: xref:Microsoft.PowerShell.Core.New-PSSession +[12]: xref:Microsoft.PowerShell.Core.Remove-Job +[13]: xref:Microsoft.PowerShell.Core.Start-Job +[14]: xref:Microsoft.PowerShell.Core.Stop-Job +[15]: xref:Microsoft.PowerShell.Core.Wait-Job diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Job_Details.md index 632e828dcb74..8534801df59a 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -1,8 +1,8 @@ --- description: Provides details about background jobs on local and remote computers. Locale: en-US -ms.date: 10/16/2020 -online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_job_details?view=powershell-7.6&WT.mc_id=ps-gethelp +ms.date: 03/24/2025 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_job_details?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Job_Details --- @@ -17,33 +17,31 @@ Provides details about background jobs on local and remote computers. This topic explains the concept of a background job and provides technical information about how background jobs work in PowerShell. -This topic is a supplement to the [about_Jobs](about_Jobs.md), -[about_Thread_Jobs](about_Thread_Jobs.md), and -[about_Remote_Jobs](about_Remote_Jobs.md) topics. +This topic is a supplement to the [about_Jobs][03], [about_Thread_Jobs][06], +and [about_Remote_Jobs][04] 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 +cmdlet, a function, a script, or any other command-based task. It's 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 PowerShell command prompt is suppressed -until the command is complete. But a background job does not suppress the +until the command is complete. But a background job doesn't suppress the 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. +However, when you start a background job, you don't get the results immediately +even if the job runs very quickly. The job object that's returned contains +useful information about the job, but it doesn't 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 PowerShell session. However, this can be a -temporary connection that is created only to run the job and is then destroyed, +temporary connection that's created only to run the job and is then destroyed, or it can be a persistent **PSSession** that you can use to run several related jobs or commands. @@ -53,16 +51,16 @@ 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 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 get the job results, use a `Receive-Job` command. If the job isn't 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](about_Jobs.md). +cmdlet, and see [about_Jobs][03]. ### Starting background jobs on remote computers @@ -73,13 +71,13 @@ command remotely. You can also start a background job in an interactive session. For more information about remote background jobs, see -[about_Remote_Jobs](about_Remote_Jobs.md). +[about_Remote_Jobs][04]. ### Child jobs Each background job consists of a parent job and one or more child jobs. In jobs started 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 +the parent job is an executive. It doesn't run any commands or return any results. The commands are actually run by the child jobs. Jobs started using other cmdlets might work differently. @@ -94,8 +92,10 @@ parameter of the `Get-Job` cmdlet. The **IncludeChildJob** parameter was introduced in Windows PowerShell 3.0. ```powershell -PS> Get-Job -IncludeChildJob +Get-Job -IncludeChildJob +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 RemoteJob Failed True localhost Get-Process @@ -108,8 +108,10 @@ value, use the **ChildJobState** parameter of the `Get-Job` cmdlet. The **ChildJobState** parameter was introduced in Windows PowerShell 3.0. ```powershell -PS> Get-Job -ChildJobState Failed +Get-Job -ChildJobState Failed +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 RemoteJob Failed True localhost Get-Process @@ -120,8 +122,10 @@ To get the child jobs of a job on all versions of PowerShell, use the **ChildJob** property of the parent job. ```powershell -PS> (Get-Job Job1).ChildJobs +(Get-Job Job1).ChildJobs +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 Job2 Completed True Server01 Get-Process @@ -132,8 +136,10 @@ You can also use a `Get-Job` command on the child job, as shown in the following command: ```powershell -PS> Get-Job Job3 +Get-Job Job3 +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 3 Job3 Failed False localhost Get-Process @@ -170,8 +176,12 @@ background jobs on the local computer and two remote computers. The command saves the job in the `$j` variable. ```powershell -PS> $j = Invoke-Command -ComputerName localhost, Server01, Server02 ` --Command {Get-Date} -AsJob +$invokeCommandSplat = @{ + ComputerName = 'localhost', 'Server01', 'Server02' + ScriptBlock = {Get-Date} + AsJob = $true +} +$j = Invoke-Command @invokeCommandSplat ``` When you display the Name and **ChildJob** properties of the job in `$j`, it @@ -179,8 +189,10 @@ shows that the command returned a job object with three child jobs, one for each computer. ```powershell -PS> $j | Format-List Name, ChildJobs +$j | Format-List Name, ChildJobs +``` +```Output Name : Job3 ChildJobs : {Job4, Job5, Job6} ``` @@ -188,8 +200,10 @@ ChildJobs : {Job4, Job5, Job6} When you display the parent job, it shows that the job failed. ```powershell -PS> $j +$j +``` +```Output Id Name PSJobTypeName State HasMoreData Location -- ---- ------------- ----- ----------- -------- 3 Job3 RemotingJob Failed False localhost,Server... @@ -199,8 +213,10 @@ But when you run a `Get-Job` command that gets the child jobs, the output shows that only one child job failed. ```powershell -PS> Get-Job -IncludeChildJobs +Get-Job -IncludeChildJobs +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 3 Job3 RemotingJob Failed False localhost,Server... @@ -209,13 +225,16 @@ Id Name PSJobTypeName State HasMoreData Location Command 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. +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. ```powershell -PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, ->> DateTime -AutoSize +Receive-Job -Name Job6 -Keep | + Format-Table ComputerName, DateTime -AutoSize +``` + +```Output ComputerName DateTime ------------ -------- Server02 Thursday, March 13, 2008 4:16:03 PM @@ -227,17 +246,15 @@ more control over the jobs that you run. ### Job types PowerShell supports different types of jobs for different tasks. Beginning in -Windows PowerShell 3.0, developers can write "job source adapters" that add -new job types to PowerShell and include the job source adapters in modules. -When you import the module, you can use the new job type in your session. - -For example, the PSScheduledJob module adds scheduled jobs and the PSWorkflow +Windows PowerShell 3.0, developers can write "job source adapters" that add new +job types to PowerShell and include the job source adapters in modules. When +you import the module, you can use the new job type in your session. For +example, the PSScheduledJob module adds scheduled jobs and the PSWorkflow module adds workflow jobs. Custom jobs types might differ significantly from standard PowerShell -background jobs. For example, scheduled jobs are saved on disk; they do not -exist only in a particular session. Workflow jobs can be suspended and -resumed. +background jobs. For example, scheduled jobs are saved on disk; they don't +exist only in a particular session. Workflow jobs can be suspended and resumed. The cmdlets that you use to manage custom jobs depend on the job type. For some, you use the standard job cmdlets, such as `Get-Job` and `Start-Job`. @@ -250,32 +267,41 @@ different job objects for different types of jobs. The value of the **PSJobTypeName** property of the job objects that `Get-Job` returns indicates the job type. -The following table lists the job types that come with PowerShell. - -| Job Type | Description | -| -------------- | -------------------------------------------------------- | -| BackgroundJob | Started using the `Start-Job` cmdlet. | -| RemoteJob | Started using the **AsJob** parameter of the | -| | `Invoke-Command` cmdlet. | -| PSWorkflowJob | Started using the **AsJob** parameter of a workflow. | -| PSScheduledJob | An instance of a scheduled job started by a job trigger. | -| CIMJob | Started using the **AsJob** parameter of a cmdlet from a | -| | CDXML module. | -| WMIJob | Started using the **AsJob** parameter of a cmdlet from a | -| | WMI module. | -| PSEventJob | Created using`Register-ObjectEvent` and specifying an | -| | action with the **Action** parameter. | +The following list describes the built-in PowerShell job types. + +- **BackgroundJob** - Started using the `Start-Job` cmdlet. +- **RemoteJob** - Started using the **AsJob** parameter of the `Invoke-Command` + cmdlet. +- **CIMJob** - Started using the **AsJob** parameter of a cmdlet from a CDXML + module. +- **WMIJob** - Started using the **AsJob** parameter of a cmdlet from a WMI + module. +- **PSEventJob** - Created using`Register-ObjectEvent` and specifying an action + with the **Action** parameter. > [!NOTE] > Before using the `Get-Job` cmdlet to get jobs of a particular type, verify > that the module that adds the job type is imported into the current session. -> Otherwise, `Get-Job` does not get jobs of that type. +> Otherwise, `Get-Job` can't get jobs of that type. + +Windows PowerShell 5.1 includes the following additional job types. + +- **PSWorkflowJob** - Started using the **AsJob** parameter of a workflow. +- **PSScheduledJob** - An instance of a scheduled job started by a job trigger. + +These job types are only available in Windows PowerShell 5.1. The modules that +add these job types aren't compatible with PowerShell 6.0 and later. + +For more information, see the following articles: + +- [about_Scheduled_Jobs][01] +- [about_Workflows][02] ## Examples The following commands create a local background job, a remote background job, a workflow job, and a scheduled job. Then, it uses the `Get-Job` cmdlet to get -the jobs. `Get-Job` does not get the scheduled job, but it gets any started +the jobs. `Get-Job` doesn't get the scheduled job, but it gets any started instances of the scheduled job. Start a background job on the local computer. @@ -291,78 +317,50 @@ Id Name PSJobTypeName State HasMoreData Location Command Start a background job that runs on a remote computer. ```powershell -PS> Invoke-Command -ComputerName Server01 {Get-Process} ` --AsJob -JobName RemoteData +$invokeCommandSplat = @{ + ComputerName = 'Server01' + AsJob = $true + JobName = 'RemoteData' + ScriptBlock = {Get-Process} +} +Invoke-Command @invokeCommandSplat +``` +```Output Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 RemoteData RemoteJob Running True Server01 Get-Process ``` -Create a scheduled job - -```powershell -PS> Register-ScheduledJob -Name ScheduledJob -ScriptBlock ` - {Get-Process} -Trigger (New-JobTrigger -Once -At "3 PM") - -Id Name JobTriggers Command Enabled --- ---- ----------- ------- ------- -1 ScheduledJob 1 Get-Process True -``` - -Create a workflow. - -```powershell -PS> workflow Test-Workflow {Get-Process} -``` - -Run the workflow as a job. - -```powershell - -PS> Test-Workflow -AsJob -JobName TestWFJob - -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 TestWFJob PSWorkflowJob NotStarted True localhost Get-Process -``` - -Get the jobs. The `Get-Job` command does not get scheduled jobs, but it gets -instances of the scheduled job that are started. - -```powershell -PS> Get-Job - -Id Name PSJobTypeName State HasMoreData Location Command --- ---- ------------- ----- ----------- -------- ------- -2 LocalData BackgroundJob Completed True localhost Get-Process -4 RemoteData RemoteJob Completed True Server01 Get-Process -6 TestWFJob PSWorkflowJob Completed True localhost WorkflowJob -8 ScheduledJob PSScheduledJob Completed True localhost Get-Process -``` - -To get scheduled jobs, use the `Get-ScheduledJob` cmdlet. - -```powershell -PS> Get-ScheduledJob - -Id Name JobTriggers Command Enabled --- ---- ----------- ------- ------- -1 ScheduledJob 1 Get-Process True -``` - ## See also -- [about_Jobs](about_Jobs.md) -- [about_Remote](about_Remote.md) -- [about_Remote_Jobs](about_Remote_Jobs.md) -- [about_Thread_Jobs](about_Thread_Jobs.md) -- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command) -- [Get-Job](xref:Microsoft.PowerShell.Core.Get-Job) -- [Remove-Job](xref:Microsoft.PowerShell.Core.Remove-Job) -- [Start-Job](xref:Microsoft.PowerShell.Core.Start-Job) -- [Stop-Job](xref:Microsoft.PowerShell.Core.Stop-Job) -- [Wait-Job](xref:Microsoft.PowerShell.Core.Wait-Job) -- [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession) -- [Exit-PSSession](xref:Microsoft.PowerShell.Core.Exit-PSSession) -- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession) +- [about_Jobs][03] +- [about_Remote][05] +- [about_Remote_Jobs][04] +- [about_Thread_Jobs][06] +- [Invoke-Command][10] +- [Get-Job][09] +- [Remove-Job][12] +- [Start-Job][13] +- [Stop-Job][14] +- [Wait-Job][15] +- [Enter-PSSession][07] +- [Exit-PSSession][08] +- [New-PSSession][11] + + +[01]: /powershell/module/psscheduledjob/about/about_scheduled_jobs?view=powershell-5.1&preserve-view=true +[02]: /powershell/module/psworkflow/about/about_workflows?view=powershell-5.1&preserve-view=true +[03]: about_Jobs.md +[04]: about_Remote_Jobs.md +[05]: about_Remote.md +[06]: about_Thread_Jobs.md +[07]: xref:Microsoft.PowerShell.Core.Enter-PSSession +[08]: xref:Microsoft.PowerShell.Core.Exit-PSSession +[09]: xref:Microsoft.PowerShell.Core.Get-Job +[10]: xref:Microsoft.PowerShell.Core.Invoke-Command +[11]: xref:Microsoft.PowerShell.Core.New-PSSession +[12]: xref:Microsoft.PowerShell.Core.Remove-Job +[13]: xref:Microsoft.PowerShell.Core.Start-Job +[14]: xref:Microsoft.PowerShell.Core.Stop-Job +[15]: xref:Microsoft.PowerShell.Core.Wait-Job