Start-Job

Syntax

Start-Job
     [-Name <String>]
     [-ScriptBlock] <ScriptBlock>
     [-Credential <PSCredential>]
     [-Authentication <AuthenticationMechanism>]
     [[-InitializationScript] <ScriptBlock>]
     [-WorkingDirectory <String>]
     [-RunAs32]
     [-PSVersion <Version>]
     [-InputObject <PSObject>]
     [-ArgumentList <Object[]>]
     [<CommonParameters>]

Start-Job
     [-DefinitionName] <String>
     [[-DefinitionPath] <String>]
     [[-Type] <String>]
     [-WorkingDirectory <String>]
     [<CommonParameters>]

Start-Job
     [-Name <String>]
     [-Credential <PSCredential>]
     [-FilePath] <String>
     [-Authentication <AuthenticationMechanism>]
     [[-InitializationScript] <ScriptBlock>]
     [-WorkingDirectory <String>]
     [-RunAs32]
     [-PSVersion <Version>]
     [-InputObject <PSObject>]
     [-ArgumentList <Object[]>]
     [<CommonParameters>]

Start-Job
     [-Name <String>]
     [-Credential <PSCredential>]
     -LiteralPath <String>
     [-Authentication <AuthenticationMechanism>]
     [[-InitializationScript] <ScriptBlock>]
     [-WorkingDirectory <String>]
     [-RunAs32]
     [-PSVersion <Version>]
     [-InputObject <PSObject>]
     [-ArgumentList <Object[]>]
     [<CommonParameters>]

Description

The Start-Job cmdlet starts a PowerShell background job on the local computer.

A PowerShell background job runs a command without interacting with the current session. When you start a background job, a job object returns immediately, even if the job takes an extended time to finish. You can continue to work in the session without interruption while the job runs.

The job object contains useful information about the job, but it doesn't contain the job results. When the job finishes, use the Receive-Job cmdlet to get the results of the job. For more information about background jobs, see about_Jobs.

To run a background job on a remote computer, use the AsJob parameter that is available on many cmdlets, or use the Invoke-Command cmdlet to run a Start-Job command on the remote computer. For more information, see about_Remote_Jobs.

Starting in PowerShell 3.0, Start-Job can start instances of custom job types, such as scheduled jobs. For information about how to use Start-Job to start jobs with custom types, see the help documents for the job type feature.

Beginning in PowerShell 6.0, you can start jobs using the ampersand (&) background operator. The functionality of the background operator is similar to Start-Job. Both methods to start a job create a PSRemotingJob job object. For more information about using the ampersand (&), see about_Operators.

PowerShell 7 introduced the WorkingDirectory parameter that specifies a background job's initial working directory. If the parameter isn't specified, Start-Job defaults to the current working directory of the caller that started the job.

Examples

Example 1: Start a background job

This example starts a background job that runs on the local computer.

Start-Job -ScriptBlock { Get-Process -Name pwsh }

Id  Name   PSJobTypeName   State     HasMoreData   Location    Command
--  ----   -------------   -----     -----------   --------    -------
1   Job1   BackgroundJob   Running   True          localhost   Get-Process -Name pwsh

Start-Job uses the ScriptBlock parameter to run Get-Process as a background job. The Name parameter specifies to find PowerShell processes, pwsh. The job information is displayed and PowerShell returns to a prompt while the job runs in the background.

To view the job's output, use the Receive-Job cmdlet. For example, Receive-Job -Id 1.

Example 2: Use the background operator to start a background job

This example uses the ampersand (&) background operator to start a background job on the local computer. The job gets the same result as Start-Job in Example 1.

Get-Process -Name pwsh &

Id    Name   PSJobTypeName   State       HasMoreData     Location      Command
--    ----   -------------   -----       -----------     --------      -------
5     Job5   BackgroundJob   Running     True            localhost     Microsoft.PowerShell.Man...

Get-Process uses the Name parameter to specify PowerShell processes, pwsh. The ampersand (&) runs the command as a background job. The job information is displayed and PowerShell returns to a prompt while the job runs in the background.

To view the job's output, use the Receive-Job cmdlet. For example, Receive-Job -Id 5.

Example 3: Start a job using Invoke-Command

This example runs a job on multiple computers. The job is stored in a variable and is executed by using the variable name on the PowerShell command line.

$jobWRM = Invoke-Command -ComputerName (Get-Content -Path C:\Servers.txt) -ScriptBlock {
   Get-Service -Name WinRM } -JobName WinRM -ThrottleLimit 16 -AsJob

A job that uses Invoke-Command is created and stored in the $jobWRM variable. Invoke-Command uses the ComputerName parameter to specify the computers where the job runs. Get-Content gets the server names from the C:\Servers.txt file.

The ScriptBlock parameter specifies a command that Get-Service gets the WinRM service. The JobName parameter specifies a friendly name for the job, WinRM. The ThrottleLimit parameter limits the number of concurrent commands to 16. The AsJob parameter starts a background job that runs the command on the servers.

Example 4: Get job information

This example gets information about a job and displays the results of a completed job that was run on the local computer.

$j = Start-Job -ScriptBlock { Get-WinEvent -Log System } -Credential Domain01\User01
$j | Select-Object -Property *

