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

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 作业执行的上下文

1. 基类 JobExecutionContext

2. 属性

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

3. 方法

   方法名	参数	说明
   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>();
    });