About Help

Choose a topic from the list on the left or search for a specific topic. Choose a topic from the list or search for a specific topic.
Cmdlets  Providers
 

about_Job_Details

Job_Details

 

SHORT DESCRIPTION

  Provides details about background jobs on local and remote computers. 
     

DETAILED DESCRIPTION

   This topic explains the concept of a background job and provides technical 
   information about how background jobs work in Windows PowerShell. 
 
   This topic is a supplement to the about_Jobs and about_Remote_Jobs topics. 
 
 

ABOUT BACKGROUND JOBS

    A background job runs a command or expression asynchronously. It might run  
    a cmdlet, a function, a script, or any other command-based task. It is 
    designed to run commands that take an extended period of time, but you 
    can use it to run any command in the background. 
 
    When a synchronous command runs, the Windows PowerShell command prompt is  
    suppressed until the command is complete. But a background job does not  
    suppress the Windows PowerShell prompt. A command to start a background job  
    returns a job object. The prompt returns immediately so you can work on  
    other tasks while the background job runs. 
   
    However, when you start a background job, you do not get the results  
    immediately even if the job runs very quickly. The job object that is  
    returned contains useful information about the job, but it does not contain  
    the job results. You must run a separate command to get the job results.  
    You can also run commands to stop the job, to wait for the job to be  
    completed, and to delete the job. 
 
    To make the timing of a background job independent of other commands, each  
    background job runs in its own Windows PowerShell environment  
    (a "session"). However, this can be a temporary connection that is created  
    only to run the job and is then destroyed, or it can be a persistent  
    session (a PSSession) that you can use to run several related jobs or  
    commands. 
 
 

USING THE JOB CMDLETS

    Use a Start-Job command to start a background job on a local computer.  
    Start-Job returns a job object. You can also get objects representing the  
    jobs that were started on the local computer by using the Get-Job cmdlet. 
 
    To get the job results, use a Receive-Job command. If the job is not  
    complete, Receive-Job returns partial results. You can also use the  
    Wait-Job cmdlet to suppress the command prompt until one or all of the  
    jobs that were started in the session are complete. 
 
    To stop a background job, use the Stop-Job cmdlet. To delete a job, use  
    the Remove-Job cmdlet. 
 
    For more information about how the cmdlets work, see the Help topic for  
    each cmdlet, and see about_Jobs. 
 
  

STARTING BACKGROUND JOBS ON REMOTE COMPUTERS

    You can create and manage background jobs on a local or remote computer. To  
    run a background job remotely, use the AsJob parameter of a cmdlet such as  
    Invoke-Command, or use the Invoke-Command cmdlet to run a Start-Job  
    command remotely. You can also start a background job in an interactive  
    session. 
 
    For more information about remote background jobs, see about_Remote_Jobs. 
 
 

