当前位置：首页 > news >正文

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

news 2025/11/4 8:04:11

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
});