State         : Completed
HasMoreData   : True
StatusMessage :
Location      : localhost
Command       : Get-WinEvent -Log System
JobStateInfo  : Completed
Finished      : System.Threading.ManualResetEvent
InstanceId    : 27ce3fd9-40ed-488a-99e5-679cd91b9dd3
Id            : 18
Name          : Job18
ChildJobs     : {Job19}
PSBeginTime   : 8/8/2019 14:41:57
PSEndTime     : 8/8/2019 14:42:07
PSJobTypeName : BackgroundJob
Output        : {}
Error         : {}
Progress      : {}
Verbose       : {}
Debug         : {}
Warning       : {}
Information   : {}

Start-Job uses the ScriptBlock parameter to run a command that specifies Get-WinEvent to get the System log. The Credential parameter specifies a domain user account with permission to run the job on the computer. The job object is stored in the $j variable.

The object in the $j variable is sent down the pipeline to Select-Object. The Property parameter specifies an asterisk (*) to display all the job object's properties.

Example 5: Run a script as a background job

In this example, a script on the local computer is run as a background job.

Start-Job -FilePath C:\Scripts\Sample.ps1

Start-Job uses the FilePath parameter to specify a script file that's stored on the local computer.

Example 6: Get a process using a background job

This example uses a background job to get a specified process by name.

Start-Job -Name PShellJob -ScriptBlock { Get-Process -Name PowerShell }

Start-Job uses the Name parameter to specify a friendly job name, PShellJob. The ScriptBlock parameter specifies Get-Process to get processes with the name PowerShell.

Example 7: Collect and save data by using a background job

This example starts a job that collects a large amount of map data and then saves it in a .tif file.

Start-Job -Name GetMappingFiles -InitializationScript {Import-Module MapFunctions} -ScriptBlock {
   Get-Map -Name * | Set-Content -Path D:\Maps.tif }

Start-Job uses the Name parameter to specify a friendly job name, GetMappingFiles. The InitializationScript parameter runs a script block that imports the MapFunctions module. The ScriptBlock parameter runs Get-Map and Set-Content saves the data in the location specified by the Path parameter.

Example 8: Pass input to a background job

This example uses the $input automatic variable to process an input object. Use Receive-Job to view the job's output.

Start-Job -ScriptBlock { Get-Content $input } -InputObject "C:\Servers.txt"
Receive-Job -Name Job45 -Keep

Server01
Server02
Server03
Server04

Start-Job uses the ScriptBlock parameter to run Get-Content with the $input automatic variable. The $input variable gets objects from the InputObject parameter. Receive-Job uses the Name parameter to specify the job and outputs the results. The Keep parameter saves the job output so it can be viewed again during the PowerShell session.

Example 9: Set the working directory for a background job

The WorkingDirectory allows you to specify an alternate directory for a job from which you can run scripts or open files. In this example, the background job specifies a working directory that's different than the current directory location.

PS C:\Test> Start-Job -WorkingDirectory C:\Test\Scripts { $PWD } | Receive-Job -AutoRemoveJob -Wait

Path
----
C:\Test\Scripts

This example's current working directory is C:\Test. Start-Job uses the WorkingDirectory parameter to specify the job's working directory. The ScriptBlock parameter uses $PWD to display the job's working directory. Receive-Job displays the background job's output. AutoRemoveJob deletes the job and Wait suppresses the command prompt until all results are received.

Example 10: Use the ArgumentList parameter to specify an array

This example uses the ArgumentList parameter to specify an array of arguments. The array is a comma-separated list of process names.

Start-Job -ScriptBlock { Get-Process -Name $args } -ArgumentList powershell, pwsh, notepad

Id     Name      PSJobTypeName   State       HasMoreData     Location     Command
--     ----      -------------   -----       -----------     --------     -------
1      Job1      BackgroundJob   Running     True            localhost    Get-Process -Name $args

The Start-Job cmdlet uses the ScriptBlock parameter to run a command. Get-Process uses the Name parameter to specify the automatic variable $args. The ArgumentList parameter passes the array of process names to $args. The process names powershell, pwsh, and notepad are processes running on the local computer.

To view the job's output, use the Receive-Job cmdlet. For example, Receive-Job -Id 1.

Example 11: Run job in a Windows PowerShell 5.1

This example uses the PSVersion parameter with value 5.1 to run job in a Windows PowerShell 5.1 session.

$PSVersionTable.PSVersion

Major  Minor  Patch  PreReleaseLabel BuildLabel
-----  -----  -----  --------------- ----------
7      0      0      rc.1

$job = Start-Job { $PSVersionTable.PSVersion } -PSVersion 5.1
Receive-Job $job

Major  Minor  Build  Revision
-----  -----  -----  --------
5      1      14393  3383

Parameters

-ArgumentList

-Authentication

-Credential

-DefinitionName

-DefinitionPath

-FilePath

-InitializationScript

-InputObject

-LiteralPath

-Name

-PSVersion

-RunAs32

-ScriptBlock

-Type

-WorkingDirectory

Inputs

String

You can use the pipeline to send an object with the Name property to the Name parameter. For example, you can pipeline a FileInfo object from Get-ChildItem to Start-Job.

Outputs

System.Management.Automation.PSRemotingJob

Start-Job returns a PSRemotingJob object that represents the job that it started.

Notes

To run in the background, Start-Job runs in its own session in the current session. When you use the Invoke-Command cmdlet to run a Start-Job command in a session on a remote computer, Start-Job runs in a session in the remote session.

Related Links

• about_Arrays
• about_Automatic_Variables
• about_Jobs
• about_Job_Details
• about_Remote_Jobs
• Get-Job
• Invoke-Command
• Receive-Job
• Remove-Job
• Stop-Job
• Wait-Job