Table of Contents

Interface IScheduler

Namespace
Quartz
Assembly
Quartz.dll

This is the main interface of a Quartz Scheduler.

public interface IScheduler : IAsyncDisposable
Inherited Members
Extension Methods

Remarks

A IScheduler maintains a registry of IJobDetails and ITriggers. Once registered, the IScheduler is responsible for executing IJob s when their associated ITrigger s fire (when their scheduled time arrives).

IScheduler instances are produced by a ISchedulerFactory. A scheduler that has already been created/initialized can be found and used through the same factory that produced it. After a IScheduler has been created, it is in "stand-by" mode, and must have its Start(CancellationToken) method called before it will fire any IJobs.

IJob s are to be created by the 'client program', by defining a class that implements the IJob interface. IJobDetail objects are then created (also by the client) to define a individual instances of the IJob. IJobDetail instances can then be registered with the IScheduler via ScheduleJob(IJobDetail, ITrigger, ScheduleJobOptions, CancellationToken) or AddJob(IJobDetail, AddJobOptions, CancellationToken).

ITrigger s can then be defined to fire individual IJob instances based on given schedules. ISimpleTrigger s are most useful for one-time firings, or firing at an exact moment in time, with N repeats with a given delay between them. ICronTrigger s allow scheduling based on time of day, day of week, day of month, and month of year.

IJob s and ITrigger s have a name and group associated with them, which should uniquely identify them within a single IScheduler. The 'group' feature may be useful for creating logical groupings or categorizations of IJobs and ITriggers. If you don't have need for assigning a group to a given IJobs of ITriggers, then you can use the DefaultGroup constant, which is what a JobKey or TriggerKey built without a group already uses.

Stored IJob s can also be 'manually' triggered through the use of TriggerJob(JobKey, JobDataMap?, CancellationToken).

Client programs may also be interested in the 'listener' interfaces that are available from Quartz. The IJobListener interface provides notifications of IJob executions. The ITriggerListener interface provides notifications of ITrigger firings. The ISchedulerListener interface provides notifications of IScheduler events and errors. Listeners can be associated with local schedulers through the IListenerManager interface.

The setup/configuration of a IScheduler instance is very customizable. Please consult the documentation distributed with Quartz.

Disposing an instance releases what that instance owns, and the rule is ownership rather than convention. A local scheduler owns the execution it drives, so disposing it is Shutdown(bool, CancellationToken) with waitForJobsToComplete: false — the scheduler cannot be restarted afterwards, and disposing one that is already shut down does nothing. Call Shutdown(waitForJobsToComplete: true) yourself first when running jobs should be allowed to finish; await using is the shape for "stop this when the block ends", not for a graceful drain.

A proxy for a scheduler in another process — HttpScheduler — owns only the connection to it. Disposing one releases that and never shuts the remote scheduler down: a client leaving is not an instruction to stop scheduling for everybody else.

Properties

Context

Returns the SchedulerContext of the IScheduler.

SchedulerContext Context { get; }

Property Value

SchedulerContext

ListenerManager

Get a reference to the scheduler's IListenerManager, through which listeners may be registered.

IListenerManager ListenerManager { get; }

Property Value

IListenerManager

the scheduler's IListenerManager

See Also

SchedulerInstanceId

Returns the instance Id of the IScheduler.

string SchedulerInstanceId { get; }

Property Value

string

SchedulerName

Returns the name of the IScheduler.

string SchedulerName { get; }

Property Value

string

Status

Where the IScheduler is in its lifecycle.

SchedulerStatus Status { get; }

Property Value

SchedulerStatus

Remarks

The value is an 'instantaneous' snapshot: by the time it is read, the scheduler may already have moved on. A scheduler in another process answers this over the network.

See Also

TimeProvider

The clock this scheduler reads: what it calls "now" when it decides a trigger is due, and what a trigger built for it should compute its fire times from.

TimeProvider TimeProvider { get; }

Property Value

TimeProvider

Remarks

A scheduler configured with a TimeProvider of its own — a test driving one forward by hand, an application on a clock it controls — answers with that one. Code that builds a trigger for a scheduler should read the clock from the scheduler rather than reach for System, or it computes "in ten minutes" against a different clock from the one the scheduling loop will compare the answer to. That includes a job rescheduling itself from inside Execute, which reads context.Scheduler.TimeProvider.

A default implementation answers System, so a scheduler written outside this repository needs no change and reports what its triggers would have used anyway. A proxy for a scheduler in another process answers the same, and cannot do better: the clock that matters is the remote scheduler's, and it is not this process's to read.

Methods

AddCalendar(string, ICalendar, AddCalendarOptions, CancellationToken)

Add (register) the given ICalendar to the Scheduler.

ValueTask AddCalendar(string calendarName, ICalendar calendar, AddCalendarOptions options = default, CancellationToken cancellationToken = default)

Parameters

calendarName string

Name of the calendar.

calendar ICalendar

The calendar.

options AddCalendarOptions

Whether an already registered calendar of the same name may be over-written, and whether the triggers that reference it have their next fire time re-computed. Defaults to neither.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask

Exceptions

ArgumentNullException

calendarName or calendar is null.

SchedulerException

The scheduler has been shut down.

ObjectAlreadyExistsException

A calendar is already registered under the same name and Replace was not asked for.

AddJob(IJobDetail, AddJobOptions, CancellationToken)

Add the given IJob to the Scheduler - with no associated ITrigger. The IJob will be 'dormant' until it is scheduled with a ITrigger, or TriggerJob(JobKey, JobDataMap?, CancellationToken) is called for it.

ValueTask AddJob(IJobDetail jobDetail, AddJobOptions options = default, CancellationToken cancellationToken = default)

Parameters

jobDetail IJobDetail

The job to store.

options AddJobOptions

Whether an already stored job of the same key may be over-written, and whether a non-durable job may be stored while it awaits a trigger. Defaults to neither.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask

Remarks

The IJob must by definition be 'durable', unless StoreNonDurableWhileAwaitingScheduling is set; if it is neither, a SchedulerException is thrown.

Exceptions

ArgumentNullException

jobDetail is null.

SchedulerException

The scheduler has been shut down; or the job is not durable and StoreNonDurableWhileAwaitingScheduling was not asked for.

ObjectAlreadyExistsException

A job is already stored under the same key and Replace was not asked for.

Clear(CancellationToken)

Clears (deletes!) all scheduling data - all IJobs, ITriggers ICalendars.

