PowerShell Logo Small

Get-Job



This is the built-in help made by Microsoft for the command 'Get-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

Gets Windows PowerShell background jobs that are running in the current session.

SYNTAX


Get-Job [[-Id] [<Int32[]>]] [-After [<DateTime>]] [-Before [<DateTime>]] [-ChildJobState {NotStarted | Running | Completed | Failed | Stopped | Blocked | Suspended |
Disconnected | Suspending | Stopping | AtBreakpoint}] [-HasMoreData [<Boolean>]] [-IncludeChildJob] [-Newest [<Int32>]] [<CommonParameters>]
Get-Job [-After [<DateTime>]] [-Before [<DateTime>]] [-ChildJobState {NotStarted | Running | Completed | Failed | Stopped | Blocked | Suspended | Disconnected | Suspending |
Stopping | AtBreakpoint}] [-Command [<String[]>]] [-HasMoreData [<Boolean>]] [-IncludeChildJob] [-Newest [<Int32>]] [<CommonParameters>]
Get-Job [-Filter] <Hashtable> [<CommonParameters>]
Get-Job [-State] {NotStarted | Running | Completed | Failed | Stopped | Blocked | Suspended | Disconnected | Suspending | Stopping | AtBreakpoint} [-After [<DateTime>]]
[-Before [<DateTime>]] [-ChildJobState {NotStarted | Running | Completed | Failed | Stopped | Blocked | Suspended | Disconnected | Suspending | Stopping | AtBreakpoint}]
[-HasMoreData [<Boolean>]] [-IncludeChildJob] [-Newest [<Int32>]] [<CommonParameters>]
Get-Job [-Name] <String[]> [-After [<DateTime>]] [-Before [<DateTime>]] [-ChildJobState {NotStarted | Running | Completed | Failed | Stopped | Blocked | Suspended |
Disconnected | Suspending | Stopping | AtBreakpoint}] [-HasMoreData [<Boolean>]] [-IncludeChildJob] [-Newest [<Int32>]] [<CommonParameters>]
Get-Job [-InstanceId] <Guid[]> [-After [<DateTime>]] [-Before [<DateTime>]] [-ChildJobState {NotStarted | Running | Completed | Failed | Stopped | Blocked | Suspended |
Disconnected | Suspending | Stopping | AtBreakpoint}] [-HasMoreData [<Boolean>]] [-IncludeChildJob] [-Newest [<Int32>]] [<CommonParameters>]



Search powershellhelp.space

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 the
Start-Job cmdlet, 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.


Beginning in Windows PowerShell 3.0, the Get-Job cmdlet also gets custom job types, such as workflow jobs and instances of scheduled jobs. To find the job type of a job, use
the PSJobTypeName property of the job.


To enable Get-Job to get a custom job type, import the module that supports the custom job type into the session before running a Get-Job command, either by using the
Import-Module cmdlet or by using or getting a cmdlet in the module. For information about a particular custom job type, see the documentation of the custom job type feature.



<

RELATED LINKS

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

REMARKS

<

Examples


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

PS C:\>Get-Job



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 --------------------------

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.
PS C:\>$j = Get-Job -Name Job1

The second command gets the InstanceId property of the object in the $j variable and stores it in the $ID variable.
PS C:\>$ID = $j.InstanceID

The third command displays the value of the $ID variable.
PS C:\>$ID

Guid
----
03c3232e-1d23-453b-a6f4-ed73c9e29d55

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.
PS C:\>Stop-Job -InstanceId $ID



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.






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

PS C:\>Get-Job -Command "*get-process*"



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 --------------------------

PS C:\>"*get-process*" | Get-Job



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 quotation marks) to the Get-Job cmdlet. It is the equivalent of the previous command.






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

PS C:\>Get-Job -State NotStarted



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 --------------------------

PS C:\>Get-Job -name Job*



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 --------------------------

The first command uses the Start-Jobcmdlet 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.
PS C:\>Start-Job -ScriptBlock {Get-Process} -Name MyJob

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.
PS C:\>
$j = Get-Job -Name MyJob

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.
PS C:\>$j
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
6 MyJob BackgroundJob Completed True localhost Get-Process

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



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.






-------------------------- EXAMPLE 8 --------------------------

The first command uses the Start-Job cmdlet to start a job on the local computer.
PS C:\>Start-Job -ScriptBlock {Get-EventLog System}

The second command uses the AsJob parameter of the Invoke-Command cmdlet 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.
PS C:\>Invoke-Command -ComputerName S1 -ScriptBlock {Get-EventLog System} -AsJob

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.
PS C:\>Invoke-Command -ComputerName S2 -ScriptBlock {Start-Job -ScriptBlock {Get-EventLog System}}

