powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Start-Job



NAME
Start-Job

SYNOPSIS
Starts a Windows PowerShell background job.

SYNTAX
Start-Job [-ScriptBlock] [[-InitializationScript] ] [-ArgumentList ] [-Authent
ication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-Credential
] [-InputObject ] [-Name ] [-RunAs32] []

Start-Job [[-FilePath] ] [[-InitializationScript] ] [-ArgumentList ] [-Authenticatio
n {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-Credential edential>] [-InputObject ] [-Name ] [-RunAs32] []


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 com
pletes, use the Receive-Job cmdlet to get the results of the job. For more information about background jobs, see a
bout_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_J
obs.


PARAMETERS
-ArgumentList
Specifies the arguments (parameter values) for the script that is specified by the FilePath parameter.

Because all of the values that follow the ArgumentList parameter name are interpreted as being values of Argume
ntList, the ArgumentList parameter should be the last parameter in the command.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Authentication
Specifies 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 Windows Vista, Windows Server 2008, and later versions of Windows.

For information about the values of this parameter, see the description of the System.Management.Automation.Run
spaces.AuthenticationMechanism enumeration in MSDN.

CAUTION: Credential Security Service Provider (CredSSP) authentication, in which the user's credentials are pas
sed 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 remo
te operation. If the remote computer is compromised, the credentials that are passed to it can be used to contr
ol the network session.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Credential
Specifies 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 the G
et-Credential cmdlet.

Required? false
Position? named
Default value Current user
Accept pipeline input? false
Accept wildcard characters? false

-FilePath
Runs the specified local script as a background job. Enter the path and file name of the script or pipe a scrip
t path to Start-Job. The script must reside on the local computer or in a directory that the local computer can
access.

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

Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false

-InitializationScript
Specifies commands that run before the job starts. Enclose the commands in braces ( { } ) to create a script bl
ock.

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.

Required? false
Position? 2
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 tha
t generates the objects.

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

Required? false
Position? named
Default value
Accept pipeline input? true (ByValue)
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 Stop-Job.

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

Required? false
Position? named
Default value Job
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-RunAs32 []
Runs 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.

Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false

-ScriptBlock
Specifies the commands to run in the background job. Enclose the commands in braces ( { } ) to create a script
block. This parameter is required.

Required? true
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
System.String
You can pipe a file path to Start-Job.


OUTPUTS
System.Management.Automation.RemotingJob
Start-Job returns an object that represents the job that it started.


NOTES


To run in the background, Start-Job runs in its own session within 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 withi
n the remote session.


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

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

C:\PS> start-job -command "get-process"

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


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





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

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


Description
-----------
This command uses the Invoke-Command cmdlet and its AsJob parameter to start a background job that runs a "get-serv
ice winrm" command on numerous computers. Because the command is running on a server with substantial network traff
ic, 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 Comput
erName 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 n
ame for the job.





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

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

C:\PS> $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 :

C:\PS> $j.JobStateInfo.state
Completed

C:\PS> $results = receive-job -job $j

C:\PS> $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...
...


Description
-----------
These commands manage a background job that gets all of the events from the System log in Event Viewer. The job run
s 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 re
turns 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 --------------------------

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


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





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

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


Description
-----------
This command runs a background job that gets the WinRM process on the local computer. The command uses the ScriptBl
ock parameter to specify the command that runs in the background job. It uses the Name parameter to specify a frien
dly name for the new job.





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

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


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






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113405
about_Jobs
about_Job_Details
about_Remote_Jobs
Get-Job
Receive-Job
Wait-Job
Stop-Job
Remove-Job
Invoke-Command