计划任务
EasyAdminBlazor 集成了 FreeScheduler 作为任务调度引擎,支持两种用法:
[Scheduler]特性标注:给静态方法加一行特性,启动时自动注册为定时任务- 代码动态管理:注入
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:59RunOnWeek— 每周几固定时间,如2:15:55:59RunOnMonth— 每月第几天固定时间,如5:15:55:59Custom— 自定义 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]特性 - 任务方法建议保持轻量,长时间操作尽量拆分或异步处理