about_job_details

TOPIC
about_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.

Important: Background jobs that are started by using Start-Job or the AsJob
             parameter of Invoke-Command rely on the Windows PowerShell
             remoting infrastructure. To use these features, Windows
             PowerShell must be configured for remoting, even if the
             background job is runs only on the local computer.
             For more information, see about_remote_requirements.

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 see the parent and child jobs in a job, use the Get-Job cmdlet to get
    the parent job, and then pipe the job to a Format-List command that displays
    the Name and ChildJobs properties of the objects, as shown in the following
    command.

        C:\PS> Get-Job | Format-List -property Name, ChildJobs

        Name         : Job1
        ChildJobs     : {Job2}

    You can also use a Get-Job command on the child job, as shown in the
    following command:

        C:\PS> Get-Job job2

        Id    Name State     HasMoreData Location    Command
        —    —- —–     ———– ——–    ——-
        2     Job2 Completed True         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.

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

        C:\PS> $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    State HasMoreData     Location             Command
        — —-    —– ———–     ——–             ——-
        1    Job3    Failed True            localhost,server… Get-Date

    But when you run a Get-Job command on each of the child jobs, it shows
    that only one failed.

        PS C:\ps-test> Get-Job job4, job5, job6

        Id Name State     HasMoreData     Location         Command
        — —- —–     ———–     ——–         ——-
        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 -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.

SEE ALSO
    about_jobs
    about_remote_Jobs
    about_remote
    Invoke-Command
    Start-Job
    Get-Job
    Wait-Job
    Stop-Job
    Remove-Job
    New-PSSession
    Enter-PSSession
    Exit-PSSession