PowerShell Logo Small

Remove-Job



This is the built-in help made by Microsoft for the command 'Remove-Job', in PowerShell version 2 - as retrieved from Windows version 'Microsoft® Windows Vista™ Ultimate ' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

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



Search powershellhelp.space

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 o
bject 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 Fo
rce 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.



<

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

REMARKS

<

Examples


-------------------------- 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 repres
enting 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-J
ob 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 Inv
oke-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 backg
round 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 t
his 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 creat
ed 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 Remov
e-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 Insta
nceID 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-cl
ick.