Struct OneOffJobOptions
- Namespace
- Quartz
- Assembly
- Quartz.dll
What the one-call ScheduleJob<TJob, TInput> overloads may be told about the single
firing they arrange, past the payload and the time.
public readonly record struct OneOffJobOptions : IEquatable<OneOffJobOptions>- Implements
- Inherited Members
Remarks
Every member is optional and every default is the one the equivalent builder call would have produced, so default — what omitting the argument gives — is "a one-shot trigger with a generated name, in this job type's own group".
Named for what the call creates rather than for the call: one off, one firing, one trigger. An overload that schedules a recurring job would say something else — a schedule, an end time, a calendar — and gets an options type of its own rather than nullable members here that mean nothing to this one.
It is not ScheduleJobOptions, whose one member says whether a store may over-write what it already holds. That one describes a store operation and is what ScheduleJob(ITrigger, ScheduleJobOptions, CancellationToken) takes; this one describes the trigger the one-liner builds, and carries Replace so that it can pass it on.
Properties
Description
The trigger's description.
public string? Description { get; init; }Property Value
ExecutionGroup
The execution group the firing counts against, when execution limits are in use. Defaults to the job type's ExecutionGroupAttribute, when that names a group without placeholders.
public string? ExecutionGroup { get; init; }Property Value
Remarks
A name, stored as written: braces are not placeholders here. A per-tenant firing says the tenant
at the call site, ExecutionGroup = $"tenant:{input.TenantId}", which is also what a job
type whose attribute has placeholders requires.
- See Also
Group
The trigger's group. Defaults to the job type's name.
public string? Group { get; init; }Property Value
Remarks
The group is the correlation axis: everything scheduled for one saga, one tenant or one conversation can share a group and be listed, paused or unscheduled together.
The default is a group of the job type's name rather than DefaultGroup,
which matters to anything that already has a trigger-key contract of its own: a caller that
cancels with new TriggerKey(id) is naming the default group, so scheduling through these
overloads without saying Group = TriggerKey.DefaultGroup puts the trigger somewhere that
cancellation silently stops matching. Name the group the contract expects, and the two agree.
MisfireInstruction
What to do when the scheduler was not running at the moment the firing was due. Defaults to SmartPolicy, which for a one-shot trigger means fire as soon as the scheduler is back.
public SimpleTriggerMisfireInstruction? MisfireInstruction { get; init; }Property Value
Name
The trigger's name. Defaults to a generated identifier, so two calls never collide by accident; give one when the firing has an identity of its own — a message id, a saga step — and it becomes the handle to UnscheduleJob(TriggerKey, CancellationToken) or to replace with.
public string? Name { get; init; }Property Value
Remarks
A name and a group rather than a TriggerKey, which is what every other place
that identifies a trigger takes. The two halves have different defaults — a generated name, a
group named after the job type — and each is worth setting without the other: "call it
order-42, wherever such firings go" and "put it in this saga's group, any name will
do" are both ordinary, and a key can express neither. The key exists once the trigger does,
and the call answers with it as TriggerKey.
OnConflict
What becomes of a firing already scheduled under the same Name. Defaults to Throw: the call throws ObjectAlreadyExistsException.
public TriggerConflict OnConflict { get; init; }Property Value
Remarks
| Replace | The new firing replaces the old one: a debounce, since only the last call fires. |
| Keep | A pending firing is left alone and its key returned: an idempotent enqueue. |
| KeepEarlier | Whichever fires first stays. |
The store decides under its lock, so two calls with one name store one firing, and
Outcome tells each call which it got. A firing already running
has nothing pending, so a Keep call stores a new one after it. Like
Replace, only meaningful with a Name.
Priority
The trigger's priority, which breaks ties when more triggers are due at once than the thread pool can run. Defaults to DefaultPriority.
public int? Priority { get; init; }Property Value
- int?
Replace
Whether a trigger already stored under the same key is over-written rather than reported as a
conflict. Scheduling over an existing trigger is then one store operation under one lock — no
CheckExists / UnscheduleJob / ScheduleJob for the caller to serialize.
public bool Replace { get; init; }Property Value
Remarks
The older spelling of OnConflict = TriggerConflict.Replace, and it reads
true when either says so. Setting it beside an OnConflict that
says something else is refused by the one-liner with ArgumentException.
Only meaningful together with Name: a generated name has nothing to replace, which is why the preset that sets this is Replacing(string) and takes the name.
RequestRecovery
Whether the durable job the firings hang off is marked RequestsRecovery, so that a firing interrupted by a hard shutdown is re-executed when the scheduler comes back. Defaults to false, which is JobBuilder's own default.
public bool RequestRecovery { get; init; }Property Value
Remarks
The one member here that describes the job rather than the trigger, because the job is the one thing the one-liner builds that a caller cannot otherwise reach — and recovery is a property of it, not of a firing.
The job is ensured once per scheduler instance, so the first call's value wins for the process's lifetime: a later call asking for something else finds the job already there and does not store it again. That is how the memo already treats every other aspect of the job — its description, its durability, the type it names — and it is why this is a named boolean rather than a configuration delegate, which would look as though it varied per call.
A process that has to change it restarts, or deletes the job ScheduledJobKey<TJob>() names — the next call finds it gone and stores it afresh with whatever that call asked for.
Methods
Replacing(string)
Schedule the firing under the given name, over-writing one already scheduled under it. The
name for new OneOffJobOptions { Name = name, OnConflict = TriggerConflict.Replace }, which is what
rescheduling a firing an application can name — a reminder, a saga step, a timeout — always
says.
public static OneOffJobOptions Replacing(string name)Parameters
namestringThe trigger's name, which is also the handle to cancel or replace it by.
Returns
Remarks
A preset rather than a bare Replacing, unlike Replacing and
its siblings, because Replace alone would do nothing here: without a name the
trigger gets a generated one, and a generated name has nothing to replace. The name is the
whole of what makes replacing meaningful, so it is a parameter rather than something to
remember to set afterwards.