Category Archives: Job

Wait-Job

February 26, 2014 Adam

SYNOPSIS
Suppresses the command prompt until one or all of the Windows PowerShell background jobs running in the session are complete.

SYNTAX
Wait-Job [[-InstanceId] <Guid[]>] [-Any] [-Timeout <int>] [<CommonParameters>]

Wait-Job [-Job] <Job[]> [-Any] [-Timeout <int>] [<CommonParameters>]

Wait-Job [[-Name] <string[]>] [-Any] [-Timeout <int>] [<CommonParameters>]

Wait-Job [-Id] <Int32[]> [-Any] [-Timeout <int>] [<CommonParameters>]

Wait-Job [-State {NotStarted | Running | Completed | Failed | Stopped | Blocked}] [-Any] [-Timeout <int>] [<CommonParameters>]

DESCRIPTION
The Wait-Job cmdlet waits for Windows PowerShell background jobs to complete before it displays the command prompt. You can wait until any background job is complete, or until all background jobs are complete, and you can set a maximum wait time for the job.

You can use Wait-Job to get background jobs that were started by using Start-Job or the AsJob parameter of Invoke-Command.

When the commands in the job are complete, Wait-Job displays the command prompt and returns a job object so that you can pipe it to another command.

PARAMETERS
-Any [<SwitchParameter>]
Displays the command prompt (and returns the job object) when any job completes. By default, Wait-Job waits until all of the specified jobs are complete before displaying the prompt.

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

-Id <Int32[]>
Waits for 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 type than the InstanceId, 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?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-InstanceId <Guid[]>
Waits for 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? false

-Job <Job[]>
Waits for the specified jobs. Enter a Variable that contains the job objects or a command that gets the job objects. You can also use a pipeline operator to send job objects to the Wait-Job cmdlet. By default, Wait-Job waits for all jobs created in the current session.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByValue, ByPropertyName)
        Accept wildcard characters? false

-Name <string[]>
Waits for jobs with the specified friendly name.

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

-State <JobState>
Waits for jobs in the specified state. Valid values are NotStarted, Running, Completed, Stopped, Failed, and Blocked.

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

-Timeout <int>
Determines the maximum wait time for each background job, in seconds. The default, -1, waits until the job completes, no matter how long it runs. The timing starts when you submit the Wait-Job command, not the Start-Job command.

If this time is exceeded, the wait ends and the command prompt returns, even if the job is still running. No error message is displayed.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        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
System.Management.Automation.RemotingJob
You can pipe a job object to Wait-Job.

OUTPUTS
System.Management.Automation.RemotingJob
Wait-Job returns job objects that represent the completed jobs. If the wait ends because the value of the Timeout parameter is exceeded, Wait-Job does not return any objects.

NOTES

————————– EXAMPLE 1 ————————–

C:\PS>Get-Job | Wait-Job

    Description
    ———–
    This command waits for all of the background jobs running in the session to complete.

————————– EXAMPLE 2 ————————–

C:\PS>$s = New-PSSession server01, server02, server03

C:\PS> Invoke-Command -session $s -scriptblock {Start-Job -name Date1 -scriptblock {Get-Date}}

C:\PS> $done = Invoke-Command -session $s -command {Wait-Job -name Date1}

C:\PS> $done.count
3

    Description
    ———–
    This example shows how to use the Wait-Job cmdlet with jobs started on remote computers by using the Start-Job cmdlet. Both the Start-Job and Wait-Job commands are submitted to the remote computer by using the Invoke-Command cmdlet.

This example uses Wait-Job to determine whether a Get-Date command running as a background job on three different computers is complete.

The first command creates a Windows PowerShell session (PSSession) on each of the three remote computers and stores them in the $s Variable.

The second command uses the Invoke-Command cmdlet to run a Start-Job command in each of the three sessions in $s. All of the jobs are named Date1.

The third command uses the Invoke-Command cmdlet to run a Wait-Job command. This command waits for the Date1 jobs on each computer to complete. It stores the resulting collection (array) of job objects in the $done Variable.

The fourth command uses the Count property of the array of job objects in the $done Variable to determine how many of the jobs are complete.

————————– EXAMPLE 3 ————————–

C:\PS>$s = New-PSSession (Get-Content machines.txt)

C:\PS> $c = ‘Get-Eventlog -log system | where {$_.EntryType -eq “error” -and $_.Source -eq “LSASRV”} | Out-File errors.txt’

C:\PS> Invoke-Command -session $s -scriptblock {param($c)Start-Job -scriptblock {$c}} -ArgumentList $c

