计划任务

EasyAdminBlazor 集成了 FreeScheduler 作为任务调度引擎,支持两种用法:

  1. [Scheduler] 特性标注:给静态方法加一行特性,启动时自动注册为定时任务
  2. 代码动态管理:注入 ISchedulerService,在程序里随时创建、暂停、恢复、删除任务

所有任务都有可视化管理页面(/Admin/TaskScheduler),可以查看执行日志、暂停/恢复、立即运行。

启用扩展

安装 EasyAdminBlazor.Scheduler 扩展包后,在 Program.cs 里调用:

builder.AddEasyAdminBlazor(new EasyAdminBlazorOptions
{
    // 使用 [Scheduler] 特性的类所在的程序集,必须加进 Assemblies
    Assemblies = [typeof(Program).Assembly],
    ...
})
    .AddEasyAdminBlazorScheduler();

方式一:用 [Scheduler] 特性注册任务

给任意静态方法加上 [Scheduler] 特性即可,方法可以无参数,也可以接收一个 IServiceProvider 参数用于解析服务:

using EasyAdminBlazor;

public static class MyJobs
{
    // 每天 03:30 执行一次(Cron 格式:秒 分 时 日 月 周)
    [Scheduler("每日备份", "0 30 3 * * *")]
    public static void DailyBackup()
    {
        // 在这里写任务逻辑
    }

    // 每隔 60 秒执行一次
    [Scheduler("心跳", Interval = SchedulerInterval.Seconds, Argument = "60")]
    public static void Heartbeat()
    {
    }

    // 方法可以接收 IServiceProvider,用来解析数据库、缓存等服务
    [Scheduler("清理过期数据", "0 0 4 * * *")]
    public static void Cleanup(IServiceProvider sp)
    {
        // 用注入的 IFreeSql:多租户下自动指向“当前租户”的库
        var fsql = sp.GetRequiredService<IFreeSql>();
        // ...
    }
}

特性参数说明:

参数 说明
Name 任务名称,在任务列表中显示,也是任务的唯一标识
构造函数 (string name, string cron) 直接传 Cron 表达式(6 位含秒,或 5 位不含秒)
Interval 触发间隔类型,见 SchedulerInterval 枚举
Argument 间隔参数:秒数、固定时刻(如 15:55:59)或 Cron 表达式
Round 执行次数,-1 表示无限循环(默认)
Status 初始状态:Running / Paused / Completed
TenantScope 多租户下的执行范围:EachTenant(默认,每个启用租户各跑一次)/ Host(只跑主库)/ HostAndEachTenant(主库 + 每个租户)

SchedulerInterval 支持的类型:

  • Seconds — 按秒触发,Argument 传秒数
  • RunOnDay — 每天固定时间,Argument 如 15:55:59
  • RunOnWeek — 每周几固定时间,如 2:15:55:59
  • RunOnMonth — 每月第几天固定时间,如 5:15:55:59
  • Custom — 自定义 Cron 表达式

程序启动时框架会自动扫描 Assemblies 注册的程序集,把这些方法注册成任务,打开 /Admin/TaskScheduler 就能看到。

方式二:代码动态创建和管理任务

注入 ISchedulerService,在任意页面或服务里管理任务:

@inject ISchedulerService Scheduler

// 添加一个每天 15:55:59 执行的任务,返回任务 ID
var taskId = Scheduler.AddTask("生成日报", "body", -1, SchedulerInterval.RunOnDay, "15:55:59");

// 添加一个 10 分钟后执行的一次性任务
Scheduler.AddTempTask(TimeSpan.FromMinutes(10), () =>
{
    // ...
});

// 管理任务
Scheduler.PauseTask(taskId);   // 暂停
Scheduler.ResumeTask(taskId);  // 恢复
Scheduler.RunNowTask(taskId);  // 立即运行一次
Scheduler.RemoveTask(taskId);  // 删除

ISchedulerService 常用方法:

方法 说明
AddTask(topic, body, round, interval, argument) 添加循环任务,返回任务 ID
AddTempTask(delay, action) 添加一次性延迟任务
PauseTask(id) / ResumeTask(id) 暂停 / 恢复任务
RunNowTask(id) 立即运行任务
RemoveTask(id) 删除任务
GetTask(id) / GetTasks(...) 查询单个任务 / 分页查询任务列表
GetTaskLogs(taskId, ...) 分页查询任务执行日志
FindTask(predicate) 按条件查找任务

可视化管理页面

访问 /Admin/TaskScheduler 可以:

  • 查看任务列表:名称、触发间隔、已执行次数、状态、上次运行时间、下次触发时间
  • 暂停 / 恢复 / 立即运行任务
  • 查看每次执行的日志(耗时、成功与否、异常信息)
  • 删除任务

注意事项

  • Cron 表达式支持两种格式:6 位(秒 分 时 日 月 周)和 5 位(分 时 日 月 周);不支持 Quartz 的 ? 占位符
  • 非法 Cron 表达式在添加任务时就会被拒绝;历史脏数据在调度时停止该任务,并把失败原因写进任务备注与日志(不再退化成「每 5 秒重试」)
  • 时区默认 +8(Asia/Shanghai),可通过 Scheduler:TimeZoneId(IANA / Windows 时区名)或 Scheduler:UtcOffsetHours(小时偏移)调整
  • Cron 按调度器时区解析:表达式里写几点,就是那个时区的几点。2.6.0 之前按 UTC 解析,在 +8 时区下触发时刻会晚 8 小时;从旧版本升级时请核对已有任务的触发时刻
  • 任务持久化在 FreeScheduler_task / FreeScheduler_tasklog 两张表,会自动创建
  • 使用 [Scheduler] 特性的类所在的程序集,必须加入 EasyAdminBlazorOptions.Assemblies
  • 多租户:[Scheduler] 任务默认每个启用的租户各执行一次,任务内用注入的 IFreeSql / 仓储访问数据库就会落到对应租户库;只在主库执行的宿主级任务设 TenantScope = SchedulerTenantScope.Host
  • 任务里不要用 MainOrmHandle.Orm 访问业务数据(它永远指向主库),也不要自己 CreateScope——框架传入的已经是按执行目标建好的作用域
  • 动态任务(SchedulerExecuting 回调 / AddTempTask)仍在宿主执行一次;需要按租户执行的业务任务请用 [Scheduler] 特性
  • 任务方法建议保持轻量,长时间操作尽量拆分或异步处理