JSON Configuration

Quartz.NET supports hierarchical JSON configuration in appsettings.json, providing a modern alternative to flat property keys. This includes both scheduler properties and declarative job/trigger definitions.

Hierarchical Properties

Instead of flat property keys like "quartz.threadPool.maxConcurrency": "10", you can use a natural nested JSON structure:

{
  "Quartz": {
    "Scheduler": {
      "InstanceName": "My Scheduler",
      "InstanceId": "AUTO"
    },
    "ThreadPool": {
      "MaxConcurrency": 10
    },
    "JobStore": {
      "Type": "Quartz.Impl.AdoJobStore.LocalTransactionJobStore, Quartz",
      "DataSource": "default",
      "TablePrefix": "QRTZ_"
    },
    "DataSource": {
      "default": {
        "Provider": "SqlServer",
        "ConnectionString": "Server=localhost;Database=quartznet"
      }
    },
    "Plugin": {
      "jobHistory": {
        "Type": "Quartz.Plugins.History.LoggingJobHistoryPlugin, Quartz.Plugins"
      }
    },
    "Serializer": {
      "Type": "stj"
    }
  }
}

Mapping Rules

Each JSON path segment becomes a dot-separated segment in the flat property key, with PascalCase automatically converted to camelCase:

Usage with DI

services.AddQuartz(Configuration.GetSection("Quartz"), q =>
{
    // Additional code-based configuration still works alongside JSON
    q.AddJob<MyJob>(j => j.WithIdentity("codeJob").StoreDurably());
});

Usage without DI

QuartzSchedulerBuilder reads the same section. There is no flattening step to write: hand it the IConfiguration and it binds the typed options and translates the flat keys itself, exactly as AddQuartz does.

ISchedulerFactory factory = QuartzSchedulerBuilder.Create()
    .UseConfiguration(Configuration.GetSection("Quartz"))
    .Build();

A NameValueCollection you built yourself — from a properties file, from environment variables — still goes in through UseProperties(properties).

Backward Compatibility

Flat property keys still work. You can mix both styles in the same section:

{
  "Quartz": {
    "quartz.scheduler.instanceId": "AUTO",
    "ThreadPool": {
      "MaxConcurrency": 10
    }
  }
}

JSON Scheduling Data

Jobs and triggers can be defined declaratively in appsettings.json under a Schedule sub-section:

{
  "Quartz": {
    "Scheduler": {
      "InstanceName": "My Scheduler"
    },
    "Schedule": {
      "Jobs": [
        {
          "Name": "sampleJob",
          "Group": "sampleGroup",
          "JobType": "MyApp.Jobs.SampleJob, MyApp",
          "Description": "A sample job",
          "Durable": true,
          "Recover": false,
          "JobDataMap": {
            "connectionString": "Server=localhost",
            "retryCount": "3"
          }
        }
      ],
      "Triggers": [
        {
          "Name": "cronTrigger",
          "JobName": "sampleJob",
          "JobGroup": "sampleGroup",
          "Description": "Fires every 10 seconds",
          "Cron": {
            "Expression": "0/10 * * * * ?",
            "TimeZone": "UTC"
          }
        }
      ]
    }
  }
}

Trigger Types

Exactly one schedule type must be specified per trigger — Simple, Cron, CalendarInterval, DailyTimeInterval or Recurrence. The trigger type is determined by which nested object is present.

Simple Trigger

{
  "Name": "simpleTrigger",
  "JobName": "myJob",
  "Simple": {
    "RepeatCount": -1,
    "Interval": "00:00:10",
    "MisfireInstruction": "SmartPolicy"
  }
}

• RepeatCount: Number of times to repeat. Use -1 for indefinite, 0 for fire once.
• Interval: TimeSpan string (e.g., "00:00:10" for 10 seconds, "01:00:00" for 1 hour).

Cron Trigger

{
  "Name": "cronTrigger",
  "JobName": "myJob",
  "Cron": {
    "Expression": "0/30 * * * * ?",
    "TimeZone": "America/New_York",
    "MisfireInstruction": "DoNothing"
  }
}

Calendar Interval Trigger

{
  "Name": "calendarTrigger",
  "JobName": "myJob",
  "CalendarInterval": {
    "RepeatInterval": 1,
    "RepeatIntervalUnit": "Day",
    "MisfireInstruction": "SmartPolicy"
  }
}

RepeatIntervalUnit values: Second, Minute, Hour, Day, Week, Month, Year.

Daily Time Interval Trigger

{
  "Name": "businessHoursTrigger",
  "JobName": "myJob",
  "DailyTimeInterval": {
    "RepeatInterval": 15,
    "RepeatIntervalUnit": "Minute",
    "RepeatCount": -1,
    "StartTimeOfDay": "08:00:00",
    "EndTimeOfDay": "17:00:00",
    "DaysOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
    "TimeZone": "America/Chicago"
  }
}

Recurrence Trigger

{
  "Name": "recurrenceTrigger",
  "JobName": "myJob",
  "StartTime": "2026-01-05T09:00:00Z",
  "Recurrence": {
    "Rule": "FREQ=WEEKLY;INTERVAL=2;BYDAY=MO",
    "TimeZone": "America/New_York",
    "MisfireInstruction": "DoNothing"
  }
}

• Rule: the RFC 5545 recurrence rule, required. See Recurrence Triggers for what a rule can say.
• TimeZone: the zone the rule's days and times are read in. Defaults to the machine's local zone, so name it if the schedule has to mean the same thing wherever it runs.
• MisfireInstruction: SmartPolicy (the default), FireOnceNow, DoNothing or IgnoreMisfirePolicy.

