Hangfire 服务注册和中间件配置必须在 Program.cs 中完成：先调用 AddHangfire 配置存储，再调用 AddHangfireServer 启动工作线程，最后在 UseEndpoints 前添加 UseHangfireDashboard；漏掉任一环节会导致作业不执行、Dashboard 404 或 IBackgroundJobClient 解析失败。
Hangfire 服务注册和中间件配置必须在 Startup.cs 或 Program.cs 中完成
ASP.NET Core 6+ 项目中，Hangfire 的服务注册和中间件启用不能只靠 NuGet 包安装就自动生效。漏掉任一环节会导致后台作业不触发、Dashboard 404 或 BackgroundJobClient 解析失败。
常见错误现象：InvalidOperationException: No service for type 'Hangfire.IBackgroundJobClient' has been registered，或访问 /hangfire 返回 404。
- 安装必需包：
Hangfire.Core、Hangfire.AspNetCore、Hangfire.SqlServer（或Hangfire.Redis） - 在
Program.cs中调用：builder.Services.AddHangfire(config => config.SetDataCompatibilityLevel(CompatibilityLevel.Version_170).UseSimpleAssemblyNameTypeSerializer().UseRecommendedSerializerSettings().UseSqlServerStorage(builder.Configuration.GetConnectionString("DefaultConnection"))) - 必须紧接着调用：
builder.Services.AddHangfireServer()—— 这一步启动后台工作线程，缺了作业永远不会执行 - 中间件需在
app.UseEndpoints之前添加：app.UseHangfireDashboard("/hangfire", new DashboardOptions { Authorization = new[] { new LocalRequestsOnlyAuthorizationFilter() } })
延迟执行、重复任务、手动触发的写法差异很大
不同调度场景对应完全不同的 API 调用方式，混用会导致计划失败或重复入队。
使用场景示例：发邮件通知（延迟 5 分钟）、每日凌晨同步数据（Cron 表达式）、管理后台点击即运行（手动触发）。
- 延迟执行（5 分钟后）：
BackgroundJob.Schedule(() => SendEmail("user@example.com"), TimeSpan.FromMinutes(5)) - 重复任务（每天 2 点）：
RecurringJob.AddOrUpdate("daily-sync", () => SyncData(), "0 2 * * *")—— Cron 表达式是秒 分 时 日 月 周（Hangfire 默认不带秒，若用Hangfire.Cronos才支持秒级） - 手动触发（无延迟/周期）：
BackgroundJob.Enqueue(() => SendEmail("admin@example.com")) - 注意：
RecurringJob的 jobId 是字符串标识，重复调用同名 jobId 会覆盖原有任务；而BackgroundJob.Enqueue每次都生成新 job
自定义 Job 类必须满足无状态、可序列化、无构造函数依赖
把业务逻辑直接写进控制器或注入 IHttpContextAccessor 是常见错误，会导致反序列化失败或空引用异常。
错误现象：System.Runtime.Serialization.SerializationException: Type 'Microsoft.AspNetCore.Http.DefaultHttpContext' in Assembly 'Microsoft.AspNetCore.Http, ...' is not marked as serializable。
- Job 方法必须是
public static，或定义在public且无参数构造函数的类中（推荐后者，便于单元测试） - 避免在 Job 方法体内访问
HttpContext、ControllerContext、ViewData等请求上下文对象 - 需要数据库操作？传入 ID 而非实体对象：
BackgroundJob.Enqueue(() => ProcessOrder(123))，Job 内部再查库 - 若需依赖服务（如
IEmailService），通过JobActivator注入，而非构造函数直接声明（默认激活器不支持 scoped 服务，需自定义）
SQL Server 存储下 Hangfire 表未自动创建或权限不足
UseSqlServerStorage 默认不会建表，也不检查连接字符串权限 —— 这是部署时最常卡住的点。
典型表现：Dashboard 打开空白，日志里出现 Invalid object name 'HangFire.Job' 或 Login failed for user。
- 首次运行前，手动执行
Hangfire.SqlServer自带的 SQL 脚本（路径通常为packages/Hangfire.SqlServer.*/tools/install.sql），或启用自动迁移（不推荐生产环境）：UseSqlServerStorage(connStr, new SqlServerStorageOptions { PrepareSchemaIfNecessary = true }) - SQL Server 登录用户至少需要
db_datareader、db_datawriter和EXECUTE权限（用于存储过程） - 确认连接字符串未指向 LocalDB 或内存数据库（如
Data Source=(localdb)\mssqllocaldb），这些在 IIS 或 Windows Service 下不可靠
Hangfire 的可靠性高度依赖存储层稳定性，尤其在分布式部署时，Redis 或 SQL Server 的高可用配置比代码逻辑更关键。别在没验证存储连通性前就写第一个 Enqueue。
