This document outlines changes needed when upgrading from Quartz.NET 3.x to 4.x. You should also check the release notes for each version.

Start here

The compiler finds most of the 3.x → 4.0 work.

Upgrading from 4.6 to 4.7

An application on 4.6 compiles on 4.7 unchanged. The upgrade has one required database migration, in database/migrations/4.7/:

A 4.7 node refuses to start without it; a 4.6 node never names it. Run it while the 4.6 nodes are up, then roll the nodes. A 4.6 node runs a trigger that measures from completion at a fixed rate, so make a trigger measure from completion only once every node is 4.7. See Version 4.7.

Behaviour that changed:

Upgrading from 4.5 to 4.6

An application on 4.5 compiles on 4.6 unchanged, unless it treats warnings as errors and has a cron literal that the new analyzer warning QZ0007 reports. The upgrade has three required database migrations, in database/migrations/4.6/:

A 4.6 node refuses to start without them; a 4.5 node never names them. A database that keeps its execution history can also take one optional migration, 4.6/add_execution_history_lookup_indexes: two indexes, performance only.

To roll a cluster from 4.5:

1. Run the migrations while the 4.5 nodes are up.
2. Roll the nodes. While any 4.5 node is live, every 4.6 firing round takes TRIGGER_ACCESS (event 3517). A 4.5 node never answers an interrupt asked of a firing it runs (event 3520), and judges every trigger by the store's misfire threshold.
3. The last 4.5 node stops. Once its row ages out, rounds of concurrent-allowed work take no lock (event 3518).

Nothing else is configured, and rolling back to 4.5 needs nothing. See Rolling upgrade from 4.5.

Behaviour that changed:

Upgrading from 4.4 to 4.5

An application on 4.4 compiles on 4.5 unchanged, and the database schema did not change.

Behaviour that changed:

Upgrading from 4.3 to 4.4

An application on 4.3 compiles on 4.4 unchanged. The database schema changed for a store that keeps its execution history in the database: run the 4.4 schema migration.

Behaviour changes:

• A cancelled run is recorded as Cancelled, with Succeeded false. 4.3 recorded it as a success. It now matches ExecutionHistoryQuery.FailedFinally = true, and the dashboard lists it as failed.

• A run whose job threw is recorded with the job's own message (#3992). 4.3 recorded the scheduler's wrapper for any exception but a JobExecutionException, so every such row read the same. ExceptionMessage on the row and LastFailureMessage on the job's status carry the new text. So does exceptionMessage on the HTTP API's JobExecuted event. Match on the job's message in any query, alert or event reader that matched the old one:

  - "exceptionMessage": "Job threw an unhandled exception"
  + "exceptionMessage": "the upstream system is down"
  

• context.Outcome reads ExecutionOutcome.Vetoed inside IJobListener.JobExecutionVetoed. It read Succeeded.

