Quartz.Plugins provides some useful ready-made plugins for your convenience.

Quartz provides an interface (ISchedulerPlugin, in the Quartz.Extensibility namespace) for plugging-in additional functionality.

The plugins that ship in this package live in the Quartz.Plugins.* namespaces — Quartz.Plugins.History, Quartz.Plugins.Interrupt, Quartz.Plugins.Json, Quartz.Plugins.Management and Quartz.Plugins.Xml, matching the assembly and NuGet package name. In 3.x they were the singular Quartz.Plugin.*; a quartz.plugin.<name>.type naming the old spelling still resolves, with a warning. They provide functionality such as auto-scheduling of jobs upon scheduler startup, logging a history of job and trigger events, and ensuring that the scheduler shuts down cleanly when the process exits.

Installation

You need to add NuGet package reference to your project which uses Quartz.

Install-Package Quartz.Plugins

Configuration

Plugins are configured by using either DI configuration extensions or adding required configuration keys.

Configuration key in in format quartz.plugin.{name-to-refer-with}.{property}.

See configuration reference on how to configure each plugin

Features

LoggingJobHistoryPlugin

Logs a history of all job executions (and execution vetoes) and writes the entries to configured logging infrastructure.

StructuredLoggingJobHistoryPlugin

Structured logging alternative to LoggingJobHistoryPlugin. Uses named message template parameters (e.g. {JobName}, {TriggerGroup}) instead of index-based placeholders, making log output compatible with structured logging sinks like Serilog and NLog. This avoids template cache memory leaks that can occur with the original plugin.

Message templates can be customized via properties. When customizing, the parameter names in templates are positionally mapped, so they must appear in the same order as the defaults.

Available template properties:

DI configuration:

services.AddQuartz(q =>
{
    q.UseStructuredJobLogging();
});

StructuredLoggingTriggerHistoryPlugin

Structured logging alternative to LoggingTriggerHistoryPlugin. Logs trigger firings, misfires, and completions using named message template parameters for structured logging compatibility.

Message templates can be customized via properties. When customizing, the parameter names in templates are positionally mapped, so they must appear in the same order as the defaults.

Available template properties:

DI configuration:

services.AddQuartz(q =>
{
    q.UseStructuredTriggerLogging();
});

ShutdownHookPlugin

This plugin catches the event of the VM terminating (such as upon a CRTL-C) and tells the scheduler to Shutdown.

XmlSchedulingDataProcessorPlugin

This plugin loads XML file(s) to add jobs and schedule them with triggers as the scheduler is initialized, and can optionally periodically scan the file for changes.

JsonSchedulingDataProcessorPlugin

This plugin loads JSON file(s) to add jobs and schedule them with triggers as the scheduler is initialized, and can optionally periodically scan the file for changes. It is the JSON analog of XmlSchedulingDataProcessorPlugin.

DI configuration:

services.AddQuartz(q =>
{
    q.UseJsonSchedulingConfiguration(x =>
    {
        x.Files = ["quartz_jobs.json"];
        x.ScanInterval = TimeSpan.FromMinutes(1);
        x.FailOnFileNotFound = true;
        x.FailOnSchedulingError = true;
    });
});

See JSON Configuration for the full JSON file format and trigger type reference.

JobInterruptMonitorPlugin

This plugin catches the event of job running for a long time (more than the configured max time) and tells the scheduler to "try" interrupting it if enabled.

Each job configuration needs to have JobInterruptMonitorPlugin.JobDataMapKeyAutoInterruptable key's value set to true in order for plugin to monitor the execution timeout. Jobs can also define custom timeout value instead of global default by using key JobInterruptMonitorPlugin.JobDataMapKeyMaxRunTime.

var job = JobBuilder.Create<SlowJob>()
    .WithIdentity("slowJob")
    .UsingJobData(JobInterruptMonitorPlugin.JobDataMapKeyAutoInterruptable, true)
    // allow only five seconds for this job, overriding default configuration
    .UsingJobData(JobInterruptMonitorPlugin.JobDataMapKeyMaxRunTime, TimeSpan.FromSeconds(5).TotalMilliseconds.ToString())
    .Build();