ValueTask Clear(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask

Exceptions

SchedulerException

The scheduler has been shut down.

DeleteCalendar(string, CancellationToken)

Delete the identified ICalendar from the Scheduler.

ValueTask<bool> DeleteCalendar(string calendarName, CancellationToken cancellationToken = default)

Parameters

calendarName string

Name of the calendar.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<bool>

true if the Calendar was found and deleted.

Remarks

If removal of the 

Calendar

would result in ITriggers pointing to non-existent calendars, then a SchedulerException will be thrown.

Exceptions

ArgumentNullException

calendarName is null.

SchedulerException

The scheduler has been shut down.

JobPersistenceException

A trigger still references the calendar, so removing it would leave that trigger pointing at nothing.

DeleteJob(JobKey, CancellationToken)

Delete the identified IJob from the Scheduler - and any associated ITriggers.

ValueTask<bool> DeleteJob(JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

jobKey JobKey
cancellationToken CancellationToken

Returns

ValueTask<bool>

true if the Job was found and deleted.

Exceptions

ArgumentNullException

jobKey is null.

SchedulerException

The scheduler has been shut down.

DeleteJobs(GroupMatcher<JobKey>, CancellationToken)

Delete every IJobDetail in the matching groups from the Scheduler - and any associated ITriggers.

ValueTask<List<JobKey>> DeleteJobs(GroupMatcher<JobKey> matcher, CancellationToken cancellationToken = default)

Parameters

matcher GroupMatcher<JobKey>

Selects the job groups to empty. Required — there is no "delete the default group" reading of null worth risking on a destructive call.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<List<JobKey>>

The keys of the jobs this call deleted.

Remarks

The group is the correlation axis: everything belonging to one tenant, one saga or one import shares a job group, and this is how the whole of it goes in one call rather than one round trip per key — and without first listing the keys, which is a window in which another node can add one more.

Unlike PauseJobGroups(GroupMatcher<JobKey>, CancellationToken), nothing is remembered about the groups: a delete has no state to impose on a job added afterwards.

One JobDeleted(IScheduler, JobKey, CancellationToken) is raised per deleted key, and the scheduling change is signalled once for the whole call. A matcher that matched nothing raises nothing.

Exceptions

ArgumentNullException

matcher is null.

SchedulerException

The scheduler has been shut down.

See Also

DeleteJobs(IReadOnlyCollection<JobKey>, CancellationToken)

Delete the identified jobs from the Scheduler - and any associated ITriggers.

ValueTask<List<JobKey>> DeleteJobs(IReadOnlyCollection<JobKey> jobKeys, CancellationToken cancellationToken = default)

Parameters

jobKeys IReadOnlyCollection<JobKey>
cancellationToken CancellationToken

Returns

ValueTask<List<JobKey>>

The keys this call deleted, in the order they were given. A key that names no job is simply absent, never a throw — result.Count == jobKeys.Count is the "every key was found" answer, and the list itself says which ones when it is not.

Remarks

Note that while this bulk operation is likely more efficient than invoking DeleteJob(JobKey, CancellationToken) several times, it may have the adverse affect of holding data locks for a single long duration of time (rather than lots of small durations of time).

One JobDeleted(IScheduler, JobKey, CancellationToken) is raised per key the deletion applied to, and the scheduling change is signalled once for the whole call. A key that was not found raises nothing, as the single-key form raises nothing when it answers false.

Exceptions

ArgumentNullException

jobKeys is null.

SchedulerException

The scheduler has been shut down.

See Also

Exists(JobKey, CancellationToken)

Determine whether a IJob with the given identifier already exists within the scheduler.

ValueTask<bool> Exists(JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

jobKey JobKey

the identifier to check for

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<bool>

true if a Job exists with the given identifier

Exceptions

SchedulerException

The scheduler has been shut down.

Exists(TriggerKey, CancellationToken)

Determine whether a ITrigger with the given identifier already exists within the scheduler.

ValueTask<bool> Exists(TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

triggerKey TriggerKey

the identifier to check for

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<bool>

true if a Trigger exists with the given identifier

Exceptions

SchedulerException

The scheduler has been shut down.

Exists(string, CancellationToken)

Determine whether an ICalendar with the given name already exists within the scheduler.

ValueTask<bool> Exists(string calendarName, CancellationToken cancellationToken = default)

Parameters

calendarName string

the name to check for

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<bool>

true if a calendar is registered under the given name

Remarks

Asks the store for the name alone. GetCalendar(string, CancellationToken) answers the same question, but only by loading and deserializing the calendar — an exclusion set that can run to thousands of dates — to throw it away again.

Exceptions

SchedulerException

The scheduler has been shut down.

GetCalendar(string, CancellationToken)

Get the ICalendar instance with the given name.

ValueTask<ICalendar?> GetCalendar(string calendarName, CancellationToken cancellationToken = default)

Parameters

calendarName string
cancellationToken CancellationToken

Returns

ValueTask<ICalendar>

Exceptions

SchedulerException

The scheduler has been shut down.

GetExecutionLimits(CancellationToken)

Gets the currently configured execution group limits, or null if none are configured.

ValueTask<ExecutionLimits?> GetExecutionLimits(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<ExecutionLimits>

A snapshot of the current execution limits, or null.

GetJobDetail(JobKey, CancellationToken)

Get the IJobDetail for the IJob instance with the given key .

ValueTask<IJobDetail?> GetJobDetail(JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

jobKey JobKey
cancellationToken CancellationToken

Returns

ValueTask<IJobDetail>

Remarks

The returned JobDetail object will be a snapshot of the actual stored JobDetail. If you wish to modify the JobDetail, you must re-store the JobDetail afterward (e.g. see AddJob(IJobDetail, AddJobOptions, CancellationToken)).

Exceptions

SchedulerException

The scheduler has been shut down.

GetJobDetails(IReadOnlyCollection<JobKey>, CancellationToken)

Retrieves the given jobs in one round trip. Keys that do not exist are simply absent from the result.

ValueTask<List<IJobDetail>> GetJobDetails(IReadOnlyCollection<JobKey> jobKeys, CancellationToken cancellationToken = default)

Parameters

jobKeys IReadOnlyCollection<JobKey>

The keys of the jobs to retrieve.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<List<IJobDetail>>

Exceptions

SchedulerException

The scheduler has been shut down.

GetMetadata(CancellationToken)

Get a SchedulerMetadata object describing the settings and capabilities of the scheduler instance.

ValueTask<SchedulerMetadata> GetMetadata(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask<SchedulerMetadata>

Remarks

Note that the data returned is an 'instantaneous' snap-shot, and that as soon as it's returned, the metadata values may be different.

GetSchedulerInstanceId(CancellationToken)

The instance Id of the IScheduler, asked asynchronously.

ValueTask<string> GetSchedulerInstanceId(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask<string>

Remarks

The asynchronous twin of SchedulerInstanceId, and the member to call from a request path. A scheduler in this process answers with the same string either way. A proxy for a scheduler in another process — HttpScheduler — has to ask it, and the property can only do that by blocking the calling thread for the round trip; this one awaits it.

A default implementation answers SchedulerInstanceId, so a scheduler written outside this repository needs no change and reports what the property does.

GetStatus(CancellationToken)

Where the IScheduler is in its lifecycle, asked asynchronously.

ValueTask<SchedulerStatus> GetStatus(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask<SchedulerStatus>

Remarks

The asynchronous twin of Status, and the member to call from a request path. A scheduler in this process answers with the same value either way, and the answer is as instantaneous a snapshot here as it is there. A proxy for a scheduler in another process — HttpScheduler — has to ask it, and the property can only do that by blocking the calling thread for the round trip; this one awaits it.

A default implementation answers Status, so a scheduler written outside this repository needs no change and reports what the property does.

See Also

GetTrigger(TriggerKey, CancellationToken)

Get the ITrigger instance with the given key.

ValueTask<ITrigger?> GetTrigger(TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

triggerKey TriggerKey
cancellationToken CancellationToken

Returns

ValueTask<ITrigger>

Remarks

The returned Trigger object will be a snap-shot of the actual stored trigger. If you wish to modify the trigger, you must re-store the trigger afterward (e.g. see RescheduleJob(TriggerKey, ITrigger, CancellationToken)).

Exceptions

SchedulerException

The scheduler has been shut down.

GetTriggerState(TriggerKey, CancellationToken)

Get the current state of the identified ITrigger.

ValueTask<TriggerState> GetTriggerState(TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

triggerKey TriggerKey
cancellationToken CancellationToken

Returns

ValueTask<TriggerState>

Exceptions

SchedulerException

The scheduler has been shut down.

See Also

GetTriggers(IReadOnlyCollection<TriggerKey>, CancellationToken)

Retrieves the given triggers in one round trip. Keys that do not exist are simply absent from the result.

ValueTask<List<ITrigger>> GetTriggers(IReadOnlyCollection<TriggerKey> triggerKeys, CancellationToken cancellationToken = default)

Parameters

triggerKeys IReadOnlyCollection<TriggerKey>

The keys of the triggers to retrieve.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<List<ITrigger>>

Remarks

The returned triggers are snapshots of the stored ones. If you wish to modify a trigger, you must re-store it afterward (e.g. see RescheduleJob(TriggerKey, ITrigger, CancellationToken)).

Exceptions

SchedulerException

The scheduler has been shut down.

Interrupt(JobKey, CancellationToken)

Request the cancellation, within this Scheduler instance, of all currently executing instances of the identified IJob.

ValueTask<bool> Interrupt(JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

jobKey JobKey
cancellationToken CancellationToken

Returns

ValueTask<bool>

true is at least one instance of the identified job was found and interrupted.

Remarks

Interruption is cooperative. What the scheduler does is cancel the token the firing was given — CancellationToken, which is the same token Execute(IJobExecutionContext, CancellationToken) receives — so a job that never observes it runs to completion.

If more than one instance of the identified job is currently executing, the token is cancelled on each of them in turn. Cancelling runs whatever the running job registered on its token, so if one of those throws, the instances not yet reached keep running.

To interrupt one specific execution when several of the job are running, list them with QueryFireInstances(FireInstanceQuery, CancellationToken) and pass the one you mean to InterruptFireInstance(string, CancellationToken).

This method is not cluster aware. That is, it will only interrupt instances of the identified job currently executing in this scheduler instance, not across the entire cluster.

Exceptions

ArgumentNullException

jobKey is null.

OperationCanceledException

cancellationToken was cancelled part-way through, which leaves the firings already reached interrupted.

See Also

InterruptFireInstance(string, CancellationToken)

Request the cancellation, within this Scheduler instance, of the identified executing job instance.

ValueTask<bool> InterruptFireInstance(string fireInstanceId, CancellationToken cancellationToken = default)

Parameters

fireInstanceId string

the unique identifier of the job instance to be interrupted (see FireInstanceId)

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<bool>

true if the identified job instance was found and interrupted.

Remarks

Interruption is cooperative, as it is for Interrupt(JobKey, CancellationToken): the firing's CancellationToken is cancelled, and a job that never observes it runs to completion.

This method is not cluster aware. That is, it will only interrupt an instance currently executing in this scheduler instance, not across the entire cluster.

Exceptions

ArgumentNullException

fireInstanceId is null.

OperationCanceledException

cancellationToken was cancelled.

See Also

PauseAll(CancellationToken)

Pause all triggers - similar to calling PauseTriggerGroups(GroupMatcher<TriggerKey>, CancellationToken) on every group, however, after using this method ResumeAll(CancellationToken) must be called to clear the scheduler's state of 'remembering' that all new triggers will be paused as they are added.

ValueTask PauseAll(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask

Remarks

When ResumeAll(CancellationToken) is called (to un-pause), trigger misfire instructions WILL be applied.

Exceptions

SchedulerException

The scheduler has been shut down.

See Also

PauseJob(JobKey, CancellationToken)

Pause the IJobDetail with the given key - by pausing all of its current ITriggers.

ValueTask<bool> PauseJob(JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

jobKey JobKey
cancellationToken CancellationToken

Returns

ValueTask<bool>

true if the job exists — including a job that currently has no triggers — false if there is no job with the given key. No listener events are raised when nothing was found.

Exceptions

ArgumentNullException

jobKey is null.

SchedulerException

The scheduler has been shut down.

PauseJobGroups(GroupMatcher<JobKey>, CancellationToken)

Pause the job groups that match - by pausing all of the ITriggers of the IJobDetails in them.

ValueTask<List<string>> PauseJobGroups(GroupMatcher<JobKey> matcher, CancellationToken cancellationToken = default)

Parameters

matcher GroupMatcher<JobKey>
cancellationToken CancellationToken

Returns

ValueTask<List<string>>

The names of the job groups that were paused by this call.

Remarks

A group, not a set of jobs, which is why this is named for groups and answers with their names where PauseJobs(IReadOnlyCollection<JobKey>, CancellationToken) answers with keys. The pause is recorded against the group itself and outlives the jobs that were in it when the call was made: it survives a restart, reaches every node of a cluster, is what IsJobGroupPaused reports, and is imposed on jobs added to the group afterwards. No list of keys can say that, and an equality matcher pauses a group that holds no job at all — which is how a caller pauses what is about to be added to it.

The Scheduler will "remember" that the groups are paused, and impose the pause on any new jobs that are added to any of those groups until it is resumed.

NOTE: There is a limitation that only exactly matched groups can be remembered as paused. For example, if there are pre-existing job in groups "aaa" and "bbb" and a matcher is given to pause groups that start with "a" then the group "aaa" will be remembered as paused and any subsequently added jobs in group "aaa" will be paused, however if a job is added to group "axx" it will not be paused, as "axx" wasn't known at the time the "group starts with a" matcher was applied. HOWEVER, if there are pre-existing groups "aaa" and "bbb" and a matcher is given to pause the group "axx" (with a group equals matcher) then no jobs will be paused, but it will be remembered that group "axx" is paused and later when a job is added in that group, it will become paused.

Exceptions

ArgumentNullException

matcher is null.

SchedulerException

The scheduler has been shut down.

See Also

PauseJobs(IReadOnlyCollection<JobKey>, CancellationToken)

Pause the IJobDetails with the given keys - by pausing all of their current ITriggers.

ValueTask<List<JobKey>> PauseJobs(IReadOnlyCollection<JobKey> jobKeys, CancellationToken cancellationToken = default)

Parameters

jobKeys IReadOnlyCollection<JobKey>
cancellationToken CancellationToken

Returns

ValueTask<List<JobKey>>

The keys this call found, in the order they were given — a job with no triggers is found and so is present. A key that names no job is simply absent, never a throw.

Remarks

One JobPaused(IScheduler, JobKey, CancellationToken) is raised per key the pause applied to, and the scheduling change is signalled once for the whole call. A key that was not found raises nothing, as the single-key form raises nothing when it answers false.

Exceptions

ArgumentNullException

jobKeys is null.

SchedulerException

The scheduler has been shut down.

See Also

PauseTrigger(TriggerKey, CancellationToken)

Pause the ITrigger with the given key.

ValueTask<bool> PauseTrigger(TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

triggerKey TriggerKey
cancellationToken CancellationToken

Returns

ValueTask<bool>

true if the trigger exists and was moved into the paused state by this call, false if there is no trigger with the given key, it was already paused, or it is in a state that cannot be paused (e.g. complete). No listener events are raised when nothing changed.

Exceptions

ArgumentNullException

triggerKey is null.

SchedulerException

The scheduler has been shut down.

PauseTriggerGroups(GroupMatcher<TriggerKey>, CancellationToken)

Pause the trigger groups that match, and every ITrigger in them.

ValueTask<List<string>> PauseTriggerGroups(GroupMatcher<TriggerKey> matcher, CancellationToken cancellationToken = default)

Parameters

matcher GroupMatcher<TriggerKey>
cancellationToken CancellationToken

Returns

ValueTask<List<string>>

The names of the trigger groups that were paused by this call.

Remarks

A group, not a set of triggers, which is why this is named for groups and answers with their names where PauseTriggers(IReadOnlyCollection<TriggerKey>, CancellationToken) answers with keys. The pause is recorded against the group itself and outlives the triggers that were in it when the call was made: it survives a restart, reaches every node of a cluster, is what IsTriggerGroupPaused reports, and is imposed on triggers stored into the group afterwards. No list of keys can say that, and an equality matcher pauses a group that holds no trigger at all — which is how a caller pauses what is about to be added to it.

The Scheduler will "remember" all the groups paused, and impose the pause on any new triggers that are added to any of those groups until it is resumed.

NOTE: There is a limitation that only exactly matched groups can be remembered as paused. For example, if there are pre-existing triggers in groups "aaa" and "bbb" and a matcher is given to pause groups that start with "a" then the group "aaa" will be remembered as paused and any subsequently added triggers in that group be paused, however if a trigger is added to group "axx" it will not be paused, as "axx" wasn't known at the time the "group starts with a" matcher was applied. HOWEVER, if there are pre-existing groups "aaa" and "bbb" and a matcher is given to pause the group "axx" (with a group equals matcher) then no triggers will be paused, but it will be remembered that group "axx" is paused and later when a trigger is added in that group, it will become paused.

Exceptions

ArgumentNullException

matcher is null.

SchedulerException

The scheduler has been shut down.

See Also

PauseTriggers(IReadOnlyCollection<TriggerKey>, CancellationToken)

Pause the ITriggers with the given keys.

ValueTask<List<TriggerKey>> PauseTriggers(IReadOnlyCollection<TriggerKey> triggerKeys, CancellationToken cancellationToken = default)

Parameters

triggerKeys IReadOnlyCollection<TriggerKey>
cancellationToken CancellationToken

Returns

ValueTask<List<TriggerKey>>

The keys this call moved into the paused state, in the order they were given. A key that names no trigger, one that was already paused, and one in a state that cannot be paused are each simply absent, never a throw.

Remarks

One TriggerPaused(IScheduler, TriggerKey, CancellationToken) is raised per key the pause applied to, and the scheduling change is signalled once for the whole call. A key that did not move raises nothing, as the single-key form raises nothing when it answers false.

Exceptions

ArgumentNullException

triggerKeys is null.

SchedulerException

The scheduler has been shut down.

See Also

QueryCalendarNames(CalendarQuery, CancellationToken)

Lists calendar names matching the query, ordered by name (ordinal).

ValueTask<PagedResult<string>> QueryCalendarNames(CalendarQuery query, CancellationToken cancellationToken = default)

Parameters

query CalendarQuery

Which names to select and which page of them to return.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<PagedResult<string>>

Exceptions

SchedulerException

The scheduler has been shut down.

QueryClusterNodes(CancellationToken)

Lists the scheduler nodes the job store knows about, as ClusterNodes — this node first, then the rest by instance id.

ValueTask<List<ClusterNode>> QueryClusterNodes(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<List<ClusterNode>>

Remarks

This node is always listed, and is the only one whose IsCurrentNode is true; its InstanceId is SchedulerInstanceId. A scheduler that is not clustered — the in-memory store, or a persistent one with clustering switched off — answers with that single node and no check-in times, which is the truthful answer rather than an empty list.

The states are what this node believes, read off its own clock against the check-in stamps the other nodes wrote, and they are decided by the same predicate cluster recovery applies. A node reported Failed has its in-flight work taken over on the next check-in pass, after which it stops being listed.

The result is an 'instantaneous' snapshot: by the time it is returned a node may have checked in or been swept away. Join it with QueryFireInstances(FireInstanceQuery, CancellationToken) on SchedulerInstanceId to see what each node is running.

Exceptions

SchedulerException

The scheduler has been shut down.

See Also

QueryFireInstances(FireInstanceQuery, CancellationToken)

Lists the firings the scheduler knows about — by default the ones that are running — as FireInstances.

ValueTask<PagedResult<FireInstance>> QueryFireInstances(FireInstanceQuery query, CancellationToken cancellationToken = default)

Parameters

query FireInstanceQuery

What to select and which page of it to return.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<PagedResult<FireInstance>>

Remarks

With a persistent job store this sees the whole cluster, not just this node, because a firing is a durable record rather than process-local state. Filter by SchedulerInstanceId to ask about one node — SchedulerInstanceId for this one.

The result is an 'instantaneous' snapshot: by the time it is returned, firings may have started or finished.

A firing an ITriggerListener vetoes does not linger here: applying the veto completes the firing, which removes it. It can be listed for the instant between the store recording the firing and the veto being decided, and never after.

Exceptions

SchedulerException

The scheduler has been shut down.

See Also

QueryJobGroups(JobGroupQuery, CancellationToken)

Lists job groups matching the query, ordered by name (ordinal).

ValueTask<PagedResult<JobGroup>> QueryJobGroups(JobGroupQuery query, CancellationToken cancellationToken = default)

Parameters

query JobGroupQuery

What to select and which page of it to return.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<PagedResult<JobGroup>>

Exceptions

SchedulerException

The scheduler has been shut down.

QueryJobs(JobQuery, CancellationToken)

Lists jobs matching the query, as JobHeaders, ordered by group and then name (ordinal). Listing never loads job data.

ValueTask<PagedResult<JobHeader>> QueryJobs(JobQuery query, CancellationToken cancellationToken = default)

Parameters

query JobQuery

What to select and which page of it to return.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<PagedResult<JobHeader>>

Exceptions

SchedulerException

The scheduler has been shut down.

QueryTriggerGroups(TriggerGroupQuery, CancellationToken)

Lists trigger groups matching the query, ordered by name (ordinal).

ValueTask<PagedResult<TriggerGroup>> QueryTriggerGroups(TriggerGroupQuery query, CancellationToken cancellationToken = default)

Parameters

query TriggerGroupQuery

What to select and which page of it to return.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<PagedResult<TriggerGroup>>

Exceptions

SchedulerException

The scheduler has been shut down.

QueryTriggers(TriggerQuery, CancellationToken)

Lists triggers matching the query, as TriggerHeaders, ordered by group and then name (ordinal). The header carries the trigger's current state and execution group, so listing callers need no further round trips.

ValueTask<PagedResult<TriggerHeader>> QueryTriggers(TriggerQuery query, CancellationToken cancellationToken = default)

Parameters

query TriggerQuery

What to select and which page of it to return.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<PagedResult<TriggerHeader>>

Exceptions

SchedulerException

The scheduler has been shut down.

RescheduleJob(TriggerKey, ITrigger, CancellationToken)

Remove (delete) the ITrigger with the given key, and store the new given one - which must be associated with the same job (the new trigger must have the job name & group specified)

  • however, the new trigger need not have the same name as the old trigger.
ValueTask<DateTimeOffset?> RescheduleJob(TriggerKey triggerKey, ITrigger newTrigger, CancellationToken cancellationToken = default)

Parameters

triggerKey TriggerKey

The ITrigger to be replaced.

newTrigger ITrigger

The new ITrigger to be stored.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<DateTimeOffset?>

null if a ITrigger with the given name and group was not found and removed from the store (and the new trigger is therefore not stored), otherwise the first fire time of the newly scheduled trigger.

Exceptions

ArgumentNullException

triggerKey or newTrigger is null.

SchedulerException

The scheduler has been shut down; or newTrigger names a calendar that is not registered, or will never fire; or it is not one of Quartz's own trigger implementations.

ResetTriggerFromErrorState(TriggerKey, CancellationToken)

Reset the current state of the identified ITrigger from Error to Normal or Paused as appropriate.

ValueTask<bool> ResetTriggerFromErrorState(TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

triggerKey TriggerKey
cancellationToken CancellationToken

Returns

ValueTask<bool>

true if the trigger existed in the Error state and was reset by this call, false if there is no trigger with the given key or it was not in the error state.

Remarks

Only affects triggers that are in Error state - if identified trigger is not in that state then the result is a no-op.

The result will be the trigger returning to the normal, waiting to be fired state, unless the trigger's group has been paused, in which case it will go into the Paused state.

Exceptions

ArgumentNullException

triggerKey is null.

SchedulerException

The scheduler has been shut down.

See Also

ResetTriggersFromErrorState(GroupMatcher<TriggerKey>, CancellationToken)

Reset every ITrigger in the matching groups that is in Error, and return the keys it moved.

ValueTask<List<TriggerKey>> ResetTriggersFromErrorState(GroupMatcher<TriggerKey> matcher, CancellationToken cancellationToken = default)

Parameters

matcher GroupMatcher<TriggerKey>

Limits the reset to triggers whose group matches.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>

The keys this call reset.

Remarks

A mutation named by a matcher, like DeleteJobs(GroupMatcher<JobKey>, CancellationToken) and UnscheduleJobs(GroupMatcher<TriggerKey>, CancellationToken), and it answers with keys as they do: what a reset changes is triggers, one at a time, and nothing about a group is recorded — which is the difference between this and PauseTriggerGroups(GroupMatcher<TriggerKey>, CancellationToken).

The default implementation names the set with QueryTriggers(TriggerQuery, CancellationToken) and hands it to ResetTriggersFromErrorState(IReadOnlyCollection<TriggerKey>, CancellationToken), which is what decides what resetting a trigger does. The listing between the two calls is deliberately unbounded: the set is "every trigger in error in these groups", and a page of it would silently reset some and leave the rest. The two calls are not one atomic operation, so a trigger that enters the error state between them is left for the next call — which is also true of a caller who writes the two calls by hand. An implementation whose store can do it in one statement overrides this.

Exceptions

ArgumentNullException

matcher is null.

SchedulerException

The scheduler has been shut down.

See Also

ResetTriggersFromErrorState(IReadOnlyCollection<TriggerKey>, CancellationToken)

Reset every one of the identified ITriggers from Error to Normal or Paused as appropriate.

ValueTask<List<TriggerKey>> ResetTriggersFromErrorState(IReadOnlyCollection<TriggerKey> triggerKeys, CancellationToken cancellationToken = default)

Parameters

triggerKeys IReadOnlyCollection<TriggerKey>
cancellationToken CancellationToken

Returns

ValueTask<List<TriggerKey>>

The keys this call reset, in the order they were given. A key that names no trigger, or one that was not in the Error state, is simply absent, never a throw.

Remarks

The set is reset in one pass, under one lock or one connection. Resetting raises no scheduler-listener event and signals no scheduling change, in the plural exactly as in the singular — the reset triggers are picked up by the next acquisition cycle.

Exceptions

ArgumentNullException

triggerKeys is null.

SchedulerException

The scheduler has been shut down.

See Also

ResumeAll(CancellationToken)

Resume (un-pause) all triggers - similar to calling ResumeTriggerGroups(GroupMatcher<TriggerKey>, CancellationToken) on every group.

ValueTask ResumeAll(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask

Remarks

If any ITrigger missed one or more fire-times, then the ITrigger's misfire instruction will be applied.

Exceptions

SchedulerException

The scheduler has been shut down.

See Also

ResumeJob(JobKey, CancellationToken)

Resume (un-pause) the IJobDetail with the given key.

ValueTask<bool> ResumeJob(JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

jobKey JobKey
cancellationToken CancellationToken

Returns

ValueTask<bool>

true if the job exists — including a job that currently has no triggers — false if there is no job with the given key. No listener events are raised when nothing was found.

Remarks

If any of the IJob'sITrigger s missed one or more fire-times, then the ITrigger's misfire instruction will be applied.

Exceptions

ArgumentNullException

jobKey is null.

SchedulerException

The scheduler has been shut down.

ResumeJobGroups(GroupMatcher<JobKey>, CancellationToken)

Resume (un-pause) the job groups that match, and the IJobDetails in them.

ValueTask<List<string>> ResumeJobGroups(GroupMatcher<JobKey> matcher, CancellationToken cancellationToken = default)

Parameters

matcher GroupMatcher<JobKey>
cancellationToken CancellationToken

Returns

ValueTask<List<string>>

The names of the job groups that were resumed by this call.

Remarks

Forgets the group's pause, whatever matcher recorded it, so a group paused by a prefix matcher is resumed by one — which is why this answers with group names, as PauseJobGroups(GroupMatcher<JobKey>, CancellationToken) does, rather than with the keys ResumeJobs(IReadOnlyCollection<JobKey>, CancellationToken) answers with.

If any of the IJob s had ITrigger s that missed one or more fire-times, then the ITrigger's misfire instruction will be applied.

Exceptions

ArgumentNullException

matcher is null.

SchedulerException

The scheduler has been shut down.

See Also

ResumeJobs(IReadOnlyCollection<JobKey>, CancellationToken)

Resume (un-pause) the IJobDetails with the given keys.

ValueTask<List<JobKey>> ResumeJobs(IReadOnlyCollection<JobKey> jobKeys, CancellationToken cancellationToken = default)

Parameters

jobKeys IReadOnlyCollection<JobKey>
cancellationToken CancellationToken

Returns

ValueTask<List<JobKey>>

The keys this call found, in the order they were given — a job with no triggers is found and so is present. A key that names no job is simply absent, never a throw.

Remarks

If any of the jobs' ITriggers missed one or more fire-times, then those triggers' misfire instructions will be applied.

One JobResumed(IScheduler, JobKey, CancellationToken) is raised per key the resume applied to, and the scheduling change is signalled once for the whole call. A key that was not found raises nothing.

Exceptions

ArgumentNullException

jobKeys is null.

SchedulerException

The scheduler has been shut down.

See Also

ResumeTrigger(TriggerKey, CancellationToken)

Resume (un-pause) the ITrigger with the given key.

ValueTask<bool> ResumeTrigger(TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

triggerKey TriggerKey
cancellationToken CancellationToken

Returns

ValueTask<bool>

true if the trigger existed in a paused state and was resumed by this call, false if there is no trigger with the given key or it was not paused. No listener events are raised when nothing changed.

Remarks

If the ITrigger missed one or more fire-times, then the ITrigger's misfire instruction will be applied.

Exceptions

ArgumentNullException

triggerKey is null.

SchedulerException

The scheduler has been shut down.

ResumeTriggerGroups(GroupMatcher<TriggerKey>, CancellationToken)

Resume (un-pause) the trigger groups that match, and every ITrigger in them.

ValueTask<List<string>> ResumeTriggerGroups(GroupMatcher<TriggerKey> matcher, CancellationToken cancellationToken = default)

Parameters

matcher GroupMatcher<TriggerKey>
cancellationToken CancellationToken

Returns

ValueTask<List<string>>

The names of the trigger groups that were resumed by this call.

Remarks

Forgets the group's pause, whatever matcher recorded it, so a group paused by a prefix matcher is resumed by one — which is why this answers with group names, as PauseTriggerGroups(GroupMatcher<TriggerKey>, CancellationToken) does, rather than with the keys ResumeTriggers(IReadOnlyCollection<TriggerKey>, CancellationToken) answers with.

If any ITrigger missed one or more fire-times, then the ITrigger's misfire instruction will be applied.

Exceptions

ArgumentNullException

matcher is null.

SchedulerException

The scheduler has been shut down.

See Also

ResumeTriggers(IReadOnlyCollection<TriggerKey>, CancellationToken)

Resume (un-pause) the ITriggers with the given keys.

ValueTask<List<TriggerKey>> ResumeTriggers(IReadOnlyCollection<TriggerKey> triggerKeys, CancellationToken cancellationToken = default)

Parameters

triggerKeys IReadOnlyCollection<TriggerKey>
cancellationToken CancellationToken

Returns

ValueTask<List<TriggerKey>>

The keys this call resumed, in the order they were given. A key that names no trigger, and one that was not paused, are each simply absent, never a throw.

Remarks

If a ITrigger missed one or more fire-times, then its misfire instruction will be applied.

One TriggerResumed(IScheduler, TriggerKey, CancellationToken) is raised per key the resume applied to, and the scheduling change is signalled once for the whole call. A key that did not move raises nothing.

Exceptions

ArgumentNullException

triggerKeys is null.

SchedulerException

The scheduler has been shut down.

See Also

ScheduleJob(IJobDetail, ITrigger, ScheduleJobOptions, CancellationToken)

Add the given IJobDetail to the Scheduler, and associate the given ITrigger with it.

ValueTask<DateTimeOffset> ScheduleJob(IJobDetail jobDetail, ITrigger trigger, ScheduleJobOptions options = default, CancellationToken cancellationToken = default)

Parameters

jobDetail IJobDetail

The job to store.

trigger ITrigger

The trigger to store.

options ScheduleJobOptions

Whether an already stored job or trigger with the same key is over-written. The whole operation is one store operation under one lock, so an upsert needs no read-then-write of its own and cannot lose a race with another node doing the same thing.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<DateTimeOffset>

Remarks

If the given Trigger does not reference any IJob, then it will be set to reference the Job passed with it into this method.

Exceptions

ArgumentNullException

jobDetail or trigger is null.

SchedulerException

The scheduler has been shut down; or trigger names a different job, names a calendar that is not registered, or will never fire; or it is not one of Quartz's own trigger implementations.

ObjectAlreadyExistsException

The job or the trigger is already stored under the same key and Replace was not asked for.

ScheduleJob(IJobDetail, IReadOnlyCollection<ITrigger>, ScheduleJobOptions, CancellationToken)

Schedule the given job with the related set of triggers.

ValueTask ScheduleJob(IJobDetail jobDetail, IReadOnlyCollection<ITrigger> triggersForJob, ScheduleJobOptions options = default, CancellationToken cancellationToken = default)

Parameters

jobDetail IJobDetail
triggersForJob IReadOnlyCollection<ITrigger>
options ScheduleJobOptions
cancellationToken CancellationToken

Returns

ValueTask

Remarks

If any of the given job or triggers already exist (or more specifically, if the keys are not unique) and Replace is not set then an exception will be thrown.

Exceptions

ArgumentNullException

jobDetail or triggersForJob is null.

SchedulerException

The scheduler has been shut down.

ObjectAlreadyExistsException

The job or one of the triggers is already stored under the same key and Replace was not asked for. Nothing is stored.

ScheduleJob(ITrigger, ScheduleJobOptions, CancellationToken)

Schedule the given ITrigger with the IJob identified by the ITrigger's settings.

ValueTask<DateTimeOffset> ScheduleJob(ITrigger trigger, ScheduleJobOptions options = default, CancellationToken cancellationToken = default)

Parameters

trigger ITrigger

The trigger to store.

options ScheduleJobOptions

Whether an already stored trigger with the same key is over-written. Replacing is one store operation under the store's own lock, so scheduling over an existing trigger needs no CheckExists / UnscheduleJob / ScheduleJob dance and cannot lose a race with another node doing the same thing.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<DateTimeOffset>

Remarks

A replaced trigger keeps its PreviousFireTimeUtc, so a job that reads PreviousFireTimeUtc is not told the schedule has never fired merely because its trigger was rewritten.

Exceptions

ArgumentNullException

trigger is null.

SchedulerException

The scheduler has been shut down; or trigger names a calendar that is not registered, or will never fire; or it is not one of Quartz's own trigger implementations.

ObjectAlreadyExistsException

A trigger is already stored under the same key and Replace was not asked for.

ScheduleJobs(IReadOnlyDictionary<IJobDetail, IReadOnlyCollection<ITrigger>>, ScheduleJobOptions, CancellationToken)

Schedule all the given jobs with the related set of triggers.

ValueTask ScheduleJobs(IReadOnlyDictionary<IJobDetail, IReadOnlyCollection<ITrigger>> triggersAndJobs, ScheduleJobOptions options = default, CancellationToken cancellationToken = default)

Parameters

triggersAndJobs IReadOnlyDictionary<IJobDetail, IReadOnlyCollection<ITrigger>>
options ScheduleJobOptions
cancellationToken CancellationToken

Returns

ValueTask

Remarks

If any of the given jobs or triggers already exist (or more specifically, if the keys are not unique) and Replace is not set then an exception will be thrown.

Exceptions

ArgumentNullException

triggersAndJobs is null.

SchedulerException

The scheduler has been shut down.

ObjectAlreadyExistsException

A key in the batch is already stored and Replace was not asked for. None of the batch is stored.

SetExecutionLimits(ExecutionLimits?, CancellationToken)

Sets the execution group limits this scheduler enforces. Execution groups allow thread limits - per node or across the cluster, as each limit's ExecutionLimitScope says - so that resource-intensive jobs do not saturate all available threads.

ValueTask SetExecutionLimits(ExecutionLimits? limits, CancellationToken cancellationToken = default)

Parameters

limits ExecutionLimits

The execution limits to apply, or null to clear.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask

Remarks

Limits take effect on the next trigger acquisition cycle. Pass null to clear all limits.

Shutdown(bool, CancellationToken)

Halts the IScheduler's firing of ITriggers, and cleans up all resources associated with the Scheduler.

ValueTask Shutdown(bool waitForJobsToComplete = false, CancellationToken cancellationToken = default)

Parameters

waitForJobsToComplete bool

if true the scheduler will not allow this method to return until all currently executing jobs have completed. If false it waits for no job, but still gives the executions already in flight a couple of seconds to report their completions, so that a firing which ends on the way out is recorded rather than left for a peer to recover; one still working when that window closes is abandoned.

cancellationToken CancellationToken

Bounds the wait for running jobs, so that a shutdown can be given a deadline. Cancelling it stops the scheduler waiting; it does not cancel the jobs, and the shutdown itself always runs to the end, so the job store, the plugins and the listeners are told the scheduler has stopped either way.

Returns

ValueTask

Remarks

The scheduler cannot be re-started.

The scheduler is ShuttingDown for the duration and Shutdown once its plugins and job store are down. It does not pass through Standby on the way, and no listener is told it stood down: a scheduler being torn down is not one waiting to be started again.

Firing stops before anything is torn down, so a trigger this scheduler had reserved is released for another node and one it had already fired is still run. What it does about the executions under way is waitForJobsToComplete's answer.

Standby(CancellationToken)

Temporarily halts the IScheduler's firing of ITriggers.

ValueTask Standby(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask

Remarks

When Start(CancellationToken) is called (to bring the scheduler out of stand-by mode), trigger misfire instructions will NOT be applied during the execution of the Start(CancellationToken) method - any misfires will be detected immediately afterward (by the IJobStore's normal process).

The scheduler is not destroyed, and can be re-started at any time. A scheduler that is running becomes Standby.

Standing down a scheduler that is not running does nothing at all: no listener is told it went into standby, and the job store is not told it paused, because neither happened. A scheduler that has never been started is already firing nothing and stays Created, which is the more precise answer than standby; one already in standby is in the state being asked for.

Exceptions

SchedulerException

The scheduler has been shut down, or is shutting down. Neither is a state to be stood down from.

See Also

Start(CancellationToken)

Starts the IScheduler's threads that fire ITriggers, taking it to Running. A newly built scheduler is Created and fires nothing until this is called; so is one that Standby(CancellationToken) has stood down.

ValueTask Start(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask

Remarks

The misfire/recovery process will be started, if it is the initial call to this method on this scheduler instance.

Starting a scheduler that is already Running does nothing at all: no listener is told the scheduler started, and the job store is not told it resumed, because neither happened.

Exceptions

SchedulerException

The scheduler has been shut down, or is shutting down. That is terminal, so there is nothing to start.

See Also

StartDelayed(TimeSpan, CancellationToken)

Calls Start(CancellationToken) after the indicated delay. (This call does not block). This can be useful within applications that have initializers that create the scheduler immediately, before the resources needed by the executing jobs have been fully initialized.

ValueTask StartDelayed(TimeSpan delay, CancellationToken cancellationToken = default)

Parameters

delay TimeSpan
cancellationToken CancellationToken

Returns

ValueTask

Exceptions

SchedulerException

The scheduler has been shut down, and cannot be restarted.

ArgumentOutOfRangeException

delay is negative, or longer than a timer will wait.

See Also

TriggerJob(JobKey, JobDataMap?, CancellationToken)

Trigger the identified IJobDetail (Execute it now).

ValueTask TriggerJob(JobKey jobKey, JobDataMap? data = null, CancellationToken cancellationToken = default)

Parameters

jobKey JobKey

The JobKey of the IJob to be executed.

data JobDataMap

the (possibly null) JobDataMap to be associated with the trigger that fires the job immediately.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask

Exceptions

ArgumentNullException

jobKey is null.

SchedulerException

The scheduler has been shut down.

JobPersistenceException

No job is stored under jobKey.

UnscheduleJob(TriggerKey, CancellationToken)

Remove the indicated ITrigger from the scheduler.

If the related job does not have any other triggers, and the job is not durable, then the job will also be deleted.

ValueTask<bool> UnscheduleJob(TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

triggerKey TriggerKey
cancellationToken CancellationToken

Returns

ValueTask<bool>

Exceptions

ArgumentNullException

triggerKey is null.

SchedulerException

The scheduler has been shut down.

UnscheduleJobs(GroupMatcher<TriggerKey>, CancellationToken)

Remove every ITrigger in the matching groups from the scheduler.

ValueTask<List<TriggerKey>> UnscheduleJobs(GroupMatcher<TriggerKey> matcher, CancellationToken cancellationToken = default)

Parameters

matcher GroupMatcher<TriggerKey>

Selects the trigger groups to empty. Required — there is no "unschedule the default group" reading of null worth risking on a destructive call.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>

The keys of the triggers this call removed.

Remarks

The group is the correlation axis: everything scheduled for one saga, one tenant or one conversation shares a trigger group, and this is how the whole of it is called off in one call rather than one round trip per key — and without first listing the keys, which is a window in which another node can add one more.

A job left with no triggers by the removal is deleted too if it is not durable, exactly as the single-key UnscheduleJob(TriggerKey, CancellationToken) does, but the answer names triggers only.

One JobUnscheduled(IScheduler, TriggerKey, CancellationToken) is raised per removed key, and the scheduling change is signalled once for the whole call. A matcher that matched nothing raises nothing.

Exceptions

ArgumentNullException

matcher is null.

SchedulerException

The scheduler has been shut down.

See Also

UnscheduleJobs(IReadOnlyCollection<TriggerKey>, CancellationToken)

Remove all of the indicated ITriggers from the scheduler.

ValueTask<List<TriggerKey>> UnscheduleJobs(IReadOnlyCollection<TriggerKey> triggerKeys, CancellationToken cancellationToken = default)

Parameters

triggerKeys IReadOnlyCollection<TriggerKey>
cancellationToken CancellationToken

Returns

ValueTask<List<TriggerKey>>

The keys this call removed, in the order they were given. A key that names no trigger is simply absent, never a throw — result.Count == triggerKeys.Count is the "every key was found" answer, and the list itself says which ones when it is not.

Remarks

If the related job does not have any other triggers, and the job is not durable, then the job will also be deleted.

Note that while this bulk operation is likely more efficient than invoking UnscheduleJob(TriggerKey, CancellationToken) several times, it may have the adverse affect of holding data locks for a single long duration of time (rather than lots of small durations of time).

One JobUnscheduled(IScheduler, TriggerKey, CancellationToken) is raised per key the removal applied to, and the scheduling change is signalled once for the whole call. A key that was not found raises nothing, as the single-key form raises nothing when it answers false.

Exceptions

ArgumentNullException

triggerKeys is null.

SchedulerException

The scheduler has been shut down.

See Also

UpdateTriggerDetails(TriggerKey, TriggerDetailsUpdate, CancellationToken)

Updates trigger metadata and selected settings without rescheduling. Fire times and trigger state are preserved. Supported properties are the description, priority, job data map, calendar name, misfire instruction, execution group and preferred node.

ValueTask<bool> UpdateTriggerDetails(TriggerKey triggerKey, TriggerDetailsUpdate update, CancellationToken cancellationToken = default)

Parameters

triggerKey TriggerKey

The key identifying the trigger to update.

update TriggerDetailsUpdate

The details to update. See TriggerDetailsUpdate for available properties.

cancellationToken CancellationToken

The cancellation instruction.

Returns

ValueTask<bool>

true if the trigger was found and updated, false if not found.

Exceptions

ArgumentNullException

triggerKey or update is null.

SchedulerException

The scheduler has been shut down.

See Also

IJob
IJobDetail
ITrigger
IJobListener
ITriggerListener
ISchedulerListener
Edit this page