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

Three questions. Each has a different part of this guide as its answer, and reading the wrong one first is most of what makes an upgrade feel long.

Is what you are upgrading a running deployment? Then the order to do things in matters more than any single rename, and two of the seven steps happen while you are still on 3.x — they are the two that are painful to discover afterwards. Read Upgrading a running deployment first, and come back for the code.

Is it an application's code? The road from 3.x, phase by phase is the reading order: six passes over the API, each with a theme, with the rest of this guide organised by topic underneath. The compiler finds most of the work for you; the passes are for knowing why a name moved and what to reach for instead. Start with Package Changes — the first error a mixed 3.x/4.x project produces is a package problem rather than a code one, and it is described there. If that application is F#, read Upgrading an F# project first: the upgrade is the same one, but F# reports it as a longer list of errors than it has causes.

Is it neither, because you are starting something new? None of this applies. Go to the quick start and then the tutorial.

If you ran a 4.0 alpha or beta, everything that changed between one pre-release and the next is collected in Appendix: if you ran a 4.0 pre-release. The rest of this guide is written as one statement about 3.x and 4.0, with no build numbers in it.

Already on 4.0? Then this guide is not your upgrade — Upgrading from 4.0 to 4.1 is, and it is short.

Upgrading from 4.0 to 4.1

Nothing in the 4.0 public surface moved and the database schema did not either, so an application on 4.0 compiles on 4.1 unchanged — unless it was using a package it took transitively from Quartz and Quartz no longer carries, which is the one dependency change below. What is here is what 4.1 makes newly possible, that change, and the two cron expressions 4.1 reads differently.

Five behaviours changed without a signature changing:

• Shutdown(waitForJobsToComplete: false) no longer drops a firing, and settles what it can. It stops the scheduler's own firing loop and waits for it before closing the thread pool, so an occurrence the loop had already committed to the store — TriggersFired has run and the trigger has moved past it — is dispatched rather than refused and lost. It then gives the executions already in flight up to two seconds to report their completions before the job store is torn down, because a completion that arrives after the store has closed is refused and leaves the firing EXECUTING with its trigger BLOCKED for a peer to recover a check-in timeout later. It is still not a wait for the jobs: it returns the moment nothing is in flight, and a job still working when the window closes is abandoned as before. What an application sees is a shutdown — the default one, since QuartzHostedServiceOptions.WaitForJobsToComplete is off — that can take up to two seconds longer when a job was running. See When a node leaves.

• HttpScheduler.UpdateTriggerDetails works rather than throwing NotSupportedException. It was the one IScheduler member the HTTP API had no route behind, and the API has one now: POST …/triggers/{triggerGroup}/{triggerName}/update-details, answering { "applied": … }. The body is a patch — a member it omits leaves the trigger's value alone, a member present as null clears it — and it carries the misfire instruction's schedule family, so an instruction aimed at a trigger of another family is refused here exactly as it is in process. A server on 4.0 answers 404 for the route, so upgrade the scheduler's host before the client that calls this. See Editing a trigger in place.

• ISchedulerFactory.LookupScheduler builds a registered-but-unbuilt scheduler rather than answering null for every name but its own factory's. What makes a scheduler exist is its registration, so "give me tenant acme" no longer depends on whether something else happened to resolve acme first. A scheduler added at runtime is found while it is alive and deliberately not rebuilt once it has been shut down — it has no registration to be rebuilt from.

• QuartzHostedService shuts down the schedulers added at runtime when the host stops, each under the QuartzHostedServiceOptions registered for its name — so AddQuartzHostedService("acme", o => o.WaitForJobsToComplete = true) configures a tenant that does not exist yet. They were otherwise left to container disposal, which happens after the graceful shutdown window has closed.

• A health check falls back to the repository when the container holds no scheduler registration under the name it was given, so AddHealthChecks().AddQuartz("acme") written at build time reports on the tenant added under that name later. Its message when nothing is found names both places it looked.

The mechanics, the refusals and the recipes are in Multi-Tenancy.

One dependency changed, and a consumer can see it: Quartz depends on Microsoft.Extensions.Logging.Abstractions rather than Microsoft.Extensions.Logging. Quartz writes log events, and building the pipeline that carries them is the application's job — the implementation package was referenced for exactly one call, AddLogging() inside AddQuartz, and it is not made any more. Nothing in the public surface moves, and an application under a host, or one that calls services.AddLogging(…) on either side of AddQuartz, sees no difference at all: Quartz logs through whatever ILoggerFactory the container holds, as it always has.

What changes is a project that used LoggerFactory, AddLogging or another Microsoft.Extensions.Logging type without ever referencing the package, taking it transitively through Quartz. That project references it:

dotnet add package Microsoft.Extensions.Logging

Two consequences follow, and a hosted application meets neither. A container that configured no logging at all now holds no ILoggerFactory: AddQuartz used to register one, and registering one now would beat the services.AddLogging(logging => logging.AddConsole()) written on the line after it and drop the application's providers in silence. Such a container still builds and runs a scheduler, and its lines go to LogProvider — where everything Quartz cannot inject a logger into already writes. And QuartzSchedulerBuilder refuses at Build() a container holding ILoggerProvider registrations with no ILoggerFactory to read them, which used to work because Quartz's own AddLogging() supplied the factory; register the provider the ordinary way, Services.AddLogging(logging => logging.AddProvider(…)), which brings a factory with it.

Two cron expressions change what they mean, and neither can be reported to you — both parse on 4.1:

The road from 3.x, phase by phase

The 4.0 API is the result of six passes over the public surface, each with its own theme. The guide below is organised by topic rather than by pass, so this is the map: what changed, in the order it is worth working through when migrating.

1. The extensibility contracts. The interfaces you implement rather than call. Quartz.Spi is Quartz.Extensibility and Quartz.Simpl is Quartz.Impl; every asynchronous member returns ValueTask and ends with a CancellationToken; jobs take that token as a parameter; the job factory hands out a scope instead of an instance; the thread pool is asynchronous; and trigger fire times are properties rather than getter/setter pairs; and a job detail of your own is finally implementable, because the one member no implementation could write is gone from IJobDetail. Start here: everything else assumes these signatures.

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 and 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 of the sections after it describe a seam that was curated and then closed, and say so. 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 and the schema migration that goes with that is mandatory; RAMJobStore is sealed; a job store of your own can join your transaction; and the two stores, held to one contract test, now answer the same way where they used to disagree.

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 job execution metrics are published by every scheduler.

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 the naming and visibility odds and ends gathered in Other Breaking Changes at the end of this guide.

Two differences run through all six and are not called out case by case, because they are almost universal: Task became ValueTask on nearly every member, and the namespaces moved as described in pass 1. If a type you used does not appear in this guide at all, check Package Changes first — it may have moved packages rather than changed.

Target Framework

Quartz.NET 4.x targets net10.0. There is no netstandard2.0 build and no support for Full Framework style .config files.

If you are running on an older .NET version, you will need to upgrade your application to .NET 10 before upgrading to Quartz 4.x.

If you are a library rather than an application

An application can be told to upgrade. An integration package that serves net8.0 and net9.0 consumers cannot, and has to reference Quartz 3.x for those targets and Quartz 4 for net10.0. That is a conditional PackageReference plus #if NET10_0_OR_GREATER at the call sites that differ, and it works only while the difference stays inside the library — the moment your own public surface would differ per target framework, a separate net10.0-only package or dropping the old targets is the answer, not a deeper #if.

Embedding Quartz in a Library has the csproj fragment, the honest limit, and the table of renames a real port hit.

Package Changes

The first error you will see

dotnet add package Quartz in a 3.x application takes the latest version, which is 4.x. The three packages that were merged into it are still in the project file, they reference Quartz with no upper bound, and so the build ends up compiling against Quartz 4.x and a 3.x Quartz.Extensions.DependencyInjection, Quartz.Extensions.Hosting or Quartz.Serialization.SystemTextJson beside it. Eight type names exist in both, so the first thing the compiler says is not about any API you have to change:

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 instead, naming both assemblies.

Neither is a migration step of its own. Remove the three package references, as the section below already says; both errors go with them, and what is left is the real work.

Quartz.Extensions.DependencyInjection, Quartz.Extensions.Hosting, and Quartz.Serialization.SystemTextJson have been merged into the main Quartz package. You can remove these package references from your project:

- <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 one of the merged assemblies 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 those four ids — 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 package that replaced them, a readme, and no assembly at all.

You still remove them. They exist for one thing you cannot do by hand, which is let a dependency bot get to 4.x. A bot that updates Quartz together with any of these as one group resolves that group to the newest version every member has, and until 4.0.1 that was 3.20.1 — so the bot closed the 4.0.0 pull request it had already opened as superseded and landed 3.20.1 with green checks, and the consumer's only signal that 4.0 existed disappeared. With the empty packages there, the group resolves to 4.x, the upgrade pull request is the one that stays open, and the reference is yours to delete in it.

Because they carry no assembly they cannot cause the CS0433 above. A 3.x one still can, so an upgrade that leaves an old version pinned is not made safe by their existence.

The two 3.x packages that are not published this way are Quartz.OpenTracing and Quartz.OpenTelemetry.Instrumentation. Neither has a 4.x package to depend on, so there is nothing an empty one could point at, and publishing it would say "you are up to date" to a reference that has to go. What replaces both is Quartz's own activity source and meter — see OpenTelemetry Integration and the two sections below.

Quartz.OpenTracing is dropped and has no 4.x release. It consumed the DiagnosticSource events that 4.x replaced with System.Diagnostics.Activity, and the OpenTracing project itself is archived. Remove the package reference and the AddQuartzOpenTracing call, and subscribe to Quartz's activity source and meter directly — 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 at all — silently. Remove that reference too, and add AddSource(QuartzInstrumentation.ActivitySourceName); see OpenTelemetry.Instrumentation.Quartz.

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

Quartz.Aspire is new

Nothing to migrate: it is a new package with no 3.x counterpart, listed here because this is where the package list lives.

Quartz.Aspire is the client integration for Aspire. It turns an Aspire connection name into a persistent job store: the driver delegate for the database behind that name, connections taken from a DbDataSource the container already holds, the scheduler's health check, and Quartz's two telemetry signals named to the OpenTelemetry pipeline your ServiceDefaults project built.

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

It takes no Aspire.* package dependency — IHostApplicationBuilder is the whole of its contract — so it works in any generic-host application and is not tied to Aspire's release cadence. There is no hosting integration: the AppHost still declares its database resources itself. See Aspire Integration for every setting it reads from Aspire:Quartz, and Running Quartz under Aspire for what the call expands to.

One of those settings decides something the rest of Quartz leaves off by default, so it is worth reading before the first run:

The health check is in Quartz, not Quartz.AspNetCore

Quartz.AspNetCore carries <FrameworkReference Include="Microsoft.AspNetCore.App" /> for the HTTP API, a framework reference reaches the nuspec, and so a worker on a dotnet/runtime image that referenced the package for the health check alone failed to start (#3532). The check reads IScheduler.Status and probes the job store, and never wanted ASP.NET Core for either, so it moved into the core package. It registers on the standard IHealthChecksBuilder, as it always did.

In 3.x the check had no registration of its own: AddQuartzServer from Quartz.AspNetCore registered the hosted service and the health check together, and the only choice on offer was the tag list. In 4.0 each is called by its own name, and neither one is in Quartz.AspNetCore:

See AddQuartzServer is AddQuartzHostedService for the split itself. What matters here is the package: if the check was the only reason your project referenced Quartz.AspNetCore, that reference can go.

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

Keep Quartz.AspNetCore if you also serve the HTTP API or the dashboard; it keeps its framework reference for those. MapHealthChecks, and the HealthCheckOptions.ResultStatusCodes mapping that decides what a degraded scheduler answers over HTTP, are ASP.NET Core's and stay documented on ASP.NET Core Integration.

Documentation pages that moved

The documentation was reorganised alongside the API. The old URLs redirect, so an existing bookmark still arrives somewhere useful, but if you keep links to these pages in a wiki or a runbook, retarget them:

The two anchors that were linked from outside the site — #h-hash-for-load-distribution and #building-cron-expressions-programmatically — travelled with the cron material and resolve on Cron Expressions.

Upgrading a running deployment

The map at the top of this guide is a reading order for the code: six passes over the API, in the order it is worth working through them. This section is the other question — the order to do things in when what you are upgrading is a deployment, with a database somebody depends on and nodes that are currently running. Every step links the page that owns it; nothing here is new.

Two of the seven happen while you are still on 3.x, and they are the two that are painful to discover afterwards.

1. Get off binary serialization, on 3.x. .NET removed BinaryFormatter and 4.x cannot read a blob written by it. The conversion needs BinaryObjectSerializer, which exists on 3.x and not here, so it is a 3.x task by construction — 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 is the one that 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 happily, and it rejects them while materialising the row — so a surviving expression fails the read of the trigger rather than only its next firing. The SQL to find candidates, and the honest caveat that several of its clauses are over-wide, are in Before you upgrade.

3. Decide what the window is. Either stop the cluster, or accept that a 3.x node and a 4.0 node will run against one set of tables for as long as the rollout takes. A mixed 3.x and 4.0 window is what has been checked about that state and what has not — including the one thing not to do during it, which is let a 4.0 node write a calendar.

4. Run the mandatory migration script. schema_30_to_40_upgrade_<database>.sql — one file per database, guarded throughout, safe to run twice, and safe to run with 3.x nodes still firing: Database Schema Migration. It is mandatory even for a database that took every optional 3.x migration going, because 4.x validates the schema and QRTZ_PAUSED_JOB_GRPS is new. The index set is the other file in that folder, and it is step 7. Schema before nodes, always: an old node tolerates a new schema and 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 done gradually — Configuration here, and the whole key table in Legacy property keys. Two things to read before the first start rather than after it: Defaults that changed, where an application that never named its scheduler stops seeing its own rows, and Silent behaviour changes.

6. Start 4.0. It validates that every table it will read exists and names the missing one if not. It reads the job type names 3.x stored — SimpleTypeLoader maps the renamed types, and a type of your own that moved is an alias you declare, in Type loader. Then 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 the optional half of the upgrade, in a file of its own precisely so that this step is one command rather than an instruction to run part of a file: Listing indexes, the reshaped acquisition index and the dropped misfire index. Run it top to bottom. It is deferred because it drops indexes a 3.x node's statements may still be driving scans from — the misfire index is the one 3.x sweeps misfires with — and because it 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 state you should be in when this is done.

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 each of these at startup and disabled the corresponding feature when it was missing. 4.x removed those probes and assumes all of them exist, so this 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 every row an upgrade brings across reads as "no retry policy" and nothing has to be backfilled. They are in the 4.0 script because 4.x no longer probes for columns: a column added after 4.0 ships would be a required column, and so a mandatory migration in the middle of a major version. The names are on AdoConstants as ColumnRetryPolicy and ColumnRetryAttempt.

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

It mirrors QRTZ_PAUSED_TRIGGER_GRPS, and it is what makes JobGroup.Paused truthful on the ADO store. A group can be paused while it holds no jobs, so there is no row on QRTZ_JOB_DETAILS to hang a flag on — the trigger side made the same call for the same reason. At startup 4.x validates that every table it will read exists, and QRTZ_PAUSED_JOB_GRPS is one of them, so this migration is mandatory even for a 3.x database that took every optional migration going.

That check is a SELECT 1 per table and a SELECT <column> … WHERE 1 = 0 for each column this migration adds to a table 3.x already had, so a database that skipped it is refused before the scheduler starts, with the column and this script named in the message. What the check cannot see is a column's shape: a hand-built table whose column is the wrong type or width still starts cleanly and fails later, on the first statement that binds it, with whatever your provider says. Run the script in full rather than section by section, and if a startup succeeded but a firing failed with a raw provider error, the column definitions are the first thing to check.

ProvisionSchema() is not a way around this. Before it creates anything it asks whose schema this is: a table it needs that is already there and short of a column it needs was made by something that is not 4.x, so a 3.x database is refused rather than half-completed. Creating the one table 4.x added and leaving the columns it added missing would produce a scheduler that starts, reports itself provisioned, and then fails every acquisition for ever.

A paused job group does not survive the upgrade, and cannot: 3.x's ADO store records nothing when it pauses one — its IsJobGroupPaused returns a hard-coded false and PauseJobs only pauses the individual triggers — so there is nothing for the migration to put in QRTZ_PAUSED_JOB_GRPS. The triggers that were paused stay paused, so no job starts running that was not running before; what is lost is the group's pause, so a trigger added to that job group after the upgrade is born running. Paused trigger groups are unaffected: they were already a QRTZ_PAUSED_TRIGGER_GRPS row on 3.x and migrate with the rest of the schema.

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

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

That writes the group's row to QRTZ_PAUSED_JOB_GRPS, which is what makes JobGroup.Paused and IsJobGroupPaused answer truthfully — and from then on the pause is imposed on the jobs added to that group afterwards, so a trigger stored for one of them is born PAUSED. An equality matcher records a group that holds no job at all, so the call is also how you pause a group before anything is deployed into it. Both stores behave that way on 4.x; see The two job stores answer the same way.

database/migrations/4.0/ holds two files per database, and they are run at two different moments:

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

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.

See Database Schema Changes for the full 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 index set with the statements 4.x issues. Two of the additions matter most 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 no existing index serves those ordered scans. These are optional — the queries work without them, but each page becomes a scan plus a sort. Add them if you list jobs or triggers from a large schema. They are in the fresh-install scripts for every dialect already.

It also drops indexes that are a leftmost prefix of a wider one, or that no 4.x statement can drive a scan from. PostgreSQL gets the largest change: several of its indexes omitted SCHED_NAME, which is the leading column of every predicate Quartz issues, so they could not serve a single-scheduler lookup at all.

The acquisition index is reshaped (optional)

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

Acquisition orders by NEXT_FIRE_TIME ASC, PRIORITY DESC, so an index carrying both directions lets the engine take the first entry instead of reading every due trigger and sorting it: against 100,000 triggers with 5,000 due, one acquisition on SQL Server goes from 21.6 ms and 20,395 logical reads to 0.6 ms and 8. MISFIRE_INSTR keeps a backlog of misfired triggers from costing a table lookup per row skipped. The statement, and every acquisition contract around it, is unchanged — this is DDL alone. Firebird's indexes take one direction for the whole index, so it keeps the 3.x shape; see Database Schema for the numbers and the MySQL and Oracle footnotes.

If you built a 4.0 preview schema before this landed, re-run schema_30_to_40_indexes_<database>.sql. The index name did not change, so the script drops it before recreating it; a guarded CREATE INDEX on its own 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):

