Upgrading Quartz.NET 3.x to 4.x: What Changed and What to Test
Contents
Quartz.NET 4 requires .NET 10, folds the DI, hosting, and System.Text.Json packages into the main Quartz package, changes most async members from Task to ValueTask, removes StdSchedulerFactory and binary serialization, and needs a database migration script if you use the ADO.NET job store. The compiler finds most of the code changes. What it doesn't find are the changed defaults, such as the scheduler instance name and the misfire threshold, and those are what break a running deployment.
This guide covers moving from Quartz.NET 3.x to 4.x. Quartz.NET 4.7.3 was the latest release on NuGet when checked on November 16, 2026. The details come from the official Quartz.NET 4.x migration guide, which is long and has separate paths for running deployments, F# projects, and users of the 4.0 previews; read the section for your situation before you start.
What 4.x Requires Before You Touch Code#
| Area | Quartz.NET 3.x | Quartz.NET 4.x |
|---|---|---|
| Target framework | netstandard2.0 and up, including .NET Framework |
.NET 10 or later only; no netstandard2.0 build, no .config file support |
| Packages | Quartz plus Extensions.DependencyInjection, Extensions.Hosting, Serialization.SystemTextJson |
Quartz alone; those three are merged in |
| Async signatures | Task |
ValueTask (IJob.Execute, ScheduleJob, listeners, job stores) |
| Scheduler factory | StdSchedulerFactory, SchedulerBuilder, DirectSchedulerFactory |
Removed; QuartzSchedulerBuilder or AddQuartz() |
| Binary serialization | BinaryObjectSerializer available |
Gone with .NET's BinaryFormatter; 4.x can't read binary blobs |
| ADO.NET schema | 3.x tables | Mandatory upgrade script; startup refuses a database that skipped it |
| Remoting | quartz.scheduler.proxy* and exporter* |
Removed |
Two consequences follow. The application moves to .NET 10 first, as its own change, and ships before Quartz changes. And if anything in your stack can't move, it pins you to 3.x: the guide says MassTransit.Quartz doesn't run on 4.x, and Quartz.OpenTracing has no 4.x release.
Do Two Things While Still on 3.x#
The guide's upgrade path for a running deployment has seven steps, and the first two happen before any 4.x node starts, because 4.x can't do them.
- Get off binary serialization. If your job store holds job data written by
BinaryObjectSerializer, 4.x can't read it, and the converter only exists in 3.x. The guide also notes thatBLOB_TRIGGERS.BLOB_DATAcan't be converted from 4.x. Follow its conversion steps on 3.x and confirm nothing binary is left. - Audit stored cron expressions. 4.x rejects some expressions that 3.x accepted and stored, and it fails when it reads such a row. List every cron trigger in the store, validate each expression against 4.x in a test project, and fix the ones it rejects while 3.x is still running them.
If you use the RAM job store, both steps reduce to "check the expressions in your code," since nothing is stored between runs.
Migrate the Schema Before the Nodes#
With the ADO.NET job store, run schema_30_to_40_upgrade_<database>.sql from the Quartz.NET repository before deploying any 4.x node. The guide says it's mandatory, safe to run twice, and safe while 3.x nodes are still firing. It makes four previously optional columns required (MISFIRE_ORIG_FIRE_TIME, EXECUTION_GROUP, PREFERRED_NODE, PREFERRED_NODE_AUTO), adds RETRY_POLICY and RETRY_ATTEMPT to QRTZ_TRIGGERS, and adds a QRTZ_PAUSED_JOB_GRPS table.
Three details to plan for:
- 4.x validates at startup. It checks every table and column it reads and refuses to start against a database that skipped the migration. That's a loud failure, which is better than the alternative, but it means the script is part of the deploy, not a follow-up.
- Paused job groups don't carry over. Re-pause them on 4.x with
PauseJobGroups. - The index script waits.
schema_30_to_40_indexes_<database>.sqlis optional and affects performance only. Run it after the last 3.x node stops, because 3.x statements may still use the indexes it drops.
Later 4.x minor releases add their own migrations. The guide lists three required scripts for 4.6 and one for 4.7, so upgrading straight to the latest 4.x means running each in order.
During the rollout you can stop the cluster, or run 3.x and 4.0 nodes against the same tables. If you overlap them, the guide says not to let a 4.0 node write a calendar during that period.
Swap the Packages#
Remove Quartz.Extensions.DependencyInjection, Quartz.Extensions.Hosting, and Quartz.Serialization.SystemTextJson, and reference Quartz 4.x. Leaving any of the 3.x packages in place produces CS0433 errors, because eight type names exist in both. Other replacements:
Quartz.Serialization.Json(Newtonsoft) becomesQuartz.Serialization.Newtonsoft.- The health check moved into
Quartz.Quartz.AspNetCoreis now needed only for the HTTP API or dashboard. Register the check withAddHealthChecks().AddQuartz(...)orAddQuartzHealthChecks(...). AddQuartzServeris replaced byAddQuartzHostedService.- For tracing,
OpenTelemetry.Instrumentation.Quartzproduces no spans on 4.x. UseAddSource(QuartzInstrumentation.ActivitySourceName)on your tracer instead.
Fix What the Compiler Reports#
Most code changes are mechanical. IJob.Execute returns ValueTask and takes the cancellation token as a parameter:
using Quartz;
public sealed class NightlyReportJob : IJob
{
public async ValueTask Execute(IJobExecutionContext context, CancellationToken cancellationToken)
{
await Task.Delay(TimeSpan.FromSeconds(1), cancellationToken);
Console.WriteLine($"Report generated for {context.ScheduledFireTimeUtc:u}");
}
}The rest of the list from the guide:
- Scheduler state.
IsStarted,InStandbyMode, andIsShutdownare replaced by oneSchedulerStatus Statusproperty. The guide mapsIsStartedtoStatus is not SchedulerStatus.CreatedandIsShutdowntoStatus is SchedulerStatus.Shutdown. ScheduleJobreturnsValueTask<DateTimeOffset>, and the overloads that took aCancellationTokenpositionally are gone; passcancellationToken: token.ISchedulerisIAsyncDisposable, soawait usingcan replace atry/finallythat callsShutdown().- Hosted service hooks.
QuartzHostedService.StartAsyncandStopAsyncare no longer virtual. OverrideStartingAsync,StartedAsync,StoppingAsync, orStoppedAsync. - Options renames.
AdoJobStoreOptions.UsePropertiesisStoreJobDataAsStrings,MakeThreadsDaemonsisUseBackgroundThreads, andPerformSchemaValidationis replaced bySchemaProvisioning(Validate,None,CreateIfMissing). JobDataMaplookups. The indexer throwsKeyNotFoundExceptionfor a missing key, where 3.x returnednull. This one compiles and fails at run time, so search for indexer reads that relied onnull.- Configuration.
quartz.configfile discovery is removed, andQuartzOptionsno longer derives fromDictionary<string, string?>. Flatquartz.*keys still work, so configuration can be translated gradually.
With StdSchedulerFactory gone, a scheduler outside dependency injection comes from QuartzSchedulerBuilder:
using Quartz;
var scheduler = await QuartzSchedulerBuilder.Create(_ => { }).BuildScheduler();
try
{
var job = JobBuilder.Create<NightlyReportJob>()
.WithIdentity("nightly-report", "reports")
.Build();
var trigger = TriggerBuilder.Create()
.WithIdentity("nightly-report-trigger", "reports")
.WithCronSchedule("0 0 2 * * ?")
.Build();
await scheduler.ScheduleJob(job, trigger);
await scheduler.Start();
await Task.Delay(Timeout.Infinite);
}
finally
{
await scheduler.Shutdown();
}Listeners Need the Most Care#
Listener interfaces return ValueTask too, and every ISchedulerListener member now takes the IScheduler as its first parameter. The compiler won't point at the callbacks you have to change: every member of IJobListener, ITriggerListener, and ISchedulerListener has a default implementation, so a method left with its 3.x signature, such as Task JobWasExecuted(...) or SchedulerStarted(CancellationToken), compiles but implements nothing. The migration guide says Quartz refuses such a listener when it is registered and names the member, so the failure shows at startup. Start the application once after the upgrade and read the registration errors before deploying.
Write 4.x scheduler listeners with the new signature:
using Quartz;
public sealed class SchedulerShutdownLogger : ISchedulerListener
{
public ValueTask SchedulerShuttingDown(IScheduler scheduler, CancellationToken cancellationToken = default)
{
Console.Error.WriteLine($"Quartz scheduler {scheduler.SchedulerName} is shutting down");
return ValueTask.CompletedTask;
}
}Two listener behaviors changed as well. A start, standby, and shutdown now raise exactly SchedulerStarting, SchedulerStarted, SchedulerInStandbyMode, SchedulerShuttingDown, and SchedulerShutdown, and a shutdown no longer raises SchedulerInStandbyMode first, so a listener that treated standby as "stopped firing" must also handle SchedulerShuttingDown. Since 4.4, context.Outcome reads Vetoed inside JobExecutionVetoed. Quartz.NET job listeners covers listeners in depth.
The Defaults That Change Silently#
These don't produce compiler errors. Each one changes behavior for an application that never configured the setting.
| Setting | 3.x default | 4.x default | Why it matters |
|---|---|---|---|
quartz.scheduler.instanceName |
DefaultQuartzScheduler |
QuartzScheduler |
Persistent stores key rows on the name |
quartz.jobStore.misfireThreshold |
60 seconds | 5 seconds | Short delays now count as misfires and apply the misfire instruction |
quartz.serializer.type = json |
Newtonsoft | System.Text.Json | Job data written by one may not read back the same in the other |
PropagateTraceContext |
Not present | On | Trace context flows into job execution |
The instance name deserves the most attention. An ADO.NET job store keys its rows on the scheduler name, so a 4.x node that never set instanceName looks for rows under QuartzScheduler, while all of your jobs and triggers are stored under DefaultQuartzScheduler. Set the name explicitly to the value the 3.x nodes used before the first 4.x node starts.
Later 4.x releases changed more behavior that a 3.x user will notice:
- 4.4: a cancelled run is recorded as
Cancelled, not as a success, and five consecutive fire failures put a trigger in theERRORstate;MaxConsecutiveFireFailures = 0restores the old behavior. - 4.6:
DefaultMisfireHandling(defaultSmartPolicy) is set on the scheduler, and a schedule builder with no instruction stores none. A clustered node with noInstanceIdnow generates one instead of sharingNON_CLUSTERED. - 4.7:
QuartzSchedulerOptions.DefaultTimeZone(defaultTimeZoneInfo.Local) applies when a trigger names no zone, andInTimeZone(null)now means "no zone" rather than local time. Job data serialization changed too: numeric, boolean, and null members of declared job-data objects read back as strings.
The 5-second misfire threshold interacts with your misfire instructions; Quartz.NET misfire instructions explains what each instruction does once a fire time counts as missed.
What to Test Before Production#
Run a 4.x build against a copy of the production job store, not an empty one. Most upgrade failures depend on stored data.
| Test | What it catches |
|---|---|
| Start a 4.x node against a migrated copy of the store | Missed schema scripts, stored expressions 4.x rejects |
| Compare job and trigger counts before and after | Instance name mismatch, unreadable job data |
Read every JobDataMap key your jobs use |
KeyNotFoundException, values that now read as strings |
Fire each job once with TriggerJob |
Job construction, DI registrations, serializer changes |
| Stop the host during a run | Cancellation handling, Cancelled outcomes, shutdown listeners |
| Pause the scheduler for 10 seconds, then resume | The 5-second misfire threshold and your instructions |
| Check next fire times for zone-less triggers | DefaultTimeZone and InTimeZone(null) changes |
| Verify paused groups and triggers | Paused job groups that didn't carry over |
The last check that matters is time. A job that runs nightly or monthly won't fire during a deploy window, so it can be broken for days before anyone looks. That is what an external monitor is for.
Keep Monitoring Working Through the Upgrade#
CronRadar.Quartz 0.2.0 supports both majors and picks one by target framework: on .NET 10 it uses Quartz.NET 4, and on earlier frameworks it uses Quartz.NET 3.13 or later. If you upgrade the app to .NET 10 but stay on Quartz.NET 3 for a while, keep CronRadar.Quartz at 0.1.1 until Quartz moves too. On Quartz.NET 4 the call is the same:
using CronRadar.Quartz;
using Quartz;
var scheduler = await QuartzSchedulerBuilder.Create(_ => { }).BuildScheduler();
var job = JobBuilder.Create<NightlyReportJob>().WithIdentity("nightly-report", "reports").Build();
var trigger = TriggerBuilder.Create()
.WithIdentity("nightly-report-trigger", "reports")
.WithCronSchedule("0 0 2 * * ?")
.Build();
await scheduler.ScheduleJob(job, trigger);
// Reads CRONRADAR_API_KEY. Call after scheduling jobs.
await scheduler.MonitorAll();
await scheduler.Start();With AddQuartz(), call MonitorAll() from an IHostedService after the scheduler starts, as the Quartz integration guide shows. The package registers a job listener that reports each run's start, completion, or failure, and translates each cron trigger to five-field cron so CronRadar knows when the next run is due.
What to check across the upgrade:
- Monitor keys come from the
JobKey(or a[CronRadar("key")]attribute on the job class), so if job names and groups don't change, the same monitors keep receiving reports and keep their history. Don't rename jobs in the same release. - A job that stops firing after the upgrade is caught. If the instance name, a rejected expression, or a misfire change stops a trigger, no start arrives. After the expected time plus the grace period (60 seconds by default), the monitor goes from
warningtocriticaland alerts by email, Slack, webhook, Discord, or PagerDuty. A job that throws reports a failure and alerts immediately. - Expressions with seconds stay unmonitored. A cron trigger with no five-field form, such as one that fires on a seconds field other than 0, logs a warning and isn't monitored.
- Time zones aren't converted. CronRadar evaluates schedules in the application's time zone, set in its settings (UTC if unset). CronRadar.Quartz copies the trigger's hours as written, so a trigger in a different zone from the CronRadar application needs its own application in that zone. Check this if the 4.7
DefaultTimeZonechange moved any zone-less trigger.
Use a separate CronRadar application and key for the environment where you test the upgrade, so a staging run can't report into production monitors.
Frequently Asked Questions#
Does Quartz.NET 4 support .NET 8 or .NET Framework?#
No. Quartz.NET 4.x requires .NET 10 or later, and every package targets net10.0. There is no netstandard2.0 build and no support for .config files. Upgrade the application to .NET 10 first, or stay on Quartz.NET 3.x.
Can Quartz.NET 3.x and 4.x nodes share one database during the upgrade?#
Yes, for a rolling upgrade, as long as the 3.0-to-4.0 schema script ran first. The migration guide says the script is safe while 3.x nodes are still firing. Don't let a 4.0 node write a calendar while 3.x nodes are running, and run the optional index script only after the last 3.x node stops.
Why are my jobs missing after upgrading to Quartz.NET 4?#
The most likely cause with a database store is the scheduler instance name. Its default changed from DefaultQuartzScheduler to QuartzScheduler, and stored rows are keyed on the name, so a 4.x node that doesn't set quartz.scheduler.instanceName reads a different, empty scheduler. Set the name to the value your 3.x nodes used.
What replaces StdSchedulerFactory in Quartz.NET 4?#
QuartzSchedulerBuilder, for example await QuartzSchedulerBuilder.Create(_ => { }).BuildScheduler(), or the AddQuartz() dependency injection integration, which is now part of the main Quartz package. SchedulerBuilder and DirectSchedulerFactory were removed as well.
Does CronRadar.Quartz work with Quartz.NET 4?#
Yes, from 0.2.0. On .NET 10 the package uses Quartz.NET 4, and on earlier frameworks it uses Quartz.NET 3.13 or later. If you are on .NET 10 but still on Quartz.NET 3, keep CronRadar.Quartz at 0.1.1 until Quartz moves to 4.
Put this guide to work
Connect your Quartz.NET job to monitoring
Follow the current integration guide, check the release limitations, and verify a real run and alert delivery.
NuGet installs CronRadar.Quartz 0.2.1, which uses Quartz.NET 4 on .NET 10 and Quartz.NET 3.13 or later on earlier frameworks. It translates cron triggers to five-field schedules. An expression with no five-field form logs a warning and stays unmonitored, and hours are not converted between time zones. Discovered monitors start with a 60-second grace period unless the code sets another; a grace period or schedule edited in the dashboard stays until the code declares a different value.