The fourth command uses Get-Job to get the jobs stored on the local computer. The PSJobTypeName property of jobs, introduced in Windows PowerShell 3.0, shows that the local
job started by using the Start-Job cmdlet is a background job and the job started in a remote session by using the Invoke-Command cmdlet is a remote job..
PS C:\>Get-Job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
1 Job1 BackgroundJob Running True localhost Get-EventLog System
2 Job2 RemoteJob Running True S1 Get-EventLog System

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 command. On the S2 computer, the job
appears to be a local job. The computer name is "localhost" and the job type is a background job.For more information about running background jobs on remote computers, see
about_Remote_Jobs.
PS C:\>Invoke-Command -ComputerName S2 -ScriptBlock {Start-Job -ScriptBlock {Get-EventLog System}}
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- ------- -------
4 Job4 BackgroundJob Running True localhost Get-Eventlog System



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.






-------------------------- EXAMPLE 9 --------------------------

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".
PS C:\>Start-Job -ScriptBlock {Get-Process}
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
1 Job1 BackgroundJob Failed False localhost Get-Process

The second command uses the Get-Job cmdlet to get the job. 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.
PS C:\>(Get-Job).JobStateInfo | Format-List -Property *
State : Failed
Reason :

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".
PS C:\>Get-Job | Format-List -Property *
HasMoreData : False

StatusMessage :

Location : localhost

Command : get-process

JobStateInfo : Failed

Finished : System.Threading.ManualReset

EventInstanceId : fb792295-1318-4f5d-8ac8-8a89c5261507

Id : 1

Name : Job1

ChildJobs : {Job2}

Output : {}

Error : {}

Progress : {}

Verbose : {}

Debug : {}

Warning : {}

StateChanged :

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



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.






-------------------------- EXAMPLE 10 --------------------------

The first command uses the Workflow keyword to create the "WFProcess" workflow.
PS C:\>Workflow WFProcess {Get-Process}

The second command uses the AsJob parameter of the WFProcess workflow to run the workflow as a background job. It uses the JobName parameter of the workflow to specify a
name for the job, and the PSPrivateMetadata parameter of the workflow to specify a custom ID.
PS C:\>WFProcess -AsJob -JobName WFProcessJob -PSPrivateMetadata @{MyCustomId = 92107}

The third command uses the Filter parameter of Get-Job to get the job by custom ID that was specified in the PSPrivateMetadata parameter.
PS C:\>Get-Job -Filter @{MyCustomId = 92107}
Id Name State HasMoreData Location Command

-- ---- ----- ----------- -------- -------

1 WFProcessJob Completed True localhost WFProcess



This example shows how to use the Filter parameter to get a workflow job. The Filter parameter, introduced in Windows PowerShell 3.0 is valid only on custom job types, such
as workflow jobs and scheduled jobs.






-------------------------- EXAMPLE 11 --------------------------

The first command gets the jobs in the current session. The output includes a background job, a remote job and several instances of a scheduled job. The remote job, Job4,
appears to have failed.
PS C:\>Get-Job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
2 Job2 BackgroundJob Completed True localhost .\Get-Archive.ps1
4 Job4 RemoteJob Failed True Server01, Server02 .\Get-Archive.ps1
7 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help
8 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help
9 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help
10 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help

The second command uses the IncludeChildJob parameter of Get-Job. The output adds the child jobs of all jobs that have child jobs.In this case, the revised output shows that
only the Job5 child job of Job4 failed.
PS C:\>Get-Job -IncludeChildJob
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
2 Job2 BackgroundJob Completed True localhost .\Get-Archive.ps1
3 Job3 Completed True localhost .\Get-Archive.ps1
4 Job4 RemoteJob Failed True Server01, Server02 .\Get-Archive.ps1
5 Job5 Failed False Server01 .\Get-Archive.ps1
6 Job6 Completed True Server02 .\Get-Archive.ps1
7 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help
8 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help
9 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help
10 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help

The third command uses the ChildJobState parameter with a value of Failed.The output includes all parent jobs and only the child jobs that failed.
PS C:\>Get-Job -Name Job4 -ChildJobState Failed
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
2 Job2 BackgroundJob Completed True localhost .\Get-Archive.ps1
4 Job4 RemoteJob Failed True Server01, Server02 .\Get-Archive.ps1
5 Job5 Failed False Server01 .\Get-Archive.ps1
7 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help
8 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help
9 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help
10 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help

The fifth command uses the JobStateInfo property of jobs and its Reason property to find out why Job5 failed.
PS C:\>(Get-Job -Name Job5).JobStateInfo.Reason
Connecting to remote server Server01 failed with the following error message :
Access is denied.
For more information, see the about_Remote_Troubleshooting Help topic.



This example shows the effect of using the IncludeChildJob and ChildJobState parameters of the Get-Job cmdlet.