Both AutoInterruptable and MaxRunTime are read from the merged job data map, so a trigger's data map can also enable interruption or override the timeout for its own fires.

Only the execution that exceeded its allowed run time is interrupted — the plugin monitors each fire instance separately, so concurrent executions of the same job are unaffected. Executions vetoed by a trigger listener do not arm the interrupt timer.

Adding a plugin

AddPlugin comes in the same three shapes as the listener registrations: the container builds the plugin, you build it, or you configure options it is given.

services.AddQuartz(q =>
{
    // the container constructs it, so it gets constructor injection
    q.AddPlugin<MyPlugin>();

    // you construct it
    q.AddPlugin(provider => new MyPlugin(provider.GetRequiredService<IMyPluginDependency>()));

    // it takes an IOptions<MyPluginOptions> of its own
    q.AddPlugin<MyPlugin, MyPluginOptions>(options => options.SomeSetting = "value");
});

Every shape takes an optional name as its last argument:

q.AddPlugin<MyPlugin>("myPlugin");
q.AddPlugin(provider => new MyPlugin(), "myPlugin");
q.AddPlugin<MyPlugin, MyPluginOptions>(options => options.SomeSetting = "value", "myPlugin");

The name is how the scheduler refers to the plugin, and some plugins derive persisted job and trigger keys from it — so it is part of the deployment's identity rather than a label. It is also the name a quartz.plugin.{name}.* key configures the same plugin under, which is what lets a plugin added in code be configured from a file. Left unset, the plugin's type name is used. The plugins shipped with Quartz use their conventional short names (xml, json, jobHistory, …) for that reason.

The options of the third shape belong to the scheduler they were added to, like every other per-scheduler setting: two schedulers can add the same plugin with the same options type and each plugin sees its own configuration. They are named options under the scheduler's name, so a plugin on services.AddQuartz("reporting", …) is configured by services.Configure<MyPluginOptions>("reporting", …) as well — a plain services.Configure<MyPluginOptions>(…) configures the default scheduler's.

Take them as IOptions<MyPluginOptions> for a fixed value, or as IOptionsMonitor<MyPluginOptions> to follow a reloading configuration source. CurrentValue is your scheduler's instance, Get(name) is whichever instance you name, and OnChange fires for your scheduler's options only — so a plugin watching for changes is never handed a sibling scheduler's configuration as though it were its own.

Authoring plugin configuration extensions

When you write your own ISchedulerPlugin, offer the same experience as the built-in plugins with an extension method on IQuartzBuilder. Take an options object of your own, apply it to the plugin, and register the plugin under its conventional name:

public static class MyPluginConfigurationExtensions
{
    public static IQuartzBuilder UseMyPlugin(
        this IQuartzBuilder builder,
        Action<MyPluginOptions>? configure = null)
    {
        ArgumentNullException.ThrowIfNull(builder);

        var options = new MyPluginOptions();
        configure?.Invoke(options);

        // companion services your plugin needs injected
        builder.Services.TryAddSingleton<IMyPluginDependency, MyPluginDependency>();

        return builder.AddPlugin<MyPlugin>(
            provider =>
            {
                var plugin = ActivatorUtilities.CreateInstance<MyPlugin>(provider);
                plugin.SomeSetting = options.SomeSetting;
                return plugin;
            },
            name: "myPlugin");
    }
}

public sealed class MyPluginOptions
{
    public string? SomeSetting { get; set; }
}

The same extension method works wherever an IQuartzBuilder does, which is both configuration styles:

// under a host
services.AddQuartz(q => q.UseMyPlugin(options => options.SomeSetting = "value"));

// standalone, without an application container
var builder = QuartzSchedulerBuilder.Create();
builder.UseMyPlugin(options => options.SomeSetting = "value");

var scheduler = await builder.BuildScheduler();

Configuration written this way and configuration written as quartz.plugin.myPlugin.someSetting reach the same plugin instance, because they agree on its name: the properties are applied to the plugin the code registered rather than building a second copy of it.