It led with MISFIRE_INSTR, which the misfire sweep and the counting peek that precedes each pass both compare with <> -1 — a predicate no B-tree can seek past, so the index could only ever be entered on SCHED_NAME. Reshaping the acquisition index above gave it the two equalities, the range and the residual those two statements actually want, and measured plan by plan on all four engines that had the misfire index, no optimizer picks it for either statement (#3608, #3656). MySQL alone appeared to, because MySQLDelegate named it in a FORCE INDEX hint; that hint now names the acquisition index. What was left is an index maintained on every trigger write and read by nothing.

The order inside the file is the precondition. The reshape above is in the same file and comes first, so a schema still carrying the three-column acquisition index is brought to the 4.x shape before this drop runs, and no schema is ever left with neither index. Run the file top to bottom, and re-run it as often as you like — every statement in it is guarded.

3.x reads this index, which is the other half of why 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

Almost none of them did. Every option that carried a default on 3.x carries the same one on 4.x — the thread pool's size, the ADO store's misfire threshold and misfire batch, the retry intervals, the table prefix, the cluster check-in interval, the hosted service's two switches. If a value matters to you and you set it, nothing here applies.

Three effective defaults did change, and they change for one group of users only: those who never configured Quartz at all. StdSchedulerFactory.Initialize() seeded them from an embedded quartz.config that 4.x does not read, so a scheduler built by new StdSchedulerFactory() or GetDefaultScheduler() — and nothing else — was running on them.

Handing the 3.x factory properties always bypassed the file, so new StdSchedulerFactory(properties) and AddQuartz already fell back to the typed defaults. See The quartz.config file is no longer read.

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

Silent behaviour changes

Most of this guide is about code that stops compiling, which is the easy half: the compiler says where to look. This section is the other half — calls that still compile and now do something different. Read it before the first run of the upgraded application rather than after it.

Reading job data

Five of these are in one place, because 3.x had two overlapping accessor sets and 4.x kept the shorter names with the longer set's semantics. If you called GetIntValue, GetBooleanValue and friends, nothing here moved for you; if you called GetInt and GetBoolean, all of it did.

• The indexer throws on a missing key. map["absent"] returned null on 3.x. On 4.x it goes straight to the backing dictionary and throws KeyNotFoundException, on both JobDataMap and SchedulerContext. The "read an optional entry" idiom has to become TryGetValue or a TryGet… accessor.
• GetString no longer throws. 3.x threw KeyNotFoundException for an absent key and InvalidCastException for a value that was not a string. 4.x returns null for both, so a mistyped key and a wrongly-typed value are indistinguishable from "no value".
• The typed accessors throw a different exception for an absent key. GetInt, GetDouble, GetBoolean and the rest threw KeyNotFoundException on 3.x and throw InvalidCastException on 4.x. A catch (KeyNotFoundException) around one stops catching.
• GetBoolean reads anything that is not "true" as false. 3.x used Convert.ToBoolean, so a stored "1" or "yes" threw InvalidCastException. 4.x compares against "true" case-insensitively and succeeds, so a flag stored as "1" used to fail loudly and now quietly reads as off. TryGetBoolean reports success for it too.
• Strings are parsed with the invariant culture. GetInt, GetLong, GetDouble, GetFloat and Get<decimal> used the current culture when the stored value was a string. On a comma-decimal culture "3.14" used to read as 314 and now reads as 3.14. The reverse case is the one to check your stored data for: "3,14" used to read as 3.14 and now throws InvalidCastException from every numeric accessor — none of them allows a group separator, precisely so that a comma written as a decimal point cannot be read as one and answer 314. The new reading is the correct one for data written by an invariant-culture writer, and it is still a different number from the one the job saw yesterday.
• Get<DateTime> parses with DateTimeStyles.RoundtripKind, so a stored 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 the json alias expanded to the Newtonsoft serializer, with a logged warning that the name was ambiguous. On 4.x json and stj both resolve to SystemTextJsonObjectSerializer, and nothing warns. A configuration file carried over verbatim therefore changes which serializer writes and reads the store's blobs, which is a different payload shape and a different set of registered trigger and calendar serializers. Spell it newtonsoft if Newtonsoft is what you meant.
• Both serializers refuse a job data value they cannot read back, at write time rather than at the next read, 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 is a change to 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 reads only its own, so this is invisible on a clean cut-over and fatal in a mixed window — see A mixed 3.x and 4.0 window.
• The formerly optional columns are required, and an unmigrated schema fails at the first trigger load or store with a provider-level missing-column error rather than at startup — 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 what the ADO store does in six places — see The two job stores answer the same way.

Lifecycle and telemetry

• Standby() after Shutdown() throws instead of silently pausing something already stopped — 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 are visible wherever trigger data is: 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

EndTimeUtc means one thing on 4.x, for every trigger type: it is the last instant at which the trigger may fire, so a fire time exactly equal to it is one the trigger fires and the first instant after it is where the schedule stops. That is what Java Quartz's AbstractTrigger has always documented — "the time after which the trigger will not fire" — and on 3.x the types disagreed about it. Three of them change:

A simple or calendar-interval trigger whose EndAt lands exactly on one of its fire times therefore fires one more time than it did on 3.x, and a daily-time-interval trigger whose EndAt lands between two of them fires fewer. Move the end time a second off the boundary to keep the old count.

TriggerFireTimes.ComputeBetween inherits the rule, because it bounds the walk by handing the window's end to the trigger as its EndTimeUtc: its to is inclusive, for every trigger type, and a fire time landing exactly on it is listed.

Ordering

• JobKey and TriggerKey compare ordinally, where 3.x compared with the current culture, so any sorted listing of keys comes out in a different order — see Key<T> moved to Quartz and is immutable.

Null arguments raise ArgumentNullException

Every IScheduler member does, reading as well as mutating — GetJobDetail, GetTrigger, GetTriggerState, GetTriggersOfJob, GetCalendar, the three Exists overloads and the six Query* members included. beta.1 brought the mutation members under the rule and left the reads as they were, which is two contracts on one interface with nothing to tell a caller which member is which; a read that was handed a null used to fault wherever the null was first dereferenced, which for a store-backed read is inside the store.

CronExpression.ResolveHash's two overloads are aligned too: they raised the base ArgumentException while the constructor and Parse on the same type raised ArgumentNullException. ArgumentNullException derives from ArgumentException, so an existing catch still catches.

IScheduler's mutation members raise ArgumentNullException, naming the parameter, where 3.x raised SchedulerException("JobDetail cannot be null") from ScheduleJob(null, trigger) and its neighbours. That was Java parity and it was undocumented, so a caller writing catch (ArgumentNullException) caught nothing while one writing catch (SchedulerException) around a scheduling call was swallowing its own bug along with the scheduler's failures. The new behaviour is what the SchedulerQueryExtensions methods on the same type have always done. RescheduleJob raised ArgumentException, of which ArgumentNullException is a subclass, so a catch there still catches. The <exception> tags on IScheduler say all of it, along with which members refuse what — 3.x had two of them over 65 members and 4.0 has ninety-seven.

Between the alphas and beta.1

Every correction made between one 4.0 pre-release and the next is now written into the section it belongs to, as one statement about 3.x and 4.0. The build-by-build list — which pre-release introduced each of them, and what an application already running one has to change — is Appendix: if you ran a 4.0 pre-release.

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

Worth stating, because the reasonable fear is that everything moved. These were checked against both branches and are identical: every misfire instruction's numeric value, so a MISFIRE_INSTR column carried over still means what it meant; TriggerState's existing values, with Executing appended; the misfire computation of every trigger family; the merge order and content of MergedJobDataMap; the rule that [PersistJobDataAfterExecution] writes back only a map that was modified; the lock handler a store picks for itself; StringOperator's matching; and the effective default of Shutdown(waitForJobsToComplete).

Configuration

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

Flat keys still work

If you configure Quartz from appsettings.json or a NameValueCollection of quartz.* keys, that keeps working. The keys are translated into the typed options, and both spellings of a setting always produce 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) check the bag the same way QuartzSchedulerBuilder.UseProperties always has: a quartz.* key Quartz does not read throws SchedulerConfigException at registration instead of being silently ignored, and a key 4.0 stopped reading is reported by name with the replacement. That is the commonest shape a 3.x application arrives in, so it is the one the advice is written for — quartz.jobstore.type differs from quartz.jobStore.type by one letter and used to turn a database-backed scheduler into an in-memory one without a word.

Set quartz.checkConfiguration to false to allow keys of your own. The IConfiguration overloads are still unchecked, because flattening a section invents quartz.* keys whether Quartz reads them or not.

A property key without the quartz. prefix is refused

The check above is on the bag handed to AddQuartz. The other way into that bag is services.Configure<QuartzOptions>(…), and it was not checked at all. QuartzOptions.Properties holds the flat quartz.* keys and QuartzPropertyBridge is its only reader, so a key without that prefix is provably read by nobody — and unlike a misspelling, it has no symptom at all: the scheduler runs as if the application had said nothing. An IValidateOptions<QuartzOptions> now refuses one, at host startup along with the rest of the options validation:

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

The commonest way to produce such a key is services.Configure<QuartzOptions>(section) against a section written for the 3.x QuartzOptions, which was a dictionary — a section already named Quartz does not supply the prefix, so Quartz:Properties:scheduler.instanceName lands as scheduler.instanceName. Note that the check cannot catch the whole of that mis-bind: a section whose keys match no property on QuartzOptions binds to nothing at all, and an options instance that came out empty is indistinguishable from one nobody configured. What is decidable is the keys that did arrive, and that is what is checked. Bind the section with AddQuartz(configuration) — the call that understands its shape — rather than with Configure<QuartzOptions>.

Unlike the registration-time check, this one does not compare the key against the ones Quartz reads: a configuration section is flattened into this bag with every sub-section turned into a quartz.* key whether Quartz reads it or not, so the stricter check would fail an appsettings.json holding settings for something else. quartz.checkConfiguration = false turns it off too.

A property bag is any dictionary

NameValueCollection is a .NET Framework type from the <appSettings> era, and requiring it at the front door made every caller who already had a dictionary build one to get in. The parameter is now IEnumerable<KeyValuePair<string, string?>> — the shape Dictionary<string, string?>, IReadOnlyDictionary<string, string?> and QuartzOptions.Properties all already have, and the one AddInMemoryCollection takes.

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

A NameValueCollection still goes in unchanged, in one call. It is exactly what a 3.x application holds — StdSchedulerFactory took one — so both UseProperties and AddQuartz keep an overload for it that forwards to the primary shape.

KeyValuePair<TKey, TValue> is a struct, so IEnumerable<KeyValuePair<string, string>> is not convertible to IEnumerable<KeyValuePair<string, string?>>. A Dictionary<string, string> whose values are genuinely never null therefore needs one conversion:

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

AddQuartz(services, properties) also copies the bag now, as UseProperties always has. The registration phases read it from closures that run later, some only when the container resolves options, so a caller that reused its own collection could reconfigure the scheduler long after AddQuartz returned.

Interrupting jobs on shutdown is one setting with four answers

QuartzSchedulerOptions.InterruptJobsOnShutdown and InterruptJobsOnShutdownWithWait were two booleans, one for a shutdown that waits for running jobs and one for a shutdown that does not. They were never independent — together they answered a single four-way question, and setting one without thinking about the other was the easy mistake, because InterruptJobsOnShutdown = true reads as "yes, interrupt" and means "only when not waiting".

They are replaced by ShutdownJobInterruption, an enum with all four answers spelled out:

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

Configuration files need no change. Both flat keys still work and map onto the enum by the table above, and Scheduler:InterruptJobsOnShutdown: true in appsettings.json still means what it meant: the typed binder no longer knows that name, but every section is also flattened onto its quartz.* key, and the property bridge reads it there. Scheduler:ShutdownJobInterruption: "Always" is the new spelling, and binds directly.

A setting stops wearing a verb

IPersistentStoreBuilder.AcceptEnlistedTransactions() was exactly ConfigureStore(options => options.AcceptEnlistedTransactions = true) — one assignment, no side effect — while the other nineteen AdoJobStoreOptions settings, UseDbLocks and StoreJobDataAsStrings among them, are set through ConfigureStore like everything else. A reader of the interface reasonably concluded that the settings with verbs were the important ones.

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

The option, the configuration key quartz.jobStore.acceptEnlistedTransactions and the JobStore:AcceptEnlistedTransactions section entry are all unchanged. UseClustering() keeps its verb: it genuinely does more than one assignment, setting 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 is unchanged: quartz.jobStore.useProperties still sets StoreJobDataAsStrings. In appsettings.json the section entry follows the option, so JobStore:UseProperties becomes JobStore:StoreJobDataAsStrings — the old spelling still works, because every section is also flattened onto its quartz.* key and read there.

The persistent store builder says which thing it configures

Three members of IPersistentStoreBuilder did not follow the conventions the rest of it set.

Configure was a bare verb inside a callback that already has ConfigureScheduler and ConfigureOptions<TOptions> in scope, so it said nothing about which of the things in reach it configured. UseDataSourceName and UseDataSource were two names for one concept, and naming a data source is the string overload of defining one. UseDriverDelegate was the only registration on the builder without a Func<IServiceProvider, T> overload — UseConnectionProvider, UseSerializer, UseLockHandler and UseTriggerPersistenceDelegate all had one — which made a dialect that needs anything from the container the one part of the store that could not be built from it.

  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 all say what they said, so only code that calls these methods has anything to change.

The hosted service's extension point is its four hooks

QuartzHostedService.StartAsync and StopAsync are no longer virtual. They maintain a private list of schedulers and an internal startup task, so an override that did not call base left the schedulers bound to the repository with nothing able to shut them down — a failure that surfaces at process exit, long after the code that caused it.

The four lifecycle hooks StartingAsync, StartedAsync, StoppingAsync and StoppedAsync stay virtual; they are no-ops that exist for nothing else, and they are what #2386 and #2522 asked for. Work in an overridden StartAsync moves into StartingAsync or StartedAsync, and work in StopAsync into StoppingAsync or StoppedAsync. What a subclass was reaching into StartAsync for is now a member of its own: protected IReadOnlyList<IScheduler> Schedulers, a snapshot of the schedulers the service is running.

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

Every configurable component Quartz ships published its settings twice: once on an options type bound from configuration and validated, and once as public settable properties on the component itself, assignable on a live instance with nothing saying which wins or when. The component-side setters are internal now, leaving the options type as the one public way:

