Hangfire 入门与实战：在 .NET Core 中实现可靠后台任务处理

Hangfire 是一个开源、免费（LGPLv3 许可）、跨平台的 .NET 后台任务处理框架，支持在控制台应用、Windows 服务等多种环境中运行。它无需额外部署 Windows 服务或计划任务，即可实现可靠、持久、分布式的后台作业处理。

一、Hangfire 是什么？

Hangfire 是一个为 .NET 和 .NET Core 应用程序设计的后台任务处理库，其核心特性包括：

• 即发即忘（Fire-and-Forget）：任务创建后立即入队并异步执行一次。
• 延迟任务（Delayed）：指定一段时间后执行一次。
• 循环任务（Recurring）：基于 CRON 表达式周期性执行。
• 延续任务（Continuations）：在父任务完成后触发后续任务。
• 批处理（Batch，Pro 功能）：将多个任务原子性地组合为一个批次。

Hangfire 的所有任务都持久化存储 （支持 SQL Server、Redis 等），即使应用崩溃或重启，任务也不会丢失，并具备自动重试机制 和内置Web 仪表盘，极大简化了后台任务的开发与运维。

二、核心功能详解

1. 即发即忘任务（Fire-and-Forget）

适用于无需等待结果、立即执行的场景，如发送邮件、日志记录等。

复制代码

BackgroundJob.Enqueue(() => Console.WriteLine("Hello, world!"));

// 调用实例方法（需注册依赖）
BackgroundJob.Enqueue<EmailService>(x => x.Send("user@example.com"));

2. 延迟任务（Delayed）

在指定时间后执行一次，适用于预约提醒、缓期处理等。

复制代码

// 7 天后执行
BackgroundJob.Schedule(() => Console.WriteLine("Delayed!"), TimeSpan.FromDays(7));

// 调用带参数的实例方法
BackgroundJob.Schedule<EmailService>(
    x => x.SendReminder("user@example.com"),
    TimeSpan.FromHours(24)
);

3. 循环任务（Recurring）

使用 CRON 表达式定期执行，适用于数据同步、定时统计等。

复制代码

// 每天凌晨执行
RecurringJob.AddOrUpdate("daily-stats", () => StatsService.Generate(), Cron.Daily);

// 每 21 秒执行一次（秒级 CRON）
RecurringJob.AddOrUpdate("heartbeat", () => HeartbeatService.Ping(), "*/21 * * * * *");

Hangfire 使用 Cronos 库解析 CRON 表达式，支持秒级精度（标准 CRON 通常只到分钟）。

4. 延续任务（Continuations）

在父任务完成后触发后续逻辑，支持成功/失败分支。

复制代码

var parentJobId = BackgroundJob.Enqueue(() => ProcessOrder());

// 无论成功失败都继续
BackgroundJob.ContinueWith(parentJobId, () => NotifyUser());

// 仅成功时继续
BackgroundJob.ContinueWith(parentJobId, () => UpdateInventory(), JobContinuationOptions.OnSuccess);

// 仅失败时执行补偿
BackgroundJob.ContinueWith(parentJobId, () => Rollback(), JobContinuationOptions.OnFailure);

⚠️ 注意：方法名应为 ContinueWith（文档中有时误写为 ContinueJobWith，实际 API 为 ContinueWith）。

三、快速开始（.NET 6+ / .NET 8）

1. 安装 NuGet 包

复制代码

dotnet add package Hangfire
dotnet add package Hangfire.SqlServer  # 使用 SQL Server 存储
# 或
dotnet add package Hangfire.Redis       # 使用 Redis 存储

2. 配置服务（Program.cs）

复制代码

var builder = WebApplication.CreateBuilder(args);

// 配置 Hangfire 使用 SQL Server
builder.Services.AddHangfire(config =>
    config.UseSqlServerStorage(builder.Configuration.GetConnectionString("HangfireDb"))
);