C:\PS> Invoke-Command -session $s -scriptblock {Wait-Job -Any}

    Description
    ———–
    This example uses the Any parameter of Wait-Job to determine when the first of many background jobs running in the current session are complete. It also shows how to use the Wait-Job cmdlet to wait for remote jobs to complete.

The first command creates a PSSession on each of the computers listed in the Machines.txt file and stores the PSSessions in the $s Variable. The command uses the Get-Content cmdlet to get the contents of the file. The Get-Content command is enclosed in parentheses to ensure that it runs before the New-PSSession command.

The second command stores a Get-EventLog command string (in quotation marks) in the $c Variable.

The third command uses the Invoke-Command cmdlet to run a Start-Job command in each of the sessions in $s. The Start-Job command starts a background job that runs the command in $c.

Because the $c Variable is on the local computer, the command uses the “param” keyword to declare the local Variables in the command and the ArgumentList parameter to supply the values for those Variables.

The fourth command uses the Invoke-Command cmdlet to run a Wait-Job command in the sessions. It uses the Wait-Job cmdlet to wait until the first job on the remote computers is complete.

————————– EXAMPLE 4 ————————–

C:\PS>$s = New-PSSession Server01, Server02, Server03

C:\PS> $jobs = Invoke-Command -session $s -scriptblock {Start-Job -script {Get-Date}}

C:\PS> $done = Invoke-Command -session $s -scriptblock {Wait-Job -Timeout 30}

    Description
    ———–
    This example shows how to use the Timeout parameter of Wait-Job to set a maximum wait time for the jobs running on remote computers.

The first command creates a PSSession on each of three remote computers (Server01, Server02, and Server03), and it saves the PSSessions in the $s Variable.

The second command uses the Invoke-Command cmdlet to run a Start-Job command in each of the PSSessions in $s. It saves the resulting job objects in the $jobs Variable.

The third command uses the Invoke-Command cmdlet to run a Wait-Job command in each of the PSSessions in $s. The Wait-Job command determines whether all of the commands have completed within 30 seconds. It uses the Timeout parameter with a value of 30 (seconds) to establish the maximum wait time and saves the results of the command in the $done Variable.

In this case, after 30 seconds, only the command on the Server02 computer has completed. Wait-Job ends the wait, displays the command prompt, and returns the object that represents the job that was completed.

The $done Variable contains a job object that represents the job that ran on Server02.

————————– EXAMPLE 5 ————————–

C:\PS>Wait-Job -Id 1,2,5 -Any

    Description
    ———–
    This command identifies three jobs by their IDs and waits until any of them are complete. The command prompt returns when the first job completes.

————————– EXAMPLE 6 ————————–

C:\PS>Wait-Job -name DailyLog -Timeout 120

    Description
    ———–
    This command waits 120 seconds (two minutes) for the DailyLog job to complete. If the job does not complete in the next two minutes, the command prompt returns anyway, and the job continues to run in the background.

————————– EXAMPLE 7 ————————–

C:\PS>Wait-Job -name Job3

    Description
    ———–
    This Wait-Job command uses the job name to identify the job to wait for.

————————– EXAMPLE 8 ————————–

C:\PS>C:\PS> $j = Start-Job -script {Get-ChildItem *.ps1| where {$_lastwritetime -gt ((Get-Date) – (New-TimeSpan -days 7))}}

C:\PS> $j | Wait-Job

    Description
    ———–
    This example shows how to use the Wait-Job cmdlet with jobs started on the local computer by using the Start-Job cmdlet.

These commands start a job that gets the Windows PowerShell script files that were added or updated in the last week.

The first command uses the Start-Job cmdlet to start a background job on the local computer. The job runs a Get-ChildItem command that gets all of the files with a “.ps1” file name extension that were added or updated in the last week.

The third command uses the Wait-Job cmdlet to wait until the job is complete. When the job completes, the command displays the job object, which contains information about the job.

————————– EXAMPLE 9 ————————–

C:\PS>$s = New-PSSession Server01, Server02, Server03

C:\PS> $j = Invoke-Command -session $s -scriptblock {Get-Process} -asjob

C:\PS> $j | Wait-Job

    Description
    ———–
    This example shows how to use the Wait-Job cmdlet with jobs started on remote computers by using the AsJob parameter of the Invoke-Command cmdlet. When using AsJob, the job is created on the local computer and the results are automatically returned to the local computer, even though the job runs on the remote computers.

