任务计划程序:创建、调度与执行历史
UI/ColorVision.Scheduler/ 负责把 SchedulerInfo 定义注册到 Quartz、保存调度意图并记录已返回的执行结果。该包当前只面向 net10.0-windows7.0,使用 Quartz 4;真正的设备、流程和客户操作由各 IJob 实现负责。任务已登记、Quartz 已触发、业务已完成和历史已落盘是不同完成条件。
创建和管理任务
- 点击主程序状态栏的**时钟图标(任务计划程序)**打开任务卡片列表。图标显示设置见状态栏。
- 点击 创建任务,选择任务类型,核对任务名称、分组及该类型的参数。只有一个可用类型时自动选中;切换类型会更新建议名称,但保留用户手填的名称和分组。
- 设置执行计划、重复方式和间隔,核对实时计划预览;“多次”的追加次数不包含首次执行。需要稍后开始时选中 延迟启动,未设置过延迟时预填
00:05:00,可继续修改。 - 优先级与超时在高级设置中,默认折叠;编辑含非默认高级参数的任务时自动展开。点击 创建任务或保存修改,成功后窗口关闭;输入格式、参数生成、校验或保存失败会在窗口内显示错误并保留表单。
- 卡片主操作按任务类型与状态显示:间隔/重复任务为执行任务、继续执行、重新执行;Cron、日历和每日间隔任务为启用计划、重新启用。计划已经启动时禁用主操作,显示等待执行、执行中或计划已启用,并提供暂停任务。编辑任务保留在卡片上;更多(•••)和右键菜单提供仅执行一次、任务历史、属性与删除入口。顶部历史查看全部记录,导出菜单提供 CSV、JSON 和报告。
创建 执行流程 任务时,选择一个已保存的流程模板。任务名称默认采用模板名称,可以自行修改。任务按模板标识读取触发时已保存的内容,主窗口当时选中的模板不决定运行目标。执行仍使用主工作区,工作区有未保存修改或已有流程在运行时,本次会报告未能启动。若已绑定模板不可用,在任务中重新选择模板。旧的未绑定任务沿用主工作区当前流程,编辑保存时可绑定已保存模板。
流程任务等待前处理、流程执行和后处理的完成链。任务历史的详情显示本次实际运行的流程名、批次号、最终状态以及可用的执行消息和后处理失败原因。模板改名或任务改绑后,已经写入的历史仍显示运行当时的流程名。
默认“间隔/重复 + 一次”计划可在创建后立即执行。重启只加载已保存的任务,不自动运行:未完成任务显示“已暂停”,完成的有限计划显示“计划已完成”。暂停后主操作保留进度,继续剩余计划;完成后点击重新执行会按原次数、间隔及延迟开始完整新一轮,无需打开编辑窗口。定时类型点击启用计划后按设定时间触发。仅执行一次额外运行一次,不消耗计划次数,也不解除暂停。涉及设备或流程的操作仍应先核对配置和运行条件。暂停、单次执行和关闭窗口的具体效果见暂停与关闭。
| 设置 | 默认值与含义 |
|---|---|
| 执行计划 | Simple,界面显示“间隔/重复” |
| 重复方式 | 一次;选择“多次”时,次数表示首次之后的追加次数,例如填 2 共触发 3 次 |
| 间隔时间 | 00:00:10;用于重复触发,Interval 模式要求整数秒 |
| 延迟启动 | 默认关闭;启用后延迟必须大于零 |
| 优先级 | 5,允许 1–10;参与触发器排序,不抢占正在执行的任务 |
| 超时(秒) | 0;由具体 Job 决定是否使用该值,调度器没有统一终止所有 Job 的超时层 |
任务名称和分组共同组成 JobKey。编辑调度参数应使用编辑任务入口;修改身份会影响统计归属,见修改完成与回退。
窗口布局与代码边界
任务窗口以少量任务为主要使用场景:卡片聚合名称、分组/类型、计划、状态、前后触发时间、运行计数及最后结果/耗时,窗口高度随内容调整;达到工作区高度上限后滚动。创建窗口也按内容调整高度,参数较多或窗口缩小时滚动表单,底部操作始终留在滚动区域之外。两种窗口使用主题动态资源,保留浅色/深色切换。
TaskViewerWindow 负责选择、窗口操作及 Copilot 上下文;CreateTask 负责编辑草稿、属性编辑器和提交。Presentation/SchedulerPresentation.cs 投影计划、状态及主操作文案,SchedulerStyles.xaml 共享样式,SchedulerTaskExporter.cs 生成导出快照;展示字段不写入 SchedulerInfo。ISchedulerService.ExecuteJob 是主操作入口,统一处理继续剩余计划与完成后重新安排;公开窗口构造、既有 SchedulerInfo 属性和序列化格式保留,内部构造允许注入服务以隔离界面验证。
正常窗口等待管理器的 InitializationTask 后启用操作。创建表单提交前检查当前可见输入的绑定转换错误及调度参数,避免非法时间或整数仍以旧解析值提交;保存期间禁用重复提交与关闭。窗口不再设置全局集合视图的无条件过滤器,也不在暂停/删除后重复修改由管理器维护的状态或集合。关闭窗口解除订阅,初始化晚到或执行回调不会再更新已关闭窗口。
首次访问和恢复顺序
QuartzSchedulerManager.GetInstance() 创建进程内单例,构造函数依次执行 Load()、RestoreStatsFromDb()、注册 Copilot 上下文,然后把 Start() 保存为 InitializationTask。取得对象不等于异步初始化已完成。
Load()读取 JSON;统计恢复会取得SchedulerDbManager,其首次构造创建目录并执行CodeFirst.InitTables<JobExecutionRecord>(),即使当前没有任务也可能创建历史数据库。Start()通过QuartzSchedulerBuilder创建本进程持有的 scheduler,显式保留DefaultQuartzScheduler名称、10 个最大并发 worker、内存 JobStore 和 60 秒 misfire 阈值;随后注册TaskExecutionListener、发现 Job 类型,再逐项调用RestoreJob登记没有自动触发器的 durable Job。最后启动 scheduler,等待用户明确执行/启用计划或选择仅执行一次;不会把加载定义当作创建新计划。TaskViewerInitializer.Order=1000的正常宿主入口等待InitializationTask,让低 Order 的服务初始化先执行。但SchedulerStatusBarProvider、TaskViewerWindow和历史窗口的上下文注册也会取得单例,不能据初始化器顺序断言所有首次访问都已等待设备就绪。- 单个任务类型丢失、定义校验失败或注册失败会汇总警告,其他可恢复任务仍会登记;启动阶段整体异常则记录日志、提示并使初始化任务失败。JSON/SQLite 加载异常有各自的捕获分支,不等于启动被统一阻断。
Job 类型来自当次 AssemblyService.Instance.GetImplementationTypes(typeof(IJob)),不来自 SQLite。发现条件是实现 IJob 的非抽象、非开放泛型类,范围限于发现视图,主程序中不含 Quartz 自身的内部 Job。显示键取 DisplayNameAttribute 或类型名,同名会覆盖目录项;当前没有持续监听新程序集重新发现 Job 的机制。
JSON 定义和计划进度
两种文件都位于 Environments.DirStateScheduler,即 DirAppData/State/Scheduler;默认公司名为 ColorVision 时是 %AppData%/ColorVision/State/Scheduler。DirAppData 可由宿主设置,实际根目录以运行配置为准。
| 文件 | 保存和恢复的责任 | 不能据此推断 |
|---|---|---|
scheduler_tasks.json | SchedulerTaskSerializer 保存整组 SchedulerInfo,含 Job 类型、配置、调度参数、本轮已触发次数、下一计划时间、完成标记及显示/统计字段 | 不是业务成功、在途执行或设备动作恰好一次的保证 |
SchedulerHistory.db | JobExecutionRecord 保存每次返回后的开始/结束时间、耗时、成功标记、结果与消息;启动时按 JobName/GroupName 恢复部分统计 | 不是任务定义,也不是设备实际静止或每次执行都已记录的保证 |
JSON 使用 TypeNameHandling.All 保留多态类型和 IJobConfig。加载依赖对应程序集和类型,应使用可信本机文件。保存先写同目录临时文件,再用 File.Replace 保留 .bak,首次保存则移动文件。JSON、Quartz 和 SQLite 各自提交。
管理器加载时,如果主文件缺失且备份可读取,会从 .bak 恢复主文件并提示核对进度。恢复的计划保持暂停或已完成。已有主文件无法解析或任务类型不可用时,管理器保留主文件和备份,并拒绝保存更改。可在修复任务类型或手动恢复有效主文件后重新启动应用。序列化器的 LoadFromFile 读取指定文件,应用的备份恢复由管理器加载入口触发。
多个实例使用同一任务文件时,管理器拒绝从过期定义保存,保留已写入的主文件和备份。收到定义变化提示后,重启该实例载入当前定义,再重试修改。
SchedulerScheduleState 分开记录累计 RunCount 和本轮进度(HasScheduleCheckpoint、ScheduledFireCount、NextScheduledFireTimeUtc、ScheduleCompleted)。自动触发先保存进度,再执行任务。暂停只拦截后续触发,同一次触发的即时重试沿用已保存的进度。保存失败则保留原进度并暂停,状态的悬停提示显示原因,修复后可继续。仅执行一次只更新累计统计和上次实际执行时间。
重启不注册自动触发器。继续时只安排未完成次数,保留仍在未来的下一时间;已过期的简单重复计划从当前时间加一个间隔开始,不补跑积压触发,也不重置已经开始的延迟。编辑保存会明确建立新一轮计划,重置计划进度并保留同身份的累计历史统计。
旧定义缺少本轮进度:只有有限计划同时保存了有效“上次执行”且“下次执行”为 N/A 时,才识别为已完成。累计历史次数可能包括旧计划、手动执行与失败,不能拿它猜剩余次数;缺乏证据的旧任务保持暂停,用户核对后再继续或编辑。JSON 检查点与设备动作、SQLite 历史并非原子事务;进程在业务进行中退出或检查点保存失败时,不能据完成标记证明业务成功,也不能保证自动补账。
缺少定义版本的旧 Interval + Forever 任务会迁移为 Paused 并写回版本:旧实现误表现为每日一次,修正后的触发器会按配置间隔重复。重新恢复这类任务可能造成高频设备动作,必须先核对间隔与实际运行授权,不能当成无风险迁移确认。
触发器、任务身份和并发
SchedulerTriggerFactory 验证 Job 类型、任务名/分组、枚举、优先级、非负超时以及相应的间隔、延迟和 Cron,然后产生稳定的 JobName-trigger/GroupName:
Simple的 Once 只设置首次触发;Multiple 的RepeatCount是首次之后的追加次数;Forever 按Interval重复。Interval使用DailyTimeIntervalScheduleBuilder,要求整数秒间隔。Multiple 同样传递追加次数,Forever 不设置零重复次数;不要把它当成 Simple 触发器或“每天只执行一次”。Calendar当前固定为一个日历日间隔,不能把界面“24 h”理解为跨夏令时始终固定秒数;Cron 直接交给 Quartz。scheduler 的全局 misfire 阈值为 60 秒,但各触发器没有额外指定时区或逐类 misfire 指令,具体时区/错过触发行为不能由任务标题推断。Priority传给触发器,不是抢占正在执行的 Job。主操作ExecuteJob在变更门内拒绝已经启用或仍在执行的任务,完成后复用编辑的校验、替换及保存失败回退路径,避免重复点击建立多轮计划。更多菜单的仅执行一次调用Scheduler.TriggerJob(JobKey),保留独立单次触发语义;返回只表示触发请求完成,不是业务完成,也不是暂停状态下绝对不可运行的保证。
_mutationGate 串行化创建、更新、删除、暂停等管理操作,并不串行化 Job 执行。是否禁止同一任务并发由 Job 自身的 [DisallowConcurrentExecution] 等机制决定;该属性以 JobKey 为界,不能防止两个不同任务名同时操作同一设备。CameraCaptureJob、SpectrumGetDataJob 和 HeadlessFlowJob 声明了此属性,不能据此扩展成所有 Job 都受保护。
TaskExecutionListener 按 FireInstanceId 记录在途执行,同一 JobKey 的一个执行结束时,另一个仍在途就保持 Running。但 Paused 意图优先保留,所以列表显示 Paused 也可能仍有在途操作;不要把 TaskInfos.Status 当作独立的设备运行锁。
修改完成、回退与界面边界
CreateTask 提交新建/编辑时检查 SchedulerOperationResult.Success,失败不关闭窗口。编辑路径先克隆定义;UpdateJob 使用原任务名/分组定位旧任务,校验新定义和身份冲突,并拒绝更新当前正在执行的原 JobKey。
创建、更新和删除等路径用 SchedulerStandbyLease 暂停新的触发分派,记录/替换 Quartz 定义和内存列表后保存 JSON,再按原状态恢复 scheduler。保存失败会尝试移除新 Job 或恢复原定义和暂停意图,恢复触发器时保留下次触发时间和已触发次数。已经耗尽的触发器不重新启用。补偿异常见日志。Standby 不等待已有 Job 结束,调度修改成功后仍须按 Job 历史核对业务执行结果。
同身份编辑会在替换前合并最新运行统计,防止编辑期间完成的执行被旧副本覆盖。改任务名或分组则被视为新统计身份,列表计数归零;旧 SQLite 历史仍保留在旧键下。删除任务不删除历史。直接修改 SchedulerInfo 属性、调用 SaveTasks 或 LoadTasks 不能替代 CreateJob/UpdateJob 的 Quartz 注册流程。
IConfigurableJob 定义配置类型与默认配置工厂,创建表单通过 PropertyEditorHelper 生成编辑器,并在保存时检查实现 IValidatableObject 的配置。管理器把 SchedulerInfo 写入 JobDataMap,FlowJob 从其配置解析模板标识。要求额外键的 HeadlessFlowJob 不能仅因出现在类型列表就视为已配置可运行,见无界面流程执行。
暂停、取消、超时和关闭
| 调用或状态 | 实际效果与限制 |
|---|---|
StopJob / PauseAll | 暂停后续触发并保存状态。全部暂停会尝试每个任务,再统一保存。保存失败时已暂停的任务保持暂停并提示错误,可再次执行暂停以保存。已开始的 Job 继续执行 |
ResumeJob / ResumeAll | 按保存的定义重建剩余触发并保存 Ready 意图。未登记的任务会重新校验并尝试登记。仍在执行的任务保持暂停,待执行结束后可恢复。全部恢复会继续处理其他任务,并汇报失败的任务和原因 |
TimeoutSeconds | 执行流程任务按此值限制引擎运行时间,0 表示无限等待,最大 4,294,967 秒。超时请求停止引擎,并等待原有后处理与归档。前处理、启动就绪和后处理使用各自的等待规则。其他 Job 自行解释该值 |
Quartz Interrupt | 执行流程任务会阻止尚未启动的图,或请求停止在运行的引擎。已经开始的前处理仍按原契约返回,已经启动的图仍等待后处理与归档;调用返回仅表示已请求取消 |
Shutdown | 调用无布尔参数的 Quartz Shutdown() 后释放其独立 factory,等价于不等待在途 Job 完成;同一已关闭 scheduler 不能通过 StartCommand 重启 |
| 关闭任务/历史窗口 | 解除窗口事件与 Copilot 上下文,不关闭进程级 scheduler,也不取消 Job |
例如相机任务通过 ScheduledDeviceJobHelper.WaitForTerminalStateAsync 等待消息 Success/Fail/Timeout,并观察 Quartz cancellation token;超时只是使等待结束并上报异常,清理的是事件订阅,没有向硬件发送停止命令。取消 token 同样不等于相机采集已停止。0 秒在该 helper 中表示无限等待,但不能将此解释为所有 Job 的实现约定;FlowJob、HeadlessFlowJob 各有自己的执行链。
排障时要分别确认调度已暂停、Job 已返回、外部设备已停止和历史写入结果,不能为“消除 Running”未经授权结束进程或控制硬件。
执行结果、历史查询与清理
JobWasExecuted 将 Quartz 返回的 JobExecutionException、结果对象的公开 bool Success=false 或该属性读取异常记为失败。null、普通字符串或没有该属性的对象默认按成功统计。结果文本格式化异常会记录原因并保留已判定的状态。Job 负责映射业务结果。
监听器通过管理器的变更门更新并保存显示/统计,再把历史写入排到串行 _historyWriteTail 并等待该次写入尝试结束,最后通知订阅者;订阅者异常被隔离。数据库初始化、插入和统计恢复的异常会记录日志但可能被捕获,历史没有记录不能证明任务没执行。SQLite 只在返回后插入终态记录,进程崩溃时的在途业务没有历史开始记录可供补账;JSON 的计划消耗记录仅用于避免重排本轮次数。
启动统计按 JobName/GroupName 从数据库全量聚合;有记录才覆盖对应计数、平均/最短/最长耗时和最后结果/消息,不会恢复完整执行现场,也不覆盖所有 JSON 显示字段(如最后耗时)。清理历史或写入失败会使这些统计与旧 JSON 快照、当前内存计数不同,不能承诺永久累计计数。
QueryExecutionHistory 的任务/结果筛选用于分页和统计同一组数据,在读事务内完成,按 StartTime、Id 倒序稳定排序,越界页收敛到末页;窗口每页100条,统计是全部匹配历史而非当前页。查询失败明确返回 QuerySucceeded=false,窗口清空旧结果并提示;不要将失败后的空列表当成零次执行。旧的 QueryRecords/QueryAllRecords/GetTaskStats 错误回退为未区分失败的空/零结果,调用方需看日志。
历史窗口清理按钮经确认删除所有任务90天前的记录,即使窗口当前只展示某个任务或失败筛选也不会限于该视图。CleanupOldRecords 失败返回0,与无可删记录相同;没有内建撤销,也没有后台自动清理调用。删除历史会影响以后重启恢复的统计,不改任务定义,当前列表累计值也不会立即同步重算。执行清理或导出前需获得对应数据操作授权。
任务窗口的 CSV、JSON 和报告导出基于当前 TaskInfos 快照。完整执行记录请在历史窗口查询,导出文件也不能用于原子恢复。手工 JSON 导出与 SchedulerTaskSerializer 使用不同的设置。
主窗口时钟位于右侧工具图标组的左端。关闭任务窗口后,状态文字仍从时钟左侧展开,时钟角标用播放、圆点和暂停符号区分执行中、等待下次触发和计划已暂停但本轮仍在执行。等待时显示已启用计划中最早的下次时间,跨日时带日期。没有在途任务或待触发计划时收起文字和角标。点击时钟或旁边的文字均打开原任务列表。
验证范围与缺口
首次宿主访问、异常退出、在途任务与管理操作交错、检查点写入失败、JSON/Quartz 补偿失败、shutdown 后任务静止、真实设备取消和时区/misfire 仍需隔离环境验证;涉及真实 Job 的验收必须另行取得设备和数据操作授权。
