PowerShell Logo Small

Start-Job



This is the built-in help made by Microsoft for the command 'Start-Job', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Starts a Windows PowerShell background job.

SYNTAX


Start-Job [-ScriptBlock] <ScriptBlock> [[-InitializationScript] [<ScriptBlock>]] [-ArgumentList [<Object[]>]] [-Authentication {Default | Basic | Negotiate |
NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-Credential [<PSCredential>]] [-InputObject [<PSObject>]] [-Name [<String>]] [-PSVersion [<Version>]]
[-RunAs32] [<CommonParameters>]
Start-Job [-FilePath] <String> [[-InitializationScript] [<ScriptBlock>]] [-ArgumentList [<Object[]>]] [-Authentication {Default | Basic | Negotiate |
NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-Credential [<PSCredential>]] [-InputObject [<PSObject>]] [-Name [<String>]] [-PSVersion [<Version>]]
[-RunAs32] [<CommonParameters>]
Start-Job [[-InitializationScript] [<ScriptBlock>]] [-ArgumentList [<Object[]>]] [-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp |
Digest | Kerberos}] [-Credential [<PSCredential>]] [-InputObject [<PSObject>]] [-Name [<String>]] [-PSVersion [<Version>]] [-RunAs32] -LiteralPath <String>
[<CommonParameters>]
Start-Job [-DefinitionName] <String> [[-DefinitionPath] [<String>]] [[-Type] [<String>]] [<CommonParameters>]



Search powershellhelp.space

DESCRIPTION


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


A Windows PowerShell background job runs a command "in the background" without interacting with the current session. When you start a background job, a job object is
returned immediately, even if the job takes an extended time to complete. 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 does not contain the job results. When the job completes, 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.


Beginning in Windows PowerShell 3.0, Start-Job can start instances of custom job types, such as scheduled jobs. For information about using Start-Job to start jobs with
custom types, see the help topics for the job type feature.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/p/?linkid=289615
Get-Job
Invoke-Command
Receive-Job
Remove-Job
Resume-Job
Start-Job
Stop-Job
Suspend-Job
Wait-Job
about_Job_Details
about_Remote_Jobs
about_Jobs

REMARKS

<

Examples


-------------------------- EXAMPLE 1 --------------------------

PS C:\>start-job -scriptblock {get-process}

Id Name State HasMoreData Location Command
--- ---- ----- ----------- -------- -------
1 Job1 Running True localhost get-process



This command starts a background job that runs a Get-Process command. The command returns a job object with information about the job. The command prompt returns immediately
so that you can work in the session while the job runs in the background.










-------------------------- EXAMPLE 2 --------------------------

PS C:\>$jobWRM = invoke-command -computerName (get-content servers.txt) -scriptblock {get-service winrm} -jobname WinRM -throttlelimit 16 -AsJob



This command uses the Invoke-Command cmdlet and its AsJob parameter to start a background job that runs a "get-service winrm" command on numerous computers. Because the
command is running on a server with substantial network traffic, the command uses the ThrottleLimit parameter of Invoke-Command to limit the number of concurrent commands to
16.

The command uses the ComputerName parameter to specify the computers on which the job runs. The value of the ComputerName parameter is a Get-Content command that gets the
text in the Servers.txt file, a file of computer names in a domain.

The command uses the ScriptBlock parameter to specify the command and the JobName parameter to specify a friendly name for the job.










-------------------------- EXAMPLE 3 --------------------------

PS C:\>$j = start-job -scriptblock {get-eventlog -log system} -credential domain01\user01
PS C:\>$j | format-list -property *

HasMoreData : True
StatusMessage :
Location : localhost
Command : get-eventlog -log system
JobStateInfo : Running
Finished : System.Threading.ManualResetEvent
InstanceId : 2d9d775f-63e0-4d48-b4bc-c05d0e177f34
Id : 1
Name : Job1
ChildJobs : {Job2}
Output : {}
Error : {}
Progress : {}
Verbose : {}
Debug : {}
Warning : {}
StateChanged :

PS C:\>$j.JobStateInfo.state
Completed
PS C:\>$results = receive-job -job $j
PS C:\>$results

Index Time Type Source EventID Message
----- ---- ---- ------ ------- -------
84366 Feb 18 19:20 Information Service Control M... 7036 The description...
84365 Feb 18 19:16 Information Service Control M... 7036 The description...
84364 Feb 18 19:10 Information Service Control M... 7036 The description...
...



These commands manage a background job that gets all of the events from the System log in Event Viewer. The job runs on the local computer.

The first command uses the Start-Job cmdlet to start the job. It uses the Credential parameter to specify the user account of a user who has permission to run the job on the
computer. Then it saves the job object that Start-Job returns in the $j variable.

At this point, you can resume your other work while the job completes.

The second command uses a pipeline operator (|) to pass the job object in $j to the Format-List cmdlet. The Format-List command uses the Property parameter with a value of
all (*) to display all of the properties of the job object in a list.

The third command displays the value of the JobStateInfo property. This contains the status of the job.

The fourth command uses the Receive-Job cmdlet to get the results of the job. It stores the results in the $results variable.

The final command displays the contents of the $results variable.










-------------------------- EXAMPLE 4 --------------------------

PS C:\>start-job -filepath c:\scripts\sample.ps1



This command runs the Sample.ps1 script as a background job.










-------------------------- EXAMPLE 5 --------------------------

PS C:\>start-job -name WinRm -scriptblock {get-process winrm}



This command runs a background job that gets the WinRM process on the local computer. The command uses the ScriptBlock parameter to specify the command that runs in the
background job. It uses the Name parameter to specify a friendly name for the new job.










-------------------------- EXAMPLE 6 --------------------------

PS C:\>start-job -name GetMappingFiles -initializationScript {import-module MapFunctions} -scriptblock {Get-Map -name * | set-content D:\Maps.tif} -runAs32



This command starts a job that collects a large amount of data and saves it in a .tif file. The command uses the InitializationScript parameter to run a script block that
imports a required module. It also uses the RunAs32 parameter to run the job in a 32-bit process even if the computer has a 64-bit operating system.