powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Remove-Job



NAME
Remove-Job

SYNOPSIS
Deletes a Windows PowerShell background job.

SYNTAX
Remove-Job [-Id] [-Force] [-Confirm] [-WhatIf] []

Remove-Job [-Command ] [-Confirm] [-WhatIf] []

Remove-Job [[-InstanceId] ] [-Force] [-Confirm] [-WhatIf] []

Remove-Job [-Job] [-Force] [-Confirm] [-WhatIf] []

Remove-Job [[-Name] ] [-Force] [-Confirm] [-WhatIf] []

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


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, o
r 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 com
mand 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
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 []
Deletes the job even if the status is "Running". Without the Force parameter, Remove-Job will not delete a runn
ing job.

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

-Id
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 (sepa
rated 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
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, us
e Get-Job or display the job object.

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

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

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

-Name
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 p
arameters when deleting jobs by name.

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

-State
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 []
Prompts you for confirmation before executing the command.

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

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


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.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 th
at are running.

It uses the Name parameter of Remove-Job to specify a job name pattern, and it uses the Force parameter to ensure t
hat 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 sta
rted 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 com
puter. A persistent connection is required when running a Start-Job command remotely. The command saves the PSSessi
on 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 us
es 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 i
n the $j variable.

The second command uses a pipeline operator (|) to send the job object in $j to a Format-List command. The Format-L
ist 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, yo
u 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