The two shipped row-lock handlers keep their retry knobs, but as init-only properties rather than setters: SelectForUpdateLockHandler has MaxRetry and RetryPeriod, and UpdateRowLockHandler has RetryPeriod — it gained one, having previously hard-coded a second. Set them at construction, or through quartz.jobStore.lockHandler.maxRetry / .retryPeriod, which the binder still writes.

Flat-key configuration is unaffected. quartz.plugin.<name>.<property> and quartz.jobStore.lockHandler.<property> write the component directly through reflection, and that binder now binds non-public setters — so every string configuration that worked keeps working, and only the code path that bypassed the options type is closed.

UseStructuredJobLogging and UseStructuredTriggerLogging gain the configure delegate their non-structured siblings always had.

Two collections stop being assignable, for the reason QuartzOptions.Properties never was — one configure callback must not be able to discard what another added, and the configuration binder needs no setter to bind into a non-null collection:

- 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

DataSourceOptions.Provider is a string naming an ADO.NET driver description, and the eight names Quartz ships one for were discoverable only from a documentation table or by reading a property file. They are constants now — DataSourceOptions.Providers.SqlServer, .Npgsql, .MySql, .MySqlConnector, .Oracle, .Sqlite, .SystemDataSqlite, .Firebird — and the UseSqlServer / UsePostgres / … extensions pass them rather than repeating literals.

The property stays a string: the set is not closed, since a driver Quartz knows nothing about is describable through UseGenericDatabase. The values are unchanged, so a configuration file naming one of them is unaffected.

The standalone builder reads a configuration section

QuartzSchedulerBuilder.UseConfiguration(IConfiguration) is new, and is the standalone counterpart of AddQuartz(configuration): it binds the typed options, reads a Schedule section, and translates the flat quartz.* keys, exactly as the hosted path does.

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

QuartzConfigurationHelper — whose one public method existed for that flatten-then-configure sample — is internal. UseProperties(NameValueCollection) is unchanged and is still the way in for a bag you built yourself, from a properties file or from environment variables.

Two scheduler thread settings were dead and are gone

The scheduling loop is a long-running Task, not a Thread, so neither of these ever did anything in 4.0 — one named a thread that does not exist, the other tried to stop a thread that does not exist from keeping the process alive.

Both keys are in the removed-key table, so a properties bag that still carries one is told why rather than told it is unknown.

The setting that does still matter is the job store's, and it is renamed to say what .NET calls it:

The flat key quartz.jobStore.makeThreadsDaemons is unchanged and still sets it. It governs the misfire handler and the cluster manager, which are the only real threads Quartz creates — so it is now the whole answer to "do Quartz's threads hold my console application open".

PerformSchemaValidation became SchemaProvisioning, which has a third position

