Suspend-Job

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

Suspend-Job
    [-Job] <Job[]>
    [-Force]
    [-Wait]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

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

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

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

Suspend-Job
    [-State] <JobState>
    [-Force]
    [-Wait]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

The Suspend-Job cmdlet suspends workflow jobs. Suspend means to temporarily interrupt or pause a workflow job. This cmdlet allows users who are running workflows to suspend the workflow. It complements the Suspend-Workflowhttps://go.microsoft.com/fwlink/?LinkId=267141 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 loss of state or data. If the workflow job does not have checkpoints, it cannot be suspended correctly. 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 could cause loss of state and data.

Before you use 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 was introduced in Windows PowerShell 3.0.

This example shows how to suspend a workflow job.

The first command creates the Get-SystemLog workflow. The workflow uses the CheckPoint-Workflow activity to define a checkpoint in the workflow.

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.

The third command uses the Get-Job cmdlet to get the LogflowJob workflow job. The output shows that the value of the PSJobTypeName property is PSWorkflowJob.

The fourth command uses the Suspend-Job cmdlet to suspend the LogflowJob job. The job runs to the checkpoint and then suspends.

#Sample Workflow
workflow Get-SystemLog
{
    $Events = Get-WinEvent -LogName System
    CheckPoint-Workflow
    inlinescript {\\Server01\Scripts\Analyze-SystemEvents.ps1 -Events $Events}
}
Get-SystemLog -AsJob -JobName "LogflowJob"
Get-Job -Name LogflowJob

Id   Name          PSJobTypeName   State       HasMoreData     Location   Command
--   ----          -------------   -----       -----------     --------   -------
4    LogflowJob    PSWorkflowJob   Running     True            localhost   Get-SystemLog

Suspend-Job -Name LogflowJob

Id   Name          PSJobTypeName   State       HasMoreData     Location   Command
--   ----          -------------   -----       -----------     --------   -------
4    LogflowJob    PSWorkflowJob   Suspended   True            localhost   Get-SystemLog

This example shows how to 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 being suspended.

The second command uses the Get-Job cmdlet to get the LogWorkflowJob job. The output shows that the workflow job suspended successfully.

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.

Suspend-Job -Name LogWorkflowJob

Id   Name          PSJobTypeName      State         HasMoreData     Location      Command
--   ----          -------------      -----         -----------     --------      -------
67   LogflowJob    PSWorkflowJob      Running       True            localhost     LogWorkflow

Get-Job -Name LogWorkflowJob

Id   Name          PSJobTypeName      State         HasMoreData     Location      Command
--   ----          -------------      -----         -----------     --------      -------
67   LogflowJob    PSWorkflowJob      Suspended     True            localhost     LogWorkflow

Get-Job -Name LogWorkflowJob | Resume-Job

Id     Name          PSJobTypeName      State       HasMoreData     Location      Command
--     ----          -------------      -----       -----------     --------      -------
67     LogflowJob    PSWorkflowJob      Running     True            localhost     LogWorkflow

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 Filter parameter is a hash table that specifies a CustomID value. This CustomID is job metadata (PSPrivateMetadata).

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 finishes and returns the job object.

Suspend-Job Maintenance -Force

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

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

You can pipe all types of jobs to this cmdlet. However, if Suspend-Job gets a job of an unsupported type, it returns a terminating error.

This cmdlet returns the jobs that it suspended.

Windows PowerShell includes the following aliases for Suspend-Job:

• sujb

The mechanism and ___location for saving a suspended job might vary depending on the job type. For example, suspended workflow jobs are saved in a flat file store by default, but can also be saved in a database.

If you submit a workflow job that is not in the Running state, Suspend-Job displays a warning message. To suppress the warning, use the WarningAction common parameter with a value of SilentlyContinue.

If a job is not of a type that supports suspending, Suspend-Job returns a terminating error.

To find the workflow jobs that are suspended, including those that were suspended by this cmdlet, use the State parameter of the Get-Job cmdlet to get workflow jobs in the Suspended state.

Some job types have options or properties that prevent Windows PowerShell from suspending the job. If attempts to suspend the job fail, verify that the job options and properties allow for suspending.