PowerShell Logo Small

Suspend-Job



This is the built-in help made by Microsoft for the command 'Suspend-Job', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' 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

Temporarily stops workflow jobs.

SYNTAX


Suspend-Job [-Id] <Int32[]> [-Force] [-Wait] [-Confirm] [-WhatIf] [<CommonParameters>]
Suspend-Job [-Filter] <Hashtable> [-Force] [-Wait] [-Confirm] [-WhatIf] [<CommonParameters>]
Suspend-Job [-State] {NotStarted | Running | Completed | Failed | Stopped | Blocked | Suspended | Disconnected | Suspending | Stopping | AtBreakpoint} [-Force] [-Wait]
[-Confirm] [-WhatIf] [<CommonParameters>]
Suspend-Job [-InstanceId] <Guid[]> [-Force] [-Wait] [-Confirm] [-WhatIf] [<CommonParameters>]
Suspend-Job [-Job] <Job[]> [-Force] [-Wait] [-Confirm] [-WhatIf] [<CommonParameters>]
Suspend-Job [-Name] <String[]> [-Force] [-Wait] [-Confirm] [-WhatIf] [<CommonParameters>]



Search powershellhelp.space

DESCRIPTION


The Suspend-Job cmdlet suspends (temporarily interrupts or pauses) workflow jobs. This cmdlet allows users who are running workflows to suspend the workflow. It complements
the Suspend-Workflow activity, which is a command in the workflow that suspends the workflow.


The Suspend-Job cmdlet works only on workflow jobs. It does not work on standard background jobs, such as those that are started by using the Start-Job cmdlet.


To identify a workflow job, look for a value of PSWorkflowJob in the PSJobTypeName property of the job. To determine whether a particular custom job type supports the
Suspend-Job cmdlet, see the help topics for the custom job type.


When you suspend a workflow job, the workflow job runs to the next checkpoint, suspends, and immediately returns a workflow job object. To wait for the suspension to
complete before getting the job, use the Wait parameter of Suspend-Job or the Wait-Job cmdlet. When the workflow job is suspended, the value of the State property of the job
is Suspended.


Suspending correctly relies on checkpoints. The current job state, metadata, and output are saved in the checkpoint so the workflow job can be resumed without any loss of
state or data. If the workflow job does not have checkpoints, it cannot be suspended properly. To add checkpoints to a workflow that you are running, use the PSPersist
workflow common parameter. You can use the Force parameter to suspend any workflow job immediately and to suspend a workflow job that does not have checkpoints, but the
action might cause loss of state and data.


NOTE: Before using a Job cmdlet on a custom job type, such as a workflow job (PSWorkflowJob) import the module that supports the custom job type, either by using the
Import-Module cmdlet or using or using a cmdlet in the module.


This cmdlet is introduced in Windows PowerShell 3.0.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/p/?linkid=289617
Get-Job
Receive-Job
Remove-Job
Resume-Job
Start-Job
Stop-Job
Suspend-Job
Wait-Job

REMARKS

<

Examples


Example 1: Suspend a workflow job by name

The first command creates the Get-SystemLog workflow. The workflow uses the CheckPoint-Workflow activity to define a checkpoint in the workflow.
#Sample Workflow
Workflow Get-SystemLog
{
$Events = Get-WinEvent -LogName System
CheckPoint-Workflow
InlineScript {\\Server01\Scripts\Analyze-SystemEvents.ps1 -Events $Events}
}

The second command uses the AsJob parameter that is common to all workflows to run the Get-SystemLog workflow as a background job. The command uses the JobName workflow
common parameter to specify a friendly name for the workflow job.
PS C:\>Get-SystemLog -AsJob -JobName Get-SystemLogJob

The third command uses the Get-Job cmdlet to get the Get-SystemLogJob workflow job. The output shows that the value of the PSJobTypeName property is PSWorkflowJob.
PS C:\>Get-Job -Name Get-SystemLogJob
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
4 Get-SystemLogJob PSWorkflowJob Running True localhost Get-SystemLog

The fourth command uses the Suspend-Job cmdlet to suspend the Get-SystemLogJob job. The job runs to the checkpoint and then suspends.
PS C:\>Suspend-Job -Name Get-SystemLogJob
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
4 Get-SystemLogJob PSWorkflowJob Suspended True localhost Get-SystemLog



This example shows how to suspend a workflow job.






Example 2: Suspend and resume a workflow job

The first command suspends the LogWorkflowJob job.The command returns immediately. The output shows that the workflow job is still running, even though it is in the process
of being suspended..
PS C:\>Suspend-Job -Name LogWorkflowJob
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
67 LogflowJob PSWorkflowJob Running True localhost LogWorkflow

The second command uses the Get-Job cmdlet to get the LogWorkflowJob job. The output shows that the workflow job suspended successfully.
PS C:\>Get-Job -Name LogWorkflowJob
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
67 LogflowJob PSWorkflowJob Suspended True localhost LogWorkflow

The third command uses the Get-Job cmdlet to get the LogWorkflowJob job and the Resume-Job cmdlet to resume it. The output shows that the workflow job resumed successfully
and is now running.
PS C:\>Get-Job -Name LogWorkflowJob | Resume-Job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
67 LogflowJob PSWorkflowJob Running True localhost LogWorkflow



This example shows how to suspend and resume a workflow job.






Example 3: Suspend a workflow job on a remote computer

PS C:\>Invoke-Command -ComputerName Srv01 -Scriptblock {Suspend-Job -Filter @{CustomID="031589"}



This command uses the Invoke-Command cmdlet to suspend a workflow job on the Srv01 remote computer. The value of the Filters parameter is a hash table that specifies a
CustomID value. This CustomID is job metadata (PSPrivateMetadata).






Example 4: Wait for the workflow job to suspend

PS C:\>Suspend-Job VersionCheck -Wait
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
5 VersionCheck PSWorkflowJob Suspended True localhost LogWorkflow



This command suspends the VersionCheck workflow job. The command uses the Wait parameter to wait until the workflow job is suspended. When the workflow job runs to the next
checkpoint and is suspended, the command completes and returns the job object.






Example 5: Force a workflow job to suspend

PS C:\>Suspend-Job Maintenance -Force



This command suspends the Maintenance workflow job forcibly. The Maintenance job does not have checkpoints, so it cannot be suspended correctly and might not resume properly.