Start-Job

Syntax

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

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

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

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

Description

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

A Windows 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 does not 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 Windows 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 topics for the job type feature.

Examples

Example 1: Start a background job

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 that has 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: Start a job by using Invoke-Command

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 command on many computers. Because the command is running on a server that has significant 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: Get events from the System log on the local computer

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 stores the job object that Start-Job returns in the $j variable.

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

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: Run a script as a background job

PS C:\> Start-Job -FilePath "c:\scripts\sample.ps1"

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

Example 5: Get a process by name by using a background job

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: Collect and save data by using a background job

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 lots of data, and then 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.

Required Parameters

Optional Parameters

Inputs

System.String

You can pipe an object that has the Name property to the Name parameter. For example, you can pipe a FileInfo object from Get-ChildItem to Start-Job .

Outputs

System.Management.Automation.PSRemotingJob

This cmdlet returns an 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

• Get-Job
• Invoke-Command
• Receive-Job
• Remove-Job
• Resume-Job
• Stop-Job
• Suspend-Job
• Wait-Job