CHILD JOBS

    Each background job consists of a parent job and one or more child jobs. In  
    jobs started by using Start-Job or the AsJob parameter of Invoke-Command,  
    the parent job is an executive. It does not run any commands or return any  
    results. The commands are actually run by the child jobs. (Jobs started by  
    using other cmdlets might work differently.) 
 
    The child jobs are stored in the ChildJobs property of the parent job  
    object. The ChildJobs property can contain one or many child job objects.  
    The child job objects have a name, ID, and instance ID that differ  
    from the parent job so that you can manage the parent and child jobs  
    individually or as a unit. 
 
    To get the parent and child jobs of a job, use the IncludeChildJobs  
    parameter of the Get-Job cmdlet. The IncludeChildJob parameter is 
    introduced in Windows PowerShell 3.0. 
 
        C:\PS> Get-Job -IncludeChildJob 
 
        Id    Name   PSJobTypeName State      HasMoreData   Location    Command 
        --    ----   ------------- -----      -----------   --------    ------- 
        1     Job1   RemoteJob     Failed     True          localhost   Get-Process 
        2     Job2                 Completed  True          Server01    Get-Process 
        3     Job3                 Failed     False         localhost   Get-Process 
 
 
    To get the parent job and only the child jobs with a particular State 
    value, use the ChildJobState parameter of the Get-Job cmdlet. The  
    ChildJobState parameter is introduced in Windows PowerShell 3.0. 
 
        C:\PS> Get-Job -ChildJobState Failed 
 
        Id    Name   PSJobTypeName State      HasMoreData   Location    Command 
        --    ----   ------------- -----      -----------   --------    ------- 
        1     Job1   RemoteJob     Failed     True          localhost   Get-Process 
        3     Job3                 Failed     False         localhost   Get-Process 
 
 
    To get the child jobs of a job on all versions of Windows PowerShell, 
    use the ChildJob property of the parent job. 
 
        C:\PS> (Get-Job Job1).ChildJobs 
 
        Id    Name   PSJobTypeName State      HasMoreData   Location    Command 
        --    ----   ------------- -----      -----------   --------    ------- 
        2     Job2                 Completed  True          Server01    Get-Process 
        3     Job3                 Failed     False         localhost   Get-Process 
 
      
 
    You can also use a Get-Job command on the child job, as shown in the  
    following command: 
 
        C:\PS> Get-Job Job3 
 
        Id    Name   PSJobTypeName State      HasMoreData   Location    Command 
        --    ----   ------------- -----      -----------   --------    ------- 
        3     Job3                 Failed     False         localhost   Get-Process 
 
 
 
    The configuration of the child job depends on the command that you use to  
    start the job. 
 
       -- When you use Start-Job to start a job on a local computer, the job  
          consists of an executive parent job and a child job that runs the  
          command. 
 
       -- When you use the AsJob parameter of Invoke-Command to start a job on  
          one or more computers, the job consists of an executive parent job  
          and a child job for each job run on each computer. 
 
       -- When you use Invoke-Command to run a Start-Job command on one or more  
          remote computers, the result is the same as a local command run on  
          each remote computer. The command returns a job object for each  
          computer. The job object consists of an executive parent job and 
          one child job that runs the command. 
     
    The parent job represents all of the child jobs. When you manage a parent  
    job, you also manage the associated child jobs. For example, if you stop a  
    parent job, all child jobs are stopped. If you get the results of a parent  
    job, you get the results of all child jobs. 
 
    However, you can also manage child jobs individually. This is most useful  
    when you want to investigate a problem with a job or get the results of  
    only one of a number of child jobs started by using the AsJob parameter of  
    Invoke-Command. (The backtick character [`] is the continuation character.) 
 
    The following command uses the AsJob parameter of Invoke-Command to start  
    background jobs on the local computer and two remote computers. The command  
    saves the job in the $j variable. 
 
        PS C:> $j = Invoke-Command -ComputerName localhost, Server01, Server02 ` 
               -Command {Get-Date} -AsJob 
 
    When you display the Name and ChildJob properties of the job in $j, it  
    shows that the command returned a job object with three child jobs, one for  
    each computer. 
 
        CPS C:> $j | Format-List Name, ChildJobs 
 
        Name      : Job3 
        ChildJobs : {Job4, Job5, Job6} 
 
 
    When you display the parent job, it shows that the job failed. 
 
        C:\PS> $j 
 
        Id    Name   PSJobTypeName State      HasMoreData   Location     
        --    ----   ------------- -----      -----------   --------    
        3     Job3   RemotingJob   Failed     False         localhost,Server... 
 
 
    But when you run a Get-Job command that gets the child jobs, the output 
    shows that only one child job failed. 
 
        PS C:\> Get-Job -IncludeChildJobs 
 
        Id    Name   PSJobTypeName State      HasMoreData   Location    Command 
        --    ----   ------------- -----      -----------   --------    ------- 
        3     Job3   RemotingJob   Failed     False         localhost,Server... 
        4     Job4                 Completed  True          localhost   Get-Date 
        5     Job5                 Failed     False         Server01    Get-Date 
        6     Job6                 Completed  True          Server02    Get-Date 
     
 
    To get the results of all child jobs, use the Receive-Job cmdlet to get  
    the results of the parent job. But you can also get the results of a  
    particular child job, as shown in the following command. 
 
        C:\PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, DateTime -Auto 
 
        ComputerName DateTime 
        ------------ -------- 
        Server02     Thursday, March 13, 2008 4:16:03 PM 
 
    The child jobs feature of Windows PowerShell background jobs gives you  
    more control over the jobs that you run. 
 
 
 

JOB TYPES

 
    Windows PowerShell supports different types of jobs for different tasks. 
    Beginning in Windows PowerShell 3.0, developers can write "job source 
    adapters" that add new job types to Windows PowerShell and include the 
    job source adapters in modules. When you import the module, you can 
    use the new job type in your session. 
 
    For example, the PSScheduledJob module adds scheduled jobs and the 
    PSWorkflow module adds workflow jobs. 
 
    Custom jobs types might differ significantly from standard Windows 
    PowerShell background jobs. For example, scheduled jobs are saved 
    on disk; they do not exist only in a particular session. Workflow 
    jobs can be suspended and resumed. 
 
    The cmdlets that you use to manage custom jobs depend on the job  
    type. For some, you use the standard job cmdlets, such as Get-Job 
    and Start-Job. Others come with specialized cmdlets that manage 
    only a particular type of job. For detailed information about 
    custom job types, see the help topics about the job type. 
     
    To find the job type of a job, use the Get-Job cmdlet. Get-Job  
    returns different job objects for different types of jobs. The  
    value of the PSJobTypeName property of the job objects that 
    Get-Job returns indicates the job type. 
 
    The following table lists the job types that come with Windows 
    PowerShell. 
 
      Job Type         Description 
      --------         ----------- 
      BackgroundJob    Started by using the Start-Job cmdlet. 
      RemoteJob        Started by using the AsJob parameter of the  
                       Invoke-Command cmdlet. 
      PSWorkflowJob    Started by using the AsJob parameter of a 
                       workflow. 
      PSScheduledJob   An instance of a scheduled job started by 
                       a job trigger. 
      CIMJob           Started by using the AsJob parameter of  
                       a cmdlet from a CDXML module. 
      WMIJob           Started by using the AsJob parameter of  
                       a cmdlet from a WMI module. 
      PSEventJob       Created by running Register-ObjectEvent  
                       and specifying an action with the Action 
                       parameter.  
 
 
    NOTE: Before using the Get-Job cmdlet to get jobs of a particular 
    type, verify that the module that adds the job type is imported 
    into the current session. Otherwise, Get-Job does not get jobs of 
    that type. 
 
 

EXAMPLE

    The following commands create a local background job, a 
    remote background job, a workflow job, and a scheduled job. 
    Then, it uses the Get-Job cmdlet to get the jobs. Get-Job 
    does not get the scheduled job, but it gets any started 
    instances of the scheduled job. 
 
    # Start a background job on the local computer. 
    PS C:\> Start-Job -Name LocalData {Get-Process} 
 
    Id   Name        PSJobTypeName   State   HasMoreData     Location   Command 
    --   ----        -------------   -----   -----------     --------   ------- 
    2    LocalData   BackgroundJob   Running        True     localhost  Get-Process 
 
 
 
    # Start a background job that runs on a remote computer. 
    PS C:\> Invoke-Command -ComputerName Server01 {Get-Process} -AsJob -JobName RemoteData 
 
    Id   Name        PSJobTypeName   State   HasMoreData     Location   Command 
    --   ----        -------------   -----   -----------     --------   ------- 
    2    RemoteData  RemoteJob       Running        True     Server01   Get-Process 
 
 
 
    # Create a scheduled job 
    PS C:\>  Register-ScheduledJob -Name ScheduledJob -ScriptBlock {Get-Process} ` 
             -Trigger (New-JobTrigger -Once -At "3 PM") 
 
    Id         Name            JobTriggers     Command       Enabled 
    --         ----            -----------     -------       ------- 
    1          ScheduledJob    1               Get-Process   True 
 
 
 
    # Create a workflow.  
    PS C:\> workflow Test-Workflow {Get-Process} 
 
    # Run the workflow as a job. 
    PS C:\> Test-Workflow -AsJob -JobName TestWFJob 
 
    Id   Name        PSJobTypeName   State   HasMoreData     Location   Command 
    --   ----        -------------   -----   -----------     --------   ------- 
    2    TestWFJob   PSWorkflowJob   NotStarted     True     localhost  Get-Process 
 
 
 
    # Get the jobs. The Get-Job command does not get scheduled jobs, but it gets 
      instances of the scheduled job that are started. 
 
    PS C:\> Get-Job 
 
    Id   Name         PSJobTypeName   State     HasMoreData     Location  Command 
    --   ----         -------------   -----     -----------     --------  ------- 
    2    LocalData    BackgroundJob   Completed True            localhost Get-Process 
    4    RemoteData   RemoteJob       Completed True            Server01  Get-Process 
    6    TestWFJob    PSWorkflowJob   Completed True            localhost WorkflowJob 
    8    ScheduledJob PSScheduledJob  Completed True            localhost Get-Process 
 
    # To get scheduled jobs, use the Get-ScheduledJob cmdlet. 
    PS C:\> Get-ScheduledJob 
 
    Id         Name            JobTriggers     Command       Enabled 
    --         ----            -----------     -------       ------- 
    1          ScheduledJob    1               Get-Process   True 
 
 

SEE ALSO

about_Jobs
about_Remote_Jobs
about_Remote
about_Scheduled_Jobs
Invoke-Command
Start-Job
Get-Job
Wait-Job
Stop-Job
Remove-Job
Suspend-Job
Resume-Job
New-PSSession
Enter-PSSession
Exit-PSSession
Register-ScheduledJob
Get-ScheduleJob