Table of Contents

Interface IJobExecutionContext

Namespace
Quartz
Assembly
Quartz.dll

A context bundle containing handles to various environment information, that is given to a JobDetail instance as it is executed, and to a ITrigger instance after the execution completes.

public interface IJobExecutionContext
Extension Methods

Properties

Calendar

Get a handle to the ICalendar referenced by the ITrigger instance that fired the IJob.

ICalendar? Calendar { get; }

Property Value

ICalendar

CancellationToken

Returns the cancellation token which will be cancelled when the job cancellation has been requested via Interrupt(JobKey, CancellationToken) or InterruptFireInstance(string, CancellationToken).

CancellationToken CancellationToken { get; }

Property Value

CancellationToken

FireInstanceId

Get the unique Id that identifies this particular firing instance of the trigger that triggered this job execution. It is unique to this JobExecutionContext instance as well.

string FireInstanceId { get; }

Property Value

string

the unique fire instance id

See Also

FireTimeUtc

The actual time the trigger fired. For instance the scheduled time may have been 10:00:00 but the actual fire time may have been 10:00:03 if the scheduler was too busy.

DateTimeOffset FireTimeUtc { get; }

Property Value

DateTimeOffset

Returns the fireTimeUtc.

See Also

JobDetail

Get the JobDetail associated with the IJob.

IJobDetail JobDetail { get; }

Property Value

IJobDetail

JobInstance

Get the instance of the IJob that was created for this execution.

Note: The Job instance is not available through remote scheduler interfaces. 

IJob JobInstance { get; }

Property Value

IJob

JobRunTime

How long the job has run for.

TimeSpan JobRunTime { get; }

Property Value

TimeSpan

Remarks

Once the job has completed — or thrown — this is what the scheduler measured, on its TimeProvider, and it is the value IJobListeners and ITriggerListeners see. That is what the member is for.

Read while the job is still running, it is the time since the run began, on the same clock and from the same start, so it grows into the final value: under a fake clock it advances by exactly what the clock was advanced. Before the job is first called — in TriggerFired(ITrigger, IJobExecutionContext, CancellationToken) or JobToBeExecuted(IJobExecutionContext, CancellationToken) — it is Zero. A refired job's run begins again with each attempt, and until it does the value is the previous attempt's measurement.

MergedJobDataMap

Get the convenience JobDataMap of this execution context.

JobDataMap MergedJobDataMap { get; }

Property Value

JobDataMap

Remarks

The JobDataMap found on this object serves as a convenience - it is a merge of the JobDataMap found on the JobDetail and the one found on the ITrigger, with the value in the latter overriding any same-named values in the former. It is thus considered a 'best practice' that the Execute code of a Job retrieve data from the JobDataMap found on this object.

Writing to it is safe, and it is this firing's own channel. The map is built once per firing by copying the two it merges, so a value put into it is visible to the job, to the rest of the middleware pipeline and to the listeners for as long as the firing lasts, and is seen by nothing else. It is the only per-firing bag there is, and passing something from a middleware to a listener is what it is for.

Nothing written here is persisted. It is a copy: neither the job's nor the trigger's stored data map is touched, and the next firing starts from the stored values again. Data that has to outlive the firing goes into JobDetail.JobDataMap on a job marked PersistJobDataAfterExecutionAttribute, which is what a job store writes back.

NextFireTimeUtc

Gets the next fire time.

DateTimeOffset? NextFireTimeUtc { get; }

Property Value

DateTimeOffset?

The next fire time.

Outcome

How this firing ended, as the scheduler classified it — the same value the job store is told on Outcome.

ExecutionOutcome Outcome { get; }

Property Value

ExecutionOutcome

Remarks

Written by the scheduler once the job has finished and before the completion notifications go out, so JobWasExecuted(IJobExecutionContext, JobExecutionException?, CancellationToken) and TriggerComplete(ITrigger, IJobExecutionContext, SchedulerInstruction, CancellationToken) read what actually happened. A vetoed firing is settled before JobExecutionVetoed(IJobExecutionContext, CancellationToken), which reads Vetoed. A listener asking earlier — or a context built by hand — is answered Succeeded, because nothing has gone wrong yet.

It says what the firing did and nothing about what the schedule makes of it: a job that ran and threw is Failed whether or not its RetryPolicy then asked for another attempt. RetryScheduled is what tells those two apart.

A default interface member, so an IJobExecutionContext implemented outside this repository compiles unchanged.

PreviousFireTimeUtc

Gets the previous fire time.

DateTimeOffset? PreviousFireTimeUtc { get; }

Property Value

DateTimeOffset?

The previous fire time.

Recovering

If the IJob is being re-executed because of a 'recovery' situation, this method will return true.

bool Recovering { get; }

Property Value

bool

RecoveringTriggerKey

Returns the TriggerKey of the originally scheduled and now recovering job.

TriggerKey? RecoveringTriggerKey { get; }

Property Value

TriggerKey

Remarks

When recovering a previously failed job execution this property returns the identity of the originally firing trigger. This recovering job will have been scheduled for the same firing time as the original job, and so is available via the ScheduledFireTimeUtc property. The original firing time of the job can be accessed via the FailedJobOriginalTriggerFireTime element of this job's JobDataMap.

RefireCount

Gets the refire count.

int RefireCount { get; }

Property Value

int

The refire count.

Result

Returns the result (if any) that the IJob set before its execution completed (the type of object set as the result is entirely up to the particular job).

object? Result { get; set; }

Property Value

object

Remarks

The result itself is meaningless to Quartz, but may be informative to IJobListeners or ITriggerListeners that are watching the job's execution.

Set the result (if any) of the IJob's execution (the type of object set as the result is entirely up to the particular job).

The result itself is meaningless to Quartz, but may be informative to IJobListeners or ITriggerListeners that are watching the job's execution.

It stays object: a job writes it and a listener reads it, and the two agree on the type between themselves. Quartz cannot name that type without making IJobExecutionContext generic, which would type the whole scheduling API for the sake of a value it never looks at.

RetryAttempt

How many times this occurrence has already been retried under its RetryPolicy: 0 on a regular fire, n on the n-th retry.

int RetryAttempt { get; }

Property Value

int

Remarks

Distinct from RefireCount, which counts iterations of the in-process refire loop within a single firing — same context, same thread, nothing persisted. A retry is a fresh firing at a later instant, recorded in the job store, and it releases the execution slot while it waits.

0 for every firing with no retry policy, which is the default.

See Also

RetryPolicy

The policy a failure of this firing is retried under, or null when a failure is not retried.

RetryPolicy? RetryPolicy { get; }

Property Value

RetryPolicy

Remarks

For a trigger derived from TriggerBase, which every built-in trigger is, the first of three, in order: the trigger's own RetryPolicy, the job type's RetryPolicyAttribute, and the scheduler's default. Whichever is found first decides, and None found at any level means no retry, so this never answers None. It is looked up when it is read rather than stored on the trigger, so a trigger stored before a job type or a scheduler declared a policy is covered by it.

The inherited policies are applied by TriggerBase.ExecutionComplete. Any other IOperableTrigger is answered with its own policy alone, and a TriggerBase subclass that overrides ExecutionComplete without calling the base is answered as though it applied them, though it does not.

Its MaxAttempts beside RetryAttempt says how many attempts an occurrence has left.

A default interface member, so an IJobExecutionContext implemented outside this repository compiles unchanged. The default answers with the trigger's own policy only.

See Also

RetryScheduled

Whether the trigger answered this firing's failure with another attempt, so the occurrence is not finished.

bool RetryScheduled { get; }

Property Value

bool

Remarks

true exactly when the scheduler decided RetryTrigger: the job failed, a RetryPolicy applies, it has attempts left, and there was room for the retry before the next scheduled occurrence. A failed firing with false here is the occurrence's last word — that is what TriggerRetriesExhausted(ITrigger, IJobExecutionContext, JobExecutionException, CancellationToken) announces.

Set beside Outcome and read in the same places. Never true on a firing that succeeded.

A default interface member, so an IJobExecutionContext implemented outside this repository compiles unchanged.

ScheduledFireTimeUtc

The scheduled time the trigger fired for. For instance the scheduled time may have been 10:00:00 but the actual fire time may have been 10:00:03 if the scheduler was too busy.

DateTimeOffset? ScheduledFireTimeUtc { get; }

Property Value

DateTimeOffset?

Returns the scheduledFireTimeUtc.

See Also

Scheduler

Get a handle to the IScheduler instance that fired the IJob.

IScheduler Scheduler { get; }

Property Value

IScheduler

Trigger

Get a handle to the ITrigger instance that fired the IJob.

ITrigger Trigger { get; }

Property Value

ITrigger

Methods

ReportProgress(int, string?)

Says how far the job has got, so that QueryFireInstances(FireInstanceQuery, CancellationToken) — and the dashboard's Currently Executing page, on every node of a cluster — can show it.

void ReportProgress(int percent, string? message = null)

Parameters

percent int

How far the job has got, from 0 to 100.

message string

What to show beside it, or null for nothing.

Remarks

Call it as often as is convenient: it returns at once and never waits on the job store or a listener. The scheduler keeps the latest value and writes it to the store at most once a second per firing, only when it has changed, and off the job's own flow. While the job runs, the last value reported is always the one written, however quickly the reports came. A write that fails is logged, and the job carries on.

Each write is announced to the job listeners through JobProgressChanged(IJobExecutionContext, FireInstanceProgress, CancellationToken), and a last report they have not heard is announced once the job returns, before JobWasExecuted(IJobExecutionContext, JobExecutionException?, CancellationToken).

A message longer than MaxMessageLength characters is cut to that length. The value lives as long as the firing does: it is gone once the job completes, and a retry or a recovered firing starts with none.

A default interface member, so an IJobExecutionContext implemented outside this repository compiles unchanged. The default does nothing.

Exceptions

ArgumentOutOfRangeException

percent is below 0 or above 100.

Edit this page