Interface ITrigger
- Namespace
- Quartz
- Assembly
- Quartz.dll
The base interface with properties common to all ITriggers - use TriggerBuilder to instantiate an actual Trigger.
public interface ITriggerRemarks
Quartz owns the implementations of this interface. Build triggers with
TriggerBuilder (or the DI configuration equivalents); a custom trigger type
derives from TriggerBase, which implements the mutable and operational contracts
the scheduler and the job stores rely on. An object that implements only
ITrigger is a read model — handing one to the scheduler is rejected with a
clear error rather than scheduled.
ITriggers have a TriggerKey associated with them, which should uniquely identify them within a single IScheduler.
ITriggers are the 'mechanism' by which IJob s are scheduled. Many ITrigger s can point to the same IJob, but a single ITrigger can only point to one IJob.
Triggers can 'send' parameters/data to IJobs by placing contents into the JobDataMap on the ITrigger.
Properties
CalendarName
Get or set the ICalendar with the given name with this Trigger. Use null when setting to dis-associate a Calendar.
string? CalendarName { get; }Property Value
Remarks
A blank name means no calendar: the built-in trigger implementations store an empty or whitespace-only name as null, because a name no calendar can be found under would otherwise stop the trigger from ever firing.
Description
Get or set the description given to the ITrigger instance by its creator (if any).
string? Description { get; }Property Value
EndTimeUtc
Gets and sets the date/time on which the trigger must stop firing. This defines the final boundary for trigger firings 舒 the trigger will not fire after this date and time. If this value is null, no end time boundary is assumed, and the trigger can continue indefinitely.
DateTimeOffset? EndTimeUtc { get; }Property Value
Remarks
The end time is inclusive, for every trigger type: it is the last instant at which the trigger may fire, so a fire time exactly equal to it is one the trigger fires, and the first instant after it is where the schedule stops.
ExecutionGroup
Gets the execution group for this trigger. Execution groups allow thread limits to be configured - per node or across the cluster - so that resource-intensive jobs do not saturate all available threads.
string? ExecutionGroup { get; }Property Value
Remarks
A null value means the trigger has no execution group (the default, backward-compatible behavior).
FinalFireTimeUtc
Returns the last UTC time at which the ITrigger will fire, if the Trigger will repeat indefinitely, null will be returned.
Note that the return time *may* be in the past.
DateTimeOffset? FinalFireTimeUtc { get; }Property Value
JobDataMap
Get or set the JobDataMap that is associated with the ITrigger.
Changes made to this map during job execution are not re-persisted, and in fact typically result in an illegal state.
JobDataMap JobDataMap { get; }Property Value
JobKey
The job this trigger fires.
JobKey JobKey { get; }Property Value
Key
The trigger's identity: its name and group, which a store keys it by.
TriggerKey Key { get; }Property Value
MayFireAgain
Used by the IScheduler to determine whether or not it is possible for this ITrigger to fire again.
If the returned value is false then the IScheduler may remove the ITrigger from the IJobStore.
bool MayFireAgain { get; }Property Value
MisfireInstructionCode
The raw code of the instruction the IScheduler follows when this trigger misses a firing. This is the number the job store persists, and it is family-agnostic: the same number means a different policy in each trigger family.
int MisfireInstructionCode { get; }Property Value
Remarks
Read the policy from the family interface's own MisfireInstruction property instead
whenever the family is known — MisfireInstruction,
MisfireInstruction and so on. This member exists for code that
is generic over every family: serializers, the wire contract, logging and diagnostics.
The default is 0, the smart policy: the trigger's family picks the policy for it.
- See Also
NextFireTimeUtc
Returns the next time at which the ITrigger is scheduled to fire. If the trigger will not fire again, null will be returned. Note that the time returned can possibly be in the past, if the time that was computed for the trigger to next fire has already arrived, but the scheduler has not yet been able to fire the trigger (which would likely be due to lack of resources e.g. threads).
DateTimeOffset? NextFireTimeUtc { get; }Property Value
Remarks
The value returned is not guaranteed to be valid until after the ITrigger has been added to the scheduler.
PreferredNode
Which cluster node this trigger prefers to run on. Only that node acquires the trigger, with automatic failover while it is down.
PreferredNode PreferredNode { get; }Property Value
Remarks
None — the default — means the trigger has no node preference.
- See Also
PreviousFireTimeUtc
The previous time at which the ITrigger fired. If the trigger has not yet fired, null will be returned.
DateTimeOffset? PreviousFireTimeUtc { get; }Property Value
Priority
The priority of a ITrigger acts as a tie breaker such that if two ITriggers have the same scheduled fire time, then Quartz will do its best to give the one with the higher priority first access to a worker thread.
int Priority { get; }Property Value
Remarks
If not explicitly set, the default value is 5.
RetryAttempt
How many times the occurrence currently being executed has already been retried. 0 on
a regular fire, n on the n-th retry.
int RetryAttempt { get; }Property Value
Remarks
Reset to 0 as soon as the occurrence succeeds, exhausts its
RetryPolicy, or misfires. Distinct from
RefireCount, which counts iterations of the in-process
refire loop within a single firing.
RetryPolicy
How the scheduler re-fires this trigger when its job fails, or null — the default — when a failed job is simply reported and the trigger waits for its next scheduled occurrence.
RetryPolicy? RetryPolicy { get; }Property Value
Remarks
A retry never displaces the next scheduled occurrence: one that would land at or within a second of it is dropped and the ordinary schedule wins.
This is not RefireImmediately, which re-runs the job on the same thread in the same firing, with no delay, no ceiling and nothing persisted.
- See Also
StartTimeUtc
The time at which the trigger's scheduling should start. May or may not be the first actual fire time of the trigger, depending upon the type of trigger and the settings of the other properties of the trigger. However the first actual first time will not be before this date.
DateTimeOffset StartTimeUtc { get; }Property Value
Remarks
Setting a value in the past may cause a new trigger to compute a first fire time that is in the past, which may cause an immediate misfire of the trigger.
Methods
Clone()
Returns a copy of this trigger.
ITrigger Clone()Returns
Remarks
The copy is shallow, and its job data map is a shallow copy too: the map itself is a new one, so adding and removing entries in the copy leaves this trigger's map alone, but the values in it are the same objects. Mutating a value read out of the copy's JobDataMap therefore mutates this trigger's as well, which is worth knowing before cloning a trigger to edit it. A store clones on the way in and on the way out, so what a caller holds is never the instance the store holds.
GetFireTimeAfter(DateTimeOffset?)
Returns the next time at which the ITrigger will fire, after the given time. If the trigger will not fire after the given time, null will be returned.
DateTimeOffset? GetFireTimeAfter(DateTimeOffset? afterTime)Parameters
afterTimeDateTimeOffset?
Returns
GetScheduleBuilder()
Get a IScheduleBuilder that is configured to produce a schedule identical to this trigger's schedule.
IScheduleBuilder GetScheduleBuilder()Returns
GetTriggerBuilder()
Get a TriggerBuilder that is configured to produce a trigger identical to this one.
TriggerBuilder<IJob> GetTriggerBuilder()Returns
Remarks
An interface member where its twin GetJobBuilder(IJobDetail) is an extension, and the asymmetry is the difference between the two rebuilds rather than an unfinished move. A detail's builder can be filled in from the detail's public state alone, so an extension can write it once for every implementation. A trigger's cannot: the builder has to be created against the trigger's own TimeProvider, so that the rebuilt trigger computes its fire times from the same reading of "now" — and a trigger's clock is not part of this interface, because nothing else has any business reading it.
- See Also