WCP.Scheduling.HangFire 8.0.0

WCP.Scheduling.HangFire

WCP.Scheduling.HangFire 是一套基于 Hangfire 的周期性任务封装组件，用于在 ASP.NET Core 中以约定优于配置的方式统一管理“后台定时作业”。

• 通过配置 JobOptions:Crons 集中管理各个 Job 的 Cron 表达式；

• 所有需要调度的任务实现 IRecurringJob 接口即可；

• 启动时调用一个扩展方法 app.UseJob() 自动扫描并注册到 Hangfire。

• Target Framework: net8.0

• License: Apache-2.0

• 作者 / Author: 吴存平

安装 (Install)

在 NuGet 中搜索并安装：

• 包名：WCP.Scheduling.HangFire

使用 .NET CLI：

dotnet add package WCP.Scheduling.HangFire

使用 Package Manager：

Install-Package WCP.Scheduling.HangFire

PackageReference 示例：

<ItemGroup>
  <PackageReference Include="WCP.Scheduling.HangFire" Version="8.0.0" />
</ItemGroup>

请确保你的项目中已正确配置 Hangfire（存储、Dashboard 等）。

核心类型 (Core Types)

命名空间：WCP.Scheduling.HangFire

• IRecurringJob：所有周期性任务的统一接口，包含单个 Task ExecuteAsync() 方法；
• JobOptions：从 appsettings.*.json 绑定的 Cron 配置类；
• JobExtensions：提供 UseJob 扩展方法，把配置与任务类注册到 Hangfire；
• RecurringJobBuilder：内部使用，负责反射扫描 IRecurringJob 实现类并调用 RecurringJob.AddOrUpdate。

快速开始 (Quick Start)

1. 定义一个周期性 Job

using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using WCP.Scheduling.HangFire;

public class SampleReportJob : IRecurringJob
{
    private readonly ILogger<SampleReportJob> _logger;

    public SampleReportJob(ILogger<SampleReportJob> logger)
    {
        _logger = logger;
    }

    public async Task ExecuteAsync()
    {
        _logger.LogInformation("SampleReportJob 执行中...");
        // TODO: 编写你的业务逻辑，例如发送报表邮件、同步数据等
        await Task.CompletedTask;
    }
}

ExecuteAsync 将由 Hangfire 按 Cron 周期性调用，请尽量保持幂等性并自行捕获业务异常。

2. 在配置文件中声明 Cron

appsettings.json 示例：

{
  "JobOptions": {
    "Crons": {
      "SampleReportJob": "0 0 * * *"  // 每天 0 点执行一次
    }
  }
}

Key 使用 Job 类型名（类名），例如 SampleReportJob。

3. 注册 JobOptions 与 Hangfire

在 Program.cs 中：

using Hangfire;
using WCP.Scheduling.HangFire;

var builder = WebApplication.CreateBuilder(args);

// Hangfire 基本配置（示意）
builder.Services.AddHangfire(config =>
{
    // config.UseSqlServerStorage(...);
});

builder.Services.AddHangfireServer();

// 绑定 JobOptions 配置
builder.Services.Configure<JobOptions>(
    builder.Configuration.GetSection("JobOptions"));

var app = builder.Build();

// 使用 Hangfire Dashboard（可选）
app.UseHangfireDashboard();

// 自动加载并注册所有 IRecurringJob
app.UseJob(removeIfExists: true);

app.Run();

removeIfExists: true 会在注册前移除同名任务，确保修改 Cron 后能生效。

工作原理 (How It Works)

1. 应用启动时，UseJob() 从 DI 中获取 JobOptions；
2. RecurringJobBuilder 通过反射扫描当前 AppDomain 中所有实现了 IRecurringJob 的具体类；
3. 对每个 Job 类型：
   • 以类型名（例如 SampleReportJob）为 key 去 JobOptions.Crons 中查找 Cron 表达式；
   • 如存在配置，则调用 RecurringJob.AddOrUpdate 注册；
   • 如未配置，对应任务会跳过并输出日志提醒。

注意事项 (Notes)

• 请确保所有 IRecurringJob 实现类能被应用程序加载（通常放在当前项目或其引用的程序集内）。
• Cron 表达式配置错误会导致任务无法按预期执行，请使用在线工具或 Hangfire 自带工具验证 Cron。
• 为避免长时间任务堆积，请合理设置队列与超时策略，并对任务内使用的资源做好异常恢复和重试设计。

License

本项目使用 Apache-2.0 许可证。详情请参阅 NuGet 包或源码中的 LICENSE 说明。