计划任务

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)
    {
        var fsql = sp.GetRequiredService<MainOrmHandle>().Orm;
        // ...
    }
}

特性参数说明：

参数 说明
Name 任务名称，在任务列表中显示，也是任务的唯一标识
构造函数 (string name, string cron) 直接传 6 位 Cron 表达式（含秒）
Interval 触发间隔类型，见 SchedulerInterval 枚举
Argument 间隔参数：秒数、固定时刻（如 15:55:59）或 Cron 表达式
Round 执行次数，-1 表示无限循环（默认）
Status 初始状态：Running / Paused / Completed

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 位格式（秒 分 时 日 月 周），秒不能省略
  • 非法 Cron 表达式会被校验拦截；历史脏数据会退化为 5 秒重试，不会导致调度器崩溃
  • 调度器固定使用 +8 时区（Asia/Shanghai）
  • 任务持久化在 FreeScheduler_task / FreeScheduler_tasklog 两张表，会自动创建
  • 使用 [Scheduler] 特性的类所在的程序集，必须加入 EasyAdminBlazorOptions.Assemblies
  • 任务方法建议保持轻量，长时间操作尽量拆分或异步处理