This example uses Wait-Job to determine whether a Get-Process command running in the sessions on three remote computers is complete.

The first command creates PSSessions on three computers and stores them in the $s Variable.

The second command uses the Invoke-Command cmdlet to run a Get-Process command in each of the three PSSessions in $s. The command uses the AsJob parameter to run the command asynchronously as a background job. The command returns a job object, just like the jobs started by using Start-Job, and the job object is stored in the $j Variable.

The third command uses a pipeline operator (|) to send the job object in $j to the Wait-Job cmdlet. Notice that an Invoke-Command command is not required in this case, because the job resides on the local computer.

————————– EXAMPLE 10 ————————–

C:\PS>Get-Job

    Id Name     State     HasMoreData     Location             Command
    — —-     —–     ———–     ——–             ——-
    1    Job1     Completed True            localhost,server01.. Get-Service
    4    Job4     Completed True            localhost            dir | where

C:\PS> Wait-Job -Id 1

    Description
    ———–
    This command waits for the job with an ID value of 1.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113422
    about_jobs
    about_job_details
    about_remote_Jobs
    Start-Job
    Get-Job
    Receive-Job
    Stop-Job
    Remove-Job
    Invoke-Command

cmdlet, Job, Start

Start-Job

February 26, 2014 Adam

NAME
Start-Job

SYNOPSIS
Starts a Windows PowerShell background job.

SYNTAX
Start-Job [-ScriptBlock] <scriptblock> [[-InitializationScript] <scriptblock>] [-ArgumentList <Object[]>] [-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-Credential <PSCredential>] [-InputObject <psobject>] [-Name <string>] [-RunAs32] [<CommonParameters>]

Start-Job [[-FilePath] <string>] [[-InitializationScript] <scriptblock>] [-ArgumentList <Object[]>] [-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-Credential <PSCredential>] [-InputObject <psobject>] [-Name <string>] [-RunAs32] [<CommonParameters>]

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 completes, use the Receive-Job cmdlet to get the results of the job. For more information about background jobs, see about_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_Jobs.

PARAMETERS
-ArgumentList <Object[]>
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 ArgumentList, 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 <AuthenticationMechanism>
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.Runspaces.AuthenticationMechanism enumeration in MSDN.

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

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

-Credential <PSCredential>
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 Get-Credential cmdlet.

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

-FilePath <string>
Runs the specified local script as a background job. Enter the path and file name of the script or pipe a script 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 <scriptblock>
Specifies commands that run before the job starts. Enclose the commands in braces ( { } ) to create a script block.

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 <psobject>
Specifies input to the command. Enter a Variable that contains the objects, or type a command or expression that 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 <string>
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<number>
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-RunAs32 [<SwitchParameter>]
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 <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

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 within 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 information about the job. The command prompt returns immediately so that you can work in the session while the job runs in the background.

————————– EXAMPLE 2 ————————–

C:\PS>$jobWRM = Invoke-Command -computerName (Get-Content servers.txt) -ScriptBlock {Get-Service winrm} -jobname WinRM -throttlelimit 16 -AsJob

    Description
    ———–
    This command uses the Invoke-Command cmdlet and its AsJob parameter to start a background job that runs a “Get-Service winrm” command on numerous computers. Because the command is running on a server with substantial network traffic, 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 ComputerName 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 name 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 runs 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 returns 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 ScriptBlock parameter to specify the command that runs in the background job. It uses the Name parameter to specify a friendly name for the new job.

————————– EXAMPLE 6 ————————–

