定时调度插件------Sundial

标签：插件作业触发器 options context Sundial ------ logger public

1 插件概述

开源链接：https://gitee.com/dotnetchina/Sundial
作者：百小僧
版本：2.5.6

2 使用方式

2.1 安装

nuget ：搜索Sundial或使用命令：Install-Package Sundial
.NET CLI ：dotnet add package Sundial
本地引用：直接编译源码，引用

2.2 使用

2.2.1快速入门

自定义作业处理类

public class TestJob : IJob{
    private readonly ILogger<TestJob> _logger;
    public MyJob(ILogger<TestJob> logger){
        _logger = logger;
    }
    public Task ExecuteAsync(JobExecutingContext context, CancellationToken stoppingToken){
        _logger.LogInformation($"异步执行：{context}");
        return Task.CompletedTask;
    }
}

调用自定义类

//在Startup.cs中注册Schedule服务
Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddSchedule(options =>
        {
            options.AddJob<TestJob>(Triggers.PeriodSeconds(5)
                , Triggers.Minutely());
        });
    })
    .Build();

2.3 AddJob方法参数说明

重载一
- 一个或多个作业触发器
- 场景：作业相互独立，并行
- 参数：AddJob(params TriggerBuilder[] triggerBuilders)
- 参数说明：
  - Triggers.Minutely() 每分钟执行一次
  - Triggers.Period(1000) 每一秒执行一次
  - Triggers.Cron("3,7,8 * * * * ?", CronStringFormat.WithSeconds)) 每分钟第 3/7/8 秒
  - 参数为数组，因此可以包含多个触发器
- 举例
```
// 每5秒和每一分钟执行一次并行的作业
options.AddJob<MyJob>(Triggers.PeriodSeconds(5),Triggers.Minutely());
```

重载二

并发执行一个或多个作业触发器
场景：作业串行，同一时间只有一个作业
参数：AddJob(bool concurrent, params TriggerBuilder[] triggerBuilders)，默认为并行

举例

//并行方式，每秒都会执行，不管上一个作业是否完成
options.AddJob<TestJob>(concurrent: true, Triggers.Secondly());
//串行方式，上一个任务完成才会执行，不一定每秒执行一次
options.AddJob<TestJob>(concurrent: false, Triggers.Secondly());

重载三
- 指定作业id的一个或多个作业触发器，默认系统会自动生成
- 场景：根据作业id进行业务处理，并行
- 参数：AddJob(string jobId, params TriggerBuilder[] triggerBuilders)
- 举例
```
// 定义一个叫job的作业，同一时间可能存在多个名为job的作业
options.AddJob<TestJob>("job", Triggers.Secondly());
```
重载四
- 指定作业id的一个或多个作业触发器且可以设置为串行
- 场景：根据作业id进行业务处理，串行
- 参数：AddJob(string jobId, bool concurrent, params TriggerBuilder[] triggerBuilders)
- 举例：
```
// 定义一个叫job的作业,串行，同一时间只有一个名为job的作业
options.AddJob<TestJob>("job", false, Triggers.Secondly());
```

2.4 JobExecutingContext 作业执行的上下文

基类 JobExecutionContext

属性

属性名	类型	说明
JobId	string	作业id
TriggerId	string	作业触发器
JobDetail	JobDetail	作业信息
Trigger	Trigger	作业触发器
OccurrenceTime	DateTime	作业计划触发时间

方法

方法名	参数	说明
ConvertToJSON(NamingConventions naming = NamingConventions.CamelCase)	NamingConventions命名转换器	输出完整作业的JSON
ToString()	无	输出作业信息+触发器+计划触发事件+下次执行时间/触发器状态