• quartz.job.execution.duration carries quartz.job.result (#3967), which splits a job's series by result. error.type is unchanged: a cancelled run still has none. A view with an attribute allow-list drops the new attribute until you add it.

• The Quartz.Job.Execute span carries quartz.job.result too (#4016). Its status is unchanged: Error only when the job threw. A run whose JobRunReport says Failed is tagged failed and its status stays Unset.

• A failed Quartz.JobStore.* span carries error.type, the exception type's full name, as its measurement already did.

• OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN=logs stops Quartz recording exceptions as span events. 4.3 ignored the variable. The span keeps its Error status, description and error.type. To keep the events where the variable is set:

    services.AddQuartz(q => q.ConfigureScheduler(options =>
    {
  +     options.RecordExceptionSpanEvents = true;
    }));
  

• A vetoed firing is recorded in the misfire feed, with MisfireReason.Vetoed. CountMisfires does not count it. An IExecutionHistoryStore of your own receives it through AddMisfire; count only MisfireReason.Missed rows.

• A TriggerJob firing carries QRTZ_MANUAL_TRIGGER = "true" in its trigger's JobDataMap, so the job sees it in MergedJobDataMap. A JobDataMap you pass to TriggerJob gains the key. JobChainingJobListener fires its follow-up jobs with TriggerJob, so they are recorded as manual too.

• The database history (UseExecutionHistory()) keeps the outcome and a status per job. Each row and its job's QRTZ_JOB_STATUS row commit in one transaction. It applies RetentionByResult, MisfireRetention and MaxEntriesPerJob, and answers QueryJobRunStatuses and GetJobRunStatus.

• One node per cluster sweeps the database history: the live node with the lowest instance id. 4.3 nodes all swept. See Who sweeps the execution history.

• A trigger that fails to fire five times in a row is stored ERROR. A persistent store used to release it and acquire it again forever, first in every round, so a [DisallowConcurrentExecution] job's other triggers never fired. Now the scheduler listeners hear TriggerInError and event 3050 is logged. Only a fire that fails for a reason a retry will not cure counts; a transient failure or an outage does not. Fix the cause, then call ResetTriggerFromErrorState. To keep 4.3's behaviour:

    services.AddQuartz(q => q.UsePersistentStore(store =>
    {
        store.UsePostgres(connectionString);
  +     store.ConfigureStore(options => options.MaxConsecutiveFireFailures = 0);
    }));
  

• A calendar that throws fails its own trigger's fire, not the in-memory store's whole batch. 4.3 left the batch stranded: fires before the throw read Executing for good, their serial job-mates Blocked, and the trigger stayed reserved. Now the other triggers fire, the failing one is left as it was, and error 2008 is logged. After five failures in a row it is set ERROR, as above. To keep releasing it:

  - services.AddQuartz(q => q.UseInMemoryStore());
  + services.AddQuartz(q => q.UseInMemoryStore(options => options.MaxConsecutiveFireFailures = 0));
  

• A calendar that throws while a misfire is handled fails only its own trigger (#3985, #4006). The trigger keeps its fire time, and error 2010 (in-memory) or 3603 (persistent) is logged. The failure counts toward MaxConsecutiveFireFailures at most once per misfire threshold, so a calendar that always throws parks its trigger after five failures a threshold apart. A misfire handled starts the count again. A failure inside a transaction the application owns is not counted, and a database failure in the same step is still retried. MaxConsecutiveFireFailures = 0 turns the parking off. What 4.3 did:

  Where	4.3
  In-memory acquisition	Ended the pass; what it had acquired stayed reserved and never fired
  In-memory completion of a [DisallowConcurrentExecution] job	Left the later triggers Blocked and skipped the instruction
  Persistent completion of such a job	Rolled back and retried forever; the job stayed BLOCKED
  Persistent misfire handler	Logged the trigger on every scan and never stored it ERROR

• Resuming a trigger no longer throws its calendar's exception. Every resume call logs it, as above, and resumes the trigger as it was; its misfire is handled again later. Read the state instead of catching:

  - try { await scheduler.ResumeTrigger(key); }
  - catch (Exception e) { logger.LogError(e, "Calendar failed"); }
  + await scheduler.ResumeTrigger(key);
  + TriggerState state = await scheduler.GetTriggerState(key); // Error once the limit is reached
  

• A recovery trigger from cluster recovery carries SchedulerConstants.FailedJobOriginalTriggerScheduledFireTime, as one from a node's own recovery at startup always did. A job reading it no longer finds it missing.

• Cluster recovery of a recovery firing keeps the original firing's markers. 4.3 overwrote FailedJobOriginalTriggerName, Group and FireTime with the recovery trigger's own, so the second replay named RECOVERING_JOBS.recover_… as the trigger it stood in for.

• The scheduler releases what it acquired when a store throws something other than a SchedulerException while firing. It used to log event 1035 and leave the batch reserved.

• The dashboard's Run again passes the failed run's input back when the history recorded it, under SchedulerConstants.JobInput (#4012). 4.3 fired the job with no data. With RecordInput off, the default, nothing changes. A run that carries the input is logged as TriggerJobWithData, and the toast says with the original input or without input. To record inputs:

  - services.AddQuartzExecutionHistory();
  + services.AddQuartzExecutionHistory(options => options.RecordInput = true);
  

• Triggers already due are fired in the transaction that acquires them (#3864). This applies to a persistent store that acquires under TRIGGER_ACCESS: any batch over one trigger, or AcquireTriggersWithinLock. The fired-trigger row is inserted as EXECUTING, with no ACQUIRED row before it. A trigger due later in the batch window is reserved and fires at its own time, as before. A lock-free acquisition of one trigger stays two transactions. The in-memory store does both under one lock.

• A firing committed on acquisition runs even if Shutdown() is called while the round is in flight. The store has recorded it, so the scheduler dispatches it rather than lose the occurrence, as it does a firing TriggersFired committed.

• A trigger fired on acquisition has no Quartz.JobStore.TriggersFired span. The Quartz.JobStore.AcquireNextTriggers span counts it in quartz.jobstore.trigger.fired_on_acquire, and quartz.trigger.acquisition.duration includes its fire. A dashboard that counts fires from TriggersFired spans adds that attribute.

• A DelegatingJobStore subclass fires nothing on acquisition. It keeps working, at two transactions a round. To keep the saving, forward the new member:

    public sealed class MyJobStore(IJobStore inner) : DelegatingJobStore(inner)
    {
  +     public override ValueTask<TriggerAcquisitionResult> AcquireNextTriggersAndFireDue(
  +         TriggerAcquisitionRequest request, CancellationToken cancellationToken = default)
  +         => InnerJobStore.AcquireNextTriggersAndFireDue(request, cancellationToken);
    }
  

• A StdAdoDelegate subclass, or a delegate of your own, keeps every override called. It answers SupportsFireOnAcquire false, so its round is one transaction but claims, reserves, reads and fires each trigger through the single-trigger members, as before. A subclass's InsertFiredTriggers now inserts each row through InsertFiredTrigger. To take the shipped round's shape, answer true once an ApplyTriggerFired override handles TriggerFiredUpdate.FiredOnAcquire or calls the base. A subclass's round is never batched, and the Oracle, Firebird and SQLite drivers cannot batch. See A subclass keeps its overrides.

• A clustered node looks again soon for a trigger a [DisallowConcurrentExecution] job holds back (#3988). The job's run on another node wakes only that node when it ends, so 4.3 found the trigger a whole IdleWaitTime later, and a trigger pinned to the node fired that late every time. Now a node that acquires nothing looks again after 100 ms, then twice as long each round, up to 5 seconds while the store still reports it held, when such a run holds back a trigger it could not fire, one acquisition passed over, or one pinned to it. A clustered round that acquires nothing makes one more query through a shipped driver delegate, to find the last kind; a subclassed delegate's node finds it after IdleWaitTime, as before. A node with nothing held back, or one not clustered, waits as before. Drop a workaround that kept a node awake, such as a trigger pinned to it and due every second. See A serial job across nodes.

• The dashboard's History page stat cards count every run the filters match, not the page in view (#4015). They are Runs, Success rate, Failed and Longest run, titled with the window. A chart of runs over time sits above the table, and a Window filter (window=24h) narrows the chart, the cards and the rows. A source that cannot count keeps the 4.3 cards. A test or scraper that reads a card by its title reads the new one:

  - Success rate (page)
  + Success rate (all retained)
  

• The dashboard's History page labels a success Succeeded, not Complete, in a column named Result. The Job Detail page's View execution history opens that job's rows only, where it used to filter by a fragment of the key.

• The HTTP API's misfire listing leaves out Vetoed rows unless reasons names them. A client of your own that reads them asks:

  GET /quartz-api/schedulers/QuartzScheduler/history/misfires?reasons=Missed,Overlap,Vetoed
  

• Quartz.HttpClient reads a name it does not know (#4017). 4.3 failed the whole call on one, and one unknown event kind ended the event subscription. Now an unknown kind's frame is skipped, an unknown status reads Unknown, and a listed item in an unknown state is left out and logged (9202). A single read of one still throws JsonException, now naming the value. The table is in A host newer than the client. A page can hold fewer items than its TotalCount says; the log names what was left out. A body member the client does not know is skipped even when your JsonSerializerOptions set UnmappedMemberHandling.Disallow. Drop a guard that caught a newer host's listing:

  - try { page = await scheduler.QueryTriggers(query); }
  - catch (JsonException) { page = new PagedResult<TriggerHeader>([], HasMore: false); } // a newer host
  + page = await scheduler.QueryTriggers(query); // a trigger the client cannot read is left out and logged
  

• Quartz.Weasel.SQLite rebuilds a table that carries your own columns, indexes or foreign keys. 4.3 refused the apply with a SchedulerException ("Weasel would rebuild table …") and changed nothing. The rebuild now keeps those objects and their rows. Drop any workaround that removed them before an apply.

• A Quartz.Weasel.SQLite apply retries only a lost race, and fails as a SchedulerException (#4002). 4.3 applied any failure twice more, then threw the failure itself, such as Weasel's InvalidOperationException. Now a failure no race causes fails at once, and every failure is a SchedulerException naming the scheduler and the database. Read the cause from InnerException:

  - catch (InvalidOperationException e)
  + catch (SchedulerException e) when (e.InnerException is InvalidOperationException)
  

• A trigger with no retry policy of its own inherits one (#4013): its job type's [RetryPolicy], else UseDefaultRetryPolicy. Without either, nothing changes. ITrigger.RetryPolicy stays the trigger's own, so read the policy that applies from the context:

  - int left = trigger.RetryPolicy!.MaxAttempts - context.RetryAttempt;
  + int left = context.RetryPolicy!.MaxAttempts - context.RetryAttempt;
  

• WithRetryPolicy(null) on TriggerDetailsUpdate now means "inherit". With a job-type policy or a default it no longer stops retries. To stop them:

  - new TriggerDetailsUpdate().WithRetryPolicy(null)
  + new TriggerDetailsUpdate().WithRetryPolicy(RetryPolicy.None)
  

• TriggerRetriesExhausted and PauseTriggerWhenRetriesExhausted() cover an inherited policy too, once its attempts are spent. An inherited retry with no room before the next occurrence settles quietly, with debug event 1062; only a trigger's own policy reports that.

• Manual runs and recovered firings inherit the job type's policy or the default. TriggerJob, the dashboard's Run now and Run again, and recovery triggers carry no policy of their own. To keep a job from being retried there:

  + [RetryPolicy(0)]
    public sealed class ChargeCardJob : IJob
  

• SendMailJob and NativeJob carry [RetryPolicy(0)]: the scheduler's default never retries them, because a retry sends the mail or runs the command again. A policy on the trigger still applies; to retry one, give its trigger a policy of its own.

• none is a retry policy in a scheduling file, an HTTP API request and the dashboard's trigger editor.

• The dashboard's Pause selected with a reason is one call. 4.3 paused a key at a time. A refusal now fails the whole selection, as the reasonless pause always did. An IQuartzApiClient of your own gets the PauseTriggersWith default, which still pauses a key at a time through your PauseTriggerWith.

• A replace that ends a trigger's pause forgets its reason. 4.3 left PAUSE_REASON, PAUSED_BY and PAUSED_AT on the row, so a later pause without a reason read the old one back. The trigger UPDATE now clears them in any state but paused, and keeps them when the replacement stays paused, in a paused group say. A StdAdoDelegate subclass that overrides UpdateTrigger with a statement of its own keeps the 4.3 behaviour.

• The new *With set defaults keep the details. The other *With defaults drop them. A scheduler or store of your own gets PauseTriggersWith and PauseJobsWith as one PauseTriggerWith or PauseJobWith call per key, so it records the reason with no change. Override them only to pause the set in one call.

• On SQL Server, ProvisionSchema() no longer creates FK_QRTZ_BLOB_TRIGGERS_QRTZ_TRIGGERS, which tables_sqlServer.sql never created (#3949). A database it provisioned before keeps the key; the store deletes blob rows itself, so nothing needs it. To make that database match a fresh install, drop it:

  ALTER TABLE QRTZ_BLOB_TRIGGERS DROP CONSTRAINT FK_QRTZ_BLOB_TRIGGERS_QRTZ_TRIGGERS;
  

Dependencies:

• The Quartz.Weasel packages need Weasel 9.39.0 or later, [9.39.0, 10.0.0); 4.3 took 9.35.1. Weasel 9.39.0 needs JasperFx 2.76.0 or later, so a Marten or Wolverine application beside Quartz resolves both at least that high. A pin below either fails restore with a downgrade error; raise it:

  - <PackageVersion Include="Weasel.Postgresql" Version="9.35.1" />
  + <PackageVersion Include="Weasel.Postgresql" Version="9.39.0" />
  

Mixed 4.3 and 4.4 versions:

• With the database history, raise Retention on the 4.3 nodes to the longest age the 4.4 nodes keep before rolling, and read the status counts as starting at the roll. See Rolling 4.3 to 4.4.
• A 4.3 node reads a Vetoed row in a shared misfire table as Missed, and its CountMisfires does not count it.
• A 4.3 node still records "Job threw an unhandled exception" for a job that throws; a 4.4 node records the job's own message.
• A 4.3 dashboard or HTTP client reads a 4.4 host's misfire listing: the host leaves Vetoed out for it.
• A 4.3 dashboard or HTTP client still fails on any name it does not know. A 4.4 one reads a later host's new names; see A host newer than the client.
• A 4.4 dashboard or HTTP client reading a 4.3 host: the new history filters throw NotSupportedException rather than return unfiltered rows, and there is no run status. The dashboard says so and leaves the status out. Upgrade the hosts to use them.
• A 4.4 dashboard or HTTP client reading a 4.3 host has no run statistics. The client reads the host's version and throws NotSupportedException without asking; the dashboard leaves the chart out and its stat cards count the page.
• A 4.3 node never parks a failing trigger. Each 4.4 node counts its own failures, so a trigger may be tried five times on each 4.4 node before one parks it.
• A 4.3 node ignores RecoverFiringsCancelledByShutdown and completes a shutdown's cancellation as cancelled. A recovery trigger a 4.4 node hands back is an ordinary trigger in RECOVERING_JOBS, which a 4.3 node fires.
• A 4.4 dashboard or HTTP client pausing a set with a reason on a 4.3 host: the host pauses the set without the reason.
• A 4.3 client's key-set pause on a 4.4 host is the reasonless pause, even from an authenticated caller.
• A 4.3 node leaves JOB_INPUT NULL, and a 4.3 host sends no input: Run again fires those rows without input.
• A trigger a 4.4 node fires on acquisition leaves the fired-trigger row a 4.3 fire leaves: EXECUTING, with the job named. A 4.3 node's [DisallowConcurrentExecution] check and recovery read it as their own.
• A 4.3 node may log warning 3028 ("returned null on nextFireTime") for a one-off a 4.4 node fired as it acquired it. It is harmless: the trigger is spent and its completion deletes it. A 4.4 node counts it as a race and logs nothing.
• A 4.4 dashboard or HTTP client scheduling a trigger paused on a 4.3 host: NotSupportedException, and nothing is stored. Schedule and pause in two calls until the host is upgraded.
• A 4.3 node ignores [RetryPolicy] and UseDefaultRetryPolicy: a trigger with no policy of its own is not retried when it fails there.
• A 4.3 node reads a stored none as no policy, then writes the column back empty when it fires the trigger, which then inherits on a 4.4 node. Give a trigger RetryPolicy.None once every node is on 4.4.
• A 4.3 HTTP API host refuses none in a trigger update as not a valid retry policy.
• A 4.3 node still waits a whole IdleWaitTime for a trigger a [DisallowConcurrentExecution] job running on another node holds back. Keep a workaround that keeps it awake until it is upgraded.

The 4.4 schema migration

Run it while 4.3 nodes are still running. The columns are nullable with no default, and a 4.3 node never names them or touches QRTZ_JOB_STATUS. See Database Schema Changes.

Upgrading from 4.2 to 4.3

An application on 4.2 compiles on 4.3 unchanged. The database schema changed: run the 4.3 schema migration.

ScheduleTrigger, StoreTrigger and the pause members are default interface members, so a scheduler or store written for 4.2 compiles and works. DelegatingScheduler and DelegatingJobStore declare them all.

Mixed 4.2 and 4.3 versions: a 4.2 host ignores onConflict. HttpScheduler also sends replace for Replace, so that still replaces; Keep and KeepEarlier throw ObjectAlreadyExistsException on a conflict there, and the outcome reads Created.

QZ1004 is information, not a warning. Every registration now has a name that binds, so the rename it reports is advice. A NoWarn or .editorconfig entry for it can stay or go.

Behaviour changes:

• A persistent store, clustered or not, batches what is already due. MaxBatchSize defaults to automatic. See MaxBatchSize is automatic.

• A firing that may run beside itself completes without TRIGGER_ACCESS. A persistent store takes no lock to complete a firing whose job allows concurrent execution and whose trigger asks for nothing (NoInstruction or DeleteTrigger); it writes only its own rows. An ILockHandler of your own sees fewer TriggerAccess acquisitions, and quartz.jobstore.lock.wait.duration no longer includes those completions. The completions that still take the lock are listed in Writing a lock handler.

• The misfire pass settles a continuation whose parent is gone. An AWAITING trigger whose parent trigger has no row and no running firing — one added to a one-off parent in the last moments of its lock-free completion, or one a 4.1 node's completion left behind — is settled on the next misfire pass as a deleted parent settles it: OnAnyOutcome released, any other condition parked in ERROR, with log event 3047. The pass asks one indexed question a cycle and takes no lock unless it finds something. The in-memory store needs no sweep: its completion holds the store's monitor throughout.

• Acquisition reads a job's stored IS_NONCONCURRENT. An ADO store took two triggers of one job into a batch when the job disallowed concurrent execution only through DisallowConcurrentExecution() on its builder. The fire path declined the second, so the job never overlapped itself, but the batch lost a slot. A driver delegate of your own that overrides SelectTriggersToAcquire sets the property.

• StdAdoDelegate.SelectTriggersToAcquire returns a candidate refused for its execution group's limit, flagged ExecutionGroupAtLimit, instead of leaving it out. The store skips the row and reads past it, so a node acquiring one trigger at a time no longer idles behind a group at its limit. A subclass that inspects the list its base returns sees the refused rows among them; one that overrides the member and leaves them out keeps working as it did.

• A brace in WithExecutionGroup is now a placeholder. WithExecutionGroup("a{b}") used to store a{b}; it now reads b from the job data and throws FormatException at Build() if it is missing. Write a{{b}} for the literal name. Scheduling files, TriggerDetailsUpdate, the HTTP API and GetTriggerBuilder() still take a name as written.

• A limit key ending in * is a prefix. quartz.executionLimit.tenant:* = 2 used to limit a group literally named tenant:*; it now limits each group starting with tenant:. ForGroup and Unlimited refuse such a name. A prefix key with no count (unlimited) is refused.

• A one-liner for a job whose [ExecutionGroup] has placeholders needs OneOffJobOptions.ExecutionGroup. Without it the call throws FormatException: a one-off trigger's job data is its input, stored whole. OneOffJobOptions.ExecutionGroup itself is stored as written, braces included, as in 4.2.

• A pause without a reason is written as 4.2 wrote it. It goes through UpdateTriggerState, UpdateTriggerStatesFromOtherStates, UpdateTriggerGroupStateFromOtherStates, UpdateTriggerGroupStateFromOtherState, InsertPausedTriggerGroup and InsertPausedJobGroups, so a StdAdoDelegate subclass that overrides them keeps working for it. Only a pause with a reason or a requester goes through PauseTriggerStates, PauseTriggerGroupStates, InsertTriggerGroupPause and InsertJobGroupPauses; override those too to customize that pause.

• A resume then calls IDriverDelegate.ClearTriggerPauses for the triggers it moved. Its own statements are unchanged. StdAdoDelegate writes only rows that carry a record; the default does nothing.

• The HTTP state, group-paused and trigger-listing answers carry a pause member, null unless paused.

• OneOffJobOptions.Replacing(name) sets OnConflict = Replace, not Replace = true. Replace still reads true. Replace = true beside a different OnConflict throws ArgumentException.

• A one-liner with OnConflict other than Throw calls IScheduler.ScheduleTrigger, not ScheduleJob(trigger, options). A test double configured for ScheduleJob sees no call for a Replacing(name) one-liner; configure ScheduleTrigger. The default Throw makes the call it always made.

• Advancing a TimeProvider wakes the scheduling loop. Its idle, pre-fire and standby waits are timers on the scheduler's clock, so FakeTimeProvider.Advance fires a trigger that came due. A test that advanced the clock and then signalled a change (ResumeAll(), another schedule) still works; the signal is no longer needed. See Controlling time.

• A schedule due after the scheduler loop's next look no longer wakes it. That look finds it anyway. A job store of your own that calls ISchedulerSignaler.SignalSchedulingChange(time) to wake the loop for some other reason passes null, which always wakes it.

• IListenerManager's GetJobListeners(), GetTriggerListeners() and GetSchedulerListeners() return one read-only list per registration change, not a new array per call. Casting the result to an array, or writing to it through IList<T>, throws.

• A scheduler with a job factory of your own registers no job types with the container. AddJob and ScheduleJob registered each job type as a scoped service whatever the factory, so ValidateOnBuild failed a job on dependencies only your factory supplies (#3930). Now the job type is registered only when the factory is MicrosoftDependencyInjectionJobFactory or derives from it. The order of UseJobFactory and AddJob does not matter, and a registration of your own is kept. Delete a RemoveAll written to get past validation:

    services.AddQuartz(q =>
    {
        q.UseJobFactory<MyJobFactory>();
        q.ScheduleJob<MyJob>(t => t.StartNow());
    });
  - services.RemoveAll<MyJob>();
  

  If your factory resolves a job from the container with GetRequiredService, register that job type yourself, for example services.AddScoped<MyJob>().

• HttpScheduler escapes every value it puts in a path or a matcher query (#3917). A ?, # or % in a name or group, and a &, #, + or % in a matcher value, now reach the scheduler as written; before, the request named another job or none. A name that contains /, or is . or .., throws ArgumentException instead of reaching another name or route. For such a name, use a member that takes a set of keys. See Names in a path. A 4.2 host reads the escaped values as a 4.3 host does.

Interface members are default interface members, so an implementation written for 4.2 compiles and behaves as it did. Properties added to records are non-positional init properties, so constructors are unchanged.

Mixed 4.2 and 4.3 versions:

• A 4.2 node never writes the progress columns, so its firings list with null progress on a 4.3 dashboard.
• A 4.2 node's history rows carry no log, and a 4.2 HTTP host has no single-entry route: a 4.3 dashboard fronting one says the target does not serve single executions.
• Behaviour change: the persistent history's QueryExecutions now returns each row's EntryId, and the recorder names every row, so an IExecutionHistoryStore of your own receives rows with EntryId set.
• A 4.2 node ignores OVERLAP_POLICY and fires every trigger as Default does. Roll every node before giving a trigger an overlap policy.
• Behaviour change: CountMisfires counts MisfireReason.Missed rows only. An IExecutionHistoryStore of your own keeps a Skip's rows beside the misfires and should do the same.
• A 4.2 node's pause records nothing, and its resume leaves a trigger's record behind, which a later pause of that trigger without a reason, on either version, makes current again. Roll every node before relying on a pause reason. See A mixed cluster.
• A 4.2 HTTP host ignores the reason body and answers no pause, so HttpScheduler.GetTriggerPause reads null there.
• A 4.2 node fires a backfill's triggers: they are plain one-shot simple triggers, and only the slot key is new. A 4.2 HTTP host has no backfill route; Backfill on an HttpScheduler still works against it, with a request per slot instead of one.

MaxBatchSize is automatic

QuartzSchedulerOptions.MaxBatchSize defaults to 0, automatic, instead of 1. It resolves when the scheduler is built:

One round now takes every trigger already due, up to the pool, with one acquisition and one TriggersFired. The fire-ahead window is still zero, so nothing fires early. On PostgreSQL a backlog of one-offs costs 16.6 statements and 2.8 commits a firing instead of 23.0 and 6.0.

On a cluster, acquisition now takes TRIGGER_ACCESS. A round that asks for more than one trigger takes the lock, including a round that finds nothing; at 1 only the fire took it. An ILockHandler of your own sees TriggerAccess taken to acquire as well as to fire, and quartz.jobstore.lock.wait.duration includes those waits. A batched cluster drained a backlog 1.5-1.8 times as fast: see Sizing a cluster.

To keep 4.2's behaviour, set it:

  services.AddQuartz(q =>
  {
+     q.ConfigureScheduler(options => options.MaxBatchSize = 1);
      q.UsePersistentStore(store => store.UsePostgres(connectionString));
  });

• The flat key quartz.scheduler.batchTriggerAcquisitionMaxCount still sets it. 0 there now means automatic; 4.2 rejected it.
• A negative value is still rejected at startup.
• An explicit value wins on every store, and may not exceed MaxConcurrency.

The 4.3 schema migration

Run them while 4.2 nodes are still running. The columns are nullable with no default, and a 4.2 node never names them. ProvisionSchema() does not add columns to an existing table; a fresh install from database/tables/ already has them. See Database Schema Changes.

Upgrading from 4.1 to 4.2

An application on 4.1 compiles on 4.2 unchanged. The database schema changed, for the first time since 4.0: run the 4.2 schema migration.

Interface members are default interface members. Every member added above to an interface (ITrigger, ITriggerConfigurator<TJob>, IJobStore, IDriverDelegate, IPersistentStoreBuilder, IJobExecutionContext, ITriggerListener, IThreadPool) has a default body, so an implementation written for 4.0 or 4.1 compiles and behaves as it did. The default is in the table where it does something. Properties added to records (TriggerHeader, ExecutionHistoryEntry, SchedulerRegistration, TriggerQuery) are non-positional init properties, so constructors are unchanged.

Mixed 4.1 and 4.2 versions:

• TriggerState travels over the HTTP API as its name. A 4.1 client reading a listing from a 4.2 host throws on "Awaiting" once a continuation exists.
• SchedulerOrigin is numeric on the wire. A 4.1 client sees an unnamed value for a window.
• A trigger with retry jitter stores a ;j<value> token, which a node older than 4.2 cannot read. A policy without jitter stores what it always did.

Conditional continuations

A conditional continuation is a trigger that waits in the store, in TriggerState.Awaiting, for another trigger's firing to end. The firing's ExecutionOutcome then releases it (if its ContinuationCondition names that outcome) or discards it. It settles once, inside the parent's lock and transaction. Job Continuations has the full rules: release and discard, deleted parents, cluster recovery, and what a listing shows.

• The parent is a TriggerKey, not a JobKey: a continuation waits for one firing, and a job may have several triggers.
• The parent must already be stored, or the continuation is refused with ObjectDoesNotExistException.
• A retried failure settles nothing. It is reported as Failed, but its TriggeredJobCompleteContext.Instruction is SchedulerInstruction.RetryTrigger, and every store skips settling on that instruction. A store that checked only the outcome would discard an OnSuccess continuation at the parent's first failure.
• A recurring conditional chain ("run the cleanup whenever the nightly job fails") is JobChainingJobListener.AddJobChainLink(first, second, condition), not a continuation.

Continuations in files, in the dashboard and on the wire

• Scheduling files, on any trigger. XML: <continues-after> (a <name> and an optional <group>) and <continuation-condition> (outcomes joined with |), optional, between <preferred-node> and <job-data-map>; the schema keeps version 2.0 and its namespace, and the XML trigger kinds stay frozen. JSON: ContinuesAfter as a Name/Group object and ContinuationCondition. A file's triggers are stored parent first. See Declaring one in a scheduling file.
• HTTP API. TriggerHeaderDto carries continuesAfterTriggerName, continuesAfterTriggerGroup and continuationCondition (as names; enums travel as names). ?state=Awaiting lists what is waiting. TriggerDetailsUpdate has no continuation fields: changing the parent is a reschedule.
• A 4.1 client throws on "Awaiting" from a 4.2 host, as a 4.0 client did on SchedulerOrigin.Remote from 4.1. It happens only once a continuation is scheduled, which the upgrade order below puts last.
• Dashboard. An Awaiting only filter, and the parent and condition on waiting triggers; see Continuations. Quartz.Dashboard's TriggerHeaderDto gains ContinuesAfter and ContinuationCondition as non-positional init properties.

The 4.2 schema migration

database/migrations/4.2/add_continuations_<db>.sql adds three nullable columns to QRTZ_TRIGGERS: CONTINUES_TRIGGER_NAME, CONTINUES_TRIGGER_GROUP and CONTINUATION_CONDITION. A 4.2 node refuses to start without them, and the error names the column and the script.

1. Run the migration while 4.1 nodes are still running. The columns are nullable with no default, and nothing a 4.1 node does on its own touches an AWAITING row: its INSERT names its own columns, its acquisition and misfire sweeps select WAITING, and its cluster recovery touches ACQUIRED and BLOCKED.
2. Roll every node to 4.2.
3. Only then schedule continuations.

The order matters because a 4.1 node mishandles continuations:

• It cannot settle one: a parent completing on a 4.1 node leaves its continuations waiting. Since 4.3 the misfire pass settles those whose parent trigger is gone, a spent one-off, as a deleted parent is settled; see the misfire pass settles a continuation whose parent is gone.
• It reads an unknown state as waiting, so it reports an AWAITING row as Normal. Its single-trigger PauseTrigger then writes PAUSED over the row, and a resume makes it WAITING: the continuation fires without its parent. A 4.1 reschedule rewrites it as an ordinary trigger. PauseJob and the group and batch pauses leave AWAITING rows alone.

While a 4.1 node runs, do not pause, resume or reschedule a continuation from it.

ProvisionSchema() does not add columns to an existing table. A fresh install from database/tables/ already has them. See Database Schema Changes.

A retry policy that gives up says so

A trigger that ran out of retry attempts used to go back to its schedule silently. It is now reported in four places; what the scheduler does is unchanged.

• Context: IJobExecutionContext.Outcome and IJobExecutionContext.RetryScheduled are written before the completion notifications, so a job listener can tell an attempt from the final result.
• Trigger listener: ITriggerListener.TriggerRetriesExhausted, once, between JobWasExecuted and TriggerComplete.
• History: every row carries RetryAttempt and RetryScheduled, and ExecutionHistoryQuery.FailedFinally selects occurrences that gave up. The dashboard's History page has the filter and a Run again button on those rows.
• Metric: quartz.trigger.retries_exhausted, with the attributes of quartz.trigger.retry.

RetryPolicy.Exponential also takes a jitter, so triggers that failed together do not retry together. See Retrying Failed Jobs.

Behaviour change: IJobExecutionContext.RetryAttempt is now the attempt the job just made. It used to read the trigger's field live, which ExecutionComplete advances or zeroes, so a listener saw the next attempt or nothing. Inside Execute the value is unchanged.

The execution history tables

database/migrations/4.2/add_execution_history_<db>.sql is optional. It creates QRTZ_EXECUTION_HISTORY and QRTZ_MISFIRE_HISTORY, used only by UsePersistentStore(store => store.UseExecutionHistory()). A scheduler that keeps no history never probes for them, so skip the file if you do not want a database-backed history.

Why use it: the default history is in memory and per process, so a node's History page shows only its own executions, and a store-attached dashboard shows none. With the tables, every node writes one history and every row carries its instance id.

• ProvisionSchema() creates these tables, and so does a fresh install from database/tables/ (whether or not the history is on). Only a database created by 4.0 or 4.1 needs the script.
• A store asked for a history it cannot keep names the script.
• Safe in a mixed cluster: a 4.1 node cannot see the tables, and a 4.2 node without UseExecutionHistory() neither reads nor writes them.

Upgrading from 4.0 to 4.1

An application on 4.0 compiles on 4.1 unchanged, and the database schema did not change. The exceptions, both at the end of this section: a logging package that Quartz no longer brings transitively, and two cron expressions that 4.1 reads differently.

Mixed 4.0 and 4.1 versions: SchedulerOrigin travels as its name in GET …/schedulers, so a 4.0 client throws on "Remote" from a 4.1 host that fronts a proxy. Upgrade the client first, or do not front proxies from a host that older clients read.

Fourteen behaviours changed without a signature changing:

• Shutdown(waitForJobsToComplete: false) no longer drops a firing. It stops and waits for the firing loop before closing the thread pool, so an occurrence already committed to the store is dispatched. It then gives running executions up to two seconds to report completion before closing the job store. A completion after that is refused, leaving the firing EXECUTING and its trigger BLOCKED until a peer recovers it. A job still running after two seconds is abandoned as before. So the default shutdown (QuartzHostedServiceOptions.WaitForJobsToComplete is off) can take up to two seconds longer. See When a node leaves.
• HttpScheduler.UpdateTriggerDetails works instead of throwing NotSupportedException. The route is POST …/triggers/{triggerGroup}/{triggerName}/update-details, answering { "applied": … }. The body is a patch: an omitted member is left alone, null clears it. A misfire instruction for the wrong schedule family is refused, as in process. A 4.0 server answers 404, so upgrade the host before the client. See Editing a trigger in place.
• ISchedulerFactory.LookupScheduler builds a registered scheduler that is not built yet, instead of answering null. A scheduler added at runtime is found while alive and not rebuilt after shutdown.
• QuartzHostedService shuts down schedulers added at runtime when the host stops, each under the QuartzHostedServiceOptions for its name. So AddQuartzHostedService("acme", o => o.WaitForJobsToComplete = true) configures a tenant added later. Before, they were left to container disposal, after the shutdown window.
• A health check falls back to the repository when the container has no registration under its name, so AddHealthChecks().AddQuartz("acme") reports on a tenant added later. The not-found message names both places it looked.
• A misspelled quartz.jobStore.* key fails startup, as on 3.x; 4.0 ignored it (for example quartz.jobStore.dbRetryIntreval). An ADO.NET store refuses an unread key under its prefix when its options are resolved. It also catches keys from an appsettings.json JobStore section, such as Quartz:JobStore:TabelPrefix.
  • lockHandler.* and driverDelegateInitString keep their own handling.
  • A store with no options type keeps failing in the binder that writes its keys.
  • quartz.checkConfiguration = false allows keys of your own, as before.
• AddQuartzHttpApi() records execution history by calling AddQuartzExecutionHistory(): in memory, 24 hours, 2000 rows per scheduler per feed. To opt out, set ExecutionHistoryOptions.MaxEntriesPerScheduler to 0. To keep it elsewhere, register an IExecutionHistoryStore before the call. See Execution history.
• AddQuartzDashboard() no longer registers DashboardHistoryPlugin. The recorder does its work. Do not register the plugin beside it, or every execution is recorded twice. IDashboardHistoryStore is unchanged and is adapted onto IExecutionHistoryStore both ways.
• AddQuartzDashboard() no longer registers DashboardLiveEventsPlugin, and the pages no longer connect to the dashboard's own hub. It calls AddQuartzSchedulerEvents(), and Live Logs subscribes to that stream: in process, or over the event route for a scheduler registered with AddQuartzHttpClient. The page used to open a SignalR client connection to the dashboard's public hub URL, which failed behind a reverse proxy (#3713). A proxy now needs to forward {DashboardPath}/hub only for your own clients. The hub is still served, with the same IQuartzDashboardHubClient payloads. Registering the plugin beside the publisher pushes every event twice.
• Dashboard events 9100 and 9101 gained two trailing placeholders: "… : {Outcome} (origin {Origin}, node {Node})" and "… and it failed: {Reason} (origin {Origin}, node {Node})". They name the SchedulerOrigin and node, or (unknown). Matching on the id or a prefix still works; matching the whole line does not. The Action Log page shows both and now records interrupts from Currently Executing. See Action Log.
• The HTTP API logs successful mutations. Event 9007, Information, "Api user {User} performed {Operation} on scheduler {SchedulerName}: {Route}", category Quartz.HttpApi. {User} is HttpContext.User.Identity.Name or (anonymous) (every line under AllowAnonymous()). Written after the handler, for 2xx answers only; refusals and failures are still 9005 and 9003/9004. Check your log volume budget. See Production hardening.
• AddQuartzHttpApi() streams events by calling AddQuartzSchedulerEvents(). With no subscriber, no event is built.
• Nothing in Quartz reads Status or SchedulerInstanceId off a remote scheduler.ISchedulerRepository used to read Status under its lock on every lookup, so one unreachable HttpScheduler stalled every lookup for the client's timeout. The listing now calls the async forms with a two-second deadline and reports a silent target as SchedulerStatus.Unknown with a null instance id. See Blocking members.
• AddQuartzHttpClient refuses a scheduler name it has already registered. A second call used to replace the first silently. Use a different scheduler name per target.

Recipes: Multi-Tenancy, and for the dashboard, Fronting a scheduler in another process over HTTP.

Quartz depends on Microsoft.Extensions.Logging.Abstractions, not Microsoft.Extensions.Logging. AddQuartz no longer calls AddLogging(). Quartz logs through whatever ILoggerFactory the container holds, so a hosted application, or one that calls services.AddLogging(…), sees no difference.

A project that used LoggerFactory, AddLogging or another Microsoft.Extensions.Logging type through Quartz without referencing the package must now reference it:

dotnet add package Microsoft.Extensions.Logging

Two more consequences, neither of which affects a hosted application:

• A container with no logging configured holds no ILoggerFactory. It still builds and runs a scheduler, and Quartz's lines go to LogProvider. (Quartz registering a factory would override a later services.AddLogging(logging => logging.AddConsole()) and drop its providers.)
• QuartzSchedulerBuilder refuses at Build() a container with ILoggerProvider registrations and no ILoggerFactory. Register the provider with Services.AddLogging(logging => logging.AddProvider(…)), which adds a factory.

Two cron expressions change meaning. Both parse on 4.1, so nothing reports it:

The road from 3.x, phase by phase

The 4.0 API came from six passes over the public surface. This guide is organised by topic; work through the passes in this order.

1. The extensibility contracts (the interfaces you implement). Start here: everything else assumes these signatures. Quartz.Spi is Quartz.Extensibility and Quartz.Simpl is Quartz.Impl; every async member returns ValueTask and ends with a CancellationToken; jobs take that token as a parameter; the job factory hands out a scope; the thread pool is asynchronous; trigger fire times are properties; and a job detail of your own is implementable, because the member no implementation could write is gone from IJobDetail.
2. The vocabulary and the surface. One word per concept, and nothing public that was never a contract. Names that were normalized, the scheduler and the job store speak the same verbs, matchers moved to Quartz, Key<T> moved to Quartz and is immutable, SchedulerMetadata replaces SchedulerMetaData, the listener API, and sealed and internalized types.
3. Listings, schedules and dates. Job store listings became queries returning PagedResult<T> of headers; misfire instructions are enums; intervals are said once per builder; TimeOfDay became TimeOnly; DateBuilder's static factories are gone; Executing is a trigger state; and the preferred node is a value.
4. The ADO.NET job store. Read the store is a store, not a base class first: the hierarchy is internal, so several later sections describe a seam that is now closed. Then trigger states are typed on the driver delegate; the stores are named for whose transaction they use; nine Execute…Lock overloads became four; locks are a SchedulerLock; the job store configuration is read-only; the driver delegate speaks in records; the optional columns are required, so the probes are gone, which makes the schema migration mandatory; RAMJobStore is sealed; a job store of your own can join your transaction; and the two stores, held to one contract test, answer the same way.
5. Configuration and hosting. The container builds the scheduler: StdSchedulerFactory is gone, the standalone builder is the same builder, there is no process-global scheduler state, AddJob registers the job with the container, one shape per registration method, clustering is configured in one place, the hosted service starts every scheduler, and every scheduler publishes job execution metrics.
6. Serialization policy and the last edges.[Serializable] survives only where a database blob needs it; the two exceptions moved out of Quartz.Core; execution limits are built once, then frozen; interruption has two names, not three; and Other Breaking Changes.

Two changes run through all six and are not repeated case by case: Task became ValueTask on nearly every member, and the namespaces moved as in pass 1. If a type you used is not in this guide, check Package Changes: it may have moved packages.

Target Framework

Quartz.NET 4.x targets net10.0 only. There is no netstandard2.0 build and no support for Full Framework style .config files. Upgrade your application to .NET 10 before upgrading to Quartz 4.x.

If you are a library rather than an application

A package that still serves net8.0 and net9.0 consumers references Quartz 3.x for those targets and Quartz 4 for net10.0: a conditional PackageReference, plus #if NET10_0_OR_GREATER where the call sites differ. This works only while the difference stays inside the library. If your own public surface would differ per target framework, ship a separate net10.0-only package or drop the old targets.

Embedding Quartz in a Library has the csproj fragment, the limits, and the renames a real port hit.

Package Changes

The first error you will see

dotnet add package Quartz in a 3.x application installs 4.x. The merged packages stay in the project file and reference Quartz with no upper bound, so the build compiles against Quartz 4.x and a 3.x Quartz.Extensions.DependencyInjection, Quartz.Extensions.Hosting or Quartz.Serialization.SystemTextJson. Eight type names exist in both:

error CS0433: The type 'QuartzOptions' exists in both
'Quartz.Extensions.DependencyInjection, Version=3.20.0.0, Culture=neutral, PublicKeyToken=f6b8c98a402cc8a4'
and 'Quartz, Version=4.0.0.0, Culture=neutral, PublicKeyToken=f6b8c98a402cc8a4'

The other seven are ITriggerConfigurator, JobFactoryOptions and SchedulingOptions (from Quartz.Extensions.DependencyInjection), QuartzHostedService, QuartzHostedServiceOptions and QuartzServiceCollectionExtensions (from Quartz.Extensions.Hosting), and JsonSerializationException (from Quartz.Serialization.SystemTextJson). Calls into the duplicated extension classes report CS0121: The call is ambiguous, naming both assemblies.

Fix: remove the three package references. Both errors go with them. A 3.x one that another package brings in, as MassTransit.Quartz does, has no reference to remove; see Message buses.

Quartz.Extensions.DependencyInjection, Quartz.Extensions.Hosting, and Quartz.Serialization.SystemTextJson have been merged into the main Quartz package:

- <PackageReference Include="Quartz.Extensions.DependencyInjection" Version="3.*" />
- <PackageReference Include="Quartz.Extensions.Hosting" Version="3.*" />
- <PackageReference Include="Quartz.Serialization.SystemTextJson" Version="3.*" />
+ <PackageReference Include="Quartz" Version="4.*" />

If you use Newtonsoft.Json serialization, reference Quartz.Serialization.Newtonsoft instead of the old Quartz.Serialization.Json.

Configuration that names a type from a merged assembly as a string keeps working: a name that fails to resolve is retried against Quartz, with a warning naming both spellings.

Empty packages under the four old ids

From 4.0.1, Quartz.Extensions.DependencyInjection, Quartz.Extensions.Hosting, Quartz.Serialization.Json and Quartz.Serialization.SystemTextJson are published at every 4.x version as empty packages: a dependency on the replacement package, a readme, and no assembly.

Still remove them. They exist so that a dependency bot can reach 4.x. A bot updating Quartz with these as one group resolves to the newest version every member has; until 4.0.1 that was 3.20.1, so bots closed the 4.0.0 pull request and landed 3.20.1. Now the group resolves to 4.x, and you delete the reference in that pull request.

An empty package cannot cause the CS0433 above. A pinned 3.x one still can.

Quartz.OpenTracing and Quartz.OpenTelemetry.Instrumentation are not published this way: they have no 4.x replacement package to depend on. Quartz's own activity source and meter replace both; see OpenTelemetry Integration.

Quartz.OpenTracing is dropped, with no 4.x release. It consumed the DiagnosticSource events that 4.x replaced with System.Diagnostics.Activity, and OpenTracing is archived. Remove the package reference and the AddQuartzOpenTracing call, and subscribe to Quartz's activity source and meter; see OpenTelemetry Integration.

- <PackageReference Include="Quartz.OpenTracing" Version="3.*" />

OpenTelemetry.Instrumentation.Quartz is not the replacement. It reads the same DiagnosticSource events, so on 4.x it produces no spans, silently. Remove it and add AddSource(QuartzInstrumentation.ActivitySourceName); see OpenTelemetry.Instrumentation.Quartz.

- <PackageReference Include="OpenTelemetry.Instrumentation.Quartz" Version="1.*" />

Quartz.Aspire is new

A new package with no 3.x counterpart; nothing to migrate.

Quartz.Aspire is the client integration for Aspire. It turns an Aspire connection name into a persistent job store: the driver delegate for that database, connections from a DbDataSource in the container, the scheduler's health check, and Quartz's two telemetry signals registered with your ServiceDefaults OpenTelemetry pipeline.

builder.AddQuartzPersistentStore("quartz");
builder.AddQuartz();

It has no Aspire.* package dependency (IHostApplicationBuilder is its whole contract), so it works in any generic-host application. There is no hosting integration: the AppHost declares its database resources itself. Aspire Integration lists every setting it reads from Aspire:Quartz; Running Quartz under Aspire shows what the call expands to.

Read this setting before the first run:

The health check is in Quartz, not Quartz.AspNetCore

The health check moved to the core package. Quartz.AspNetCore has a <FrameworkReference Include="Microsoft.AspNetCore.App" />, so a worker on a dotnet/runtime image that referenced it only for the check failed to start (#3532). The check still registers on the standard IHealthChecksBuilder.

In 3.x, AddQuartzServer from Quartz.AspNetCore registered the hosted service and the health check together, with only a tag list to choose. In 4.0 each has its own call, both in Quartz:

See AddQuartzServer is AddQuartzHostedService. If the check was your only reason to reference Quartz.AspNetCore, remove it:

- <PackageReference Include="Quartz.AspNetCore" Version="3.*" />
+ <PackageReference Include="Quartz" Version="4.*" />

Keep Quartz.AspNetCore for the HTTP API or the dashboard. MapHealthChecks and HealthCheckOptions.ResultStatusCodes, which decides what a degraded scheduler answers over HTTP, belong to ASP.NET Core; see ASP.NET Core Integration.

Documentation pages that moved

The old URLs redirect. Update links you keep in a wiki or runbook:

The externally linked anchors #h-hash-for-load-distribution and #building-cron-expressions-programmatically moved with the cron material and resolve on Cron Expressions.

Upgrading a running deployment

The order for upgrading a deployment: a database others depend on, and nodes that are running. Each step links the page that owns it. Steps 1 and 2 happen while you are still on 3.x.

1. Get off binary serialization, on 3.x. .NET removed BinaryFormatter, and 4.x cannot read a blob it wrote. The conversion needs BinaryObjectSerializer, which exists only on 3.x. Either let the scheduler rewrite blobs as it runs, or run a program that loads and writes back every serialized asset. Migrating from binary serialization says which blobs rewrite themselves, which never do, and how to find what is left. BLOB_TRIGGERS.BLOB_DATA cannot be converted from 4.x at all.
2. Audit the stored cron expressions, on 3.x. 4.x rejects several expressions 3.x stored, and rejects them when it reads the row, so the trigger cannot even be loaded. The SQL to find candidates (some clauses match too widely) is in Before you upgrade.
3. Decide on the window. Either stop the cluster, or run 3.x and 4.0 nodes against the same tables during the rollout. A mixed 3.x and 4.0 window says what has been checked about that state; in particular, do not let a 4.0 node write a calendar during it.
4. Run the mandatory migration script schema_30_to_40_upgrade_<database>.sql: one file per database, guarded, safe to run twice, and safe with 3.x nodes still firing. See Database Schema Migration. It is mandatory even for a database that took every optional 3.x migration, because 4.x validates the schema and QRTZ_PAUSED_JOB_GRPS is new. Always migrate the schema before the nodes: an old node tolerates a new schema, a new node does not tolerate an old one (Schema first, then nodes).
5. Translate the configuration. Flat quartz.* keys still work and mean the same thing, so this can be gradual; see Configuration and Legacy property keys. Before the first start, read Defaults that changed (an application that never named its scheduler stops seeing its own rows) and Silent behaviour changes.
6. Start 4.0. It checks that every table it reads exists, and names a missing one. It reads the job type names 3.x stored: SimpleTypeLoader maps renamed Quartz types, and you declare an alias for a type of your own that moved (Type loader). Replace the nodes one at a time (Replacing the nodes).
7. Run schema_30_to_40_indexes_<database>.sql once the last 3.x node is gone. It is optional and performance only; see Listing indexes, the reshaped acquisition index and the dropped misfire index. Run it top to bottom. It waits because it drops indexes 3.x statements may still use (3.x sweeps misfires with the misfire index), and drops and recreates the index both versions acquire on. On an offline upgrade, run it straight after step 4.

Before you go live is the checklist for the finished state.

Database Schema Migration

Quartz 4.x requires four columns on QRTZ_TRIGGERS (and one on QRTZ_FIRED_TRIGGERS) that were optional in 3.x:

3.x probed for these at startup and disabled a feature when its column was missing. 4.x has no probes and assumes all of them exist, so the migration is mandatory even if you never used misfire reporting, execution groups or node affinity.

4.x also adds two columns 3.x never had:

Both are nullable with no default, so existing rows read as "no retry policy" and need no backfill. They are in the 4.0 script because 4.x has no column probes, so a column added later would force a mandatory migration mid-version. AdoConstants names them ColumnRetryPolicy and ColumnRetryAttempt.

4.x also adds a table 3.x never had:

It mirrors QRTZ_PAUSED_TRIGGER_GRPS and makes JobGroup.Paused truthful on the ADO store. A group can be paused while it holds no jobs, so the flag cannot live on QRTZ_JOB_DETAILS. 4.x checks at startup that every table it reads exists, including this one, so the migration is mandatory even for a 3.x database that took every optional migration.

The startup check runs SELECT 1 per table and SELECT <column> … WHERE 1 = 0 for each column this migration adds to an existing table. A database that skipped the migration is refused before the scheduler starts, and the message names the column and this script. The check cannot see a column's type or width: a hand-built column of the wrong shape starts cleanly, then fails on the first statement that binds it with a provider error. Run the script in full. If startup succeeded but a firing failed with a raw provider error, check the column definitions first.

ProvisionSchema() does not replace the migration. It refuses a database where a table it needs exists but lacks a column it needs, so a 3.x database is refused rather than half-completed.

A paused job group does not survive the upgrade. 3.x's ADO store records nothing when it pauses a job group (IsJobGroupPaused returns a hard-coded false, and PauseJobs only pauses the individual triggers), so the migration has nothing to copy. The paused triggers stay paused. What is lost is the group's pause: a trigger added to that job group after the upgrade starts running. Paused trigger groups are unaffected; they were already QRTZ_PAUSED_TRIGGER_GRPS rows on 3.x.

If you rely on a paused job group, pause it again once you are on 4.x:

await scheduler.PauseJobGroups(GroupMatcher<JobKey>.GroupEquals("nightly"));

This writes the QRTZ_PAUSED_JOB_GRPS row, so JobGroup.Paused and IsJobGroupPaused answer correctly, and a trigger stored later for a job in that group is created PAUSED. An equality matcher records a group with no jobs, so this also pauses a group before anything is deployed into it. Both stores behave this way on 4.x; see The two job stores answer the same way.

database/migrations/4.0/ holds two files per database, run at different times:

<database> is sqlServer, postgres, mysql_innodb, oracle, sqlite or firebird. Every statement in both files is guarded, so each is safe whether or not you applied the optional 3.x migrations, and safe to run twice. The three sections below describe the index file.

For SQL Server the column additions look like this:

IF COL_LENGTH('QRTZ_TRIGGERS','MISFIRE_ORIG_FIRE_TIME') IS NULL
BEGIN
  ALTER TABLE [dbo].[QRTZ_TRIGGERS] ADD [MISFIRE_ORIG_FIRE_TIME] bigint NULL;
END

Replace QRTZ_ with your configured table prefix if different.

Database Schema Changes has the version-by-version history, including what each optional 3.x migration does and what skipping it costs.

Listing indexes (optional)

The index file aligns the indexes with the statements 4.x issues. Two additions matter for the job and trigger listings:

Listings page with ORDER BY JOB_GROUP, JOB_NAME and ORDER BY TRIGGER_GROUP, TRIGGER_NAME, and the primary keys are name-before-group, so without these indexes each page is a scan plus a sort. They are optional; add them if you list jobs or triggers from a large schema. Fresh-install scripts for every dialect already have them.

The file also drops indexes that are a leftmost prefix of a wider one, or that no 4.x statement uses. PostgreSQL changes most: several of its indexes omitted SCHED_NAME, the leading column of every Quartz predicate, so they could not serve a single-scheduler lookup.

The acquisition index is reshaped (optional)

The same file drops and recreates IDX_QRTZ_T_NFT_ST, the index acquisition uses (#3510):

Acquisition orders by NEXT_FIRE_TIME ASC, PRIORITY DESC, so an index with both directions lets the engine take the first entry instead of sorting every due trigger. With 100,000 triggers and 5,000 due, one acquisition on SQL Server drops from 21.6 ms and 20,395 logical reads to 0.6 ms and 8. MISFIRE_INSTR avoids a table lookup per skipped misfired trigger. Only the DDL changed; the statement did not. Firebird keeps the 3.x shape because its indexes take one direction for the whole index. See Database Schema for the numbers and the MySQL and Oracle notes.

If you built a 4.0 preview schema before this change, re-run schema_30_to_40_indexes_<database>.sql. The index name did not change, so the script drops and recreates it; a guarded CREATE INDEX alone would find the name taken and keep the old three columns.

The misfire index is dropped (optional)

The same file drops IDX_QRTZ_T_NFT_ST_MISFIRE (#3656):

No optimizer uses it on any of the four engines that had it (#3608, #3656). It leads with MISFIRE_INSTR, which the misfire sweep and its counting query compare with <> -1, so it can only be entered on SCHED_NAME; the reshaped acquisition index serves both statements. MySQLDelegate's FORCE INDEX hint named it, and now names the acquisition index. The dropped index was maintained on every trigger write and read by nothing.

• Run the file top to bottom. The acquisition reshape comes first, so a schema is never left with neither index. Every statement is guarded; re-run it as often as you like.
• 3.x reads this index, which is the other reason the index file waits for the last 3.x node to shut down.

Full table creation scripts for fresh installations are available in database/tables/.

Defaults that changed

Option defaults are the same on 4.x as on 3.x: thread pool size, the ADO store's misfire threshold and misfire batch, retry intervals, table prefix, cluster check-in interval, and the hosted service's two switches. If you set a value yourself, this section does not apply.

Three effective defaults changed for applications that never configured Quartz, that is, built their scheduler with new StdSchedulerFactory() or GetDefaultScheduler(). On 3.x those read an embedded quartz.config that 4.x does not read.

new StdSchedulerFactory(properties) and AddQuartz never read the file, so they already used the typed defaults. See The quartz.config file is no longer read.

One default is new: QuartzSchedulerOptions.PropagateTraceContext is on, so a trigger scheduled inside an Activity carries two extra data map entries. See Silent behaviour changes.

Silent behaviour changes

These calls still compile but behave differently. Read this before the first run of the upgraded application.

Reading job data

4.x kept 3.x's shorter accessor names (GetInt, GetBoolean) with the semantics of the longer set (GetIntValue, GetBooleanValue). If you called the longer set, nothing here changes for you.

• The indexer throws on a missing key. map["absent"] returned null on 3.x; on 4.x it throws KeyNotFoundException, on both JobDataMap and SchedulerContext. Use TryGetValue or a TryGet… accessor for an optional entry.
• GetString no longer throws. 3.x threw KeyNotFoundException for an absent key and InvalidCastException for a non-string. 4.x returns null for both, so a mistyped key or a wrongly typed value looks like "no value".
• The typed accessors throw InvalidCastException for an absent key, not KeyNotFoundException (GetInt, GetDouble, GetBoolean and the rest). A catch (KeyNotFoundException) around one stops catching.
• GetBoolean reads anything but "true" as false. 3.x used Convert.ToBoolean, so "1" or "yes" threw InvalidCastException. 4.x compares with "true" case-insensitively, so a flag stored as "1" now reads as off without an error. TryGetBoolean reports success for it too.
• Strings are parsed with the invariant culture. GetInt, GetLong, GetDouble, GetFloat and Get<decimal> used the current culture for a string value. On a comma-decimal culture, "3.14" read as 314 and now reads as 3.14. Check stored data for the reverse case: "3,14" read as 3.14 and now throws InvalidCastException from every numeric accessor, because none allows a group separator.
• Get<DateTime> parses with DateTimeStyles.RoundtripKind, so a string ending in Z comes back as Kind=Utc rather than shifted to local time. See PutAsString writes round-trip formats now.
• The scheduler context is no longer merged into job properties. See Scheduler context entries are no longer injected into job properties.

Serialization and the store

• quartz.serializer.type = json means System.Text.Json now. On 3.x json meant Newtonsoft, with a warning. On 4.x json and stj both resolve to SystemTextJsonObjectSerializer, with no warning. A configuration file carried over verbatim changes the blob format and the registered trigger and calendar serializers. Write newtonsoft if you meant Newtonsoft.
• Both serializers refuse a job data value they cannot read back, at write time, and both refuse the same set. See Both serializers refuse a job data value they cannot read back.
• A Dictionary<string, string> job data value is written the same way by both serializers, which changes what Newtonsoft writes. See A string dictionary is written the same way by both serializers.
• Five calendar types serialize to a new shape. 4.x reads both forms and 3.x only its own: harmless on a clean cut-over, fatal in a mixed window. See A mixed 3.x and 4.0 window.
• The formerly optional columns are required. Schema validation refuses an unmigrated schema at startup, naming the missing column and the migration script. With SchemaProvisioning.None it fails later instead, at the first statement that names the column. See The optional columns are required, so the probes are gone.
• The two stores now answer the same way where they used to disagree, which changes the ADO store in six places. See The two job stores answer the same way.

Lifecycle and telemetry

• Standby() after Shutdown() throws instead of doing nothing. See The transitions are honest about themselves.
• A trigger scheduled inside an Activity carries two extra job-data entries.QuartzSchedulerOptions.PropagateTraceContext is on by default, and the two reserved keys show wherever trigger data does: MergedJobDataMap, the dashboard, GET /triggers. Turn it off with q.ConfigureScheduler(options => options.PropagateTraceContext = false).

The end time is the last instant at which a trigger may fire

On 4.x, EndTimeUtc is the last instant a trigger may fire, for every trigger type: a fire time equal to it fires. This matches Java Quartz's AbstractTrigger. On 3.x the types disagreed:

So a simple or calendar-interval trigger whose EndAt lands exactly on a fire time fires once more than on 3.x, and a daily-time-interval trigger whose EndAt falls between two fire times fires fewer. To keep the old count, move the end time one second off the boundary.

TriggerFireTimes.ComputeBetween follows the same rule: its to is inclusive for every trigger type.

Ordering

• JobKey and TriggerKey compare ordinally; 3.x used the current culture. Sorted key listings come out in a different order. See Key<T> moved to Quartz and is immutable.

Null arguments raise ArgumentNullException

Every IScheduler member throws ArgumentNullException for a null argument, reads included: GetJobDetail, GetTrigger, GetTriggerState, GetTriggersOfJob, GetCalendar, the three Exists overloads and the six Query* members. (beta.1 covered only the mutation members; a read handed a null failed wherever it was first dereferenced, often inside the store.)

• The mutation members name the parameter. 3.x raised SchedulerException("JobDetail cannot be null") from ScheduleJob(null, trigger) and similar, so catch (SchedulerException) around a scheduling call also swallowed the caller's own bug. SchedulerQueryExtensions already behaved the new way.
• RescheduleJob and CronExpression.ResolveHash's two overloads raised ArgumentException. ArgumentNullException derives from it, so an existing catch still catches.
• The <exception> tags on IScheduler list which members refuse what: 97 of them, against 2 over 65 members on 3.x.

Between the alphas and beta.1

Corrections between 4.0 pre-releases are written into the sections above and below as 3.x against 4.0. The per-build list, with what an application on a pre-release must change, is in Appendix: if you ran a 4.0 pre-release.

What is on nobody's list because it did not change

Checked against both versions and identical:

• every misfire instruction's numeric value, so a carried-over MISFIRE_INSTR column means the same;
• TriggerState's existing values (Executing is appended);
• the misfire computation of every trigger family;
• the merge order and content of MergedJobDataMap;
• [PersistJobDataAfterExecution] writes back only a modified map;
• the lock handler a store picks for itself;
• StringOperator's matching;
• the effective default of Shutdown(waitForJobsToComplete).

Configuration

This is the largest change in 4.x. Configuration is strongly typed options and service registrations instead of a bag of quartz.* strings, and the dependency injection container builds the scheduler.

Flat keys still work

quartz.* keys from appsettings.json or a NameValueCollection keep working. They are translated into the typed options, and both spellings of a setting give the same result. You do not have to migrate configuration files to move to 4.x.

A flat property bag is checked for keys nobody reads

AddQuartz(services, properties) and AddQuartz(services, name, properties) now check the bag as QuartzSchedulerBuilder.UseProperties always did:

• A quartz.* key Quartz does not read throws SchedulerConfigException at registration. For example, quartz.jobstore.type (for quartz.jobStore.type) used to silently give you an in-memory store.
• A key 4.0 stopped reading is reported by name, with its replacement.
• Set quartz.checkConfiguration to false to allow keys of your own.
• The IConfiguration overloads are not checked, because flattening a section invents quartz.* keys whether Quartz reads them or not.

A property key without the quartz. prefix is refused

services.Configure<QuartzOptions>(…) was not checked at all. QuartzOptions.Properties holds flat quartz.* keys and QuartzPropertyBridge is its only reader, so a key without the prefix is read by nobody and has no symptom. An IValidateOptions<QuartzOptions> now refuses one at host startup:

  services.Configure<QuartzOptions>(options =>
  {
-     options.Properties["scheduler.instanceName"] = "svc";
+     options.Properties["quartz.scheduler.instanceName"] = "svc";
  });

The usual cause is services.Configure<QuartzOptions>(section) on a section written for the 3.x QuartzOptions, which was a dictionary: Quartz:Properties:scheduler.instanceName arrives as scheduler.instanceName. The check cannot catch a section whose keys match no QuartzOptions property, because that binds nothing. Bind the section with AddQuartz(configuration) instead.

This check does not compare keys against the ones Quartz reads, because a flattened section can hold settings for something else. quartz.checkConfiguration = false turns it off too.

A property bag is any dictionary

The property bag parameter is now IEnumerable<KeyValuePair<string, string?>>, the shape of Dictionary<string, string?>, IReadOnlyDictionary<string, string?>, QuartzOptions.Properties and AddInMemoryCollection's argument.

services.AddQuartz(new Dictionary<string, string?>
{
    ["quartz.scheduler.instanceName"] = "core",
    ["quartz.threadPool.maxConcurrency"] = "10"
});

A NameValueCollection (what a 3.x application passed to StdSchedulerFactory) still goes in unchanged: UseProperties and AddQuartz keep an overload for it.

KeyValuePair<TKey, TValue> is a struct, so IEnumerable<KeyValuePair<string, string>> does not convert to IEnumerable<KeyValuePair<string, string?>>. A Dictionary<string, string> needs one conversion:

- services.AddQuartz(settings);
+ services.AddQuartz(settings.ToDictionary(x => x.Key, x => (string?) x.Value));

AddQuartz(services, properties) now copies the bag, as UseProperties always did. Before, a caller that reused its collection could change the scheduler's configuration after AddQuartz returned.

Interrupting jobs on shutdown is one setting with four answers

QuartzSchedulerOptions.InterruptJobsOnShutdown and InterruptJobsOnShutdownWithWait are replaced by the enum ShutdownJobInterruption. (InterruptJobsOnShutdown = true meant "only when not waiting", which was easy to misread.)

  q.ConfigureScheduler(options =>
  {
-     options.InterruptJobsOnShutdown = true;
-     options.InterruptJobsOnShutdownWithWait = true;
+     options.ShutdownJobInterruption = ShutdownJobInterruption.Always;
  });

Configuration files need no change. Both flat keys still map onto the enum by the table above, and Scheduler:InterruptJobsOnShutdown: true in appsettings.json still works through its flattened quartz.* key. The new spelling is Scheduler:ShutdownJobInterruption: "Always".

A setting stops wearing a verb

IPersistentStoreBuilder.AcceptEnlistedTransactions() is gone. It only set one option, so set it through ConfigureStore, like the other nineteen AdoJobStoreOptions settings:

  q.UsePersistentStore(store =>
  {
      store.UsePostgres(connectionString);
-     store.AcceptEnlistedTransactions();
+     store.ConfigureStore(options => options.AcceptEnlistedTransactions = true);
  });

The option, the key quartz.jobStore.acceptEnlistedTransactions and the section entry JobStore:AcceptEnlistedTransactions are unchanged. UseClustering() keeps its verb because it sets two things: Enabled on ClusteringOptions and UseDbLocks on AdoJobStoreOptions.

Two names that said the wrong thing

  q.UsePersistentStore(store =>
  {
      store.UseSqlServer(connectionString);
-     store.Configure(options => options.UseProperties = true);
+     store.ConfigureStore(options => options.StoreJobDataAsStrings = true);
  });

- Matchers.Group<JobKey>(@operator: StringOperator.StartsWith, compareTo: "reports");
+ Matchers.Group<JobKey>(matchOperator: StringOperator.StartsWith, compareTo: "reports");

The flat key quartz.jobStore.useProperties still sets StoreJobDataAsStrings. In appsettings.json the entry is now JobStore:StoreJobDataAsStrings; JobStore:UseProperties still works through its flattened quartz.* key.

The persistent store builder says which thing it configures

UseDriverDelegate now has the Func<IServiceProvider, T> overload that UseConnectionProvider, UseSerializer, UseLockHandler and UseTriggerPersistenceDelegate already had, so a dialect can take services from the container.

  q.UsePersistentStore(store =>
  {
-     store.UseDataSourceName("reporting-db");
+     store.UseDataSource("reporting-db");
      store.UseSqlServer(connectionString);
-     store.Configure(options => options.TablePrefix = "RPT_QRTZ_");
+     store.ConfigureStore(options => options.TablePrefix = "RPT_QRTZ_");
  });

No configuration key moved: quartz.jobStore.*, Quartz:JobStore:* and quartz.jobStore.dataSource are unchanged.

The hosted service's extension point is its four hooks

QuartzHostedService.StartAsync and StopAsync are no longer virtual. An override that skipped the base call left schedulers that nothing could shut down.

Override the four virtual hooks instead (requested in #2386 and #2522):

• work in StartAsync moves to StartingAsync or StartedAsync;
• work in StopAsync moves to StoppingAsync or StoppedAsync;
• protected IReadOnlyList<IScheduler> Schedulers is a snapshot of the schedulers the service runs.

A shipped component is configured through its options type, and only there

The public setters on shipped components are now internal. Configure them through their options type:

• The row-lock handlers' retry settings are init-only: SelectForUpdateLockHandler has MaxRetry and RetryPeriod, and UpdateRowLockHandler gained RetryPeriod (it was hard-coded to a second). Set them at construction or through quartz.jobStore.lockHandler.maxRetry / .retryPeriod.
• Flat-key configuration is unaffected. quartz.plugin.<name>.<property> and quartz.jobStore.lockHandler.<property> set the component through reflection, which now binds non-public setters.
• UseStructuredJobLogging and UseStructuredTriggerLogging gain a configure delegate.

Two collections are no longer assignable, so one configure callback cannot discard another's additions. The configuration binder still binds into them.

- x.Files = ["~/quartz_jobs.xml"];
+ x.Files.Add("~/quartz_jobs.xml");

- options.Tags = ["ready", "live"];
+ options.Tags.AddRange(["ready", "live"]);

FileSchedulingOptions.Files is a List<string> rather than a string[], and QuartzHealthCheckOptions.Tags a List<string> rather than an IReadOnlyCollection<string>.

The provider names have constants

The eight driver names Quartz ships for DataSourceOptions.Provider are constants: DataSourceOptions.Providers.SqlServer, .Npgsql, .MySql, .MySqlConnector, .Oracle, .Sqlite, .SystemDataSqlite, .Firebird. The UseSqlServer / UsePostgres / … extensions use them.

The property stays a string, because UseGenericDatabase can describe other drivers. The values are unchanged, so configuration files are unaffected.

The standalone builder reads a configuration section

QuartzSchedulerBuilder.UseConfiguration(IConfiguration) is new. Like AddQuartz(configuration), it binds the typed options, reads a Schedule section and translates flat quartz.* keys.

- var properties = QuartzConfigurationHelper.ToNameValueCollection(configuration.GetSection("Quartz"));
- var factory = QuartzSchedulerBuilder.Create().UseProperties(properties).Build();
+ var factory = QuartzSchedulerBuilder.Create().UseConfiguration(configuration.GetSection("Quartz")).Build();

QuartzConfigurationHelper is internal. UseProperties(NameValueCollection) is unchanged, for a bag you built yourself from a properties file or environment variables.

Two scheduler thread settings were dead and are gone

The scheduling loop is a long-running Task, not a Thread, so these never did anything in 4.0:

Both keys are in the removed-key table, so a properties bag that still has one gets an explanation, not "unknown key".

The job store's setting is renamed:

The flat key quartz.jobStore.makeThreadsDaemons still sets it. It covers the misfire handler and the cluster manager, the only real threads Quartz creates, so it alone decides whether Quartz's threads keep a console application open.

PerformSchemaValidation became SchemaProvisioning, which has a third position

A persistent store can now create its own schema (#3531), so validation and creation are one three-valued setting:

• The flat key quartz.jobStore.performSchemaValidation still works: true maps to Validate, false to None.
• The new key quartz.jobStore.schemaProvisioning takes None, Validate or CreateIfMissing, case-insensitively. If both keys are present, the new one wins.
• CreateIfMissing only creates; it never alters or drops. It is safe on an existing schema, but a mis-typed TablePrefix gets a second, empty schema.
• It is not an upgrade: a missing column is left missing. database/migrations/ moves a schema forward, and the 3.x → 4.0 upgrade is still mandatory.
• It is not the default, because it needs DDL permission. Without that permission, the error names the fresh-install script for your database and tells you to run it and return to Validate.

IDriverDelegate gained the member behind it:

ValueTask CreateSchema(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default);

A delegate deriving from StdAdoDelegate inherits an implementation that runs an embedded script, named by overriding protected virtual string? SchemaResourceName. The lookup walks the base chain nearest first: a delegate deriving from a shipped one inherits that dialect's script, and one that overrides the name wins. A delegate with no script in its chain throws when asked to provision.

Code-first configuration is typed

Settings that were write-only properties on the configurator are now options:

  services.AddQuartz(q =>
  {
-     q.ConfigureScheduler(options => options.InstanceName = "core");
-     q.ConfigureScheduler(options => options.InstanceId = "node-1");
-     q.MaxBatchSize = 5;
-     q.InterruptJobsOnShutdown = true;
+     q.ConfigureScheduler(options =>
+     {
+         options.InstanceName = "core";
+         options.InstanceId = "node-1";
+         options.MaxBatchSize = 5;
+         options.ShutdownJobInterruption = ShutdownJobInterruption.WhenNotWaitingForJobs;
+     });
  });

The option names match the configuration keys: Quartz:Scheduler:MaxBatchSize and options.MaxBatchSize are the same setting.

Data sources no longer need a name

A scheduler has one job store and so one database; the data source takes no name:

  q.UsePersistentStore(store =>
  {
-     store.UseProperties = true;
      store.UseClustering();
-     store.UseSqlServer("sql-server-01", connectionString);
+     store.UseSqlServer(connectionString);
      store.UseSystemTextJsonSerializer();
+     store.ConfigureStore(options => options.StoreJobDataAsStrings = true);
  });

Schedulers that need different databases are registered under different names, each with its own services.

The quartz.config file is no longer read

Nothing is loaded from disk. A quartz.config file next to the application, one named by the quartz.config environment variable, and the embedded copy Quartz used to ship are all ignored. Configure a scheduler with properties passed to QuartzSchedulerBuilder.UseProperties, an IConfiguration section passed to AddQuartz, or code.

The three values the embedded file supplied (quartz.scheduler.instanceName, quartz.threadPool.threadCount, quartz.jobStore.misfireThreshold) are no longer defaults; see Defaults that changed for the old and new values. Only StdSchedulerFactory.Initialize() ever read the file; see StdSchedulerFactory is gone. Set the values explicitly if you want the old ones.

To describe an ADO.NET driver Quartz ships no metadata for, use the code-first form below. The quartz.dbprovider.* keys still work through IConfiguration or a NameValueCollection.

q.UsePersistentStore(store => store.UseGenericDatabase("MyDatabase", connectionString, () => new DbMetadata
{
    ProductName = "My Database",
    ConnectionType = typeof(MyConnection),
    CommandType = typeof(MyCommand),
    ParameterType = typeof(MyParameter),
    ParameterDbType = typeof(MyDbType),
    ParameterDbTypePropertyName = nameof(MyParameter.MyDbType),
    ParameterNamePrefix = "@",
    DbBinaryTypeName = "VarBinary",
}));

See the configuration reference. DbProvider.RegisterDbMetadata is gone with the process-wide lookup it wrote into; use the callback above, once per driver.

QuartzOptions is no longer a dictionary

QuartzOptions used to derive from Dictionary<string, string?> and hold jobs and triggers as well as flat keys. The keys moved to a Properties dictionary, and jobs and triggers are per-scheduler registrations.

  services.Configure<QuartzOptions>(options =>
  {
-     options["quartz.plugin.jobHistory.type"] = "Quartz.Plugins.History.LoggingJobHistoryPlugin, Quartz.Plugins";
+     options.Properties["quartz.plugin.jobHistory.type"] = "Quartz.Plugins.History.LoggingJobHistoryPlugin, Quartz.Plugins";
  });

A plugin whose type you know is better added directly, which also gives it constructor injection:

services.AddQuartz(q => q.AddPlugin<LoggingJobHistoryPlugin>());

A section of flat keys no longer binds onto QuartzOptions (it would bind Quartz:Properties:*). Pass the section to AddQuartz, which reads the keys and binds the typed options from it:

- services.Configure<QuartzOptions>(configuration.GetSection("Quartz"));
  services.AddQuartz(configuration.GetSection("Quartz"), q => { /* ... */ });

Add jobs and triggers through the builder. The overloads taking an IServiceProvider replace the options callback:

- services.AddOptions<QuartzOptions>()
-     .Configure<IOptions<SampleOptions>>((options, sample) =>
-     {
-         options.AddJob<ExampleJob>(j => j.WithIdentity("job", "group"));
-         options.AddTrigger(t => t
-             .ForJob("job", "group")
-             .WithCronSchedule(sample.Value.CronSchedule));
-     });
+ services.AddQuartz(q =>
+ {
+     q.AddJob<ExampleJob>(j => j.WithIdentity("job", "group"));
+     q.AddTrigger((provider, t) => t
+         .ForJob("job", "group")
+         .WithCronSchedule(provider.GetRequiredService<IOptions<SampleOptions>>().Value.CronSchedule));
+ });

QuartzOptions.SchedulerName read and wrote schedName, an ADO.NET column key that nothing reads, so a name set through it was silently ignored. It is gone with SchedulerId and MisfireThreshold; see QuartzOptions lost its three typed settings.

Removed

Deferred configuration

The AddQuartz overloads taking an IServiceProvider are gone. They ran the callback against a throwaway container. Instead, ask for the service where the value is used, when the real container exists.

A value that depends on a service: configure the option from the service, through the options pattern.

- services.AddQuartz((q, provider) => q.UsePersistentStore(store =>
- {
-     store.UseSqlServer(connectionString);
-     store.TablePrefix = provider.GetRequiredService<IMyService>().TablePrefix;
- }));
+ services.AddQuartz(q => q.UsePersistentStore(store => store.UseSqlServer(connectionString)));
+ services.AddOptions<AdoJobStoreOptions>()
+     .Configure<IMyService>((options, service) => options.TablePrefix = service.TablePrefix);

Use this route by default. Every option a scheduler reads is resolved after the container is built, so Configure, PostConfigure and IValidateOptions have all run. Two silent mistakes to avoid:

• A scheduler's options are its own named instance. AddQuartz(q => …) configures the unnamed one, which reaches only the default scheduler. AddQuartz("reporting", q => …) is configured with services.AddOptions<AdoJobStoreOptions>("reporting").

• Reading IConfiguration yourself skips the options pipeline. builder.Configuration.GetSection("…") .Get<MyOptions>() runs no Configure<MyOptions>, PostConfigure<MyOptions> or IValidateOptions<MyOptions>. Use it for a literal from configuration, not for a value the application computes:

  - var settings = builder.Configuration.GetSection("Jobs").Get<JobOptions>()!;
  - services.AddQuartz(q => q.UseExecutionLimits(l => l.ForGroup("reports", settings.MaxConcurrent)));
  + services.AddQuartz(q => q.UseExecutionLimits((provider, l) => l.ForGroup(
  +     "reports",
  +     provider.GetRequiredService<IOptions<JobOptions>>().Value.MaxConcurrent)));
  

A registration that depends on a service: every builder member that builds something has an overload that is handed the container, so the service is resolved when the thing is built.

Listeners, plugins and middleware rarely need this: they are registered services and get their dependencies through their constructors.

SPI changes

A custom IJobStore or ISchedulerPlugin takes its collaborators through its constructor.

IJobStore loses InstanceId, InstanceName, ThreadPoolSize and TimeProvider, and Initialize takes the scheduler's identity instead of collaborators:

- ValueTask Initialize(ITypeLoadHelper loadHelper, ISchedulerSignaler signaler, CancellationToken cancellationToken = default);
+ ValueTask Initialize(SchedulerIdentity identity, CancellationToken cancellationToken = default);

Take ISchedulerSignaler, ITypeLoader, TimeProvider or IOptions<QuartzSchedulerOptions> through the constructor. The identity cannot come through a constructor; see If you implement IJobStore. Initialize keeps only work that must happen before the scheduler runs and cannot be done in the constructor, such as verifying a database schema.

Options arrive as the scheduler's own through IOptions<>, IOptionsMonitor<QuartzSchedulerOptions> and IOptionsSnapshot<QuartzSchedulerOptions>: CurrentValue and Value are your scheduler's options, Get(name) answers for the name you pass, and OnChange reports only your scheduler's changes.

Plugin configuration extension methods extend IQuartzBuilder and register the plugin as a service, instead of deriving from PropertiesSetter to write string keys.

No process-global scheduler or connection state

SchedulerRepository.Instance and DBConnectionManager.Instance are gone. The repository is a container registration, so a scheduler is only visible in the repository of the container that built it:

- var scheduler = SchedulerRepository.Instance.Lookup("reporting");
+ var scheduler = serviceProvider.GetRequiredService<ISchedulerRepository>().Lookup("reporting");

The connection manager is removed outright. Register a connection provider through the store configuration, and resolve it from the container:

- DBConnectionManager.Instance.AddConnectionProvider("default", myProvider);
+ services.AddQuartz(q => q.UsePersistentStore(store => store.UseConnectionProvider(_ => myProvider)));

See The connection manager is gone.

As a result, a scheduler registered with AddQuartz and one built by a QuartzSchedulerBuilder in the same process do not see each other:

• ISchedulerFactory.GetAllSchedulers() on either lists only its own schedulers.
• ISchedulerFactory.LookupScheduler(name) returns null for the other's name.
• ISchedulerRepository.Lookup(name) sees only its own container's schedulers.

To reach a scheduler from code that has no reference to its factory, register it with AddQuartz and inject IScheduler, ISchedulerFactory or ISchedulerRepository. To share one repository across several entry points, register your own before calling AddQuartz; every Quartz registration is TryAdd, so yours wins:

var repository = new SchedulerRepository();
services.AddSingleton<ISchedulerRepository>(repository);
services.AddQuartz(/* ... */);

A QuartzSchedulerBuilder owns its container, so its repository holds only the schedulers it built. Instead of StdSchedulerFactory.GetSchedulerRepository() and GetDbConnectionManager(), resolve ISchedulerRepository from the container, and a scheduler's IDbProvider keyed by the scheduler's name.

StdSchedulerFactory is gone

The properties-based factory has been removed, along with its 47 public constants. Since 4.0 it only forwarded to the container path that AddQuartz uses.

Flat quartz.* keys are not going away; hand them to QuartzSchedulerBuilder instead:

- ISchedulerFactory factory = new StdSchedulerFactory(properties);
- IScheduler scheduler = await factory.GetScheduler();
+ IScheduler scheduler = await QuartzSchedulerBuilder.Create()
+     .UseProperties(properties)
+     .BuildScheduler();

UseProperties uses the same translator, so every key means what it did, including the quartz.checkConfiguration check that rejects a misspelled key. Configuration written in code wins over the properties in either order: property-derived options are applied first, and implementations the properties name are registered after (options are last-wins, registrations first-wins, as with AddQuartz).

Two behaviours lived in Initialize() and are gone:

• The quartz.* environment-variable overlay. new StdSchedulerFactory() read every quartz.* environment variable. Nothing does now. Use IConfiguration with AddEnvironmentVariables() and pass the section to AddQuartz, or flatten it into the NameValueCollection you hand to UseProperties.
• The embedded quartz.config defaults (instanceName = DefaultQuartzScheduler, threadCount = 10, misfireThreshold = 60000). A builder with no properties uses the typed defaults; see Defaults that changed. Set them explicitly to keep the old values. new StdSchedulerFactory(properties) never read the file.

IsSupportedConfigurationKey is gone, so you can no longer allow keys of your own by subclassing the factory. Set quartz.checkConfiguration to false instead.

GetDefaultScheduler() is gone: there is no process-wide scheduler any more (see No process-global scheduler or connection state). Build one scheduler where the application starts and hold it, or register it with AddQuartz and inject IScheduler.

Every removed constant

The key strings are unchanged. Search this table for the constant you used:

Three constants were already gone before this release but are likely in a 3.x configuration:

Every removed member

A 3.x application that subclassed the factory usually wanted one of these override points:

The builder surface says each thing once

Three members duplicated a neighbour and are removed:

ScheduleJobOptions.Replace now picks the store path, not the overload. Not replacing calls IJobStore.ScheduleJob as before, with the same span and metric names. Replacing calls IJobStore.ScheduleJobs, because overwriting a job and its trigger must be one operation under one lock. So an explicit new ScheduleJobOptions() now takes the plain path: same store outcome, better span name.

QuartzAspireSettings.ProvisionSchema became SchemaProvisioning, of type SchemaProvisioning?; see the Quartz.Aspire is new settings table.

The standalone builder is the same builder

QuartzSchedulerBuilder.Create takes the same callback as AddQuartz and hands it the same IQuartzBuilder. Use AddQuartz when the application has a container and QuartzSchedulerBuilder when it does not; the callback reads the same.

- var scheduler = await QuartzSchedulerBuilder.Create()
-     .Configure(q =>
-     {
-         q.UsePersistentStore(store => store.UseSqlServer(connectionString));
-         q.AddJob<ReportJob>(j => j.WithIdentity("report"));
-     })
-     .UseDefaultThreadPool(maxConcurrency: 20)
-     .BuildScheduler();
+ IScheduler scheduler = await QuartzSchedulerBuilder
+     .Create(q => q
+         .UseDefaultThreadPool(maxConcurrency: 20)
+         .UsePersistentStore(store => store.UseSqlServer(connectionString))
+         .AddJob<ReportJob>(j => j.WithIdentity("report").StoreDurably()))
+     .BuildScheduler();

The callback has everything on IQuartzBuilder (jobs, triggers, calendars, listeners, plugins, execution limits) and every extension a package adds. The builder itself declares only Create(configure), Build(), BuildScheduler(), UseConfiguration(IConfiguration) and the two UseProperties overloads.

The callback is optional, as with AddQuartz(): a scheduler configured entirely from configuration or flat keys is Create().UseConfiguration(section) or Create().UseProperties(properties).

Services and SchedulerName belong to IQuartzBuilder: read them as q.Services and q.SchedulerName. If a 4.0 pre-release let you chain calls directly on QuartzSchedulerBuilder, see Appendix: if you ran a 4.0 pre-release.

Build() returns something you can dispose

Build() returns StandaloneSchedulerFactory, an ISchedulerFactory that is also IAsyncDisposable and IDisposable. It used to return ISchedulerFactory, so disposing it needed a cast:

- ISchedulerFactory factory = builder.Build();
- using IDisposable container = (IDisposable) factory;
+ await using StandaloneSchedulerFactory factory = builder.Build();

Prefer await using: disposal shuts the scheduler down, which Dispose() can only block on. If you never dispose it, the scheduler runs until the process ends, as before.

Two members moved from the standalone builder onto IQuartzBuilder, so a scheduler registered with AddQuartz can also be given a pre-built part:

IScheduler is IAsyncDisposable

IScheduler implements IAsyncDisposable, so await using can replace a try/finally that shuts it down:

  IScheduler scheduler = await factory.GetScheduler();
- try
- {
-     await scheduler.Start();
-     …
- }
- finally
- {
-     await scheduler.Shutdown(waitForJobsToComplete: false);
- }
+ await using (scheduler)
+ {
+     await scheduler.Start();
+     …
+ }

What disposing does depends on the instance:

• Disposal is idempotent: disposing a scheduler that is already shut down does nothing.
• It does not wait for jobs. To let running jobs finish, call Shutdown(waitForJobsToComplete: true) first; disposing afterwards does nothing.
• IScheduler only inherits IAsyncDisposable. An earlier 4.0 preview redeclared DisposeAsync with new ValueTask DisposeAsync(). An IScheduler of your own implements IAsyncDisposable.DisposeAsync; the method you already have satisfies it.