Hangfire for C# (.NET): 完整指南及示例

什么是 Hangfire，为什么需要它？

Hangfire 是一个强大且流行的 C# (.NET) 库，用于执行后台任务（background jobs）。在现代 Web 开发中，经常需要执行那些不应阻塞应用程序主执行流程的操作。例如：发送电子邮件通知、生成报告、处理上传的文件、与外部 API 同步数据、清理数据库中的过期记录等等。

Hangfire 提供了一种简单而灵活的方式来启动此类任务。该库的关键功能包括：

\n
• 后台执行任务： 任务异步执行，不会阻塞对用户的响应。
\n
• 计划任务： 可以按计划（cron 表达式）或延迟启动任务。
\n
• 可靠性： Hangfire 将任务信息保存在持久化存储（数据库）中。即使应用程序重启，未完成的任务也会被执行。
\n
• 监控： 内置的 Web 界面（Dashboard）允许您跟踪任务状态、查看日志、重新启动失败的任务。
\n
• 重试机制： 如果任务因错误而失败，Hangfire 会自动尝试重新执行（具有可配置的重试策略）。
\n
• 与 DI 集成： 易于与 ASP.NET Core 中的依赖注入（Dependency Injection）容器集成。
\n

Hangfire 支持多种存储：SQL Server、PostgreSQL、Redis、MongoDB 等。这使其适用于任何规模的项目——从小型网站到高负载的企业级系统。

安装

Hangfire 通过 NuGet 包管理器安装。与 Python 使用 pip install 不同，在 .NET 生态系统中使用 dotnet add package 或 Visual Studio 的包管理器。

要安装 Hangfire 基础包，请在终端（项目根文件夹中）执行以下命令：

dotnet add package Hangfire

此命令将安装 Hangfire 核心以及用于内存存储（InMemory）的依赖项。对于生产环境，您需要安装特定数据库的包，例如：

\n
• SQL Server: dotnet add package Hangfire.SqlServer
\n
• PostgreSQL: dotnet add package Hangfire.PostgreSql
\n
• Redis: dotnet add package Hangfire.Redis
\n

安装包后，需要在 Program.cs（对于 ASP.NET Core）或 Startup.cs 文件中配置 Hangfire。

快速入门

让我们看一个在 ASP.NET Core 应用程序中配置和使用 Hangfire 的最小示例。

步骤 1：在 Program.cs 中配置

using Hangfire;\nusing Hangfire.SqlServer;\n\nvar builder = WebApplication.CreateBuilder(args);\n\n// 添加 Hangfire 并使用 SQL Server 存储\nbuilder.Services.AddHangfire(configuration => configuration\n    .SetDataCompatibilityLevel(CompatibilityLevel.Version_180)\n    .UseSimpleAssemblyNameTypeSerializer()\n    .UseRecommendedSerializerSettings()\n    .UseSqlServerStorage(builder.Configuration.GetConnectionString("HangfireConnection")));\n\n// 添加 Hangfire 服务器\nbuilder.Services.AddHangfireServer();\n\nvar app = builder.Build();\n\n// 启用 Dashboard（监控面板）\napp.UseHangfireDashboard();\n\n// 一个简单的后台任务示例\napp.MapGet("/fire-and-forget", () =>\n{\n    var jobId = BackgroundJob.Enqueue(() => Console.WriteLine("Hello from Hangfire!"));\n    return $"Job {jobId} has been enqueued.";\n});\n\napp.Run();

步骤 2：创建任务

在上面的示例中，我们使用了方法 <