C:\PS>Start-Job -Name GetMappingFiles -InitializationScript {Import-Module MapFunctions} -ScriptBlock {Get-Map -Name * | 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 InitializationScript parameter to run a script block that imports a required module. It also uses the RunAs32 parameter 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

cmdlet, Job, Stop

Stop-Job

February 26, 2014 Adam

NAME
Stop-Job

SYNOPSIS
Stops a Windows PowerShell background job.

SYNTAX
Stop-Job [[-InstanceId] <Guid[]>] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Stop-Job [-Job] <Job[]> [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Stop-Job [[-Name] <string[]>] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Stop-Job [-Id] <Int32[]> [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Stop-Job [-State {NotStarted | Running | Completed | Failed | Stopped | Blocked}] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Stop-Job cmdlet stops Windows PowerShell background jobs that are in progress. You can use this cmdlet to stop all jobs or stop selected jobs based on their name, ID, instance ID, or state, or by passing a job object to Stop-Job.

You can use Stop-Job to stop jobs that were started by using Start-Job or the AsJob parameter of Invoke-Command. When you stop a background job, Windows PowerShell completes all tasks that are pending in that job queue and then ends the job. No new tasks are added to the queue after this command is submitted.

This cmdlet does not delete background jobs. To delete a job, use Remove-Job.

PARAMETERS
-Id <Int32[]>
Stops jobs with the specified IDs. The default is all jobs in the current session.

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

-InstanceId <Guid[]>
Stops only 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? false

-Job <Job[]>
Specifies the jobs to be stopped. Enter a Variable that contains the jobs or a command that gets the jobs. You can also use a pipeline operator to submit jobs to the Stop-Job cmdlet. By default, Stop-Job deletes all jobs that were started in the current session.

-Name <string[]>
Stops only the jobs with the specified friendly names. Enter the job names in a comma-separated list or use wildcard characters (*) to enter a job name pattern. By default, Stop-Job stops all jobs created in the current session.

Because the friendly name is not guaranteed to be unique, use the WhatIf and Confirm parameters when stopping jobs by name.

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

-PassThru [<SwitchParameter>]
Returns an object representing the new background job. By default, this cmdlet does not generate any output.

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

-State <JobState>
Stops only jobs within the specified state. Valid values are NotStarted, Running, Completed, Stopped, Failed, and Blocked.

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

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

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

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

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

INPUTS
System.Management.Automation.RemotingJob
You can pipe a job object to Stop-Job.

OUTPUTS
None or System.Management.Automation.RemotingJob
When you use the PassThru parameter, Stop-Job returns a job object. Otherwise, this cmdlet does not generate any output.

NOTES

————————– EXAMPLE 1 ————————–

C:\PS>$s = New-PSSession -computername Server01 -credential domain01\admin02

C:\PS> $j = Invoke-Command -session $s -scriptblock {Start-Job -scriptblock {Get-Eventlog system}}

C:\PS> Invoke-Command -session $s -scriptblock {param($j) Stop-Job -job $j} -ArgumentList $j

    Description
    ———–
    This example shows how to use the Stop-Job cmdlet to stop a job that is running on a remote computer.

Because the job was started by using Invoke-Command to run a Start-Job command remotely, the job object is stored on the remote computer, and you must use another Invoke-Command command to run a Stop-Job command remotely. For more information about remote background jobs, see about_remote_Jobs.

The first command creates a Windows PowerShell session (PSSession) on the Server01 computer and saves the session object in the $s Variable. The command uses the credentials of a domain administrator.

The second command uses the Invoke-Command cmdlet to run a Start-Job command in the session. The command in the job gets all of the events in the System event log. The resulting job object is stored in the $j Variable.

The third command stops the job. It uses the Invoke-Command cmdlet to run a Stop-Job command in the PSSession on Server01. Because the job objects are stored in $j, which is a Variable on the local computer, the command uses the “param” keyword to declare the local Variables in the command, and it uses the ArgumentList parameter to supply values for the Variables.

When the command completes, the job is stopped and the PSSession in $s is available for use.

————————– EXAMPLE 2 ————————–

C:\PS>Stop-Job -state failed

    Description
    ———–
    This command stops all jobs with a State value of “Failed”.

————————– EXAMPLE 3 ————————–

C:\PS>Stop-Job -name job1

    Description
    ———–
    This command stops the Job1 background job.

————————– EXAMPLE 4 ————————–

C:\PS>Stop-Job -Id 1, 3, 4

    Description
    ———–
    This command stops three jobs. It identifies them by their IDs.

————————– EXAMPLE 5 ————————–

C:\PS>Get-Job | Stop-Job

    Description
    ———–
    This command stops all the background jobs in the current session.

————————– EXAMPLE 6 ————————–

C:\PS>Stop-Job -state blocked

    Description
    ———–
    This command stops all the jobs with a job status of “Blocked”.

————————– EXAMPLE 7 ————————–

C:\PS>Get-Job | Format-Table ID, Name, Command, @{Label=”State”;Expression={$_.jobstateinfo.state}}, I
nstanceID -auto

    Id Name Command                 State InstanceId
    — —- ——-                 —– ———-
     1 Job1 Start-Service schedule Running 05abb67a-2932-4bd5-b331-c0254b8d9146
     3 Job3 Start-Service schedule Running c03cbd45-19f3-4558-ba94-ebe41b68ad03
     5 Job5 Get-Service s*         Blocked e3bbfed1-9c53-401a-a2c3-a8db34336adf

C:\PS> Stop-Job -instanceid e3bbfed1-9c53-401a-a2c3-a8db34336adf

    Description
    ———–
    These commands show how to stop a job based on its instance ID.

The first command uses a Get-Job command to get the jobs in the current session. The command uses a pipeline operator (|) to send the jobs to a Format-Table command, which displays a table of the specified properties of each job. The table includes the Instance ID of each job. It uses a calculated property to display the job state.

The second command uses a Stop-Job command with the InstanceID parameter to stop a selected job.

————————– EXAMPLE 8 ————————–

C:\PS>$j = Invoke-Command -computername Server01 -scriptblock {Get-Eventlog system} -asjob

C:\PS> $j | Stop-Job -PassThru

    Id    Name    State     HasMoreData     Location         Command
    —    —-    —-     ———–     ——–         ——-
    5     Job5    Stopped    True            judithh-tablet Get-Eventlog system

    Description
    ———–
    This example shows how to use the Stop-Job cmdlet to stop a job that is running on a remote computer.

Because the job was started by using the AsJob parameter of Invoke-Command, the job object is located on the local computer, even though the job runs on the remote computer. As such, you can use a local Stop-Job command to stop the job.

The first command uses the Invoke-Command cmdlet to start a background job on the Server01 computer. The command uses the AsJob parameter to run the remote command as a background job.

This command returns a job object, which is the same job object that Start-Job returns. The command saves the job object in the $j Variable.

The second command uses a pipeline operator to send the job in the $j Variable to Stop-Job. The command uses the PassThru parameter to direct Stop-Job to return a job object. The job object display confirms that the State of the job is “Stopped”.

For more information about remote background jobs, see about_remote_Jobs.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113413
    about_jobs
    about_job_details
    about_remote_Jobs
    Start-Job
    Get-Job
    Receive-Job
    Wait-Job
    Remove-Job
    Invoke-Command

cmdlet, Job, Remove

Remove-Job

February 26, 2014 Adam

NAME
Remove-Job

SYNOPSIS
Deletes a Windows PowerShell background job.

SYNTAX
Remove-Job [-Id] <Int32[]> [-Force] [-Confirm] [-WhatIf] [<CommonParameters>]

Remove-Job [-Command <string[]>] [-Confirm] [-WhatIf] [<CommonParameters>]

Remove-Job [[-InstanceId] <Guid[]>] [-Force] [-Confirm] [-WhatIf] [<CommonParameters>]

Remove-Job [-Job] <Job[]> [-Force] [-Confirm] [-WhatIf] [<CommonParameters>]

Remove-Job [[-Name] <string[]>] [-Force] [-Confirm] [-WhatIf] [<CommonParameters>]

Remove-Job [-State {NotStarted | Running | Completed | Failed | Stopped | Blocked}] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Remove-Job cmdlet deletes Windows PowerShell background jobs that were started by using Start-Job or the AsJob parameter of any cmdlet.

You can use this cmdlet to delete all jobs or delete selected jobs based on their name, ID, instance ID, command, or state, or by passing a job object to Remove-Job. Without parameters or parameter values, Remove-Job has no effect.

Before deleting a running job, use the Stop-Job cmdlet to stop the job. If you try to delete a running job, the command fails. You can use the Force parameter of Remove-Job to delete a running job.

If you do not delete a background job, the job remains in the global job cache until you close the session in which the job was created.

PARAMETERS
-Command <string[]>
Removes jobs that include the specified words in the command.

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

-Force [<SwitchParameter>]
Deletes the job even if the status is “Running”. Without the Force parameter, Remove-Job will not delete a running job.

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

-Id <Int32[]>
Deletes background 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 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?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-InstanceId <Guid[]>
Deletes jobs with the specified instance IDs.

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 or display the job object.

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

-Job <Job[]>
Specifies the jobs to be deleted. Enter a Variable that contains the jobs or a command that gets the jobs. You can also use a pipeline operator to submit jobs to the Remove-Job cmdlet.

-Name <string[]>
Deletes only the jobs with the specified friendly names. Wildcards are permitted.

Because the friendly name is not guaranteed to be unique, even within the session, use the WhatIf and Confirm parameters when deleting jobs by name.

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

-State <JobState>
Deletes only jobs with the specified status. Valid values are NotStarted, Running, Completed, Stopped, Failed, and Blocked. To delete jobs with a status of Running, use the Force parameter.

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

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

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

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

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

INPUTS
System.Management.Automation.Job
You can pipe a job object to Remove-Job.

OUTPUTS
None
This cmdlet does not generate any output.

NOTES

————————– EXAMPLE 1 ————————–

C:\PS>$batch = Get-Job -name BatchJob

C:\PS> $batch | Remove-Job

    Description
    ———–
    These commands delete a background job named BatchJob from the current session. The first command uses the Get-Job cmdlet to get an object representing the job, and then it saves the job in the $batch Variable. The second command uses a pipeline operator (|) to send the job to the Remove-Job cmdlet.

This command is equivalent to using the Job parameter of Remove-Job, for example, “Remove-Job -job $batch”.

————————– EXAMPLE 2 ————————–

C:\PS>Get-Job | Remove-Job

    Description
    ———–
    This command deletes all of the jobs in the current session.

————————– EXAMPLE 3 ————————–

C:\PS>Remove-Job -state NotStarted

    Description
    ———–
    This command deletes all jobs from the current session that have not yet been started.

————————– EXAMPLE 4 ————————–

C:\PS>Remove-Job -name *batch -Force

    Description
    ———–
    This command deletes all jobs with friendly names that end with “batch” from the current session, including jobs that are running.

It uses the Name parameter of Remove-Job to specify a job name pattern, and it uses the Force parameter to ensure that all jobs are removed, even those that might be in progress.

————————– EXAMPLE 5 ————————–

C:\PS>$j = Invoke-Command -computername Server01 -scriptblock {Get-Process} -asJob

C:\PS> $j | Remove-Job

    Description
    ———–
    This example shows how to use the Remove-Job cmdlet to remove a job that was started on a remote computer by using the AsJob parameter of the Invoke-Command cmdlet.

The first command uses the Invoke-Command cmdlet to run a job on the Server01 computer. It uses the AsJob parameter to run the command as a background job, and it saves the resulting job object in the $j Variable.

Because the command used the AsJob parameter, the job object is created on the local computer, even though the job runs on a remote computer. As a result, you use local commands to manage the job.

The second command uses the Remove-Job cmdlet to remove the job. It uses a pipeline operator (|) to send the job in $j to Remove-Job. Note that this is a local command. A remote command is not required to remove a job that was started by using the AsJob parameter.

————————– EXAMPLE 6 ————————–

C:\PS>$s = New-PSSession -computername Server01

C:\PS> Invoke-Command -session $s -scriptblock {Start-Job -scriptblock {Get-Process} -name MyJob}

C:\PS> Invoke-Command -session $s -scriptblock {Remove-Job -name MyJob}

    Description
    ———–
    This example shows how to remove a job that was started by using Invoke-Command to run a Start-Job command. In this case, the job object is created on the remote computer and you use remote commands to manage the job.

The first command uses the New-PSSession cmdlet to create a PSSession (a persistent connection) to the Server01 computer. A persistent connection is required when running a Start-Job command remotely. The command saves the PSSession in the $s Variable.

The second command uses the Invoke-Command cmdlet to run a Start-Job command in the PSSession in $s. The job runs a Get-Process command. It uses the Name parameter of Start-Job to specify a friendly name for the job.

The third command uses the Invoke-Command cmdlet to run a Remove-Job command in the PSSession in $s. The command uses the Name parameter of Remove-Job to identify the job to be deleted.

————————– EXAMPLE 7 ————————–

C:\PS>$j = Start-Job -script {Get-Process powershell}

C:\PS> $j | Format-List -property *

C:\PS> Remove-Job -instanceID dce2ee73-f8c9-483e-bdd7-a549d8687eed

C:\PS> $j = Start-Job -script {Get-Process powershell}

C:\PS> $j | Format-List -property *

    HasMoreData : False
    StatusMessage :
    Location     : localhost
    Command     : Get-Process powershell
    JobStateInfo : Failed
    Finished     : System.Threading.ManualResetEvent
    InstanceId    : dce2ee73-f8c9-483e-bdd7-a549d8687eed
    Id            : 1
    Name         : Job1
    ChildJobs     : {Job2}
    Output        : {}
    Error         : {}
    Progress     : {}
    Verbose     : {}
    Debug         : {}
    Warning     : {}
    StateChanged :

C:\PS> Remove-Job -instanceID dce2ee73-f8c9-483e-bdd7-a549d8687eed

    Description
    ———–
    This example shows how to remove a job based on its instance ID.

The first command uses the Start-Job cmdlet to start a background job. The command saves the resulting job object in the $j Variable.

The second command uses a pipeline operator (|) to send the job object in $j to a Format-List command. 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 job object display shows the values of the ID and InstanceID properties, along with the other properties of the object.

The third command uses a Remove-Job command to remove the job from the current session. To generate the command, you can copy and paste the InstanceID value from the object display.

To copy a value in the Windows PowerShell console, use the mouse to select the value, and then press Enter to copy it. To paste a value, right-click.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113377
    about_jobs
    about_job_details
    about_remote_Jobs
    Start-Job
    Get-Job
    Receive-Job
    Wait-Job
    Stop-Job
    Invoke-Command

cmdlet, Job, Receive

Receive-Job

February 26, 2014 Adam

NAME
Receive-Job

SYNOPSIS
Gets the results of the Windows PowerShell background jobs in the current session.

SYNTAX
Receive-Job [-Job] <Job[]> [[-ComputerName] <string[]>] [-Keep] [-NoRecurse] [<CommonParameters>]

Receive-Job [[-InstanceId] <Guid[]>] [-Keep] [-NoRecurse] [<CommonParameters>]

Receive-Job [-Job] <Job[]> [[-Location] <string[]>] [-Keep] [-NoRecurse] [<CommonParameters>]

Receive-Job [[-Name] <string[]>] [-Keep] [-NoRecurse] [<CommonParameters>]

Receive-Job [-Job] <Job[]> [[-Session] <PSSession[]>] [-Keep] [-NoRecurse] [<CommonParameters>]

Receive-Job [-Id] <Int32[]> [-Keep] [-NoRecurse] [<CommonParameters>]

DESCRIPTION
The Receive-Job cmdlet gets the results of Windows Powershell background jobs. Use Receive-Job to get the results of jobs started by using the Start-Job cmdlet or the AsJob parameter of any cmdlet. You can get the results of all jobs or identify jobs by their name, ID, instance ID, computer name, location, or session, or by submitting a job object.

When you start a Windows PowerShell background job, the job starts, but the results do not appear immediately. Instead, the command returns an object that represents the background job. The job object contains useful information about the job, but it does not contain the results. This method allows you to continue working in the session while the job runs. For more information about background jobs in Windows PowerShell, see about_jobs.

To get the results of the command, use the Receive-Job cmdlet. Receive-Job gets the results that have been generated by the time that the Receive-Job command is submitted. If the results are not yet complete, you can run additional Receive-Job commands to get the remaining results.

By default, job results are deleted from the system when you receive them, but you can use the Keep parameter to save the results so that you can receive them again. To delete the job results, receive them again (without the Keep parameter), close the session, or use the Remove-Job cmdlet to delete the job from the session.

PARAMETERS
-ComputerName <string[]>
Gets the results of jobs that were run on the specified computers. Enter the computer names. The default is all jobs in the current session.

This parameter selects from among the job results that are stored on the local computer. It does not get data from remote computers. To get job results that are stored on remote computers, use the Invoke-Command cmdlet to run a Receive-Job command remotely.

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

-Id <Int32[]>
Gets the results of jobs with the specified IDs. The default is all jobs in the current session.

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

-InstanceId <Guid[]>
Gets the results of jobs with the specified instance IDs. The default is all jobs in the current session.

An instance ID is a GUID that uniquely identifies the job on the computer. To find the instance ID of a job, use the Get-Job cmdlet.

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

-Job <Job[]>
Specifies the job for which results are being retrieved. This parameter is required in a Receive-Job command. Enter a Variable that contains the job or a command that gets the job. You can also pipe a job object to Receive-Job.

-Keep [<SwitchParameter>]
Saves the job results in the system, even after you have received them. By default, the job results are deleted when they are retrieved.

To delete the results, use Receive-Job to receive them again without the Keep parameter, close the session, or use the Remove-Job cmdlet to delete the job from the session.

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

-Location <string[]>
Gets only the results of jobs with the specified location. The default is all jobs in the current session.

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

-Name <string[]>
Gets the results of jobs with the specified friendly name. The default is all jobs in the current session.

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

-NoRecurse [<SwitchParameter>]
Gets results only from the specified job. By default, Receive-Job also gets the results of all child jobs of the specified job.

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

-Session <PSSession[]>
Gets the results of jobs that were run in the specified Windows Powershell session (PSSession). Enter a Variable that contains the PSSession or a command that gets the PSSession, such as a Get-PSSession command. The default is all jobs in the current session.

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

INPUTS
System.Management.Automation.Job
You can pipe job objects to Receive-Job.

OUTPUTS
PSObject
Receive-Job returns the results of the commands in the job.

NOTES

————————– EXAMPLE 1 ————————–

C:\PS>$job = Start-Job -scriptblock {Get-Process}

C:\PS> Receive-Job -Job $job

    Description
    ———–
    These commands use the Job parameter to get the results of a particular job. The first command uses the Start-Job cmdlet to start a job that runs a “Get-Process” command. The command uses the assignment operator (=) to save the resulting job object in the $job Variable.

The second command uses the Receive-Job cmdlet to get the results of the job. It uses the Job parameter to specify the job.

————————– EXAMPLE 2 ————————–

C:\PS>$job = Start-Job -scriptblock {Get-Process}

C:\PS> $job | Receive-Job

    Description
    ———–
    This example is the same as Example 2, except that the command uses a pipeline operator (|) to send the job object to Receive-Job. As a result, the command does not need a Job parameter to specify the job.

————————– EXAMPLE 3 ————————–

C:\PS>$j = Invoke-Command -computername Server01, Server02, Server03 -scriptblock {Get-Service} -AsJob

C:\PS> $j.childjobs

    Id Name     State     HasMoreData Location     Command
    — —-     —–     ———– ——–     ——-
    2    Job2     Completed True         Server01     Get-Service
    3    Job3     Completed True         Server02     Get-Service
    4    Job4     Completed True         Server03     Get-Service

C:\PS> Receive-Job -name Job3 -Keep

    Status Name        DisplayName                        PSComputerName
    —— ———– ———–                        ————–
    Running AeLookupSvc Application Experience             Server02
    Stopped ALG         Application Layer Gateway Service Server02
    Running Appinfo     Application Information            Server02
    Running AppMgmt     Application Management             Server02

    Description
    ———–
    These commands use the Name parameter of Receive-Job to get the results of one of several background jobs run on remote computers.

The first command uses the Invoke-Command cmdlet to start a background job that runs a Get-Service command on three remote computers. The command uses the AsJob parameter to run the command as a background job. The command saves the resulting job object in the $j Variable.

When you use the AsJob parameter of Invoke-Command to start a job, the job object is created on the local computer, even though the job runs on the remote computers. As a result, you use local commands to manage the job.

Also, when you use AsJob, Windows PowerShell returns one job object that contains a child job for each job that was started. In this case, the job object contains three child jobs, one for each job on each remote computer.

The second command uses the dot method to display the value of the ChildJobs property of the job object in $j. The display shows that the command created three child jobs, one for the job on each remote computer.

The third command uses the Receive-Job cmdlet to get the results of the Job3 child job that ran on the Server02 computer. It uses the Name parameter to specify the name of the child job and the Keep parameter to save the job results even after they are received.

————————– EXAMPLE 4 ————————–

C:\PS>$s = New-PSSession -computername Server01, Server02, Server03

C:\PS> $j = Invoke-Command -session $s -scriptblock {Start-Job -scriptblock {Get-Eventlog -logname system}}

C:\PS> $j

    Id Name     State     HasMoreData Location Command
    — —-     —–     ———– ——– ——-
    1    Job1     Completed True         Localhost Get-Eventlog system
    2    Job2     Completed True         Localhost Get-Eventlog system
    3    Job3     Completed True         Localhost Get-Eventlog system

C:\PS> $results = Invoke-Command -session $s -scriptblock {param($j) Receive-Job -Job $j} -ArgumentList $j

    Description
    ———–
    This example shows how to get the results of background jobs run on three remote computers.

The first command uses the New-PSSession cmdlet to create three PSSessions, one on each of the servers specified in the command. It saves the PSSessions in the $s Variable.

The second command uses the Invoke-Command cmdlet to run a Start-Job command in each of the PSSessions in the $s Variable. The job runs a Get-Eventlog command that gets the events in the System log. The command saves the results in the $j Variable.

Because the command used Invoke-Command to run the Start-Job command, the command actually started three independent jobs on each of the three computers. As a result, the command returned three job objects representing three jobs run locally on three different computers.

The third command displays the three job objects in $j.

The fourth command uses Invoke-Command to run a Receive-Job command in each of the PSSessions in $s and save the results in the $results Variable.

Because $j is a local Variable, the script block uses the “param” keyword to declare the Variables in the command and the ArgumentList parameter to supply the value of $j.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113372
    about_jobs
    about_job_details
    about_remote_Jobs
    Start-Job
    Get-Job
    Wait-Job
    Stop-Job
    Remove-Job
    Invoke-Command

cmdlet, Get, Job

Get-Job

February 26, 2014 Adam

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

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