// 启动 Hangfire 服务器（工作线程）
builder.Services.AddHangfireServer();

var app = builder.Build();

// 启用 Hangfire Dashboard（默认路径：/hangfire）
app.UseHangfireDashboard();

// 示例：启动时调度一个任务
app.MapGet("/test", () =>
{
var jobId = BackgroundJob.Enqueue(() => Console.WriteLine("Test job executed!"));
return Results.Ok($"Job ID: {jobId}");
});

app.Run();

3. 连接字符串（appsettings.json）

复制代码

{
"ConnectionStrings":{
"HangfireDb":"Server=.;Database=HangfireDB;Trusted_Connection=true;TrustServerCertificate=true;"
}
}

Hangfire 会自动创建所需表结构（如 HangFire.Job, HangFire.State 等），无需手动建表。

四、高级特性

1. 依赖注入（IoC 容器集成）

Hangfire 支持通过构造函数注入依赖：

复制代码

publicclassEmailService
{
privatereadonly IEmailSender _sender;
publicEmailService(IEmailSender sender) => _sender = sender;

publicvoidSend(string to) => _sender.Send(to, "Hello!");
}

在 Program.cs 中注册服务：

复制代码

builder.Services.AddScoped<IEmailSender, SmtpEmailSender>();
builder.Services.AddScoped<EmailService>();

Hangfire 会自动从 DI 容器解析 EmailService 实例。

2. 多队列与优先级

可为任务指定队列，并配置服务器优先处理高优先级队列：

复制代码

[Queue("critical")]
publicvoidSendUrgentNotification() { }

// 注册时指定队列顺序（先处理 critical）
builder.Services.AddHangfireServer(options =>
{
    options.Queues = new[] { "critical", "default" };
});

3. 自动重试与取消

• 自动重试 ：默认重试 10 次，可通过 [AutomaticRetry(Attempts = 5)] 自定义。
• 取消令牌：支持优雅终止长时间运行任务。

publicvoidLongRunningTask(CancellationToken token)
{
for (int i = 0; i < 1000; i++)
{
token.ThrowIfCancellationRequested();
Thread.Sleep(1000);
}
}

4. 文化信息（Culture）自动保留

Hangfire 默认通过 PreserveCultureAttribute 捕获并恢复 CurrentCulture 和 CurrentUICulture，确保本地化行为一致。

五、存储支持

Hangfire 官方支持：

• SQL Server（含 Azure SQL）：安装简单，适合大多数企业环境。
• Redis：高性能，低延迟，适合高吞吐场景。

社区还提供了 PostgreSQL、MongoDB、LiteDB 等存储实现。

SQL Server 配置建议（Hangfire 1.7+）：

复制代码

.UseSqlServerStorage("conn", new SqlServerStorageOptions
{
    QueuePollInterval = TimeSpan.Zero,
    SlidingInvisibilityTimeout = TimeSpan.FromMinutes(5),
    UseRecommendedIsolationLevel = true,
    DisableGlobalLocks = true
});

六、监控与运维

• 内置 Dashboard ：访问 /hangfire 可查看任务状态、重试、日志等。
• 自动清理：成功/删除的任务默认 24 小时后自动过期（可配置）。
• 日志集成：通过 LibLog 自动对接 NLog、Serilog 等主流日志框架。

七、总结

Hangfire 以极简的 API 提供了企业级后台任务处理能力：

✅ 无需额外进程

✅ 持久化 + 自动重试

✅ 支持多种任务类型

✅ 内置监控仪表盘

✅ 开源免费（商业可用）

无论是发送邮件、处理订单、定时同步，还是构建微服务后台作业系统，Hangfire 都是一个值得信赖的选择。

官网：https://www.hangfire.io(👉 点击[阅读原文]查看官方文档)
GitHub ：https://github.com/HangfireIO/Hangfire
文档：https://docs.hangfire.io