Hyz.FreeScheduler 0.1.0

Hyz.FreeScheduler

基于开源 FreeScheduler 封装轻量化定时任务调度，支持集群任务、临时的延时任务和重复循环任务，可按秒、每天/每周/每月固定时间、自定义间隔执行。

特性

• 支持 netstandard2.0;net8.0;net9.0;net10.0 多目标框架
• 基于 FreeRedis 持久化，支持单节点、集群、哨兵、主从四种 Redis 连接模式
• 自动扫描程序集中的 BaseJob 子类并注册
• 支持 5 种任务间隔方式：按秒(SEC)、每天(RunOnDay)、每周(RunOnWeek)、每月(RunOnMonth)、自定义(Custom)
• JobId/Expression 优先级规则：ScheduledJobAttribute > 类重写
• CancellationToken 异步取消支持
• 自动清理日志任务
• Redis 缓存 TaskInterval 以枚举名称存储，可读性强

快速开始

1. 安装 NuGet 包

dotnet add package Hyz.FreeScheduler

2. 配置 appsettings.json

{
  "Redis": {
    "ConnectionString": "127.0.0.1:6379,password=xxx,poolsize=10,defaultDatabase=1"
  },
  "AutoClean": {
    "Enabled": true,
    "Expression": "0 0 0 1 * ?"
  }
}

3. 注册服务

using Hyz.FreeScheduler.Extensions;

builder.Services.AddHyzFreeSchedulerService(
    configureOptions: config =>
    {
        config.Redis = new RedisConfig()
        {
            ConnectionString = configuration.GetValue<string>("Redis:ConnectionString")!
        };
        config.AutoClean = new AutoCleanLogConfig()
        {
            Enabled = configuration.GetValue<bool>("AutoClean:Enabled"),
            Expression = configuration.GetValue<string?>("AutoClean:Expression") ?? "0 0 0 1 * ?"
        };
    },
    loggingBuilder: loggingBuilder => loggingBuilder.AddNLog(),
    assembly: typeof(Program).Assembly
);

var app = builder.Build();

// 停止时释放资源
app.Services.UseHyzDisposeFreeScheduler();

Redis 连接模式

支持四种 Redis 连接模式，通过 RedisConfig.Mode 指定，默认为 Single。

Single - 单节点（默认）

{
  "Redis": {
    "ConnectionString": "127.0.0.1:6379,password=xxx,defaultDatabase=1"
  }
}

Cluster - 集群模式

只需提供部分主节点地址，客户端自动发现全部节点。

{
  "Redis": {
    "Mode": "Cluster",
    "Hosts": [
      "192.168.0.2:7001",
      "192.168.0.2:7002",
      "192.168.0.2:7003"
    ]
  }
}

Sentinel - 哨兵模式

ConnectionString 提供连接参数（如 password），MasterName 为哨兵监控的 master 名称，Hosts 为哨兵节点地址（默认端口 26379）。

{
  "Redis": {
    "Mode": "Sentinel",
    "ConnectionString": "password=xxx,defaultDatabase=1",
    "MasterName": "mymaster",
    "Hosts": [
      "192.168.1.10:26379",
      "192.168.1.11:26379",
      "192.168.1.12:26379"
    ],
    "ReadWriteSeparate": true
  }
}

MasterSlave - 主从模式

ConnectionString 为主节点（写），Slaves 为从节点列表（读，随机选择）。

{
  "Redis": {
    "Mode": "MasterSlave",
    "ConnectionString": "127.0.0.1:6379,password=xxx,defaultDatabase=1",
    "Slaves": [
      "127.0.0.1:6380,password=xxx,defaultDatabase=1",
      "127.0.0.1:6381,password=xxx,defaultDatabase=1"
    ]
  }
}

代码配置示例

// 集群模式
config.Redis = new RedisConfig
{
    Mode = RedisMode.Cluster,
    Hosts = new[] { "192.168.0.2:7001", "192.168.0.2:7002", "192.168.0.2:7003" }
};

// 哨兵模式
config.Redis = new RedisConfig
{
    Mode = RedisMode.Sentinel,
    ConnectionString = "password=xxx,defaultDatabase=1",
    MasterName = "mymaster",
    Hosts = new[] { "192.168.1.10:26379", "192.168.1.11:26379" },
    ReadWriteSeparate = true
};

// 主从模式
config.Redis = new RedisConfig
{
    Mode = RedisMode.MasterSlave,
    ConnectionString = "127.0.0.1:6379,password=xxx",
    Slaves = new[] { "127.0.0.1:6380,password=xxx", "127.0.0.1:6381,password=xxx" }
};

定义定时任务

继承 BaseJob 并使用 [ScheduledJob] 特性标记：

Custom（默认）- CRON 表达式

[ScheduledJob(nameof(TestJob), Expression = "0/5 * * * * ?")]
public class TestJob : BaseJob
{
    public override async Task ExecuteAsync(CancellationToken cancellationToken = default)
    {
        // TODO: 实现任务逻辑
        await Task.CompletedTask;
    }
}

SEC - 按秒触发

[ScheduledJob(nameof(IntervalJob), TaskInterval = TaskInterval.SEC, Expression = "10")]
public class IntervalJob : BaseJob
{
    public override async Task ExecuteAsync(CancellationToken cancellationToken = default)
    {
        await Task.CompletedTask;
    }
}

RunOnDay - 每天固定时间

[ScheduledJob(nameof(DailyJob), TaskInterval = TaskInterval.RunOnDay, Expression = "20:00:00")]
public class DailyJob : BaseJob
{
    public override async Task ExecuteAsync(CancellationToken cancellationToken = default)
    {
        await Task.CompletedTask;
    }
}

RunOnWeek - 每周固定时间

// 每周一 20:00:00 执行（格式: 周几:时:分:秒）
[ScheduledJob(nameof(WeeklyJob), TaskInterval = TaskInterval.RunOnWeek, Expression = "1:20:00:00")]
public class WeeklyJob : BaseJob
{
    public override async Task ExecuteAsync(CancellationToken cancellationToken = default)
    {
        await Task.CompletedTask;
    }
}

RunOnMonth - 每月固定时间

// 每月1日 20:00:00 执行（格式: 日:时:分:秒）
[ScheduledJob(nameof(MonthlyJob), TaskInterval = TaskInterval.RunOnMonth, Expression = "1:20:00:00")]
public class MonthlyJob : BaseJob
{
    public override async Task ExecuteAsync(CancellationToken cancellationToken = default)
    {
        await Task.CompletedTask;
    }
}

JobId / Expression 优先级规则

JobId 和 Expression 支持两种来源，优先级：特性 > 类重写

// 示例：特性提供 JobId，Expression 从类属性读取
[ScheduledJob("MyJob")]
public class MyJob : BaseJob
{
    public override string Expression => "0/10 * * * * ?";

    public override async Task ExecuteAsync(CancellationToken cancellationToken = default)
    {
        await Task.CompletedTask;
    }
}

TaskInterval 间隔类型

Round 循环次数

// 执行 10 次后自动停止（默认 -1 永久循环）
[ScheduledJob("MyJob", TaskInterval = TaskInterval.SEC, Expression = "5", Round = 10)]

配置项

SchedulerConfig

RedisConfig

AutoCleanLogConfig