powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Stop-Job



NAME
Stop-Job

SYNOPSIS
Stops a Windows PowerShell background job.

SYNTAX
Stop-Job [[-InstanceId] ] [-PassThru] [-Confirm] [-WhatIf] []

Stop-Job [-Job] [-PassThru] [-Confirm] [-WhatIf] []

Stop-Job [[-Name] ] [-PassThru] [-Confirm] [-WhatIf] []

Stop-Job [-Id] [-PassThru] [-Confirm] [-WhatIf] []

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


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

You can use Stop-Job to stop jobs that were started by using Start-Job or the AsJob parameter of Invoke-Command. Wh
en you stop a background job, Windows PowerShell completes all tasks that are pending in that job queue and then en
ds 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
Stops jobs with the specified IDs. The default is all jobs in the current session.

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 (separ
ated 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
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, us
e Get-Job.

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

-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 t
hat were started in the current session.

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

-Name
Stops only the jobs with the specified friendly names. Enter the job names in a comma-separated list or use wil
dcard characters (*) to enter a job name pattern. By default, Stop-Job stops all jobs created in the current se
ssion.

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

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

-PassThru []
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
Stops only jobs within the specified state. Valid values are NotStarted, Running, Completed, Stopped, Failed, a
nd Blocked.

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.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 an
y 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 o
n 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 o
bject 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 Se
rver01. 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 valu
es 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 operat
or (|) 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 th
e job.

The first command uses the Invoke-Command cmdlet to start a background job on the Server01 computer. The command us
es 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 o
bject 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 Pa
ssThru parameter to direct Stop-Job to return a job object. The job object display confirms that the State of the j
ob 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