The rule says how the firings repeat; the trigger's own StartTime says what they repeat from, the way DTSTART anchors an iCalendar rule. FREQ=WEEKLY;INTERVAL=2 therefore means "every second week counted from the start time", and a trigger given no StartTime is anchored to the moment its scheduler read the declaration. A rule that cannot be parsed is refused as the file is read, naming the rule, rather than at the first firing.

Common Trigger Fields

All trigger types support these optional fields:

PreferredNode is the one that says something about the deployment rather than about the schedule, and declaring it in a file is what a deployment-specific file is for: every machine that reads the file pins the trigger to the node it names, which is the point of pinning it at all.

{
  "Name": "nightlyReport",
  "JobName": "reportJob",
  "PreferredNode": "production-node-1",
  "Cron": { "Expression": "0 0 2 * * ?" }
}

The same field is spelled <preferred-node> in the XML format.

Multiple Named Schedulers

When the Quartz section contains a Schedulers sub-section, each child is automatically registered as a named scheduler:

{
  "Quartz": {
    "Schedulers": {
      "Primary": {
        "Scheduler": {
          "InstanceId": "AUTO"
        },
        "ThreadPool": {
          "MaxConcurrency": 10
        },
        "Schedule": {
          "Jobs": [
            {
              "Name": "primaryJob",
              "JobType": "MyApp.Jobs.PrimaryJob, MyApp",
              "Durable": true
            }
          ],
          "Triggers": [
            {
              "Name": "primaryTrigger",
              "JobName": "primaryJob",
              "Cron": { "Expression": "0/10 * * * * ?" }
            }
          ]
        }
      },
      "Secondary": {
        "ThreadPool": {
          "MaxConcurrency": 5
        }
      }
    }
  }
}

// Registers "Primary" and "Secondary" named schedulers automatically
services.AddQuartz(Configuration.GetSection("Quartz"));
services.AddQuartzHostedService();

Each named scheduler section supports the same hierarchical properties, Schedule sub-section with Jobs/Triggers, and code-based overrides.

You can also register a single named scheduler explicitly. The named overload accepts either the scheduler's own section or the root Quartz section — when given the root section it resolves the matching Schedulers:{name} sub-section automatically:

// Both lines are equivalent
services.AddQuartz("Primary", Configuration.GetSection("Quartz"));
services.AddQuartz("Primary", Configuration.GetSection("Quartz:Schedulers:Primary"));

Standalone JSON Files (quartz_jobs.json)

For file-based scheduling with hot-reload support, use JsonSchedulingDataProcessorPlugin from the Quartz.Plugins package. See Quartz Plugins for plugin configuration.

Standalone JSON files use the same Jobs and Triggers format as the Schedule section above, wrapped in an envelope with optional PreProcessingCommands and ProcessingDirectives:

{
  "PreProcessingCommands": {
    "DeleteJobsInGroup": ["obsoleteGroup"],
    "DeleteTriggersInGroup": ["oldTriggerGroup"],
    "DeleteJobs": [
      { "Name": "oldJob", "Group": "DEFAULT" }
    ],
    "DeleteTriggers": [
      { "Name": "oldTrigger" }
    ]
  },
  "ProcessingDirectives": {
    "OverwriteExistingData": true,
    "IgnoreDuplicates": false,
    "ScheduleTriggerRelativeToReplacedTrigger": false
  },
  "Schedule": {
    "Jobs": [
      {
        "Name": "myJob",
        "JobType": "MyApp.Jobs.MyJob, MyApp",
        "Durable": true
      }
    ],
    "Triggers": [
      {
        "Name": "myTrigger",
        "JobName": "myJob",
        "Cron": {
          "Expression": "0/30 * * * * ?"
        }
      }
    ]
  }
}

PreProcessingCommands

Commands executed before scheduling. All fields are optional:

ProcessingDirectives

Trigger 'DEFAULT.myTrigger' is defined more than once in the scheduling data.

When a file is wrong

Two settings on the plugin decide what a bad file does, and they answer different questions. Both are on FileSchedulingOptions, and everything below is the same for the XML format.

A file that is not there. FailOnFileNotFound is true by default, so a named file that does not exist stops the scheduler being built, with a SchedulerException naming it:

File named 'quartz_jobs.json' does not exist.

Set it to false and the file is logged as missing and skipped, which is what an optional overlay file wants.

A file that is there and is wrong. Whatever went wrong — malformed JSON, a trigger with two schedule blocks, a JobType that will not load, a key declared twice — the processor raises it, the plugin logs it, wraps it in a SchedulerException naming the file, and hands that to every registered ISchedulerListener through SchedulerError. It is rethrown only when FailOnSchedulingError is true, and that setting is false by default: the scheduler otherwise starts without the schedule the file was carrying. Turn it on where a schedule that failed to load should stop the deployment instead of running a scheduler with nothing in it.

Which exception, and why it matters. Quartz.SchedulingDataValidationException — a SchedulerException — is the one that carries every violation it found rather than the first: ValidationExceptions is the list and Message is every message, one per line. A document is checked against the schema, and its keys checked for duplicates, before any of it is applied, so a file with three mistakes in it reports three. Everything else a file can get wrong is an ordinary SchedulerException raised where it happens — a JobType that will not load, a non-durable job with no trigger — so it names the one thing that failed.

Neither makes the file a transaction against the store. PreProcessingCommands have already run by the time a job is stored, and a document with several jobs applies them one at a time.