Zongsoft.Externals.Hangfire 2.9.2

Zongsoft.Externals.Hangfire Extension Plugin Library

English | 简体中文

Overview

Zongsoft.Externals.Hangfire adapts Hangfire to the Zongsoft scheduling abstractions. It provides:

• IScheduler<TriggerOptions.Cron> for recurring jobs driven by Cron expressions.
• IScheduler<TriggerOptions.Latency> for one-off jobs executed after a delay.
• A background Server worker that dispatches jobs to Zongsoft IHandler instances.
• Optional Redis storage and ASP.NET Core Dashboard integration.

The library targets .NET 8, .NET 9, and .NET 10. Hangfire storage must be configured before the scheduler or server starts.

Packages

Install the packages required by the host:

dotnet add package Zongsoft.Externals.Hangfire
dotnet add package Zongsoft.Externals.Hangfire.Storages.Redis
dotnet add package Zongsoft.Externals.Hangfire.Web

Plugin setup

Load Zongsoft.Externals.Hangfire.plugin to register the schedulers. A daemon host should also load Zongsoft.Externals.Hangfire-daemon.plugin; it creates and starts the background server and exposes /Workbench/Scheduler/Handlers as the handler registration point.

Choose and configure exactly one Hangfire JobStorage. The Redis adapter is available through Zongsoft.Externals.Hangfire.Storages.Redis.plugin and uses the Hangfire connection setting from the Zongsoft Redis settings provider.

Server configuration

The server reads options from Externals/Hangfire/Server. The packaged defaults set the schedule polling interval to 10 seconds:

<options>
	<option path="Externals/Hangfire">
		<server scheduleInterval="10s" />
	</option>
</options>

Supported server attributes:

Only positive numeric or duration values override Hangfire defaults. When the worker is named something other than Server, its Hangfire server name is emitted as <worker-name>@<machine-name>.

Register a handler

The real sample plugin registers MyHandler, a HandlerBase<object> that logs its argument, parameters and process-local invocation count:

<extension path="/Workbench/Scheduler/Handlers">
	<object name="MyHandler" type="Zongsoft.Externals.Hangfire.Samples.MyHandler, Zongsoft.Externals.Hangfire.Samples" />
</extension>

Deploy the sample assembly and its full manifest, not just this extension fragment. Each running server whose collection contains that name receives dispatched jobs. The name is persisted with jobs; changing it can orphan queued work. This sample does not generate business reports.

Schedule jobs

The following API adaptation schedules the existing MyHandler sample through the public scheduler contract. Run it only after daemon/storage/sample plugin composition, with isolated test storage:

using Zongsoft.Services;
using Zongsoft.Scheduling;

var services = ApplicationContext.Current.Services;
var cron = services.ResolveRequired<IScheduler<TriggerOptions.Cron>>();
var latency = services.ResolveRequired<IScheduler<TriggerOptions.Latency>>();

var recurringId = await cron.ScheduleAsync(
	"MyHandler", "Zongsoft.Externals.Hangfire.Samples",
	new TriggerOptions.Cron("hangfire-samples", "0 2 * * *", TimeZoneInfo.Utc),
	CancellationToken.None);

var delayedId = await latency.ScheduleAsync(
	"MyHandler", "Zongsoft.Externals.Hangfire.Samples",
	new TriggerOptions.Latency(TimeSpan.FromMinutes(5)),
	CancellationToken.None);

These are alternative trigger modes; schedule only the one needed. The result is a job identifier: retain it for RescheduleAsync or UnscheduleAsync. Clean up recurring test jobs explicitly. The framework's real ScheduleCommand also passes handler names, pipeline values and trigger options to IScheduler.ScheduleAsync; it does not require a ReportScheduler wrapper.

Command integration

The generic Scheduler, Schedule, Reschedule, and Unschedule commands are provided by the Zongsoft.Commands package under Zongsoft.Scheduling.Commands. Load Zongsoft.Commands.plugin when command-line scheduling is required; the Hangfire package itself no longer owns those commands.

Web Dashboard

Loading Zongsoft.Externals.Hangfire.Web.plugin registers Hangfire with the ASP.NET Core host and calls UseHangfireDashboard() during application initialization. Configure Dashboard authorization and routing according to the security requirements of the hosting application; do not expose the Dashboard publicly without access controls.

Samples

See the sample project for a minimal handler plugin. Storage-specific and web-specific projects are available under storages and web.

Plugin-Based Integration

Compose this feature through the host; a package reference supplies compile-time APIs, while plugin loading also requires deployed manifests and runtime assets. See the complete plugin workflow.

The manifest selects Zongsoft.Externals.Hangfire-$(site).plugin; the daemon variant contributes the scheduler and startup worker. Deploy a storage adapter such as Redis and configure it before enabling the worker. A Web dashboard is a separate package, not a worker host.

Add this fragment to an existing host .deploy (retain Main and the host’s other base manifests; do not replace the whole file):

[plugins zongsoft externals hangfire]
nuget:Zongsoft.Externals.Hangfire

Run dotnet deploy against a test deployment as explained in the workflow, with the host's framework, platform, architecture and, where needed, site. Pin compatible versions in real deployments; application dependencies such as databases, caches or commercial runtimes are still separate prerequisites.

Additional artifacts listed by the deployment manifest include Zongsoft.Externals.Hangfire.option, Zongsoft.Externals.Hangfire.plugin, Zongsoft.Externals.Hangfire-$(site).plugin. Retain assemblies, dependencies and satellite resource directories as well. Restart the host after deployment, check plugin loading and service/driver registration, then verify the workflow above; copied files alone do not prove that the feature is active.