Remove-Job

Syntax

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

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

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

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

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

Remove-Job
      [-State] <JobState>
      [-WhatIf]
      [-Confirm]
      [<CommonParameters>]

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

Description

The Remove-Job cmdlet deletes PowerShell background jobs that were started by the Start-Job cmdlet or by cmdlets such as Invoke-Command that support the AsJob parameter.

You can use Remove-Job to delete all jobs or delete selected jobs. The jobs are identified by their Name, ID, Instance ID, Command, or State. Or, a job object can be sent down the pipeline to Remove-Job. Without parameters or parameter values, Remove-Job has no effect.

Since PowerShell 3.0, Remove-Job can delete custom job types, such as scheduled jobs and workflow jobs. For example, Remove-Job deletes the scheduled job, all instances of the scheduled job on disk, and the results of all triggered job instances.

If you try to delete a running job, Remove-Job fails. Use the Stop-Job cmdlet to stop a running job. Or, use Remove-Job with the Force parameter to delete a running job.

Jobs remain in the global job cache until you delete the background job or close the PowerShell session.

Examples

Example 1: Delete a job by using its name

This example uses a variable and the pipeline to delete a job by name.

$batch = Get-Job -Name BatchJob
$batch | Remove-Job

Get-Job uses the Name parameter to specify the job, BatchJob. The job object is stored in the $batch variable. The object in $batch is sent down the pipeline to Remove-Job.

An alternative is to use the Job parameter, such as Remove-Job -Job $batch.

Example 2: Delete all jobs in a session

In this example, all the jobs in the current PowerShell session are deleted.

Get-job | Remove-Job

Get-Job gets all the jobs in the current PowerShell session. The job objects are sent down the pipeline to Remove-Job.

Example 3: Delete NotStarted jobs

This example deletes all jobs from the current PowerShell session that haven't started.

Remove-Job -State NotStarted

Remove-Job uses the State parameter to specify the job status.

Example 4: Delete jobs by using a friendly name

This example deletes all jobs from the current session with friendly names that end with batch*, including jobs that are running.

Remove-Job -Name *batch -Force

Remove-Job uses the Name parameter to specify a job name pattern. The pattern includes the asterisk (*) wildcard to find all job names that end with batch. The Force parameter deletes jobs that running.

Example 5: Delete a job that was created by Invoke-Command

This example removes a job that was started on a remote computer using Invoke-Command with the AsJob parameter.

Because the example uses the AsJob parameter, the job object is created on the local computer. But, the job runs on a remote computer. As a result, you use local commands to manage the job.

$job = Invoke-Command -ComputerName Server01 -ScriptBlock {Get-Process} -AsJob
$job | Remove-Job

Invoke-Command runs a job on the Server01 computer. The AsJob parameter runs the ScriptBlock as a background job. The job object is stored in the $job variable. The $job variable object is sent down the pipeline to Remove-Job.

Example 6: Delete a job that was created by Invoke-Command and Start-Job

This example shows how to remove a job on a remote computer that was started by using Invoke-Command to run Start-Job. The job object is created on the remote computer and remote commands are used to manage the job. A persistent connection is required when running a remote Start-Job command.

$S = New-PSSession -ComputerName Server01
Invoke-Command -Session $S -ScriptBlock {Start-Job -ScriptBlock {Get-Process} -Name MyJob}
Invoke-Command -Session $S -ScriptBlock {Remove-Job -Name MyJob}

New-PSSession creates a PSSession, a persistent connection, to the Server01 computer. The connection is saved in the $S variable.

Invoke-Command connects to the session saved in $S. The ScriptBlock uses Start-Job to start a remote job. The job runs a Get-Process command and uses the Name parameter to specify a friendly job name, MyJob.

Invoke-Command uses the $S session and runs Remove-Job. The Name parameter specifies that the job named MyJob is deleted.

Example 7: Delete a job by using its InstanceId

This example removes a job based on its InstanceId.

$job = Start-Job -ScriptBlock {Get-Process PowerShell}
$job | Format-List -Property *
Remove-Job -InstanceId ad02b942-8007-4407-87f3-d23e71955872

State         : Completed
HasMoreData   : True
StatusMessage :
Location      : localhost
Command       : Get-Process PowerShell
JobStateInfo  : Completed
Finished      : System.Threading.ManualResetEvent
InstanceId    : ad02b942-8007-4407-87f3-d23e71955872
Id            : 3
Name          : Job3
ChildJobs     : {Job4}
PSBeginTime   : 7/26/2019 11:36:56
PSEndTime     : 7/26/2019 11:36:57
PSJobTypeName : BackgroundJob
Output        : {}
Error         : {}
Progress      : {}
Verbose       : {}
Debug         : {}
Warning       : {}
Information   : {}

Start-Job starts a background job and the job object is saved in the $job variable.

The object in $job is sent down the pipeline to Format-List. The Property parameter uses an asterisk (*) to specify that all the object's properties are displayed in a list.

Remove-Job uses the InstanceId parameter to specify the job to delete.

Parameters

-Command

-Confirm

-Filter

-Force

-Id

-InstanceId

-Job

-Name

-State

-WhatIf

Inputs

Job

You can send a job object down the pipeline to Remove-Job.

Outputs

None

Remove-Job doesn't generate any output.

Notes

A PowerShell job creates a new process. When the job completes, the process exits. When Remove-Job is run, the job's state is removed.

If a job stops before completion and its process hasn't exited, the process is forcibly terminated.

Related Links

• about_Jobs
• about_Job_Details
• about_Remote_Jobs
• Get-Job
• Invoke-Command
• Receive-Job
• Start-Job
• Stop-Job
• Wait-Job