NAME
Get-Job
SYNOPSIS
Gets Windows PowerShell background jobs that are running in the current session.
SYNTAX
Get-Job [-Command <string[]>] [<CommonParameters>]
Get-Job [[-InstanceId] <Guid[]>] [<CommonParameters>]
Get-Job [[-Name] <string[]>] [<CommonParameters>]
Get-Job [[-Id] <Int32[]>] [<CommonParameters>]
Get-Job [-State {NotStarted | Running | Completed | Failed | Stopped | Blocked}] [<CommonParameters>]
DESCRIPTION
The Get-Job cmdlet gets objects that represent the background jobs that were started in the current session. You can use Get-Job to get jobs that were started by using Start-Job, or by using the AsJob parameter of any cmdlet.
Without parameters, a “Get-Job” command gets all jobs in the current session. You can use the parameters of Get-Job to get particular jobs.
The job object that Get-Job returns contains useful information about the job, but it does not contain the job results. To get the results, use the Receive-Job cmdlet.
A Windows PowerShell background job is a command that runs “in the background” without interacting with the current session. Typically, you use a background job to run a complex command that takes a long time to complete. For more information about background jobs in Windows PowerShell, see about_jobs.
PARAMETERS
-Command <string[]>
Gets the jobs that include the specified command. The default is all jobs. Enter a command (as a string). You can use wildcards to specify a command pattern.
Required? false
Position? named
Default value All jobs
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? true
-Id <Int32[]>
Gets only jobs with the specified IDs.
The ID is an integer that uniquely identifies the job within the current session. It is easier to remember and to type than the instance ID, but it is unique only within the current session. You can type one or more IDs (separated by commas). To find the ID of a job, type “Get-Job” without parameters.
Required? false
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-InstanceId <Guid[]>
Gets jobs with the specified instance IDs. The default is all jobs.
An instance ID is a GUID that uniquely identifies the job on the computer. To find the instance ID of a job, use Get-Job.
Required? false
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? true
-Name <string[]>
Gets the job with the specified friendly names. Enter a job name, or use wildcard characters to enter a job name pattern. By default, Get-Job gets all jobs in the current session.
Required? false
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? true
-State <JobState>
Gets only jobs in the specified state. Valid values are NotStarted, Running, Completed, Stopped, Failed, and Blocked. By default, Get-Job gets all the jobs in the current session.
Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
“Get-Help about_CommonParameters“.
INPUTS
None
You cannot pipe input to this cmdlet.
OUTPUTS
System.Management.Automation.RemotingJob
Get-Job returns objects that represent the jobs in the session.
NOTES
————————– EXAMPLE 1 ————————–
C:\PS>Get-Job
Description
———–
This command gets all background jobs started in the current session. It does not include jobs created in other sessions, even if the jobs run on the local computer.
————————– EXAMPLE 2 ————————–
C:\PS>$j = Get-Job -name Job1
C:\PS> $ID = $j.InstanceID
C:\PS> $ID
Guid
—-
03c3232e-1d23-453b-a6f4-ed73c9e29d55
C:\PS> Stop-Job -instanceid $ID
Description
———–
These commands show how to get the instance ID of a job and then use it to stop a job. Unlike the name of a job, which is not unique, the instance ID is unique.
The first command uses the Get-Job cmdlet to get a job. It uses the Name parameter to identify the job. The command stores the job object that Get-Job returns in the $j Variable. In this example, there is only one job with the specified name.
The second command gets the InstanceId property of the object in the $j Variable and stores it in the $ID Variable.
The third command displays the value of the $ID Variable.
The fourth command uses Stop-Job cmdlet to stop the job. It uses the InstanceId parameter to identify the job and $ID Variable to represent the instance ID of the job.
————————– EXAMPLE 3 ————————–
C:\PS>Get-Job -command “*Get-Process*”
Description
———–
This command gets the jobs on the system that include a Get-Process command. The command uses the Command parameter of Get-Job to limit the jobs retrieved. The command uses wildcard characters (*) to get jobs that include a Get-Process command anywhere within the command string.
————————– EXAMPLE 4 ————————–
C:\PS>”*Get-Process*” | Get-Job
Description
———–
Like the command in the previous example, this command gets the jobs on the system that include a Get-Process command. The command uses a pipeline operator (|) to send a string (in double quotation marks) to the Get-Job cmdlet. It is the equivalent of the previous command.
————————– EXAMPLE 5 ————————–
C:\PS>Get-Job -state NotStarted
Description
———–
This command gets only those jobs that have been created but have not yet been started. This includes jobs that are scheduled to run in the future and those not yet scheduled.
————————– EXAMPLE 6 ————————–
C:\PS>Get-Job -name job*
Description
———–
This command gets all jobs that have job names beginning with “job”. Because “job<number>” is the default name for a job, this command gets all jobs that do not have an explicitly assigned name.
————————– EXAMPLE 7 ————————–
C:\PS>Start-Job -scriptblock {Get-Process} -name MyJob
C:\PS> $j = Get-Job -name MyJob
C:\PS> $j
Id Name State HasMoreData Location Command
— —- —– ———– ——– ——-
1 myjob Completed True localhost Get-Process
C:\PS> Receive-Job -job $j
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
——- —— —– —– —– —— — ———–
124 4 13572 12080 59 1140 audiodg
783 16 11428 13636 100 548 CcmExec
96 4 4252 3764 59 3856 ccmsetup
…
Description
———–
This example shows how to use Get-Job to get a job object, and then it shows how to use the job object to represent the job in a command.
The first command uses the Start-Job cmdlet to start a background job that runs a Get-Process command on the local computer. The command uses the Name parameter of Start-Job to assign a friendly name to the job.
The second command uses Get-Job to get the job. It uses the Name parameter of Get-Job to identify the job. The command saves the resulting job object in the $j Variable.
The third command displays the value of the job object in the $j Variable. The value of the State property shows that the job is complete. The value of the HasMoreData property shows that there are results available from the job that have not yet been retrieved.
The fourth command uses the Receive-Job cmdlet to get the results of the job. It uses the job object in the $j Variable to represent the job. You can also use a pipeline operator to send a job object to Receive-Job.
————————– EXAMPLE 8 ————————–
C:\PS>Start-Job -scriptblock {Get-Eventlog system}
C:\PS> Invoke-Command -computername S1 -scriptblock {Get-Eventlog system} -AsJob
C:\PS> Invoke-Command -computername S2 -scriptblock {Start-Job -scriptblock {Get-Eventlog system}}
C:\PS> Get-Job
Id Name State HasMoreData Location Command
— —- —– ———– ——– ——-
1 Job1 Running True localhost Get-Eventlog system
2 Job2 Running True S1 Get-Eventlog system
C:\PS> Invoke-Command -computername S2 -scriptblock {Get-Job}
Id Name State HasMoreData Location Command
— —- —– ———– ——– ——-
4 Job4 Running True localhost Get-Eventlog system
Description
———–
This example demonstrates that the Get-Job cmdlet can get all of the jobs that were started in the current session, even if they were started by using different methods.
The first command uses the Start-Job cmdlet to start a job on the local computer.
The second command uses the AsJob parameter of Invoke-Command to start a job on the S1 computer. Even though the commands in the job run on the remote computer, the job object is created on the local computer, so you use local commands to manage the job.
The third command uses the Invoke-Command cmdlet to run a Start-Job command on the S2 computer. With this method, the job object is created on the remote computer, so you use remote commands to manage the job.
The fourth command uses Get-Job to get the jobs stored on the local computer.
The fifth command uses Invoke-Command to run a Get-Job command on the S2 computer.
The sample output shows the results of the Get-Job commands.
For more information about running background jobs on remote computers, see about_remote_Jobs.
————————– EXAMPLE 9 ————————–
C:\PS>Start-Job -scriptblock {Get-Process}
Id Name State HasMoreData Location Command
— —- —– ———– ——– ——-
1 Job1 Failed False localhost Get-Process
C:\PS> (Get-Job).jobstateinfo | Format-List -property *
State : Failed
Reason :
C:\PS> Get-Job | Format-List *
HasMoreData : False
StatusMessage :
Location : localhost
Command : Get-Process
JobStateInfo : Failed
Finished : System.Threading.ManualResetEvent
InstanceId : fb792295-1318-4f5d-8ac8-8a89c5261507
Id : 1
Name : Job1
ChildJobs : {Job2}
Output : {}
Error : {}
Progress : {}
Verbose : {}
Debug : {}
Warning : {}
StateChanged :
C:\PS> (Get-Job -name job2).jobstateinfo.reason
Connecting to remote server using WSManCreateShellEx api failed. The async callback gave the following error message :
Access is denied.
Description
———–
This command shows how to use the job object that Get-Job returns to investigate why a job failed. It also shows how to get the child jobs of each job.
The first command uses the Start-Job cmdlet to start a job on the local computer. The job object that Start-Job returns shows that the job failed. The value of the State property is “Failed”.
The second command uses Get-Job to get the job object. The command uses the dot method to get the value of the JobStateInfo property of the object. It uses a pipeline operator to send the object in the JobStateInfo property to the Format-List cmdlet, which formats all of the properties of the object (*) in a list.
The result of the Format-List command shows that the value of the Reason property of the job is blank.
The third command investigates further. It uses a Get-Job command to get the job and then uses a pipeline operator to send the entire job object to the Format-List cmdlet, which displays all of the properties of the job in a list.
The display of all properties in the job object shows that the job contains a child job named “Job2”.
The fourth command uses Get-Job to get the job object that represents the Job2 child job. This is the job in which the command actually ran. It uses the dot method to get the Reason property of the JobStateInfo property.
The result shows that the job failed because of an “access denied” error. In this case, the user forgot to use the “Run as administrator” option when opening Windows PowerShell.
Because background jobs use the remoting features of Windows PowerShell, the computer must be configured for remoting to run a job, even when the job runs on the local computer.
For information about requirements for remoting in Windows PowerShell, see about_remote_requirements. For troubleshooting tips, see about_remote_TroubleShooting.
RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113328
about_jobs
about_job_details
about_remote_Jobs
Start-Job
Receive-Job
Wait-Job
Stop-Job
Remove-Job
Invoke-Command