Export (0) Print
Expand All

Suspend-Job

Published: February 29, 2012

Updated: September 27, 2012

Applies To: Windows PowerShell 3.0

Suspend-Job

Temporarily stops workflow jobs.

Aliases

The following abbreviations are aliases for this cmdlet:

  • sujb

Syntax

Parameter Set: SessionIdParameterSet
Suspend-Job [-Id] <Int32[]> [-Force] [-Wait] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: FilterParameterSet
Suspend-Job [-Filter] <Hashtable> [-Force] [-Wait] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: InstanceIdParameterSet
Suspend-Job [-InstanceId] <Guid[]> [-Force] [-Wait] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: JobParameterSet
Suspend-Job [-Job] <Job[]> [-Force] [-Wait] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: NameParameterSet
Suspend-Job [-Name] <String[]> [-Force] [-Wait] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: StateParameterSet
Suspend-Job [-State] <JobState> [-Force] [-Wait] [-Confirm] [-WhatIf] [ <CommonParameters>]




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

Parameters

-Filter<Hashtable>

Suspends only workflow jobs that satisfy all of the conditions established in the associated hash table. Enter a hash table where the keys are workflow job properties and the values are workflow job property values.


Aliases

none

Required?

true

Position?

1

Default Value

None

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-Force

Suspends the workflow job immediately. This action might cause a loss of state and data.

By default, Suspend-Job lets the workflow job run until the next checkpoint and then suspends it. You can also use this parameter to suspend workflow jobs that do not have checkpoints.


Aliases

F

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Id<Int32[]>

Suspends the workflow 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 to type than the instance ID, but it is unique only within the current session. You can type one or more IDs (separated by commas). To find the ID of a job, use the Get-Job cmdlet.


Aliases

none

Required?

true

Position?

1

Default Value

None

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-InstanceId<Guid[]>

Suspends workflow 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, use the Get-Job cmdlet.


Aliases

none

Required?

true

Position?

1

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-Job<Job[]>

Specifies the workflow jobs to be suspended. Enter a variable that contains the workflow jobs or a command that gets the workflow jobs. You can also pipe workflow jobs to the Suspend-Job cmdlet.


Aliases

none

Required?

true

Position?

1

Default Value

None

Accept Pipeline Input?

True (ByValue, ByPropertyName)

Accept Wildcard Characters?

false

-Name<String[]>

Suspends workflow jobs with the specified friendly names. Enter one or more workflow job names. Wildcards are supported.


Aliases

none

Required?

true

Position?

1

Default Value

None

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-State<JobState>

Suspends only those workflow jobs in the specified state. Valid values are NotStarted, Running, Completed, Failed, Stopped, Blocked, Suspended, Disconnected, Suspending, Stopping but Suspend-Job suspends only workflow jobs in the Running state.

For more information about job states, see "JobState Enumeration" in MSDN at http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.jobstate(v=vs.85).aspx


Aliases

none

Required?

true

Position?

1

Default Value

None

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-Wait

Returns only after the workflow job is in the suspended state. By default, Suspend-Job suspends immediately, even if the workflow job is not yet in the suspended state.

The Wait parameter is equivalent to piping a Suspend-Job command to the Wait-Job cmdlet.


Aliases

none

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Confirm

Prompts you for confirmation before running the cmdlet.


Required?

false

Position?

named

Default Value

false

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.


Required?

false

Position?

named

Default Value

false

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see  about_CommonParameters (http://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

  • System.Management.Automation.Job

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


Outputs

The output type is the type of the objects that the cmdlet emits.

  • System.Management.Automation.Job

    Suspend-Job returns the jobs that it suspended.


Notes

  • 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 throw 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 suspending.

Examples

Example 1: Suspend a workflow job by name

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.


#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

Example 2: Suspend and resume a workflow job

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

Example 3: Suspend a workflow job on a remote computer

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


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

Example 4: Wait for the workflow job to suspend

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.


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

Example 5: Force a workflow job to suspend

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.


PS C:\> Suspend-Job Maintenance -Force

Related topics



Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft