Class JobExecutionContextImpl
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 sealed class JobExecutionContextImpl : IJobExecutionContext, IDisposable- Inheritance
-
JobExecutionContextImpl
- Implements
- Inherited Members
- Extension Methods
Remarks
The JobDataMap found on this object (via the MergedJobDataMap method) 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
That map is this firing's own copy: writing to it is safe and reaches the job, the middleware and the listeners, and none of it is written back to what the job or the trigger has stored.
A context exists only inside the process running the job, and only for as long as it runs. The scheduler does not hand it out: QueryFireInstances(FireInstanceQuery, CancellationToken) lists firings across the cluster as FireInstance projections, which carry keys, times and the owning node but none of the live state below. Code that needs the live state — the job instance, the merged job data, the result, the cancellation handle — gets it from an IJobListener of its own, which is handed the context and can keep it for the duration of the execution.
Constructors
JobExecutionContextImpl(IScheduler, TriggerFiredBundle, IJob, IJobInputSerializer?)
Create a JobExecutionContext with the given context data.
public JobExecutionContextImpl(IScheduler scheduler, TriggerFiredBundle firedBundle, IJob job, IJobInputSerializer? inputSerializer = null)Parameters
schedulerISchedulerThe scheduler this firing belongs to.
firedBundleTriggerFiredBundleWhat the job store handed back when the trigger fired.
jobIJobThe job instance the factory built for this firing.
inputSerializerIJobInputSerializerWhat GetInput<TInput>(IJobExecutionContext) and an IJob<TInput> read a stored input with. Quartz hands the scheduler's own; a context built by hand without one reports a SchedulerException if a job asks it for a stored input, rather than reflecting its way to an answer.
Remarks
JobRunTime counts from here, on System: a context built by hand is built to be handed to the job straight away.
Properties
Calendar
public ICalendar? Calendar { get; }Property Value
CancellationToken
Returns the cancellation token which will be cancelled when the job cancellation has been requested via Interrupt(JobKey, CancellationToken) or InterruptFireInstance(string, CancellationToken).
public CancellationToken CancellationToken { get; }Property Value
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.
public string FireInstanceId { get; }Property Value
- string
the unique fire instance id
Remarks
Never null here, although FireInstanceId is: a context exists only for a firing, and a store writes the id as it hands the trigger over.
- 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.
public DateTimeOffset FireTimeUtc { get; }Property Value
- DateTimeOffset
Returns the fireTimeUtc.
- See Also
JobDetail
public IJobDetail JobDetail { get; }Property Value
JobInstance
Get the instance of the IJob that was created for this execution.
Note: The Job instance is not available through remote scheduler interfaces.
public IJob JobInstance { get; }Property Value
JobRunTime
How long the job has run for.
public TimeSpan JobRunTime { get; }Property Value
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.
public JobDataMap MergedJobDataMap { get; }Property Value
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 JobDataMap on a job marked PersistJobDataAfterExecutionAttribute, which is what a job store writes back.
NextFireTimeUtc
Gets the next fire time.
public 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.
public ExecutionOutcome Outcome { get; }Property Value
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.
public DateTimeOffset? PreviousFireTimeUtc { get; }Property Value
- DateTimeOffset?
The previous fire time.
Recovering
public bool Recovering { get; }Property Value
RecoveringTriggerKey
Returns the TriggerKey of the originally scheduled and now recovering job.
public TriggerKey? RecoveringTriggerKey { get; }Property Value
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.
public int RefireCount { get; }Property Value
- int
The refire count.
Remarks
Written by the run shell as it refires the job, and by WithRefireCount(int) for a context built by hand.
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).
public object? Result { get; set; }Property Value
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.
RetryAttempt
How many times this occurrence has already been retried under its RetryPolicy.
public int RetryAttempt { get; }Property Value
Remarks
Taken from the trigger this firing was handed, which is the copy the job store fired: the store wrote the attempt when it scheduled the retry and read it back when it acquired the trigger, so this is the count as the store has it and not something the run shell keeps.
Copied when the context is built rather than read through the trigger, because
ExecutionComplete writes that field on its way out — advancing it on a firing that is
being retried and zeroing it on one that has settled — and it runs before the listeners are
told. Reading it live left JobWasExecuted(IJobExecutionContext, JobExecutionException?, CancellationToken) and
TriggerComplete(ITrigger, IJobExecutionContext, SchedulerInstruction, CancellationToken) with the attempt that is about to be made, or
with nothing at all, rather than with the attempt the job just made.
RetryPolicy
The policy a failure of this firing is retried under, or null when a failure is not retried.
public RetryPolicy? RetryPolicy { get; }Property Value
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.
public bool RetryScheduled { get; }Property Value
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.
public DateTimeOffset? ScheduledFireTimeUtc { get; }Property Value
- DateTimeOffset?
Returns the scheduledFireTimeUtc.
- See Also
Scheduler
Get a handle to the IScheduler instance that fired the IJob.
public IScheduler Scheduler { get; }Property Value
Trigger
public ITrigger Trigger { get; }Property Value
Methods
Dispose()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
public void Dispose()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.
public void ReportProgress(int percent, string? message = null)Parameters
percentintHow far the job has got, from
0to100.messagestringWhat 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
percentis below0or above100.
ToString()
public override string ToString()