Start-Job

Start a PowerShell background job.

Syntax
      Start-Job [-ScriptBlock] scriptblock [[-InitializationScript] scriptblock]
         [-ArgumentList Object[]] [-Authentication AuthenticationMechanism]
            [-Credential PSCredential] [-InputObject psobject]
               [-Name string] [-RunAs32] [CommonParameters]

      Start-Job [[-FilePath] string] [[-InitializationScript] scriptblock]
         [-ArgumentList Object[]] [-Authentication AuthenticationMechanism]
            [-Credential PSCredential] [-InputObject psobject]
               [-Name string] [-RunAs32] [CommonParameters]

Key
   -ArgumentList Object[]
       The arguments (parameter values) for the script specified by the -FilePath parameter. 
       Because all of the values that follow -ArgumentList are interpreted as being values
       of ArgumentList, the ArgumentList parameter should be the last parameter in the command.

   -Authentication AuthenticationMechanism
       The mechanism that is used to authenticate the user's credentials.
       Valid values are Default, Basic, Credssp, Digest, Kerberos, Negotiate, and
       NegotiateWithImplicitCredential.  The default value is Default.
       CredSSP authentication is available only in Vista, Windows Server 2008, and later.

       MSDN description.
       CAUTION: Accessing a remote resource via CredSSP) authentication presents
       a security risk if the remote computer is compromised.

   -Credential PSCredential
       A user account that has permission to perform this action.
       The default is the current user.
       Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential
       object, such as one from Get-Credential.

   -FilePath string
       Run the specified local script as a background job.
       Enter the path and file name of the script or pipe a script path
       to Start-Job. The script must reside on the local computer or in a directory that
       the local computer can access. 
       PowerShell will convert the contents of the script file to a script block
       and run it as a background job.

   -InitializationScript scriptblock
       Specify commands that run before the job starts.
       Enclose the commands in braces { } to create a script block. 
       Use this parameter to prepare the session in which the job runs.
       For example, use it to add functions, snap-ins, and modules to the session.

   -InputObject psobject
       Input to the command.
       Enter a variable that contains the objects, or type a command or expression that
       generates the objects.

       When the -InputObject parameter is used to submit a collection of items,
       Start-Job receives one object that represents the collection.
       Because this cannot be started, Start-Job returns the entire collection unchanged.

       To start multiple jobs, pipe them to Start-Job.

       This parameter is an implementation detail: its purpose is to enable input via the pipeline, and its
       direct use with arrays (collections) does not (yet) provide any useful functionality.

   -Name string
       A friendly name for the new job.
       This name can be used toidentify the job to other job cmdlets, such as Stop-Job. 
       The default friendly name is Job#, where "#" is an ordinal number that is incremented for each job.

   -RunAs32
       Run the job in a 32-bit process. 
       Use this parameter to force the job to run in a 32-bit process on a 64-bit operating system.

   -ScriptBlock scriptblock
       The commands to run in the background job.
       Enclose the commands in braces { } to create a script block.
       This parameter is required.
       Use the $input automatic variable to represent the input objects.

Standard Aliases for Start-Job: sajb

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

When a background job is started, 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 Receive-Job 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 Invoke-Command to run a Start-Job command on the remote computer. For more information, see about_Remote_Jobs.

In PowerShell 3.0 and above, jobs can be scheduled using the PowerShell Scheduling cmdlets.

Examples

Start a background job that runs a Get-Process command:

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

Start a background job (using Invoke-Command... -AsJob) that runs "get-service winrm" on numerous computers. To limit the number of concurrent commands to 16, the -ThrottleLimit parameter is used:

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

Get all events from the System log in Event Viewer, then use Receive-Job to get the results and store in a variable:

PS C:\> $myjob = start-job -scriptblock {get-eventlog -log system}
PS C:\> $results = receive-job -job $myjob

Run a PowerShell script as a background job:

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

Run a PowerShell cmdlet (Get-Process) as a background job:

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

“The beautiful thing about learning is nobody can take it away from you” ~ B. B. King

Related PowerShell Cmdlets

Get-Job - Get PowerShell background jobs that are running.
Invoke-Command - Run command.


 
Copyright © 1999-2024 SS64.com
Some rights reserved