A persistent store can now create its own schema (#3531), which the old flag had nowhere to say. The check and the creation are one decision — a store that may create its schema obviously validates it too — so they are one setting with three positions rather than two flags that can contradict each other.

The flat key quartz.jobStore.performSchemaValidation still works and still means what it meant: true bridges to Validate and false to None. quartz.jobStore.schemaProvisioning is the new key and takes a member name — None, Validate or CreateIfMissing, case-insensitively. A file carrying both is decided by the new key, since it is the only one of the two that can express the third position.

CreateIfMissing only ever creates: no object is altered and none is dropped, so it is safe to leave on against a schema that already exists and cannot turn a mis-typed TablePrefix into data loss — though it will happily create a second, empty schema under the mis-typed one. It is equally not an upgrade: a schema that has every table but is missing a column a later release added is left exactly as it is. database/migrations/ is still what moves a schema forward, and the 3.x → 4.0 upgrade is still mandatory.

It is not the default, because creating tables needs DDL permission that a production database is usually right not to grant. When the account has none, the failure names the fresh-install script for your database and says to run it and drop back 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, and names the script by overriding protected virtual string? SchemaResourceName. The six shipped delegates each name their own, and the lookup walks the base chain nearest first — so a delegate that derives from one of them to change a statement or two inherits that dialect's script and needs no override, while one that overrides the name still wins. A delegate that names no script anywhere in its chain throws when asked to provision, saying so, rather than reporting success and creating nothing.

Code-first configuration is typed

Settings that used to be 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 are the same words as the configuration keys, so Quartz:Scheduler:MaxBatchSize and options.MaxBatchSize are the same setting said two ways.

Data sources no longer need a name

A scheduler has one job store and therefore one database, so there is no name to invent:

  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, and each gets its own services.

The quartz.config file is no longer read

Nothing is loaded from disk any more. A quartz.config file next to your application — or named by the quartz.config environment variable — is ignored, and so is the copy of it Quartz used to ship as an embedded resource. A scheduler is configured by the properties you hand to QuartzSchedulerBuilder.UseProperties, by an IConfiguration section passed to AddQuartz, or in code through the container.

The three settings the embedded file supplied are not defaults any more either. They were seeded by StdSchedulerFactory.Initialize(), which is the only entry point that ever read the file, and which is gone with the factory — see StdSchedulerFactory is gone:

Note these were never the defaults for AddQuartz or for new StdSchedulerFactory(properties) in the first place: handing the factory properties always bypassed the file, so those paths fell back — and still fall back — to the typed option defaults. Set them explicitly if you want the other values.

The one thing the file was still needed for was describing an ADO.NET driver Quartz ships no metadata for. That now has a code-first form, and the quartz.dbprovider.* keys themselves still work — they just arrive through IConfiguration or a NameValueCollection like every other key:

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 for the full description. 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 to hold a scheduler's jobs and triggers as well as its flat keys. It was the pivot the whole configuration model turned on; now that settings are typed options, the only things left in it were the legacy keys and the one thing that was never configuration at all. The keys moved to a Properties dictionary, and jobs and triggers became a per-scheduler registration like every other part of a scheduler.

  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 as one, which also gives it constructor injection:

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

Because the keys are a property rather than the object itself, a section of flat keys no longer binds onto QuartzOptions directly — it would bind Quartz:Properties:*. Pass the section to AddQuartz, which reads the keys where they have always been and binds the typed options from the same section:

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

Jobs and triggers are added through the builder. The overloads taking an IServiceProvider cover the case the options callback used to be needed for:

- 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 used to read and write schedName — an ADO.NET column key that nothing reads — so a scheduler name set through it was accepted and then silently ignored. It is gone along with SchedulerId and MisfireThreshold; see QuartzOptions lost its three typed settings.

Removed

Deferred configuration

The AddQuartz overloads taking an IServiceProvider are gone. They existed to reach services while configuring, which the options pattern already does:

- services.AddQuartz((q, provider) =>
- {
-     var connectionString = provider.GetRequiredService<IConfiguration>().GetConnectionString("Scheduler");
-     q.UsePersistentStore(store => store.UseSqlServer("default", connectionString));
- });
+ var connectionString = builder.Configuration.GetConnectionString("Scheduler");
+ services.AddQuartz(q => q.UsePersistentStore(store => store.UseSqlServer(connectionString)));

For an option that genuinely depends on a service, use the options pattern directly:

services.AddOptions<AdoJobStoreOptions>()
    .Configure<IMyService>((options, service) => options.TablePrefix = service.TablePrefix);

Listeners and plugins do not need this at all: they are registered services, so the container injects their dependencies.

SPI changes

If you implement IJobStore or ISchedulerPlugin yourself, they take their collaborators through constructors now instead of being handed them afterwards.

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

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

Take what you need — ISchedulerSignaler, ITypeLoader, TimeProvider, IOptions<QuartzSchedulerOptions> — through your constructor. The identity is the one thing a constructor cannot carry, for the reason If you implement IJobStore gives. What remains in Initialize is work that has to happen before the scheduler runs and cannot be done while constructing, such as verifying a database schema.

Options arrive as the scheduler's own, whichever of the three interfaces you ask for. IOptionsMonitor<QuartzSchedulerOptions> and IOptionsSnapshot<QuartzSchedulerOptions> work as well as IOptions<>: CurrentValue and Value are the options of the scheduler your component belongs to, Get(name) answers for the name you pass, and OnChange reports your scheduler's changes and not another's.

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

No process-global scheduler or connection state

SchedulerRepository.Instance and DBConnectionManager.Instance are gone. The repository is an ordinary container registration now, which means a scheduler is only visible in the repository belonging to the container that built it:

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

The connection manager did not become a container registration — it was one, holding a copy of what the container already knew, and it is removed outright. Registering a connection provider is a store configuration call, and reading one back is container resolution:

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

See The connection manager is gone for the full picture.

The observable consequence is that schedulers built different ways no longer find each other. Given a scheduler registered with AddQuartz and another built by a QuartzSchedulerBuilder in the same process:

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

If you were relying on that reach — typically to find a scheduler from code that had no reference to the factory that created it — register the scheduler with AddQuartz and inject IScheduler, ISchedulerFactory or ISchedulerRepository instead. If you genuinely need one repository across several entry points, register your own instance before calling AddQuartz; every Quartz registration is TryAdd, so yours wins:

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

A QuartzSchedulerBuilder owns the container it creates, so its repository holds only the schedulers it built. StdSchedulerFactory.GetSchedulerRepository() and GetDbConnectionManager() went with the class; resolve ISchedulerRepository from the container instead, and a scheduler's IDbProvider from the same container under the scheduler's name as the service key.

StdSchedulerFactory is gone

The properties-based factory has been removed. It was the last construction path that was not the container: it parsed quartz.* strings, loaded types by name, set properties by reflection, and built a scheduler of its own. Since 4.0 it did none of that itself — it built a service collection, handed the properties to the same translation layer AddQuartz uses, and resolved the scheduler from the container like everything else. What was left was a second front door onto one hallway, plus 47 public constants whose only purpose was to spell keys that a configuration file spells anyway.

Flat quartz.* keys are not going away. What changed is which type you hand them to:

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

UseProperties feeds the same translator, so every key means exactly what it always did, including the quartz.checkConfiguration check that rejects a misspelled key. Configuration written in code wins over the properties whichever order the two are applied in: property-derived options are applied before anything the builder was told, and implementations the properties name are registered after — options being last-wins and registrations first-wins, the same rule AddQuartz follows.

Two behaviors did not survive, because they lived in Initialize() rather than in the properties:

• The quartz.* environment-variable overlay. new StdSchedulerFactory() with no arguments read every quartz.* environment variable. Nothing does that now. Use IConfiguration with AddEnvironmentVariables(), which is the ordinary way to say it, and pass the section to AddQuartz or flatten it yourself into the NameValueCollection you hand to UseProperties.
• The embedded quartz.config defaults. A factory constructed with no properties used to start from instanceName = DefaultQuartzScheduler, threadCount = 10 and misfireThreshold = 60000. A builder given no properties starts from the typed option defaults instead — InstanceName QuartzScheduler, MaxConcurrency 10, and an in-memory MisfireThreshold of 5 seconds. Set them explicitly if you were relying on the old values. Note that this was never the behavior of new StdSchedulerFactory(properties) either, which always bypassed the file.

IsSupportedConfigurationKey is gone with the class, so a configuration carrying keys of your own can no longer be allowed by subclassing the factory. Set quartz.checkConfiguration to false instead.

GetDefaultScheduler() is gone too. It returned a process-wide scheduler from a process-wide factory, which stopped being a coherent idea when the repository became the container's — 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 strings are unchanged. This table is here so a Ctrl+F for the constant you used finds the key to write instead, and the typed option that is usually the better answer.

Three more constants existed in 3.x and had already gone before this release, listed here because a 3.x configuration is the one most likely to still name them:

Every removed member

The factory was also a set of override points, and a 3.x application that subclassed it was usually reaching for one of them. Each had a reason that the container now covers directly.

The builder surface says each thing once

Three members were spellings of a member beside them, and the audit that found them ruled on the rest of their families at the same time — the reasoning lives on the members, and AGENTS.md lists the sets that were counted and left alone.

ScheduleJob's store path is now chosen by ScheduleJobOptions.Replace rather than by which overload was called: not replacing goes through IJobStore.ScheduleJob exactly as before, so that member keeps its caller and a store's span and metric names for the ordinary call are unchanged, while replacing still goes through IJobStore.ScheduleJobs because over-writing a job and its trigger has to be one operation under one lock. An explicit new ScheduleJobOptions() therefore takes the plain path now, which is the same store outcome and the 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 callback AddQuartz takes, and hands it the same IQuartzBuilder. There is one configuration API with two front doors: AddQuartz for an application that has a container, QuartzSchedulerBuilder for one that does not, and the callback in between reads identically either way.

- 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();

Everything on IQuartzBuilder — jobs, triggers, calendars, listeners, plugins, execution limits — and every extension a package contributes is available to the callback, which is the point. The builder itself declares five members and no more: Create(configure), Build(), BuildScheduler(), UseConfiguration(IConfiguration) and the two UseProperties overloads. It re-declares nothing, so nothing can fall behind what IQuartzBuilder grows.

The callback is optional, exactly as AddQuartz()'s is, so a scheduler described entirely by configuration or by flat keys is still Create().UseConfiguration(section) or Create().UseProperties(properties).

Services and SchedulerName are IQuartzBuilder's and are read off the callback's argument, as q.Services and q.SchedulerName. If you ran a 4.0 pre-release that let a chain be written directly on QuartzSchedulerBuilder, see Appendix: if you ran a 4.0 pre-release.

Build() returns something you can dispose

Build() used to return ISchedulerFactory while handing back an object that owned a container, so every caller that wanted to shut it down had to cast to a type the type system never mentioned. It now returns StandaloneSchedulerFactory, which is an ISchedulerFactory and is also IAsyncDisposable and IDisposable:

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

Prefer await using: disposal shuts the scheduler down, which is asynchronous work that Dispose() can only block on. A caller that never disposes behaves as it always did — the scheduler runs until the process ends.

Two members moved the other way, from the standalone builder onto IQuartzBuilder, so that a scheduler registered with AddQuartz can also be given a part that was built rather than configured:

IScheduler is IAsyncDisposable

IScheduler now implements IAsyncDisposable, so a scheduler can be scoped with await using instead of a try/finally that remembers to shut it down:

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

Disposing releases what that instance owns, which is not the same thing for every scheduler:

Disposal is idempotent: disposing a scheduler that is already shut down does nothing. It is deliberately the non-waiting shutdown — await using means "stop this when the block ends", not "drain gracefully". Call Shutdown(waitForJobsToComplete: true) yourself when running jobs should be allowed to finish; disposing afterwards is then a no-op.

IScheduler only inherits IAsyncDisposable; it does not redeclare DisposeAsync. An earlier 4.0 preview did, with new ValueTask DisposeAsync(), which forced every implementation of the interface to carry a member the base interface had already asked for. An IScheduler of your own implements IAsyncDisposable.DisposeAsync and nothing else changes — the method that satisfied the redeclared one satisfies this too.

A container holding a scheduler is disposed asynchronously

This is the one change that can surface as a runtime error. ServiceProvider.Dispose() throws when a singleton it created implements only IAsyncDisposable, so a container that resolved an IScheduler has to be disposed with await using:

- using var provider = services.BuildServiceProvider();
+ await using var provider = services.BuildServiceProvider();

Applications hosted by IHost need no change — the host already disposes its container asynchronously, and AddQuartzHostedService shuts the schedulers down before that anyway. This is about a container built by hand, which is mostly tests.

A scheduler's lifecycle is one value

IScheduler.IsStarted, IScheduler.InStandbyMode and IScheduler.IsShutdown are gone. One SchedulerStatus Status replaces all three:

public enum SchedulerStatus
{
    Unknown,        // a scheduler that could not be asked - a remote one that did not answer
    Created,        // built, never started
    Running,        // firing triggers
    Standby,        // started once, stood down, can be started again
    ShuttingDown,   // Shutdown() is running
    Shutdown        // down for good; a new scheduler replaces it, this one never runs again
}

The three booleans mapped onto it exactly, so every call site has a mechanical replacement:

Those rows are the faithful translations, and two of them are worth reading twice. IsStarted stayed true after a shutdown — it meant "Start has been called at some point", not "is running now" — so code that used it as "is running" was already wrong and should say Status is SchedulerStatus.Running. And InStandbyMode was true for a scheduler that had never been started at all, which is why Created exists: both fire nothing, but only one of them has ever run and has a RunningSince.

SchedulerMetadata follows, for the same reason:

- if (metadata.Shutdown) { … }
- else if (metadata.InStandbyMode) { … }
- else if (metadata.Started) { … }
+ switch (metadata.Status) { … }

The two producers derive it the same way now. They did not before: StdScheduler.GetMetadata set Started from "has ever been started" while HttpScheduler.GetMetadata set it from "is running now", so the same scheduler described itself differently depending on which side of an HTTP call you asked from. RunningSince is unchanged.

The transitions are honest about themselves

Reducing the state to one value made four behaviours that were only true of some of the booleans have to become true of the value. A transition that does not happen is not announced:

The last one is a listener-visible change, inherited from Java, and it is the one to check for. A listener that counted SchedulerInStandbyMode to detect "the scheduler stopped firing" should be counting SchedulerShuttingDown as well — it is raised by every shutdown, as it always was. The full sequence over a start, a standby and a shutdown is now exactly:

SchedulerStarting → SchedulerStarted → SchedulerInStandbyMode → SchedulerShuttingDown → SchedulerShutdown

Status becomes Shutdown at the end of the shutdown, once the plugins and the job store are down, so a scheduler that is draining its running jobs reads ShuttingDown for as long as it takes — and it reads Shutdown even when a plugin or job store threw on the way down, because the shutdown is claimed once and cannot be run again to finish the job.

A scheduler that has begun shutting down refuses work exactly as a shut-down one does, and ISchedulerFactory.GetScheduler() refuses to hand it back for the same reason. It is still listed by ISchedulerRepository and by the dashboard while it drains, which is what ShuttingDown is for.

The health check reports the state it found

AddQuartzHealthChecks() read IsStarted alone, which made a scheduler in standby healthy (it had been started once) and a shut-down one fall through to the store probe, where the failure was reported as a connectivity problem. It reports the state it actually found instead:

The check also no longer throws when it is registered for a default scheduler in a container that has only named ones: it reports Unhealthy and says to call AddQuartzHealthChecks() on the scheduler's own builder.

A clustered scheduler is also asked when this node last checked in. The check-in loop runs on its own timer, so a node whose cluster manager has wedged still fires, still answers a store query and still reports Running — while its peers, to whom it looks dead, recover its triggers. A last check-in older than QuartzHealthCheckOptions.ClusterCheckinTolerance times that node's own configured check-in interval now reports Degraded, naming the node and how late it is. The tolerance is a double defaulting to 3; set it to null or 0 to make no such query. Nothing is read on an unclustered scheduler, so an in-memory or single-node store is unaffected.

Clustering is configured in one place

AdoJobStoreOptions no longer carries Clustered, ClusterCheckinInterval and ClusterCheckinMisfireThreshold. Those three said the same thing as UseClustering(…) and ClusteringOptions, so a scheduler had two places to be clustered from and they could disagree. ClusteringOptions is now the one place, and whether a store is clustered is something it reports rather than something you can also set on it.

ClusteringOptions' two intervals are no longer nullable — UseClustering() with no arguments turns clustering on without touching them, because it configures the options object rather than assigning a copy over it.

Code-first configuration is unchanged:

store.UseClustering(cluster =>
{
    cluster.CheckinInterval = TimeSpan.FromSeconds(10);
    cluster.CheckinMisfireThreshold = TimeSpan.FromSeconds(20);
});

The flat keys are unchanged as well — quartz.jobStore.clustered, quartz.jobStore.clusterCheckinInterval and quartz.jobStore.clusterCheckinMisfireThreshold all still work, and so does the JobStore:Clustered spelling in appsettings.json, because AddQuartz reads every section as flat keys too. What is new is the hierarchical spelling that matches the options type:

{
  "Quartz": {
    "JobStore": {
      "Clustering": {
        "Enabled": true,
        "CheckinInterval": "00:00:10",
        "CheckinMisfireThreshold": "00:00:20"
      }
    }
  }
}

AdoJobStoreOptions validation lost the rule that UseDbLocks must be on when Clustered is: it can no longer see both settings, and it never needed to, since every path that enables clustering enables database locking with it and a store with an explicit lock handler of its own — the Redis one, say — was never wrong to leave UseDbLocks off.

The SQLite extension methods swapped names

- store.UseSQLite(connectionString);          // System.Data.SQLite
+ store.UseSystemDataSqlite(connectionString);

- store.UseMicrosoftSQLite(connectionString); // Microsoft.Data.Sqlite
+ store.UseSqlite(connectionString);

The short name goes to the driver you should reach for, which is the same rule UseMySql and UseMySqlConnector already followed, and the same spelling Entity Framework Core uses for the same choice. The provider names themselves — what a quartz.dataSource.<name>.provider key says — are unchanged, so nothing in a configuration file has to move.

A data source is defined, referred to, or handed over

There were five ways to say where a job store's connections come from, and two of them said the same thing. UseDataSourceConnectionProvider() is gone; it existed only to set DataSourceOptions.UseRegisteredDataSource, and being a method it also had to be called in the right order to take effect.

  q.UsePersistentStore(store =>
  {
-     store.UsePostgres(db => db.Provider = "Npgsql");
-     store.UseDataSourceConnectionProvider();
+     store.UsePostgres(db => db.UseRegisteredDataSource = true);
  });

What is left says four different things:

Where connections come from is a property of the data source, so the first three are said in DataSourceOptions alongside ConnectionString and ConnectionStringName, and UseRegisteredDataSource wins over both. UseConnectionProvider is the one that is not a data source setting, because it does not describe a database — it hands over the object that reaches one. It is therefore also the one method here that replaces rather than defers: it beats whatever UseSqlServer and its siblings registered, whichever order the two were called in, and names this store's data source so it needs no UseDataSource call of its own.

AddDataSourceProvider() went with it

The two always travelled together. AddDataSourceProvider(), on the configurator, registered DataSourceDbProvider in the container as the IDbProvider to use; UseDataSourceConnectionProvider(), on the store, then named it as that data source's connection provider. Two calls, in two different places, that had to agree with each other to do anything. Both are gone, and UseRegisteredDataSource does the whole job — the data source builds its own DataSourceDbProvider around the DbDataSource it resolves from the container:

  services.AddQuartz(q =>
  {
-     q.AddDataSourceProvider();
      q.UsePersistentStore(store =>
      {
-         store.UsePostgres(db => db.Provider = "Npgsql");
-         store.UseDataSourceConnectionProvider();
+         store.UsePostgres(db => db.UseRegisteredDataSource = true);
      });
  });

Registering the DbDataSource itself is still yours to do — services.AddNpgsqlDataSource(…), or whatever your provider offers. What is no longer yours to do is wiring it up to Quartz.

UseRegisteredDataSource asks for the container's one unkeyed DbDataSource, which was the only shape 3.x's AddDataSourceProvider() could express either. A container holding several — a scheduler per tenant — says which one it means with DataSourceServiceKey, and a data source built rather than registered goes in DataSourceFactory:

services.AddNpgsqlDataSource(tenantA, serviceKey: "tenant-a");
services.AddQuartz("tenant-a", q => q.UsePersistentStore(store =>
    store.UsePostgres(db => db.DataSourceServiceKey = "tenant-a")));

Both are settable from code only — a service key is any object and a factory is a delegate, so a configuration binder can produce neither. Both imply UseRegisteredDataSource, so neither needs a connection string.

Commands on this path are now made by the connection rather than built from the driver description. A DbDataSource configures the connections it hands out — NpgsqlDataSource attaches its type mappers, its logging and its composite type registrations — and a command reaches those through the connection it belongs to, which a command constructed by reflection and given a connection afterwards does not. The connection-string path is unchanged.

QuartzOptions lost its three typed settings

QuartzOptions is the flat quartz.* property bag. Three of its members were typed settings that existed nowhere else in it, each reading and writing a key that has a typed option of its own, so they were a third spelling of a setting that already had two.

- services.Configure<QuartzOptions>(options => options.SchedulerName = "core");
+ services.AddQuartz(q => q.ConfigureScheduler(options => options.InstanceName = "core"));

MisfireThreshold also had a round-trip problem of its own: it stored a TimeSpan as a string of whole milliseconds, so a value with sub-millisecond precision did not read back as it was written.

Properties, ToProperties() — which is what ToNameValueCollection() became, see "A property bag is any dictionary" — and Scheduling stay. Scheduling is the exception that proves the rule — its three directives say how a configured schedule is applied to a scheduler rather than how a component is configured, and they have no options type of their own to bind onto, so this is where they live.

Scheduling is get-only, like Properties. Options callbacks run in order over one instance, so assigning a fresh SchedulingOptions threw away whatever Quartz:Scheduling — or an earlier callback — had already set, with nothing to show for it. Set the properties instead; the configuration binder needs no setter to bind into a non-null complex property.

- services.Configure<QuartzOptions>(options => options.Scheduling = new SchedulingOptions { IgnoreDuplicates = true });
+ services.Configure<QuartzOptions>(options => options.Scheduling.IgnoreDuplicates = true);

AddJob registers the job with the container

AddJob<T>(), AddJob(type, …) and ScheduleJob<T>() now register the job type as a scoped service, with TryAdd semantics.

Before, they described the job to the scheduler and nothing else. The job factory resolved the job from the container and fell back to ActivatorUtilities when it found no registration, so a job whose constructor the container could not satisfy was never noticed at startup: ValidateOnBuild — which the host turns on by default in the Development environment — had never heard of the type. The failure arrived at fire time instead, as a JobInstantiationException, by which point the trigger had fired, the job had not run, and every trigger of that job had been moved to TriggerState.Error (discussion #3211).

services.AddQuartz(q => q.AddJob<SendReportsJob>(j => j.WithIdentity("send-reports")));

// now throws when the container is built:
// Unable to resolve service for type 'IReportStore' while attempting to activate 'SendReportsJob'

Two things follow from this.

A job you register yourself keeps your registration. The lifetime, factory or implementation type you chose wins, because Quartz's registration is a TryAdd. Registering the same job with AddJob twice is harmless for the same reason. If you were registering your jobs explicitly to get startup validation, that line is now redundant, but it is not wrong:

- services.AddScoped<SendReportsJob>();   // no longer needed for validation
  services.AddQuartz(q => q.AddJob<SendReportsJob>(j => j.WithIdentity("send-reports")));

Scoped is the lifetime the job factory uses. It opens a dependency injection scope per fire, resolves the job from it, and disposes the scope when the job returns — so a job may take scoped dependencies such as a database context. If a job of yours has to be a singleton, register it as one yourself; it must then be thread-safe and must not capture scoped dependencies.

A job type that is an interface or an abstract class is not registered, since the container could not construct it. Jobs named by an XML or JSON schedule are not registered either — nothing describes them to the container — so those still fail at fire time if their dependencies are missing.

A registered job may not take a scheduler's own parts by constructor. IScheduler, ISchedulerFactory, IJobStore, IThreadPool and IOptions<QuartzSchedulerOptions> belong to one scheduler. A job that injected one of them used to be activated through its scheduler's view of the container and was handed that scheduler's; a registered job is now resolved from the container like any other service, which resolves them unkeyed — the default scheduler's, or nothing at all in a container holding only named schedulers. Rather than leave a job silently holding another scheduler's collaborators, the constructor is refused when the host starts, with a message naming the job and the parameter:

Job type ArchiveJob is registered on scheduler 'acme', and its constructor takes ISchedulerFactory
schedulerFactory — a part that belongs to one scheduler. …

Take the scheduler from IJobExecutionContext.Scheduler, which is the scheduler actually running the job; take IJobExecutionContextAccessor in code the context is not handed to; or, where the job really has to be constructed with something of its scheduler's, register it with AddJobType<T>(factory) — below — and resolve that part by key inside the factory, which is not examined. A job type the container does not hold is unaffected: it is still activated by the job factory and still receives its own scheduler's parts.

AddJobType gives one scheduler its own build of a job type

New in 4.0, and only interesting when a container holds more than one scheduler. AddJob<T>'s registration is unkeyed and TryAdd, so under a scheduler per tenant the first registration is what every scheduler gets — different implementations or different lifetimes for one job type were not expressible. AddJobType says the registration belongs to this scheduler:

services.AddQuartz("acme", q =>
{
    q.AddJobType<ReportJob, AcmeReportJob>();                        // a different implementation
    q.AddJobType<AuditJob>(ServiceLifetime.Singleton);               // a different lifetime
    q.AddJobType<ExportJob>(sp => new ExportJob(sp.GetRequiredKeyedService<IExportSink>("acme")));
    q.AddJob<ReportJob>(j => j.WithIdentity("report"));
});

The registration is made under the scheduler's service key, or unkeyed for the default scheduler — whose registrations are the unkeyed ones, so an empty key would not be the same thing. The job factory looks there first and falls back to the container's unkeyed registration, so a scheduler that was given nothing of its own resolves exactly as before, and the default scheduler resolves in one lookup as it always has. Nothing about a single-scheduler application changes.

The lifetime defaults to ServiceLifetime.Scoped — the lifetime the job factory is built around — and is named through an overload rather than an optional parameter. That is not a style choice: a default value that is an enum from an assembly which only ships in a shared framework is a metadata constant whose type coverlet's Cecil resolver cannot resolve, and it silently drops the entire containing assembly from the coverage report.

Naming a job type by string says so under trimming

Quartz is marked trimmable in 4.0, and the job-type APIs say what they need. Nothing here is a source or binary break — the attributes are annotations — but an application published with PublishTrimmed now gets told things 3.x never mentioned.

The typed spelling carries the requirement. JobBuilder.Create<T>(), JobBuilder<TJob>.OfType<T>() and OfType(Type), AddJob<T>(), AddJob(Type, …), AddJobType<T>(), AddJobType<TJob, TImpl>(), AddTrigger<TJob>(), ScheduleJob<T>(), TriggerBuilder.Create<TJob>(), new JobType(Type) and the implicit Type → JobType conversion all declare [DynamicallyAccessedMembers(PublicConstructors | PublicProperties | Interfaces)] on the job type — what a job factory constructs, what a JobDataMap binds onto, and where [DisallowConcurrentExecution] may be inherited from. The generic JobBuilder<TJob>, TriggerBuilder<TJob>, IJobConfigurator<TJob> and ITriggerConfigurator<TJob> declare the same on their type parameter. PublicMethods, which some of these declared in earlier 4.0 previews, is gone: a kept property keeps its accessors, and IJob.Execute is reached through the interface.

If you pass a Type variable rather than a typeof or a generic argument, the compiler now asks the same of your code, which is the annotation doing its job:

- static IJobDetail Build(Type jobType) => JobBuilder.Create().OfType(jobType).Build();
+ static IJobDetail Build(
+     [DynamicallyAccessedMembers(
+         DynamicallyAccessedMemberTypes.PublicConstructors
+         | DynamicallyAccessedMemberTypes.PublicProperties
+         | DynamicallyAccessedMemberTypes.Interfaces)] Type jobType)
+     => JobBuilder.Create().OfType(jobType).Build();

The name-taking spelling is [RequiresUnreferencedCode]. The JobType(string) constructor and the explicit string → JobType cast report IL2026 in a trimmed build, because a type resolved from a string cannot be proven reachable. So does the job_scheduling_data XML loader. Prefer the typed spelling, or root the type yourself with a trimmer root descriptor. See Publishing Trimmed and Native AOT for what a trimmed application has to do.

DbMetadata.ConnectionType, .CommandType and .ParameterType carry annotations too, saying what DbProvider does with each: constructs connections and commands, and reads the properties the metadata names. A UseGenericDatabase callback that sets them from typeof(...) already satisfies that.

One behaviour change came with it. An ADO.NET store's trigger acquisition decided [DisallowConcurrentExecution] with a check that did not look at interfaces, while IJobDetail.ConcurrentExecutionDisallowed did. A job that inherited the attribute from an interface was therefore serialized when it fired but not when it was acquired, so a batch could hold two of its triggers and the second was released again. Both now ask the same question.

A named type is checked against IJob before it is constructed

A job type given as a Type — AddJob(Type), new JobType(Type) — was always checked for IJob. A job type given as a name was not, and the first thing that established it was a job at all was the cast that followed construction: the container was asked for the type (and GetService constructs whatever is registered for it), then ActivatorUtilities, so the type's static constructor, module initializer and instance constructor had all run — with the scheduler scope's services injected — before anything refused.

The check now runs first, in the job factory, in the activator cache and in TypeActivator. A firing of a job whose type is not an IJob fails with a JobInstantiationException naming the type instead of an InvalidCastException, and nothing of that type runs. If you catch InvalidCastException around a firing for this reason, catch SchedulerException instead.

A job type rename is declared as a map

A persistent job store keeps the job's type as text, in QRTZ_JOB_DETAILS.JOB_CLASS_NAME. Renaming the class, moving its namespace or moving it to another assembly therefore breaks every row that names it, and on 3.x the supported answer was an ITypeLoadHelper of your own: a class to write, register and keep, for a one-line fact.

4.0 lets the fact be stated as a fact. TypeLoaderOptions.Aliases maps the name as it was stored to the name the type has now, and UseTypeLoader(configure) is the typed way to add one:

services.AddQuartz(q => q.UseTypeLoader(loader =>
    loader.Map("Acme.Jobs.NightlyReport, Acme.Jobs", typeof(NightlyRollupJob))));

The same map binds from configuration, so the rename can ship in appsettings.json with the deployment that performs it:

{
  "Quartz": {
    "TypeLoader": {
      "Aliases": {
        "Acme.Jobs.NightlyReport, Acme.Jobs": "Acme.Jobs.NightlyRollupJob, Acme.Jobs"
      }
    }
  }
}

The map is read by the loader Quartz ships, which is the one place a type name is resolved at run time — so it applies to JOB_CLASS_NAME, to jobs named in XML or JSON scheduling data, and to the quartz.plugin.<name>.type key. The flat keys naming a scheduler's own components are read while the service collection is still being built, before any options exist, and are not aliased. Keys are compared the way that loader already compares its own table of Quartz's 3.x → 4.0 renames: ordinal, matching either the whole name or the part of it before the comma that starts the assembly.

Two things are deliberate. An alias whose target names no loadable type fails options validation at startup, naming both halves of the entry, rather than surfacing later as a TypeLoadException that names the dead name and nothing about the mapping meant to save it. And nothing is ever written back: a job read under an aliased name still has the old spelling in its row, which is what makes an alias safe during a rolling deployment — the nodes still running the old build keep writing the old name while the new ones read it. Retiring an alias is still the SQL UPDATE in Job deserialization failures after refactoring, run once nothing is hitting it any more.

UseTypeLoader<T>() is unchanged and still replaces the loader outright, for a scheme rather than a list — a name resolved out of a plugin's AssemblyLoadContext, say. Replacing the loader takes the map with it, since the map is the shipped loader's.

The job scope is prepared without writing a job factory

ConfigureScope — the hook that prepares the dependency injection scope a job is built in, and the place an AsyncLocal is set for the job's dependencies to read — was reachable only by deriving from MicrosoftDependencyInjectionJobFactory, overriding a protected method, and registering the derived factory. That is a class and a registration to set one ambient value:

- public sealed class TenantJobFactory : MicrosoftDependencyInjectionJobFactory
- {
-     public TenantJobFactory(IServiceProvider serviceProvider) : base(serviceProvider) { }
-
-     protected override void ConfigureScope(IServiceScope scope, TriggerFiredBundle bundle, IScheduler scheduler)
-         => Tenant.Current.Value = bundle.JobDetail.JobDataMap.GetString("tenant");
- }
- services.AddQuartz(q => q.UseJobFactory<TenantJobFactory>());
+ services.AddQuartz(q => q.ConfigureJobScope(
+     (scope, bundle, scheduler) => Tenant.Current.Value = bundle.JobDetail.JobDataMap.GetString("tenant")));

The contract is the one the virtual method always had: it runs before the job is resolved, and it is synchronous so that an AsyncLocal set in it survives into Execute. Callbacks combine rather than replace, and the same delegate is JobFactoryOptions.ConfigureScope, which is per-scheduler like every other component's options. Overriding the protected method still works and still takes the delegate's place if the override does not call base.

The firing can be read without being handed it

New in 4.0: IJobExecutionContextAccessor, registered by AddQuartz as a singleton, is the firing the calling code is part of. It is for code that is not the job and cannot be handed an IJobExecutionContext — a scoped service, a logging enricher, a repository three calls below Execute. 3.x had no such thing, so an application that needed one wrote its own AsyncLocal and set it from a job factory:

- public static class Tenant { public static readonly AsyncLocal<string?> Current = new(); }
- services.AddQuartz(q => q.ConfigureJobScope(
-     (scope, bundle, scheduler) => Tenant.Current.Value = bundle.Trigger.Key.Group));
+ public sealed class TenantConnectionFactory(IJobExecutionContextAccessor accessor)
+ {
+     public string ConnectionString => connectionStrings[accessor.Current!.Trigger.Key.Group];
+ }

Current is set from the moment the execution context exists — before the trigger and job listeners are notified — until the job has been returned to the job factory, and is null at every other time, including on the scheduling thread. It travels with the ExecutionContext, so it survives await and is captured by Task.Run, and it can never be another firing's. Work a job leaves running past the end of its execution reads null rather than the finished context, since by then the job's scope has been disposed. There is no setter.

It does not replace ConfigureJobScope. The execution context takes the job instance, so it does not exist while the job is being constructed: anything that needs the tenant at construction time still gets it from the hook.

A job can take a typed input

New in 4.0, and purely additive: IJob<TInput> lets a job declare the type of the payload it is scheduled with, instead of digging it out of a stringly JobDataMap. 3.x had no such thing, so every framework that embedded Quartz wrote the same adapter job and payload-carrying context by hand.

- public sealed class SendEmailJob : IJob
- {
-     public ValueTask Execute(IJobExecutionContext context, CancellationToken cancellationToken = default)
-     {
-         SendEmail input = JsonSerializer.Deserialize<SendEmail>(context.MergedJobDataMap.GetString("payload")!)!;
-         // ...
-     }
- }
- trigger.UsingJobData("payload", JsonSerializer.Serialize(new SendEmail(to, subject)));
+ public sealed class SendEmailJob : IJob<SendEmail>
+ {
+     public ValueTask Execute(IJobExecutionContext context, SendEmail input, CancellationToken cancellationToken = default)
+     {
+         // ...
+     }
+ }
+ trigger.UsingInput(new SendEmail(to, subject));

The whole of the dispatch is IJob<TInput>'s default implementation of IJob.Execute, so the job factory, JobRunShell and the listeners still see an IJob and nothing closes a generic method over a runtime type — which is what keeps this working in a trimmed or native-AOT publish.

The API added. In Quartz: IJob<TInput>; SchedulerConstants.JobInput ("QRTZ_JOB_INPUT"); JobExecutionContextInputExtensions.GetInput<TInput>(this IJobExecutionContext) and TryGetInput<TInput>(this IJobExecutionContext, out TInput?); and JobInputBuilderExtensions.UsingInput<TJob, TInput> on JobBuilder<TJob>, TriggerBuilder<TJob>, IJobConfigurator<TJob> and ITriggerConfigurator<TJob>. In Quartz.Extensibility: IJobInputSerializer. In Quartz.Impl: SystemTextJsonJobInputSerializer, and a fourth optional IJobInputSerializer? inputSerializer = null parameter on the JobExecutionContextImpl constructor — the one existing signature that moved, and source-compatible because it is optional.

Where the payload lives. The value goes into the ordinary JobDataMap under SchedulerConstants.JobInput, and the scheduler serializes it to a string as the job or trigger is stored — so it survives StoreJobDataAsStrings, the System.Text.Json write gate, the Newtonsoft serializer, the binary blob column and the HTTP wire without any of them knowing about it. A trigger's input overrides a job's, which is the MergedJobDataMap rule everything else follows.

UsingInput is offered only on a builder for a job that declares an input; it is an extension method rather than a builder member because a method cannot constrain its own type's type parameter (CS0699). GetInput<TInput>() is an extension on IJobExecutionContext rather than a member for the same kind of reason: a member would break every hand-written context in the wild.

Two things to know. The input type is inferred from the argument's static type, so pass the type argument explicitly — UsingInput<SendEmailJob, SendEmail>(payload) — when the payload is held as a base type. And a [PersistJobDataAfterExecution] job whose detail carries the input writes it back after every firing; that is harmless, since it is already the string it will be read as, but an input that differs per firing belongs on the trigger.

Converting a job over a store that predates the input. An IJob<TInput> fails a firing that carries no input, by name, rather than running it with a default payload — right for a fresh application, and a trap for one whose store already holds triggers written by its 3.x self, whose payload is spread over flat JobDataMap keys with nothing under QRTZ_JOB_INPUT. A job that has to serve both shapes while those triggers drain stays an IJob and reads them apart with TryGetInput:

public ValueTask Execute(IJobExecutionContext context, CancellationToken cancellationToken = default)
{
    SendEmail input = context.TryGetInput(out SendEmail? typed) && typed is not null
        ? typed
        : new SendEmail(context.MergedJobDataMap.GetString("to")!, context.MergedJobDataMap.GetString("subject")!);

    // ...
}

TryGetInput answers false only when the key is absent; a value that is present and unreadable still throws, because corruption is not compatibility. GetInput<TInput>() cannot tell the two apart — a payload that read back as null and no payload at all are the same answer there.

Serialization. IJobInputSerializer is registered per scheduler, keyed by name like every other component, and defaults to SystemTextJsonJobInputSerializer built from the same SystemTextJsonSerializerRegistry as the store's IObjectSerializer. An application published trimmed or natively declares its payload types with SystemTextJsonSerializerRegistry.AddTypeInfoResolver, exactly as it declares a job data value type — there is no second registration to learn. See Job Data.

Scheduling a trigger can replace one atomically

New in 4.0, and purely additive: IScheduler.ScheduleJob has two more overloads, which take a ScheduleJobOptions and can therefore replace what is already stored.

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

On 3.x — and on the two existing overloads, which are unchanged — rescheduling under a key you may or may not already hold meant three round trips and a window:

- if (await scheduler.CheckExists(trigger.Key, cancellationToken))
- {
-     await scheduler.UnscheduleJob(trigger.Key, cancellationToken);
- }
- await scheduler.ScheduleJob(trigger, cancellationToken);
+ await scheduler.ScheduleJob(trigger, new ScheduleJobOptions { Replace = true }, cancellationToken);

The new form is one store operation under the store's own lock — SchedulerLock.TriggerAccess on an ADO store, the single lock on the in-memory one — so two nodes doing it at once cannot interleave into a schedule with the trigger deleted and not replaced. The job-and-trigger overload goes through the store's ScheduleJobs, so the job and its trigger are written together rather than under two locks.

options deliberately has no default on either overload. Giving it one would make scheduler.ScheduleJob(trigger) and scheduler.ScheduleJob(job, trigger) ambiguous between the pair.

A replaced trigger keeps its previous fire time. The ADO store has done this since #1834; the in-memory store cloned the incoming trigger and lost it, so the same code reported "never fired" on one store and a real time on the other. The in-memory store now carries the value over, and JobStoreContractTest pins it on every store — along with the rule that a trigger replaced into a paused group is still born paused, so an upsert is not a way to escape a pause. A caller who means to reset the history sets PreviousFireTimeUtc on the incoming trigger, which is honoured.

Over HTTP, POST /triggers/schedule takes a replace flag, HttpScheduler implements both new overloads, and the flag reaches the scheduler unchanged. A request that omits it behaves exactly as before.

A scheduler says which clock it keeps

New in 4.0: IScheduler.TimeProvider, a default interface member answering TimeProvider.System. Nothing has to implement it — a scheduler written outside this repository keeps compiling and reports what its triggers would have used anyway — and the schedulers Quartz ships answer better:

3.x had no way to ask. Code that builds a trigger for a scheduler had to reach for DateTimeOffset.UtcNow, so an application or a test running the scheduler on a clock of its own computed "in ten minutes" against a different clock from the one the scheduling loop compares the answer to:

- ITrigger trigger = TriggerBuilder.Create()
-     .StartAt(DateTimeOffset.UtcNow.AddMinutes(10))
-     .Build();
+ ITrigger trigger = TriggerBuilder.Create(scheduler.TimeProvider)
+     .StartAt(scheduler.TimeProvider.GetUtcNow().AddMinutes(10))
+     .Build();

It is also what a job rescheduling itself from inside Execute reads, as context.Scheduler.TimeProvider, and it is what the one-call ScheduleJob<TJob, TInput> overloads below use for their TimeSpan form and for the trigger they build.

A typed job can be scheduled in one call

Also new, on top of typed inputs: two extension methods on IScheduler that schedule one firing of a job with a payload and a time, and nothing else to build.

ValueTask<ScheduledOneOffJob> ScheduleJob<TJob, TInput>(this IScheduler scheduler, TInput input, DateTimeOffset at,
    OneOffJobOptions options = default, CancellationToken cancellationToken = default) where TJob : IJob<TInput>;

ValueTask<ScheduledOneOffJob> ScheduleJob<TJob, TInput>(this IScheduler scheduler, TInput input, TimeSpan delay,
    OneOffJobOptions options = default, CancellationToken cancellationToken = default) where TJob : IJob<TInput>;

They are the imperative twin of IQuartzBuilder.ScheduleJob<TJob>, which only ever existed for the firings an application declares at start-up. 3.x had nothing of the kind.

ScheduledOneOffJob firing = await scheduler.ScheduleJob<SendInvoiceJob, SendInvoice>(
    invoice, TimeSpan.FromDays(7),
    OneOffJobOptions.Replacing($"invoice-{invoice.CustomerId}") with { Group = invoice.CustomerId });

logger.LogInformation("Reminder {Trigger} scheduled for {At}", firing.TriggerKey, firing.FirstFireTimeUtc);

await scheduler.UnscheduleJob(firing.TriggerKey);

What the call answers with is ScheduledOneOffJob, a two-member readonly record struct: the TriggerKey of the firing — the handle to cancel it with, or to replace it by scheduling the same name again — and the FirstFireTimeUtc the store computed, which is what the ScheduleJob(trigger, options) overload it wraps returns and what a caller logging "scheduled for X" would otherwise have to infer from the time it asked for. It stays two members: everything else about the firing is a property of the trigger the key names.

One durable job per job type, many triggers. The job is stored once under SchedulerConstants.ScheduledJobKey<TJob>(), which is (typeof(TJob).Name, SchedulerConstants.ScheduledJobGroup) — a new reserved constant spelled "QRTZ_SCHEDULED" — and every call adds a trigger to it. That is the shape a message bus's Quartz integration converges on: a scheduled message is a trigger, so there is no job churn to pay for. The job is ensured with AddJob and Replace, which is idempotent and cluster-safe, and remembered per scheduler instance; a store that reports the job missing gets it put back and the firing retried once, so a cluster restore or an operator's delete does not turn into a permanent failure. The key is public because an integration with a second scheduling path — a recurring trigger it builds itself for the same job — has to point that trigger at the same job rather than add one of its own to a group it is told to stay out of.

OneOffJobOptions is named for what the call creates, not for the call: one off, one firing, one trigger. It carries what would otherwise be TriggerBuilder calls — Name, Group, Description, Priority, ExecutionGroup, MisfireInstruction — plus Replace, which it passes on to the store, and RequestRecovery, the one member that describes the ensured job: set it and that job is marked RequestsRecovery, so a firing interrupted by a hard shutdown is re-executed when the scheduler comes back. Because the job is ensured once per scheduler instance, the first call's value wins for the lifetime of the process — which is why it is a named boolean rather than a configuration delegate that would look as though it varied per call. Every member is optional, and default is "a one-shot trigger with a generated name, in this job type's own group". An overload that schedules a recurring job would have something else to say — a schedule, an end time, a calendar — and will get an options type of its own rather than nullable members here that mean nothing to a single firing. It is a different thing from ScheduleJobOptions, which describes a store operation and says only whether it may over-write.

OneOffJobOptions.Replacing(name) is its preset, and it is the one in the family that takes an argument. AddJobOptions.Replacing and its siblings are properties because Replace = true is the whole of what they say; here Replace alone would do nothing, because a firing with no name of its own is given a generated one and a generated name has nothing to replace. The name is what makes replacing mean something, so it is a parameter rather than something to remember to set afterwards. AddJobOptions gained the preset for its second flag at the same time — AddJobOptions.ReplacingAndStoringNonDurable, the twin of AddCalendarOptions.ReplacingAndUpdatingTriggers.

Name and Group are two loose strings rather than a TriggerKey, and that is deliberate: the two halves have different defaults — a generated name, a group named after the job type — and each is worth setting without the other. "Call it order-42, wherever such firings go" and "put it in this saga's group, any name will do" are both ordinary, and a key can express neither. The key exists once the trigger does, and the call answers with it.

SchedulerConstants.ScheduledJobKey<TJob>() is where the durable job's key is spelled. In the 4.0 previews it was SchedulerJobExtensions.ScheduledJobKey<TJob>() — a static that took no receiver, sitting in a class of extension methods, so every call site had to name the class anyway. It moved to sit beside SchedulerConstants.ScheduledJobGroup, which is the other half of the same convention.

The trigger group is the correlation axis: everything scheduled for one saga, one tenant or one conversation can share a group and be listed, paused or unscheduled together. Cancelling is UnscheduleJob(key); the durable job stays behind, one row per job type whatever the traffic. Mind the default when adopting these overloads inside something that already has a trigger-key contract: Group defaults to the job type's name, so an integration whose callers cancel with new TriggerKey(id) — the default group — must say Group = TriggerKey.DefaultGroup or its cancellation silently stops matching.

See One-Off Job.

A scheduled job links back to the trace that scheduled it

New in 4.0, and on by default: when a scheduling call is made inside an Activity, the scheduler records that activity's W3C trace context on the trigger, and the firing's Quartz.Job.Execute span carries an ActivityLink back to it. Nothing has to be configured, and no code changes.

3.x propagated nothing, so every integrator that cared reached into the trigger's JobDataMap and invented a key of its own:

- trigger.UsingJobData("traceparent", Activity.Current?.Id);   // and a job that read it back by hand
+ // nothing — the scheduler writes it, and the execute span links to it

A link, not a parent. A job scheduled for next Tuesday runs a week after the request that asked for it, quite possibly on another node. Making the firing a child of the scheduling span would produce a trace that stays open for a week, which no backend can render and no operator can read. The firing is its own trace root and the link is how you walk back — the shape OpenTelemetry gives an asynchronous producer and the consumer that eventually picks the work up. The span name is unchanged.

The API added. In Quartz: SchedulerConstants.TraceParent ("QRTZ_TRACEPARENT"), SchedulerConstants.TraceState ("QRTZ_TRACESTATE"), and QuartzSchedulerOptions.PropagateTraceContext, which defaults to true. There is no flat quartz.* key for it: nothing on 3.x did this, so there is no configuration to migrate — and LegacyPropertyKeys correctly rejects an invented one.

q.ConfigureScheduler(options => options.PropagateTraceContext = false);

Where it is written. On the trigger's data map, by the scheduler, at every entry point that stores a trigger — both ScheduleJob overload pairs, ScheduleJobs, both TriggerJob forms and RescheduleJob. A reschedule counts because it is the call that decided when the firing happens, so the link follows the move: a replacement trigger rebuilt from the original carries the original's data map, reserved keys included, and the new context overwrites the old one rather than being kept beside it.

UpdateTriggerDetails deliberately writes no trace context. It changes metadata on a trigger that stays scheduled and keeps its fire times, so the trace that asked for the firing is still the one that scheduled it — re-pointing the link at whoever later edited a description would make it say something false. (It does normalize a typed input in the map it is given, because that is about what a store can hold rather than about what scheduled anything.)

Two consequences worth knowing:

• Two more entries per trigger row. They are ordinary string job data, so they travel through StoreJobDataAsStrings, the System.Text.Json write gate, the Newtonsoft serializer, the binary blob column and the HTTP wire without any of them knowing about it — and they are visible in MergedJobDataMap, in the dashboard and in GET /triggers, like every other QRTZ_* reserved key. Turn the option off if that is not wanted.
• The trigger's map, never the job's. [PersistJobDataAfterExecution] writes back only the job's map, so the two never meet and a persisted job cannot carry a traceparent forward into its next firing.

A stale context is removed rather than kept. The scheduler stores the trigger object it was handed rather than a copy of it, so a trigger scheduled once inside a request and again outside one has the key removed on the second call. A stale link reads exactly like a true one, which makes leaving it the worst of the three answers.

Over HTTP it is free. POST /jobs/{group}/{name}/trigger and the scheduling endpoints run inside ASP.NET Core's own server span, so the request's trace reaches the trigger without Quartz.AspNetCore mentioning tracing at all.

See Observability.

A component of your own is chosen the same way a shipped one is

Three seams that had no code-first spelling at all, and one that only worked through a type-name string:

q.UseJobStore<MyJobStore>();                                   // built by the container
q.UseJobStore<MyJobStore, MyJobStoreOptions>(o => o.X = 1);     // with options of its own
q.UseJobStore(provider => new MyJobStore(provider.GetRequiredService<ISchedulerSignaler>()));

q.UseInstanceIdGenerator<HostNameInstanceIdGenerator>();

UseJobStore<T> is the seam for a store that keeps scheduling data somewhere Quartz has never heard of; UseInMemoryStore and UsePersistentStore remain the way to select the stores Quartz ships, since they configure them as well as choose them — and since those stores are internal, a shipped store is chosen by the call rather than by a type argument. UsePersistentStore<T>(configure) takes a persistent store of your own, and UseJobStore(IJobStore), which takes a store you built yourself, is unchanged.

UseInstanceIdGenerator<T>() replaces the pair of keys quartz.scheduler.instanceId = AUTO and quartz.scheduler.instanceIdGenerator.type, and it says both: choosing a generator sets GenerateInstanceId, because a generator that was chosen and then never called is configuration that says nothing. Only a clustered scheduler generates an id — the generator is not called otherwise — which is unchanged.

The <T, TOptions> shapes are sugar over ConfigureOptions<TOptions>: the options are declared as that scheduler's, so a component that takes IOptions<TOptions> under AddQuartz("reporting", …) is handed what was configured for reporting rather than the unnamed instance.

Listener matchers are a collection

The builder's nine listener overloads took params IMatcher<T>[]; they take params IReadOnlyCollection<IMatcher<T>>, which is what IListenerManager.AddJobListener and AddTriggerListener already took. Existing call sites are unaffected — loose arguments still bind, and an array is still a IReadOnlyCollection<T> — and a caller that holds a List<IMatcher<JobKey>> no longer has to call ToArray() on the way in.

AddQuartzHttpApi is registered on the service collection

The HTTP API serves every scheduler in the container through one set of endpoints, so it was never a scheduler's own setting; it just had nowhere else to be written:

- services.AddQuartz(q => q.AddQuartzHttpApi());
+ services.AddQuartzHttpApi();

The IQuartzBuilder form is gone rather than kept as a synonym: written inside AddQuartz(name, …) it read as that scheduler's API while configuring everybody's, and two of them with different ApiPaths were last-writer-wins with nothing to say so. QuartzHttpApiOptions stays singular for the same reason — ApiPath is a property of the process.

The route is named where the endpoints are mapped

MapQuartzHttpApi and MapQuartzDashboard take a route pattern, which is how the rest of ASP.NET Core reads — MapHealthChecks("/health") — and it puts the path with the application's other routes instead of in a registration callback somewhere else:

- services.AddQuartzHttpApi(options => options.ApiPath = "/ops/api");
- services.AddQuartzDashboard(options => options.DashboardPath = "/ops/quartz");
  …
- endpoints.MapQuartzHttpApi();
- endpoints.MapQuartzDashboard();
+ endpoints.MapQuartzHttpApi("/ops/api");
+ endpoints.MapQuartzDashboard("/ops/quartz");

Nothing is removed. QuartzHttpApiOptions.ApiPath and QuartzDashboardOptions.DashboardPath are still there and still the shape to use when the path comes from configuration, and the parameterless overloads read them. When both are given the pattern at the map site wins, being the more specific of the two. A pattern given there is held to the same rule as the option it overrides, and a bad one is an ArgumentException naming the parameter rather than an options-validation failure — by the time the endpoints are mapped, the validators have already run.

There is no MapQuartzDashboard(existingComponents, pattern): the dashboard page routes are fixed at /quartz when integrating with an application's own Blazor root, which is the same reason a custom DashboardPath is rejected in that mode.

The HTTP API and the dashboard will not serve anonymously by accident

Both surfaces can schedule a job whose type is a string the request carries, resolved later with Type.GetType — so with Quartz.Jobs on the probing path an endpoint anybody can reach is remote code execution rather than an information leak. 4.0 therefore refuses to start rather than serve one by omission.

A hosted lifecycle service enumerates the endpoints Quartz mapped, before the server binds its listener, and throws unless every one of them carries authorization metadata or an explicit AllowAnonymous(). A non-null AuthorizationOptions.FallbackPolicy satisfies it too, since that covers every endpoint that states nothing, and authorization on a MapGroup above the mapping counts. Registering the services without mapping anything is left alone. The message names all three fixes:

app.MapQuartzHttpApi().RequireAuthorization();                 // the whole surface
// or QuartzHttpApiOptions.SchedulerAuthorizationPolicy        // each scheduler on its own
// or QuartzDashboardOptions.AuthorizationPolicy
app.MapQuartzDashboard().AllowAnonymous();                     // deliberately open

AllowAnonymous() is a supported answer; what is not supported is saying nothing. Quartz authorizes and something else authenticates, so the application still registers the scheme — see Production hardening.

One builder covers the dashboard's pages and its hub

MapQuartzDashboard() returns an IEndpointConventionBuilder, where 3.x returned a RazorComponentsEndpointConventionBuilder. The dashboard is two sets of endpoints — the Blazor pages and the SignalR hub that streams the same data — and the old return type was the pages' builder alone, so MapQuartzDashboard().RequireAuthorization() protected the pages and left the hub open. In the overload taking an existing components builder it reached the host application's own pages as well. What comes back now is the dashboard's pages and its hub, and nothing else, so one RequireAuthorization() or AllowAnonymous() is the whole answer.

Code that called a member specific to RazorComponentsEndpointConventionBuilder on the result — a render-mode call, say — configures that on its own MapRazorComponents and passes that builder to the existingComponents overload instead.

A paged request is bounded by MaxPageSize

QuartzHttpApiOptions.MaxPageSize is 1000, and a take naming a number above it is a 400 naming the cap — ?take=2147483647 included. ?take=all names no number, so it is bounded by the cap rather than refused by it, and reports hasMore.

That asymmetry is what keeps the 3.x-compatible listings working: GetJobKeys and its neighbours ask for everything whether the answer is three rows or three million, and HttpScheduler turns a truncated answer to one of those into an exception rather than a short list. Set MaxPageSize to 0 to bound nothing.

A 500 says nothing about the server

The detail of a 500 is one fixed sentence — "The scheduler failed to handle the request. The failure is recorded in the server's log." — rather than the exception's message, which for a driver fault names the server, the database, the login or the constraint. The exception's type was never returned on that path; its message is now withheld too, and both keep being logged. QuartzHttpApiOptions.IncludeStackTraceInProblemDetails — the switch that already says "I am debugging this" — puts the real message back. A client matching on a 500's detail now matches on a constant.

A job's two attribute flags are nullable on the wire

concurrentExecutionDisallowed and persistJobDataAfterExecution are bool? rather than bool in every job body the API reads or writes, and in Quartz.Dashboard.Services.JobDetailDto. Present means the sender stated the flag; absent means "whatever [DisallowConcurrentExecution] and [PersistJobDataAfterExecution] on the type say", which is what JobBuilder has always done with a flag nobody set.

The old shape had no way to say "not stated", and JSON's default for a missing bool is false, so a well-formed POST …/jobs that simply did not mention concurrency stored a job its author had declared unsafe to run concurrently as safe to. A client that sent both fields is unaffected; one that omitted them now gets the attribute honoured.

The other half is on the way out: a job whose type the answering process cannot resolve reports both flags as null instead of failing the whole read. GET …/jobs/{group}/{name} used to answer 500 for such a job — permanently, for every caller — because the projection read an effective value and the lazy getter threw. That is the ordinary heterogeneous-cluster case as much as it is a bad type name.

Reading them off an IJobDetail in code is unchanged: IJobDetail.ConcurrentExecutionDisallowed is still bool, and now answers false for a type that cannot be resolved rather than throwing InvalidOperationException.

A job type name is never resolved by the contract types

JobDetailDto.AsIJobDetail() and JobDetailDto.Create() no longer resolve a job type name, in either direction, and JobBuilder.Build() no longer deduces the two attribute flags — JobDetailImpl does it lazily, when something asks and the type is at hand.

Two things follow. Quartz.HttpClient can schedule and add jobs whose type only the server has, which packages/http-client.md always promised and beta.1 could not do (InvalidOperationException: Job type … cannot be resolved); and a hostile or compromised server can no longer choose an assembly simple name that a client's runtime goes looking for. If you were relying on Build() to snapshot the attributes at build time — for instance by building a detail, unloading the assembly and reading the flags — read them before the assembly goes.

The persistent store does not resolve one outside firing either. A process that cannot load its job classes — the UseThreadPool<ZeroSizeThreadPool>() administration node, a web application that edits schedules without referencing the worker that runs them — reads, pauses, resumes, reschedules, updates, triggers, adds triggers to and deletes jobs on the stored name alone, and both attribute flags come from QRTZ_JOB_DETAILS.IS_NONCONCURRENT and IS_UPDATE_DATA rather than from the type. RescheduleJob is the call that used to fail — JobPersistenceException: Couldn't replace trigger: Could not load type 'Acme.Jobs.MessageCleanupJob, Acme.Jobs' — because it resolved the class in order to answer "may this job run concurrently?", and the row now answers that. Such a process therefore needs no ITypeLoader of its own, and the placeholder type 3.x required is no longer the way to get there; a placeholder was always a hazard, because whether it carried [DisallowConcurrentExecution] decided whether a replacement trigger was stored WAITING or BLOCKED for a job it was standing in for. Only the firing path resolves a job's class, and that runs where the job runs.

IScheduler.Interrupt is the one administration operation this does not reach: it is documented as not cluster aware, cancels the tokens of the firings running in the scheduler it is called on, and an administration node runs none. That is a property of the operation rather than of the missing assembly.

One shape per registration method

The AddJob / AddTrigger / AddCalendar grid had overloads that said the same thing twice, and optional parameters that made the no-argument calls ambiguous. Each method now has one pair of shapes: one taking a configurator, one taking a configurator and the IServiceProvider.

  var jobKey = new JobKey("awesome job", "awesome group");
- q.AddJob<ExampleJob>(jobKey, j => j.WithDescription("my awesome job"));
+ q.AddJob<ExampleJob>(j => j.WithIdentity(jobKey).WithDescription("my awesome job"));

The job type on AddTrigger<TJob> is what lets the trigger's job data name the job's properties. A trigger that only points at its job with ForJob has nothing to name, and AddTrigger with no type argument is that call — the 3.x spelling, unchanged.

The interface these methods extend is IQuartzBuilder, which is what 3.x called IServiceCollectionQuartzConfigurator. The AddQuartz overloads that handed the callback an IServiceProvider alongside it are gone with it: a container built while the container is still being described could only be a second, throwaway one. Ask for the service provider where it is actually used — each registration method has a shape that is given one, at the point where the container really exists:

- services.AddQuartz((q, serviceProvider) =>
- {
-     var schedule = serviceProvider.GetRequiredService<IOptions<SampleOptions>>().Value.CronSchedule;
-     q.AddTrigger(t => t.WithIdentity("custom").ForJob(jobKey).WithCronSchedule(schedule));
- });
+ services.AddQuartz(q =>
+ {
+     q.AddTrigger((serviceProvider, t) => t
+         .WithIdentity("custom")
+         .ForJob(jobKey)
+         .WithCronSchedule(serviceProvider.GetRequiredService<IOptions<SampleOptions>>().Value.CronSchedule));
+ });

AddCalendar takes the same AddCalendarOptions record that IScheduler.AddCalendar does, instead of two adjacent bools whose order was impossible to remember, and its first parameter is name rather than calendarName:

- q.AddCalendar<HolidayCalendar>("holidays", replace: true, updateTriggers: true,
-     cal => cal.AddExcludedDay(new DateOnly(2025, 12, 25)));
+ q.AddCalendar<HolidayCalendar>("holidays", new AddCalendarOptions { Replace = true, UpdateTriggers = true },
+     cal => cal.AddExcludedDay(new DateOnly(2025, 12, 25)));

Both the options and the configurator are optional in the type-based overload, so q.AddCalendar<HolidayCalendar>("holidays") is a valid registration of an empty calendar.

A calendar can be built from the container

Both generic AddCalendar<T> overloads are constrained where T : ICalendar, new() and construct the calendar themselves, so a calendar that needs a dependency — a holiday list read from a database, a clock, an options snapshot — could not be registered at all. There is a factory overload for that:

q.AddCalendar("holidays", serviceProvider =>
{
    AnnualCalendar calendar = new() { TimeZone = TimeZoneInfo.Utc };
    foreach (MonthDay day in serviceProvider.GetRequiredService<IHolidayList>().Days)
    {
        calendar.AddExcludedDay(day);
    }

    return calendar;
});

The factory is handed the scheduler-scoped IServiceProvider, so a calendar registered for a named scheduler is given that scheduler's parts rather than the default scheduler's, and it runs once, when the scheduler's content is resolved. AddCalendarOptions is the optional third parameter as it is on the other overloads. It is an IQuartzBuilder extension, so it reads the same inside QuartzSchedulerBuilder.Create(q => …).

Plugins are registered like listeners

AddPlugin had four shapes, one of which took the plugin's name first and the rest of which could not take a name at all. It now has the same three shapes as the listener registrations, each with an optional trailing name:

- q.AddPlugin("xml", provider => new XmlSchedulingDataProcessorPlugin());
+ q.AddPlugin(provider => new XmlSchedulingDataProcessorPlugin(), "xml");

The name is how the scheduler refers to the plugin and the name a quartz.plugin.<name>.* key configures it under — some plugins derive persisted job and trigger keys from it — so it is part of the deployment's identity rather than a label. Left unset, the plugin's type name is used, exactly as before.

A plugin implements only what it has to say

ISchedulerPlugin.Start and ISchedulerPlugin.Shutdown have default implementations that do nothing. Most plugins do all their work in Initialize — attaching a listener, registering a resolver — and had to write two empty members to say so:

  public sealed class MyPlugin : ISchedulerPlugin
  {
      public ValueTask Initialize(string name, IScheduler scheduler, CancellationToken ct = default) { … }
-
-     public ValueTask Start(CancellationToken ct = default) => default;
-
-     public ValueTask Shutdown(CancellationToken ct = default) => default;
  }

Nothing about the lifecycle changes: the scheduler still calls both, through the interface, at the same two moments. An existing plugin that declares them keeps working and needs no change. The plugins shipped here dropped every such member they had, which is the only visible effect in the public API — a member that did nothing is no longer on the concrete type. Call the plugin through ISchedulerPlugin if you were invoking one of those directly.

The two scheduling-data plugins have one surface

XmlSchedulingDataProcessorPlugin and JsonSchedulingDataProcessorPlugin read one schedule out of two file formats, and had drifted into two different types: one published ProcessFile and no Shutdown, the other a do-nothing Shutdown and no ProcessFile, and both published the settings that configure them as get-only properties. Their surface is now the same, and it is the two constructors plus what ISchedulerPlugin and IFileScanListener ask for:

Nothing here was writable from outside, so nothing that configured a plugin stops compiling. Code that read one of these properties is what changes, and the answer is the options rather than the plugin: IOptionsFactory<FileSchedulingOptions>.Create(schedulerName) is the same value from the place that decided it.

The FileNames/Files split stays, on purpose: FileSchedulingOptions.Files is a List<string> because that is what code and a configuration binder say naturally, and the plugin keeps a delimited FileNames string because quartz.plugin.<name>.fileNames is one. The join happens in UseXmlSchedulingConfiguration / UseJsonSchedulingConfiguration, and both plugins now agree about it.

Both also take a params string[] overload — q.UseJsonSchedulingConfiguration("~/quartz_jobs.json") — for the case every sample showed, which is one file and nothing else to say about it. It adds to Files rather than replacing it, so it composes with the callback form and with itself; rescanning and the two FailOn* settings still need the callback.

The container is not in the scheduler context

3.x's ServiceCollectionSchedulerFactory put the IServiceProvider into scheduler.Context["Quartz.ServiceProvider"], and a plugin that needed the container read it back out of there. 4.0 writes no such entry. Plugins and listeners are constructed by the container, so they take what they need by constructor — and a job takes its dependencies the same way:

- private IServiceProvider? services;
-
- public ValueTask Initialize(string name, IScheduler scheduler, CancellationToken cancellationToken = default)
- {
-     services = (IServiceProvider) scheduler.Context["Quartz.ServiceProvider"]!;
+ private readonly IMyService service;
+
+ public MyPlugin(IMyService service) => this.service = service;

The entry was Quartz's plumbing in a map that belongs to the application, and the HTTP API's GET …/schedulers/{name}/context answered 500 for every container-built scheduler because of it (#3408). That endpoint renders every value as text now, so a context entry of any type reads back.

Cross-cutting concerns run as middleware

A log scope, a tenant context, a metric or a translation of what a library throws has to surround the call to the job, and on 3.x nothing could. IJobListener is notification-only — it is told a job is about to run and told what it did, with the execution happening between the two notifications rather than inside them — so the only place left was a job that wrapped another job. That adapter is what ABP, Elsa and Brighter each ship, and asking for the seam has been open since 2021 (#988).

4.0 adds it:

public delegate ValueTask JobExecutionDelegate(IJobExecutionContext context, CancellationToken cancellationToken);

public interface IJobExecutionMiddleware
{
    ValueTask Invoke(IJobExecutionContext context, JobExecutionDelegate next, CancellationToken cancellationToken = default);
}

registered on the scheduler's builder in the three shapes listeners already have:

q.AddJobMiddleware<LogScopeMiddleware>();
q.AddJobMiddleware(provider => new MeteredMiddleware(provider.GetRequiredService<IMeterFactory>()));
q.AddJobMiddleware(new TenantScopeMiddleware());

Middleware is keyed per scheduler, so a named scheduler's is its own; it runs in registration order, outermost first; and the chain is composed once when the scheduler is built, so one instance serves every firing and per-firing state belongs in an AsyncLocal<T> or in the job's scope rather than in a field. A scheduler with no middleware has no pipeline at all, so nothing changes for an application that adds none.

It runs inside the execution span and the duration measurement — what a middleware costs is part of what the firing cost — and outside the run shell's exception handling, so a JobExecutionException a middleware throws is honoured exactly like one the job raised, RefireImmediately and all.

Nothing about listeners changed. They stay notification-only, VetoJobExecution stays the way to refuse a fire, and matchers stay a listener's way of choosing which jobs it hears about. The tutorial's Job Execution Middleware lesson has the whole of it, including which of the two a given concern belongs in.

JobInterruptMonitorPlugin is retired; a job timeout is middleware

The plugin's opt-in surface was two JobDataMap strings the compiler never saw — "AutoInterruptable" to enable it at all, "MaxRunTime" for a number of milliseconds whose unit was documented only by the parse — and behind them a monitor task scheduled per firing. The middleware seam is where that belongs, so JobInterruptMonitorPlugin, UseJobAutoInterrupt, JobAutoInterruptOptions and both keys are gone. The replacement is in the core Quartz package and is typed end to end:

The budget travels with the job type rather than with its stored data, which is why it moved to an attribute: [JobTimeout] is read the same way [DisallowConcurrentExecution] is, is inherited from a base class or an interface, and needs no schema column, no wire format and no migration of existing job data. Delete the two keys from any job or trigger data map that carries them — they mean nothing now.

One behaviour is deliberately different, and it is the point of the change. The plugin interrupted the firing and stopped there, which the run shell classifies as a completed execution: no JobExecutionException reached a job listener, and a trigger's retry policy was never consulted. The middleware interrupts through the same public IScheduler.InterruptFireInstance path and then raises a JobExecutionException naming the budget, so a timeout is an ordinary failure — visible to listeners, counted as an error, and retried by the trigger's RetryPolicy if it has one. A job that swallows its cancellation and returns normally is reported as timed out too.

What has not changed is that a job which ignores its CancellationToken cannot be stopped. That was the plugin's limit as well; CA2016 is the mitigation.

ShutdownHookPlugin is retired; the host already shuts the scheduler down

ShutdownHookPlugin subscribed to AppDomain.CurrentDomain.ProcessExit with an async void handler, so nothing awaited the shutdown it started: the process was free to exit part-way through, which is the opposite of the clean shutdown the plugin's name promised. ShutdownHookPlugin, UseShutdownHook and ShutdownHookOptions are gone.

QuartzHostedService is an IHostedLifecycleService, so the host stops every registered scheduler as part of its own shutdown and awaits it, inside HostOptions.ShutdownTimeout rather than in a handler the runtime abandons. It also shuts several schedulers down concurrently, which ProcessExit never did.

An application with no host has an exit path of its own — the end of Main, a Ctrl+C handler, the disposal of a scope — and that path can await the shutdown:

await using StandaloneSchedulerFactory schedulerFactory = QuartzSchedulerBuilder.Create().Build();
IScheduler scheduler = await schedulerFactory.GetScheduler();
await scheduler.Start();

// ... the application runs ...

await scheduler.Shutdown(waitForJobsToComplete: true);

3.x's Quartz.Server host already shut down this way and never used the plugin.

Registered schedulers can be listed without being started

ISchedulerFactory.GetAllSchedulers() — GetAllSchedulers() on 3.x too — lists the schedulers something has already created. It reads ISchedulerRepository, and a repository holds instances, so a scheduler nobody has asked for is not in it. Under a scheduler-per-tenant registration that meant there was no way to ask a container which tenants it knows about short of building every one of them, which is the opposite of what an operator wanted when they asked.

ISchedulerRegistry answers from the registrations instead, and is registered by AddQuartz, so any container with Quartz in it has one:

foreach (SchedulerRegistration registration in await registry.QuerySchedulers())
{
    Console.WriteLine($"{registration.Name}: {registration.Status?.ToString() ?? "not created"}");
}

public sealed record SchedulerRegistration(string Name, SchedulerOrigin Origin, SchedulerStatus? Status)
{
    public bool IsCreated { get; }   // Status is not null
}

public enum SchedulerOrigin { Container, Runtime }

• Status is null exactly when nothing has been built under that name. Asking does not build it — that is the whole point.
• Origin.Container is a scheduler AddQuartz() or AddQuartz(name, …) registered. Origin.Runtime is one that is in the repository without a registration behind it: a QuartzSchedulerBuilder scheduler bound by hand, or a remote scheduler from AddQuartzHttpClient. Nothing in the container owns a runtime scheduler's lifetime.
• The default scheduler is listed under its configured InstanceName, which is the one name that is not the name it was registered under — it has no service key at all.

Nothing is removed: GetAllSchedulers() still means what it always meant, and it is still the call to make when you want the live schedulers themselves rather than an inventory.

GET /schedulers answers from the registry

The HTTP API's scheduler listing reads ISchedulerRegistry too, so it carries the registrations rather than only what has been built, and each entry says which it is:

{ "name": "acme", "schedulerInstanceId": null, "status": null, "origin": "Container" }

A reader that assumed status and schedulerInstanceId are always present has to handle null, and one that took the listing to mean "the schedulers that are running" should filter on status. Nothing else moved: a scheduler's own routes still resolve through the repository, so GET /schedulers/{name} answers 404 for a registration nothing has built.

Quartz.Dashboard's own projection changed with it — SchedulerHeaderDto.Status and SchedulerInstanceId are nullable, it gained Origin and IsCreated, and SchedulerDetailDto grew the SchedulerMetadata the dashboard used to drop: Clustered, Persistent, JobStoreTypeName, ThreadPoolTypeName, ThreadPoolSize, RunningSince, JobsExecuted and Version. Both types are public because IQuartzApiClient is replaceable; an application that implements that interface itself has to fill the new members.

ISchedulerRegistry is deliberately the narrow half of the API #3338 sketches for runtime tenant lifecycle, and the promise held: 4.1's ISchedulerRuntime extends this interface rather than replacing it, and resolving either answers with the same object. See Upgrading from 4.0 to 4.1.

A shared database says so when two schedulers disagree about the table prefix

Two schedulers sharing a database are told apart by SCHED_NAME and share one table prefix. Pointing one of them at a different prefix by accident used to be silent in the worst possible way: the scheduler connects, schema validation passes against the tables it was pointed at, it starts, it reports healthy, and it never sees its tenant's data. SchemaProvisioning.CreateIfMissing makes that easier to reach rather than harder, since it will create the mis-typed table set rather than needing one to be there.

Creating a scheduler now records its database and table prefix, and a scheduler that shares a database with one already created but disagrees about the prefix is reported at Warning, naming both schedulers and both prefixes. It is a warning rather than an error because separate table sets in one database are legal and occasionally deliberate; the message says which two registrations to look at and leaves the decision where it belongs.

The check sees what one container can see, which is its own schedulers. Two processes, or two containers in one process, sharing a database cannot be compared this way, and a database reached through a provider that reports no connection string and no DbDataSource is not guessed about. Nothing about the check is configurable, and nothing fails because of it.

Several schedulers are registered explicitly

AddQuartz(IConfiguration) used to look for a Schedulers sub-section and, if it found one, register one named scheduler per child instead of the single scheduler it otherwise registers. One call did two different things depending on the shape of a file. The fan-out has a name of its own now:

- services.AddQuartz(builder.Configuration.GetSection("Quartz"));   // with a Schedulers section
+ services.AddQuartzSchedulers(builder.Configuration.GetSection("Quartz"));

AddQuartz(configuration) throws a SchedulerConfigException naming AddQuartzSchedulers when it is handed a section with a Schedulers sub-section, and AddQuartzSchedulers throws when handed one without. AddQuartz(name, configuration), which registers one of the schedulers a Schedulers section describes, is unchanged.

The six phases that decide which of a scheduler's descriptions wins — configuration is last-wins, registration is first-wins — are now documented on AddQuartz itself rather than in comments inside it.

Every scheduler in the container can be configured at once

ConfigureAllQuartzSchedulers(Action<IQuartzBuilder>) is new. It is the options pattern's ConfigureAll, for schedulers: the delegate is applied to every scheduler AddQuartz(), AddQuartz(name, …) or AddQuartzSchedulers(…) registers in the container.

services.AddQuartz();
services.AddQuartz("acme", q => q.UseInMemoryStore());
services.AddQuartz("initech", q => q.UseInMemoryStore());

// Both named schedulers and the default one get their own instance of each.
services.ConfigureAllQuartzSchedulers(q =>
{
    q.AddPlugin<AuditPlugin>("audit");
    q.AddJobListener<TenantMetricsListener>();
});

The order of the calls does not matter. Schedulers already registered are configured where this is called; schedulers registered afterwards are configured by their own AddQuartz. That is the point: a library that adds something to every scheduler cannot know whether the application registers its schedulers before or after calling it.

The delegate is handed a builder per scheduler, so everything it registers lands under that scheduler's own service key — exactly as if it had been written inside that scheduler's AddQuartz(name, q => …) callback. A plugin or listener added this way is therefore one instance per scheduler, each initialized with the name of the scheduler it belongs to, rather than one instance shared between them.

It runs after each scheduler's own configuration callback, which is what makes the order immaterial. The usual precedence follows: registration is first-wins, so a job store or thread pool a scheduler chose for itself is not replaced by one chosen here; options are last-wins, so a value set here overrides the same option set on one scheduler, exactly as ConfigureAll<TOptions> overrides an earlier named Configure.

Remote schedulers registered with AddQuartzHttpClient are not built by a builder and are skipped. Calling it when no scheduler is registered at all is not an error.

AddQuartzDashboard() is its first caller: it installs its live-events and history plugins this way, so a scheduler registered with AddQuartz("acme", …) finally has a populated live view and execution history rather than two silently empty pages.

IScheduler is a service, keyed by the scheduler's name

AddQuartz() now registers IScheduler as well as ISchedulerFactory. The default scheduler is registered unkeyed and a named scheduler under its own name, so a scheduler is injected the way any other service is:

public sealed class ReportRunner(
    IScheduler scheduler,                                       // the default scheduler
    [FromKeyedServices("reporting")] IScheduler reporting)      // AddQuartz("reporting", …)

var scheduler = provider.GetRequiredService<IScheduler>();
var reporting = provider.GetRequiredKeyedService<IScheduler>("reporting");

Resolving ISchedulerFactory and awaiting GetScheduler() still works and is unchanged; it is no longer the only way.

What is registered is a handle rather than the scheduler itself, because building a scheduler is asynchronous and a container constructs synchronously. Every asynchronous member awaits the scheduler being built, so they are always safe. The synchronous ones — SchedulerInstanceId, Status, Context and ListenerManager — can only answer once the scheduler exists, and throw InvalidOperationException if reading one would have to build it. Under AddQuartzHostedService() that cannot happen: every scheduler in the container is built while the host starts, which is all those members need — starting them is a separate step, and by default waits until the application has started. SchedulerName is answered from the registration and never builds anything.

A remote scheduler is registered by name, not by a marker interface

AddQuartzHttpClient<TScheduler>(…) is removed, along with the runtime type generation behind it. A second remote scheduler needed a marker interface only because the container had no other way to tell two IScheduler registrations apart; the service key says it directly:

- services.AddQuartzHttpClient<IMyScheduler>("MyScheduler", "QuartzHttpClient");
- services.AddQuartzHttpClient<IMySecondScheduler>("MySecondScheduler", "QuartzHttpClient");
+ services.AddQuartzHttpClient("MyScheduler", "QuartzHttpClient");
+ services.AddQuartzHttpClient("MySecondScheduler", "QuartzHttpClient");

- var mine = provider.GetRequiredService<IMyScheduler>();
+ var mine = provider.GetRequiredKeyedService<IScheduler>("MyScheduler");

The marker interfaces themselves can be deleted, and the first remote scheduler registered is still the unkeyed IScheduler for a container that holds only one.

In a container that also holds a local scheduler, AddQuartz() goes first:

A client is named or built, never handed over

HttpClientOptions.HttpClient and the AddQuartzHttpClient(schedulerName, HttpClient, …) overload are removed. An options object is bound from configuration, cached and shared; a live HttpClient sitting in one is a disposable resource with no owner, unreachable from appsettings.json, and it goes around IHttpClientFactory — which is what keeps a long-lived client from pinning stale DNS.

There are two shapes, both of which say who made the client:

- var client = new HttpClient { BaseAddress = new Uri("http://localhost:5000/quartz-api/") };
- services.AddQuartzHttpClient("MyScheduler", client);
+ services.AddHttpClient("QuartzHttpClient", c => c.BaseAddress = new Uri("http://localhost:5000/quartz-api/"));
+ services.AddQuartzHttpClient("MyScheduler", "QuartzHttpClient");

To keep building the client yourself, wrap it in a factory — it runs once, when the scheduler is first resolved, and is handed the container:

- services.AddQuartzHttpClient("MyScheduler", client);
+ services.AddQuartzHttpClient("MyScheduler", _ => client);

Either way the client belongs to whoever made it. The scheduler never disposes it.

This removes Quartz.HttpClient's only use of System.Reflection.Emit, so the package no longer emits a type at runtime for a scheduler interface — one fewer thing standing between it and ahead-of-time compilation.

Remote schedulers are also bound into ISchedulerRepository when the host starts, rather than the first time one is injected. A dashboard or an HTTP API listing the container's schedulers now shows them without something else having had to use them first. They are bound under their own name; reading a remote scheduler's instance id costs a request, and a name identifies one registration on its own. A container with no host is unaffected — nothing runs the binder, and the scheduler is built when it is first used, exactly as before.

Quartz can be added to the host application builder

AddQuartz and AddQuartzHostedService have IHostApplicationBuilder overloads, which is how an application built by Host.CreateApplicationBuilder or WebApplication.CreateBuilder adds everything else. A builder has both halves of what the configuration overload needs, so the section is found rather than handed over:

- services.AddQuartz(builder.Configuration.GetSection("Quartz"), q => { });
- services.AddQuartzHostedService();
+ builder.AddQuartz(q => { });
+ builder.AddQuartzHostedService();

The section it reads is Quartz, which is the name every sample and documentation page uses. An application whose Quartz configuration lives elsewhere passes the section explicitly, through the IServiceCollection overloads — nothing was removed, and they mean exactly what they always did.

A string is a scheduler's name here as it is everywhere else in Quartz: builder.AddQuartz("reporting") registers a scheduler called reporting and reads its settings from Quartz:Schedulers:reporting, and builder.AddQuartzSchedulers() registers one scheduler per child of that sub-section.

The hosted service starts every scheduler

AddQuartzHostedService() registered the hosted service only if an unkeyed ISchedulerFactory was already in the service collection. Calling it before AddQuartz() therefore registered nothing for the default scheduler and said nothing about it — the application started, and no job ever ran.

The hosted service is now registered unconditionally and resolves its schedulers when the host starts, so the two calls can be made in either order. It starts every scheduler in the container, the default one and each named one, which is what the pair of services it replaces did between them.

- services.AddQuartz(q => …);            // had to come first
  services.AddQuartzHostedService(options => options.WaitForJobsToComplete = true);
+ services.AddQuartz(q => …);            // either order now

A container with no scheduler in it at all is a SchedulerConfigException at startup: the hosted service was asked for, so something was meant to run.

QuartzHostedServiceOptions are now named options, keyed by scheduler name. Options passed to AddQuartzHostedService(configure) apply to every scheduler, which is what one shared options object meant before; a scheduler that has to differ is configured by name, and its settings are applied after the shared ones whichever order the calls are made in:

services.AddQuartzHostedService(options => options.WaitForJobsToComplete = true);
services.AddQuartzHostedService("Reporting", options => options.StartDelay = TimeSpan.FromMinutes(2));

QuartzHostedService's constructor changed to match: it takes the IServiceProvider it resolves the schedulers from and an IOptionsMonitor<QuartzHostedServiceOptions> instead of one factory and one options object. Subclasses registered with AddQuartzHostedService<T>() need their constructors updated; the Starting/Started/Stopping/Stopped overrides are unchanged. The internal NamedSchedulerHostedService is gone, its work having moved into the one service.

A hosted scheduler can be started by the application

New in 4.x, with nothing to migrate. QuartzHostedServiceOptions.AutoStart defaults to true, which is what the hosted service has always done; setting it to false has the scheduler resolved, initialized and bound with the host but left in SchedulerStatus.Created for the application to start:

services.AddQuartzHostedService("Reporting", options => options.AutoStart = false);

On 3.x the only way not to start a scheduler was not to register the hosted service, which lost the shutdown handling with it. The scheduler is bound, so ISchedulerRegistry, the dashboard and GET /schedulers all report it, and it is still shut down when the host stops — opting out of the start is not opting out of the stop. AutoStart wins over AwaitApplicationStarted and StartDelay, both of which say when the hosted service starts a scheduler that it does not start at all.

The health check follows: a scheduler in Created whose AutoStart is false is reported degraded rather than unhealthy, on the same argument as standby — it is doing what it was told, and failing the probe would take a correctly configured node out of rotation. A Created scheduler that nothing opted out of is unhealthy as before.

A library embedding Quartz in someone else's application is what this is for, and the how-to page on embedding Quartz in a library covers the whole pattern.

The ASP.NET Core methods say Quartz once

- services.AddQuartz(q => q.AddHttpApi());
+ services.AddQuartzHttpApi();

- app.MapQuartzApi().RequireAuthorization();
+ app.MapQuartzHttpApi().RequireAuthorization();

The health check is no longer one of them — it ships in the core Quartz package (see The health check is in Quartz, not Quartz.AspNetCore), and it composes with an application's other checks rather than needing a call of its own:

services.AddHealthChecks()
    .AddSqlServer(connectionString)
    .AddQuartz()
    .AddQuartz("Reporting");

services.AddQuartzHealthChecks() is gone; the health-checks builder is the receiver, and services.AddHealthChecks().AddQuartz() is the same call with the composition made visible. A named scheduler can also ask for its own check from inside AddQuartz, and it reports on its scheduler rather than the default one; either way it is named quartz-scheduler-<scheduler name> unless you say otherwise:

services.AddQuartz("Reporting", q => q.AddQuartzHealthChecks(options => options.Tags.Add("ready")));

QuartzHealthCheckOptions goes through the options pipeline. It used to be constructed and read inside the registration call, so services.Configure<QuartzHealthCheckOptions>(...) and a configuration section bound to the type silently did nothing; both now apply, whichever order they are written in. The options belong to the scheduler being checked, so a named scheduler's are configured under its name:

services.Configure<QuartzHealthCheckOptions>("Reporting", options => options.Tags.Add("ready"));

QuartzHealthCheckOptions.Name is nullable, and left unset the check is named after the scheduler it reports on. Assigning a name still overrides that.

AddQuartzServer is AddQuartzHostedService

Quartz.AspNetCore.AddQuartzServer did two unrelated things behind one name: it registered the hosted service that starts the scheduler, and — on frameworks that had them — a health check. Both are separately available, and neither was ever specific to ASP.NET Core, so the combined method is gone and each half is called by its own name:

  services.AddQuartz(q => { /* ... */ });

- services.AddQuartzServer(options => options.WaitForJobsToComplete = true);
+ services.AddQuartzHostedService(options => options.WaitForJobsToComplete = true);
+ services.AddHealthChecks().AddQuartz();

Both halves live in the core Quartz package, so an application replacing AddQuartzServer needs no Quartz.AspNetCore reference at all — see The hosted service starts every scheduler for what the hosted service now starts, The health check is in Quartz, not Quartz.AspNetCore for where the check went, and The ASP.NET Core methods say Quartz once for what is left in that package.

The health-check overload that took IEnumerable<string> healthCheckTags is gone with it; tags are QuartzHealthCheckOptions.Tags, which is added to rather than assigned:

- services.AddQuartzServer(configure, healthCheckTags: ["ready", "live"]);
+ services.AddHealthChecks().AddQuartz(options => options.Tags.AddRange(["ready", "live"]));

QuartzHealthCheckOptions.StandbyStatus is the one setting that changes a verdict rather than the registration: a scheduler in standby reports Degraded, and setting this reports something else. Degraded is the right default — standby is deliberate and reversible — but ASP.NET Core maps it to HTTP 200, and a worker project has no endpoint on which to remap it, so a deployment whose standby nodes must leave the rotation had nothing to say. It covers standby alone: a scheduler still in Created because AutoStart is false keeps reporting degraded. FailureStatus is unrelated and unchanged — it is what the registration reports when the check says it failed.

The OpenAPI calendar schema names the properties the payload actually uses

The HTTP API's endpoints handle ICalendar, which OpenAPI cannot describe, so the published document has always been shaped by a stand-in type. Nothing compiled against that stand-in, so two of its property names were simply wrong, and a client generated from the document did not round-trip a calendar at all:

Nothing about the wire format changed — the server has always written type and baseCalendar. What changes is generated clients: regenerate against 4.x and the two properties on your calendar model are renamed, which is a compile error at each use rather than a silent one. Hand-written clients were already having to send type and baseCalendar to be understood, so they need no change.

The rest of the schema was already right: description, timeZoneId, excludedDays, excludedDates, cronExpressionString, rangeStart, rangeEnd and invertTimeRange are what a calendar of each built-in type serializes to. A test in Quartz.Tests.AspNetCore now compares the stand-in against those names in both directions, so the schema cannot quietly drift again.

Remoting a scheduler is not a Quartz concern

ISchedulerProxyFactory and HttpSchedulerProxyFactory are removed, and the quartz.scheduler.proxy* and quartz.scheduler.exporter* keys are now rejected rather than silently accepted and ignored.

Nothing read them. ISchedulerProxyFactory had no caller inside Quartz once .NET Remoting went away — no builder member reached it, no configuration key selected it — while the key validator still whitelisted quartz.scheduler.proxy, so a configuration file could carry a proxy setting that changed nothing. A configuration that still carries one now gets a SchedulerConfigException saying what to use instead:

- quartz.scheduler.proxy = true
- quartz.scheduler.proxy.type = Quartz.Impl.HttpSchedulerProxyFactory, Quartz.HttpClient

// talk to a remote scheduler over HTTP, from Quartz.HttpClient
services.AddQuartzHttpClient("Quartz ASP.NET Core Sample Scheduler", "QuartzHttpClient");

// or serve one over HTTP: AddQuartzHttpApi + MapQuartzHttpApi, from Quartz.AspNetCore

Tasks Changed to ValueTask

In a majority of interfaces that previously returned or took a Task or Task<T> parameter, these have been changed to ValueTask or ValueTask<T>.

In most cases, all you will need to do is adjust the signature from Task to ValueTask.

For example, to migrate jobs:

// 3.x
public async Task Execute(IJobExecutionContext context)

// 4.x
public async ValueTask Execute(IJobExecutionContext context, CancellationToken cancellationToken = default)

Execute also gained a CancellationToken. See Jobs take a CancellationToken below for why, and for what to do with it.

Listeners are the one place where a missed Task → ValueTask does not fail the build. Every member of IJobListener, ITriggerListener and ISchedulerListener has a default implementation, so a 3.x signature still compiles and simply stops implementing anything — the default runs, and the method is never called. Quartz refuses a listener in that shape when it is registered, naming the member; see The compiler will not point at the callbacks you have to change, but the registration will.

For more information on ValueTask please see Microsoft docs.

Upgrading an F# project

Every 4.0 signature is reachable from F#, and F# honours a C# optional parameter at a call site, so scheduler.Start() and scheduler.ScheduleJob(job, trigger) are written the way this guide writes them. Four things still go differently, and the first build of an upgraded F# project reports many more errors than it has causes: F# infers the types of function parameters, so one signature it cannot match leaves everything downstream of it untyped, and each of those becomes an error of its own. ForNeVeR/nightwatch#68 — the upgrade this section was written from — reported thirteen errors for four causes. Fix them from the top of the file down, and rebuild after each one.

FS0856 — a job is implemented with both parameters

error FS0856: This override takes a different number of arguments to the corresponding abstract member. The following abstract members were found:
   IJob.Execute(context: IJobExecutionContext, ?cancellationToken: System.Threading.CancellationToken) : ValueTask

?cancellationToken is how F# displays a C# optional parameter. It means what it says at a call site and nothing at all at an implementation, where the whole signature has to be written out. C# is no different — Execute gaining the token is a break for both languages, and Jobs take a CancellationToken is why the parameter is there. What is F#-specific is the shape of the diagnostic: it reports the arity and not the parameter, and the reading of ?cancellationToken it invites — declaring the parameter optional in F#'s own sense, with a leading ? — trades FS0856 for FS0001: This expression was expected to have type 'CancellationToken' but here has type 'CancellationToken option', because that syntax means an option rather than a defaulted argument.

Write both parameters, and annotate them. Until the override matches there is nothing for F# to infer context from, which is where the FS0072 and FS0008 errors further down the file come from; they go away with this one.

member _.Execute(context: IJobExecutionContext, cancellationToken: CancellationToken) : ValueTask =
    ValueTask(
        task {
            do! Task.Delay(TimeSpan.FromMilliseconds 1.0, cancellationToken)
            printfn "GreetJob fired at %O" context.FireTimeUtc
            Firings.record ()
        }
    )

FSharp.Core has no valueTask { } builder, so a task { } handed to ValueTask's constructor is the idiom. A 3.x job written as upcast task { … } cannot be repaired by leaving the upcast in place: ValueTask is a struct and no supertype of Task, and what that produces is FS0013: The static coercion from type Task<unit> to 'a ... involves an indeterminate type.

FS0041 — ScheduleJob has to know what it is being handed

error FS0041: A unique overload for method 'ScheduleJob' could not be determined based on type information prior to this program point. A type annotation may be needed.

Known types of arguments: IJobDetail * 'a

Candidates:
 - (extension) SchedulerJobExtensions.ScheduleJob<'TJob,'TInput when 'TJob :> IJob<'TInput>>(input: 'TInput, at: System.DateTimeOffset, ?options: OneOffJobOptions, ?cancellationToken: System.Threading.CancellationToken) : ValueTask<ScheduledOneOffJob>
 - (extension) SchedulerJobExtensions.ScheduleJob<'TJob,'TInput when 'TJob :> IJob<'TInput>>(input: 'TInput, delay: System.TimeSpan, ?options: OneOffJobOptions, ?cancellationToken: System.Threading.CancellationToken) : ValueTask<ScheduledOneOffJob>
 - IScheduler.ScheduleJob(jobDetail: IJobDetail, trigger: ITrigger, ?options: ScheduleJobOptions, ?cancellationToken: System.Threading.CancellationToken) : ValueTask<System.DateTimeOffset>
 - IScheduler.ScheduleJob(jobDetail: IJobDetail, triggersForJob: System.Collections.Generic.IReadOnlyCollection<ITrigger>, ?options: ScheduleJobOptions, ?cancellationToken: System.Threading.CancellationToken) : ValueTask

The 'a in Known types of arguments is the whole of it: the trigger arrived as an inferred function parameter, so at that point F# does not yet know what it is, and it will not pick an overload it cannot distinguish. C# never reaches this position, because a C# parameter has a declared type — which is why this is an F#-only error rather than an ambiguity in the API.

4.0 widened the candidate set in two ways, both deliberate and both harmless in C#: options gained a default so that ScheduleJob(job, trigger) keeps compiling (the surviving overloads), which makes every candidate a match for two arguments; and SchedulerJobExtensions adds the two typed-input overloads (a typed job can be scheduled in one call), which F# considers beside the interface's own.

Annotate the value — as a parameter here, but a let binding or the call itself does just as well:

let scheduleOne (scheduler: IScheduler) (job: IJobDetail) (trigger: ITrigger) : Task<DateTimeOffset> =
    task {
        return! scheduler.ScheduleJob(job, trigger)
    }