2.3 作者的文档很全

	[参见作者帮助文档](https://furion.baiqian.ltd/docs/job/#2613-%E4%BD%9C%E4%B8%9A%E4%BF%A1%E6%81%AF-jobdetail-%E5%8F%8A%E6%9E%84%E5%BB%BA%E5%99%A8)

3 关于调度器的通用理念

3.1 个人对调度器的理解

进行作业调度，首先要有一个或者多个作业（Job——英文名直译为工作/任务），一般是一个个独立的业务，例如车间通过某个零件使用率来判断是否需要向库房提报备件计划。
那什么时候执行这个任务呢？这就需要一个或者多个触发器（Trigger）来明确什么时候执行作业，触发器可以是一次性的，也可能是通过cron来定时。这样就形成了一个最基本的调度。

3.2 Sundial

作业计划 Scheduler
- 包含作业信息，作业触发器，作业处程序的基础信息
- 包含SchedulerBuilder和TriggerBuilder，任务和触发器的实例，可进行修改

作业信息 JobDetail

通过JobDetail来进行初始化设置，只读类型不可更改
JobBuilder为运行时的JobDetial的类型，可直接修改运行时JobDetail数据

作业调度模块可提供多种方式创建JobBuilder对象

通过Create静态方法创建

// 根据作业 Id 创建
var jobBuilder = JobBuilder.Create("job1");
// 根据 IJob 实现类类型创建
var jobBuilder = JobBuilder.Create<MyJob>();
// 根据程序集名称和类型完全限定名（FullName）创建
var jobBuilder = JobBuilder.Create("YourProject", "YourProject.MyJob");
// 根据 Type 类型创建
var jobBuilder = JobBuilder.Create(typeof(MyJob));
// 通过委托创造动态作业
var jobBuilder = JoBuilder.Create((serviceProvider, context, stoppingToken) =>
{
      serviceProvider.GetLogger().LogInformation($"{context}");
      return Task.CompletedTask;
});

通过JobDetail类型创建

var jobBuilder = JobBuilder.From(jobDetail);
//也可以通过以下方式
var jobBuilder = jobDetail.GetBuilder();

通过LoadForm实例填充当前的JobBuilder

// 会覆盖所有相同的值
jobBuilder.LoadFrom(new
{
      Description = "我是描述",
      Concurrent = false
});
// 支持多个填充，还可以配置跳过 null 值覆盖
jobBuilder.LoadFrom(new
{
      Description = "我是另外一个描述",
      Concurrent = false,
      IncludeAnnotations = default(object)      // 会跳过赋值
}, ignoreNullValue: true);
// 支持忽略特定属性名映射
jobBuilder.LoadFrom(new
{
      Description = "我是另外一个描述",
      Concurrent = false,
      IncludeAnnotations = default(object)      // 会跳过赋值
}, ignorePropertyNames: new[]{ "description" });
// 支持字典类型
jobBuilder.LoadFrom(new Dictionary<string, object>
{
      {"Description", "这是新的描述" },
      {"include_annotations", false },
      {"updatedTime", DateTime.Now }
});

通过注解进行赋值

[JobDetail("jobId")]    // 仅作业 Id
[JobDetail("jobId", "这是一段描述")] // 描述
[JobDetail("jobId", false)] // 串行
[JobDetail("jobId", false, "这是一段描述")] // 串行 + 描述
[JobDetail("jobId", Concurrent = false, Description = "这是一段描述")]
public class MyJob : IJob
{
      // ....
}

通过JSON字符串创建

var jobBuilder = JobBuilder.From(@"{
    ""jobId"": ""job1"",
    ""groupName"": null,
    ""jobType"": ""MyJob"",
    ""assemblyName"": ""ConsoleApp13"",
    ""description"": null,
    ""concurrent"": true,
    ""includeAnnotations"": false,
    ""properties"": ""{}"",
    ""updatedTime"": null
}");

作业触发器Trigger

Trigger在初始化时使用，运行时只读。
TriggerBuilder为运行时的实例，可修改监听

创建TriggerStatus

通过TriggerBuilder.Create进行创建

自定义作业触发器

继承 Trigger 并重写 GetNextOccurrence 方法即可

public class CustomTrigger : Trigger
{
    public override DateTime GetNextOccurrence(DateTime startAt)
    {
        return startAt.AddSeconds(2);
    }
}

调用CustomTrigger触发器

services.AddSchedule(options =>
{
	//TriggerBuilder.Create 或 Triggers.Create都可以
    options.AddJob<MyJob>(Triggers.Create<CustomTrigger>());
});

通过Tirgger类型创建（运行时更新作业触发器）

//通过tigger获得运行的triggerBuilder
var triggerBuilder = TriggerBuilder.From(trigger);
//直接get
triggerBuilder = trigger.GetBuilder();

作业处理程序IJob

作业处理类型注册模式，默认为单例模式，非单例模式，可通过IServiceProvder 创建

// 瞬时的非单例模式，执行完毕即销毁
public class MyJob : IJob
{
    private readonly ILogger<MyJob> _logger;
    private readonly IConfiguration _configuration;
    //当前的服务环境
    private readonly IServiceProvider _serviceProvider;

    public MyJob(ILogger<MyJob> logger, IConfiguration configuration, IServiceProvider serviceProvider)
    {
        _logger = logger;
        _configuration = configuration;
        _serviceProvider = serviceProvider;
    }

    public async Task ExecuteAsync(JobExecutingContext context, CancellationToken stoppingToken)
    {
    	//创建不同的环境对象
        using var serviceScope = _serviceProvider.CreateScope();
        //在另一个环境对象中进行业务操作
        var repository = serviceScope.ServiceProvider.GetService<IRepository<User>>();
        _logger.LogInformation($"{context} {_configuration["key"]}");
        await Task.CompletedTask;
    }
}

// 在该Job中有效的非单例注册模式
public class MyJob : IJob, IDisposable
{
    private readonly ILogger<MyJob> _logger;
    private readonly IConfiguration _configuration;
    private readonly IServiceScope _serviceScope;

    public MyJob(ILogger<MyJob> logger
        , IConfiguration configuration
        , IServiceProvider serviceProvider)
    {
        _logger = logger;
        _configuration = configuration;
        _serviceScope = serviceProvider.CreateScope();
    }

    public async Task ExecuteAsync(JobExecutingContext context, CancellationToken stoppingToken)
    {
        var repository = _serviceScope.ServiceProvider.GetService<IRepository<User>>();
        var user = await repository.GetAsync(1);

        _logger.LogInformation($"{context} {_configuration["key"]}");
        await Task.CompletedTask;
    }

    public void Dispose()
    {
        _serviceScope?.Dispose();
    }
}

作业监视器 IJobMonitor

可通过serviceProvider.GetService()获得一个IJobMonitor

也可自定义一个监视器

public class YourJobMonitor : IJobMonitor
{
    private readonly ILogger<YourJobMonitor> _logger;
    public YourJobMonitor(ILogger<YourJobMonitor> logger)
    {
        _logger = logger;
    }
    public Task OnExecutingAsync(JobExecutingContext context, CancellationToken stoppingToken)
    {
        _logger.LogInformation("执行之前：{context}", context);
        return Task.CompletedTask;
    }
    public Task OnExecutedAsync(JobExecutedContext context, CancellationToken stoppingToken)
    {
        _logger.LogInformation("执行之后：{context}", context);

        if (context.Exception != null)
        {
            _logger.LogError(context.Exception, "执行出错啦：{context}", context);
        }
        return Task.CompletedTask;
    }
}

//在服务中注册
services.AddSchedule(options =>
{
    // 添加作业执行监视器
    options.AddMonitor<YourJobMonitor>();
});

作业执行器 IJobExecutor

当任务出现异常时-超时，异常，熔断，可通过作业执行器来定义执行策略

public class YourJobExecutor : IJobExecutor
{
    private readonly ILogger<YourJobExecutor> _logger;
    public YourJobExecutor(ILogger<YourJobExecutor> logger)
    {
        _logger = logger;
    }
	//jobHandler 当前实例的句柄
    public async Task ExecuteAsync(JobExecutingContext context, IJob jobHandler, CancellationToken stoppingToken)
    {
        // 实现失败重试策略，如失败重试 3 次
        await Retry.InvokeAsync(async () =>
        {
            await jobHandler.ExecuteAsync(context, stoppingToken);
        }, 3, 1000
        // 每次重试输出日志
        , retryAction: (total, times) =>
        {
            _logger.LogWarning("Retrying {current}/{times} times for {context}", times, total, context);
        });
    }
}

//在服务中注册
services.AddSchedule(options =>
{
      // 添加作业执行器
      options.AddExecutor<YourJobExecutor>();
});

标签：插件,作业,触发器,options,context,Sundial,------,logger,public
From： https://www.cnblogs.com/wanghun315/p/16992592.html