Start-Job

Starts a PowerShell background 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>]
     [<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.

Note

Creating an out-of-process background job with Start-Job is not supported in the scenario where PowerShell is being hosted in other applications, such as the PowerShell Azure Functions.

This is by design because Start-Job depends on the pwsh executable to be available under $PSHOME to start an out-of-process background job, but when an application is hosting PowerShell, it's directly using the PowerShell NuGet SDK packages and won't have pwsh shipped along.

The substitute in that scenario is Start-ThreadJob from the module ThreadJob.

Examples

Example 1: Start a background job

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

Start-Job -ScriptBlock {Get-Process}

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

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

Example 2: 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 3: 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 4: 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 5: 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 6: 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 7: 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

Example 8: Set the working directory to a background job

This example starts a job that has $PSHOME as its working directory.

$jb = Start-Job -WorkingDirectory $PSHOME { "Hi from $PWD." }; Receive-Job -AutoRemove -Wait $jb

Hi from C:\Program Files\PowerShell\6.0.0-beta.4

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.

Parameters

-ArgumentList

Specifies an array of arguments, or parameter values, for the script that is specified by the FilePath parameter.

Because all the values that follow the ArgumentList parameter name are interpreted as being values of ArgumentList, specify this parameter as the last parameter in the command.

Type:Object[]
Aliases:Args
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Authentication

Specifies the mechanism that is used to authenticate user credentials.

The acceptable values for this parameter are as follows:

  • Default
  • Basic
  • Credssp
  • Digest
  • Kerberos
  • Negotiate
  • NegotiateWithImplicitCredential

The default value is Default.

CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions of the Windows operating system.

For more information about the values of this parameter, see AuthenticationMechanism.

Caution

Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. This mechanism increases the security risk of the remote operation. If the remote computer is compromised, the credentials that are passed to it can be used to control the network session.

Type:AuthenticationMechanism
Accepted values:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:Default
Accept pipeline input:False
Accept wildcard characters:False
-Credential

Specifies a user account that has permission to perform this action. If the Credential parameter isn't specified, the command uses the current user's credentials.

Type a user name, such as User01 or Domain01\User01, or enter a PSCredential object, such as one from the Get-Credential cmdlet.

Type:PSCredential
Position:Named
Default value:Current user
Accept pipeline input:False
Accept wildcard characters:False
-DefinitionName

Specifies the definition name of the job that this cmdlet starts. Use this parameter to start custom job types that have a definition name, such as scheduled jobs.

When you use Start-Job to start an instance of a scheduled job, the job starts immediately, regardless of job triggers or job options. The resulting job instance is a scheduled job, but it isn't saved to disk like triggered scheduled jobs. You can't use the ArgumentList parameter of Start-Job to provide values for parameters of scripts that run in a scheduled job.

This parameter was introduced in PowerShell 3.0.

Type:String
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-DefinitionPath

Specifies path of the definition for the job that this cmdlet starts. Enter the definition path. The concatenation of the values of the DefinitionPath and DefinitionName parameters is the fully qualified path of the job definition. Use this parameter to start custom job types that have a definition path, such as scheduled jobs.

For scheduled jobs, the value of the DefinitionPath parameter is $home\AppData\Local\Windows\PowerShell\ScheduledJob.

This parameter was introduced in PowerShell 3.0.

Type:String
Position:1
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-FilePath

Specifies a local script that Start-Job runs as a background job. Enter the path and file name of the script or use the pipeline to send a script path to Start-Job. The script must be on the local computer or in a folder that the local computer can access.

When you use this parameter, PowerShell converts the contents of the specified script file to a script block and runs the script block as a background job.

Type:String
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-InitializationScript

Specifies commands that run before the job starts. To create a script block, enclose the commands in curly braces ({}).

Use this parameter to prepare the session in which the job runs. For example, you can use it to add functions, snap-ins, and modules to the session.

Type:ScriptBlock
Position:1
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-InputObject

Specifies input to the command. Enter a variable that contains the objects, or type a command or expression that generates the objects.

In the value of the ScriptBlock parameter, use the $input automatic variable to represent the input objects.

Type:PSObject
Position:Named
Default value:None
Accept pipeline input:True (ByValue)
Accept wildcard characters:False
-LiteralPath

Specifies a local script that this cmdlet runs as a background job. Enter the path of a script on the local computer.

Start-Job uses the value of the LiteralPath parameter exactly as it's typed. No characters are interpreted as wildcard characters. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences.

Type:String
Aliases:PSPath
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Name

Specifies a friendly name for the new job. You can use the name to identify the job to other job cmdlets, such as the Stop-Job cmdlet.

The default friendly name is Job#, where # is an ordinal number that is incremented for each job.

Type:String
Position:Named
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-PSVersion

Specifies a version. Start-Job runs the job with the version of PowerShell. The acceptable values for this parameter are: 2.0 and 3.0.

This parameter was introduced in PowerShell 3.0.

Type:Version
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-RunAs32

Beginning with PowerShell 7, the RunAs32 parameter doesn't work on 64-bit PowerShell (pwsh). If RunAs32 is specified in 64-bit PowerShell, Start-Job throws a terminating exception error. To start a 32-bit PowerShell (pwsh) process with RunAs32, you need to have the 32-bit PowerShell installed.

In 32-bit PowerShell, RunAs32 forces the job to run in a 32-bit process, even on a 64-bit operating system.

On 64-bit versions of Windows 7 and Windows Server 2008 R2, when the Start-Job command includes the RunAs32 parameter, you can't use the Credential parameter to specify the credentials of another user.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False
-ScriptBlock

Specifies the commands to run in the background job. To create a script block, enclose the commands in curly braces ({}). Use the $input automatic variable to access the value of the InputObject parameter. This parameter is required.

Type:ScriptBlock
Aliases:Command
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Type

Specifies the custom type for jobs started by Start-Job. Enter a custom job type name, such as PSScheduledJob for scheduled jobs or PSWorkflowJob for workflows jobs. This parameter isn't valid for standard background jobs.

This parameter was introduced in PowerShell 3.0.

Type:String
Position:2
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-WorkingDirectory

Specifies the initial working directory(location) of the background job. If it is not specified it defaults to $HOME.

Type:String
Position:Named
Default value:$HOME on Unix (macOS, Linux) and $HOME\Documents on Windows
Accept pipeline input:False
Accept wildcard characters:False

Inputs

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