Flow 隔离无界面执行
FlowHeadlessExecutionService 执行脱离编辑器的 STN 快照,每次请求独占 FlowRuntimeHost。它不复用当前 ViewFlow / FlowControl,不自动创建 UI 批次,也不执行共享前后处理。需要业务最终化的调用方应选用共享执行会话,或明确编排自己的批次与业务阶段。
无界面不等于无副作用:节点仍可能控制硬件、写文件或调用远程服务。创建说明或检索文档不授权实际运行;调用前确认 STN、起始节点、SN、服务快照、超时和可影响的设备/数据范围。
选择执行入口
| 入口 | 读取什么 | 完成含义 |
|---|---|---|
RunHeadlessAsync(request) | 调用方提供的不可变 STN/服务请求 | 本次隔离节点图的终止结果 |
RunSavedFlowHeadlessAsync(flowKey, ...) | 在 TemplateFlow.Params 按 FlowKey 找到的 DataBase64,随后复制到请求 | 与裸执行相同,不自动增加前后处理 |
RunSelectedFlowAndWaitForFinalizationAsync() | 单例 FlowEngineManager.View 的主工作区,不是任意激活的独立窗口 | 共享会话的最终业务结果,详见执行会话 |
“读取已保存流程”入口当前读取模板集合中的内容,不是每次直接向 MySQL 重新查询;也不读取当前尚未保存的编辑器画布。需要最新持久化内容时,先确认模板集合已经加载/刷新。创建请求后的字节副本不受后续编辑影响。
裸 FlowHeadlessExecutionService 不访问 WPF Application/Dispatcher/Window。按 FlowKey 取模板的协调器在 WPF 应用存在时可能通过 Dispatcher 读取模板集合,这与“执行节点时不触碰编辑器”并不矛盾。
请求与隔离
FlowHeadlessExecutionRequest 接收非空 STN、起始节点、SN、可选 MQTT 服务列表以及 readiness / execution timeout。构造时复制 STN、服务 token 和设备信息,计算 ContentHash;读取请求属性或创建宿主输入时再次复制,后续编辑和调用方修改不得改变正在执行的请求。ContentHash 是 STN 字节的 SHA-256,小写十六进制;不包含起始节点、SN、服务/设备快照或超时配置。相同哈希不能证明两次调用具有相同的执行条件,也不是请求幂等键。
无界面请求默认向节点传递 PersistResults=false,已保存流程和独立 Quartz 任务也采用此默认值。调用方已为请求的实际执行 SN 准备独立 MySQL 批次时,可在裸请求上显式设置 PersistResults=true。MySQL 未连接时,此请求会在图启动前返回 StartRejected。该标记由节点执行,节点仍可能按各自配置写文件、调用设备或服务。
有限超时必须大于零且最多为 4,294,967,294 ms。仅 execution timeout 接受 Timeout.InfiniteTimeSpan。请求构造和直接运行 FlowRuntimeHost 都会在启动图前拒绝非法值。
RunAsync 每次创建并最终释放一个 FlowRuntimeHost,加载后由 FlowEngineRunner 等待运行结束;并发请求各自持有节点实例。图中有需要远程服务的节点且未提供 MQTT 服务快照时,返回 StartRejected。纯本地图(包括命令行脚本节点)可以在 MQTT 起始节点断线时运行。具体节点仍需满足自身的运行环境和设备依赖。
调用示例
示例中的 using 指令放在文件顶部,其余语句放在调用方的异步方法内。stnBytes 是已确认的原始 STN 字节,startNodeName 是该图中的起始节点名,serialNumber、mqttServices 和 cancellationToken 由调用方提供;请求不接收 .cvflow 压缩包作为 STN。调用会实际执行图内节点,须先确认对应设备与数据操作范围。
using System;
using ColorVision.Engine.FlowProcessing;
var request = new FlowHeadlessExecutionRequest(
stnSnapshot: stnBytes,
startNodeName: startNodeName,
serialNumber: serialNumber,
services: mqttServices,
readinessTimeout: TimeSpan.FromSeconds(2),
executionTimeout: TimeSpan.FromMinutes(2));
FlowHeadlessExecutionResult result =
await FlowExecutionCoordinator.Instance.RunHeadlessAsync(
request, cancellationToken);这里显式设置了 2 分钟执行等待;省略该项时执行不限时。调用后使用 result.Succeeded 判断本次节点图结果,并读取 Termination、Data.Status、Data.Message 排查失败;业务批次和前后处理需要对应执行入口负责。
就绪、执行与停止边界
未提供超时时间时,FlowRuntimeHost.RunAsync 使用 2 秒就绪等待,但 执行等待不限时;执行参数为 null 或 Timeout.InfiniteTimeSpan 都没有运行计时器。这不是整次调用的统一截止时间。
| 阶段 | 等待范围与结果 |
|---|---|
| 起始节点就绪 | FlowEngineControl.EnsureStartNodeReadyAsync 向要求连接就绪的节点传递带就绪时限的取消 token;不要求连接就绪的节点跳过此等待。收到迟到的就绪结果也按未就绪处理,运行器给出 Started=false、StartRejected、Data.Status=Failed |
| 节点图执行 | 起始节点同步派发成功返回后,execution timeout 才用于等待本次运行的完成通知;仍在运行时超时给出 Started=true、TimedOut、Data.Status=OverTime |
| 运行中取消 | 取消仍在运行的图时返回 Started=true、Canceled、Data.Status=Canceled;启动前已捕获的取消则为 Started=false |
执行超时不覆盖 STN 加载、前面的就绪等待、TryStartNode 内同步启动代码、随后观察器收尾或宿主释放。因此设置执行时限不保证整个 RunAsync 在同样的时间内返回,也不能约束已经发出的外部动作持续多久。
就绪时限依赖节点响应取消。自定义节点忽略取消时,宿主继续等它退出,并拒绝迟到的就绪结果。MQTT 起始节点等待已分离连接退役时可响应取消,旧连接随后自行完成订阅与连接清理。
超时或取消时,运行器只停止本次启动的图。若本次终态已经确定,即使通知延迟也保留状态、耗时和失败详情。同一起点和 SN 的旧通知无法完成新运行。停止活动图会移除运行记录并传递停止信号;设备停稳或外部写入回滚仍由相应设备及业务边界确认。
并发 StopAsync 等待同一次托管运行收尾,各调用方可设置自己的等待时限。并发或重复 DisposeAsync 共用一次清理,先取消当前运行,再等托管运行和取消回调退出后释放节点图。节点长期不响应取消时,释放会继续等待,直到其退出。运行错误由 RunAsync 返回,释放仍会清理节点图。
结果与失败语义
FlowHeadlessExecutionResult 返回 Started、Termination、ContentHash、Data 和 ElapsedMilliseconds。Succeeded 只有在已经启动、终止类型为 Completed 且引擎状态也为 Completed 时才为真。
Termination | 含义 |
|---|---|
Completed | 运行器完成;仍须检查 Data.Status,不能只读枚举名判成功 |
StartRejected | 门禁、服务快照或起始节点等条件未满足,包括就绪等待超时及起始节点已在执行另一次启动 |
Canceled | 取消请求导致终止 |
TimedOut | 启动后的执行完成等待超时,不是整次调用超时 |
LoadFailed | 加载 STN/运行图失败 |
Faulted | 已进入加载后的运行阶段发生异常 |
RunCoreAsync 的外层异常处理通过 CreateFailure() 统一设置 Started=false,并没有保留此前是否已启动的信息;例如运行或宿主释放抛出异常后可能得到 Faulted 与 Started=false。因此该字段为假不能单独证明没有执行过节点或发出过设备动作,重试仍需核对本次 SN、日志和外部状态。
ToFlowControlData() 保留起始节点、SN、状态、时间、消息和错误节点映射,不会凭空创建 RunFinalized 或客户报表。调用边界也有会直接抛出的错误,例如空请求、非法请求参数,以及已保存流程不存在/非合法 Base64;不要假定所有失败都以 Termination 返回。
FlowHeadlessExecutionObserver 只附着于本次隔离图,用于节点 Run/End 诊断,不作为全局编辑器事件注册。运行器返回后,服务最多再等待 1 秒,让已观察到 Run 的节点补齐 End;AsyncOperationDrain.WaitAsync 返回的“是否排空”布尔值没有进入运行结果。随后解除订阅,因此返回成功或取消结果都不保证所有节点结束诊断已经收齐,迟到事件也不保证被该观察器接收。
正常结果的 ElapsedMilliseconds 从进入 RunCoreAsync 开始计量,包含加载、就绪、执行和上述观察器等待;在解除订阅和 await using 释放宿主之前停止计时。调用本身仍会等待宿主释放后才返回,所以此字段不是调用方测得的完整墙钟耗时,也不能当成设备动作耗时。ToFlowControlData() 原样保留 Data.TotalTime,不会用 ElapsedMilliseconds 替换;两者并不总相等,例如运行器构造取消/超时结果时,Data.TotalTime 为零。
Quartz 独立调度
HeadlessFlowJob 使用 RunSavedFlowHeadlessAsync,带 DisallowConcurrentExecution,限制同一 JobDetail 并发;不同作业与裸请求仍须自行考虑硬件共享。它将结果转换为 FlowJobResult 写入 context.Result,作业内抛出的异常统一记录为 HeadlessStartupException;这是作业包装层的状态名,不证明异常一定发生在启动前。耗时优先取正值 Data.TotalTime,否则取 ElapsedMilliseconds,两者的计时范围并不相同。
| JobDataMap 字段 | 约束 |
|---|---|
FlowKey、StartNode | 必填且非空白;FlowKey 对应模板的稳定键,按区分大小写的精确比较查找,不是显示名称 |
SerialNumber | 可选;键缺失时由作业名与 UTC 时间生成。显式空白字符串不会触发生成,会被请求参数校验拒绝 |
ReadinessTimeoutMs、ExecutionTimeoutMs | 可选,设置时必须为正整数毫秒 |
未设置这两个字段时沿用就绪 2 秒、执行不限时的默认值;JobDataMap 不接受用负数表示无限等待。
这些字段由 HeadlessFlowJob 消费。普通执行流程任务在主工作区运行,包含批次和前后处理,并等待最终化。新任务按配置选择已保存模板,旧的未绑定任务沿用主工作区流程。
源码定位
| 契约 | 源码与符号 |
|---|---|
| 请求、结果、观察器和计时收尾 | Engine/ColorVision.Engine/FlowProcessing/Runtime/FlowHeadlessExecutionService.cs:FlowHeadlessExecutionRequest、FlowHeadlessExecutionResult、FlowHeadlessExecutionObserver、RunCoreAsync |
| 诊断等待是否排空 | Engine/ColorVision.Engine/FlowProcessing/Runtime/AsyncOperationDrain.cs:WaitAsync |
| 独占图、默认就绪时限和释放 | Engine/FlowEngineLib/Runtime/FlowRuntimeHost.cs:LoadAsync、RunAsync、DisposeAsync |
| 完成匹配、执行超时和取消结果 | Engine/FlowEngineLib/Runtime/FlowEngineRunner.cs:RunAsync |
| 就绪门禁与指定 SN 停止链 | Engine/FlowEngineLib/FlowEngineControl.cs:EnsureStartNodeReadyAsync、StopNode;Engine/FlowEngineLib/Start/BaseStartNode.cs:Stop、DoStartTransferData、RemoveStartAction |
验证入口与缺口
设备停稳、Quartz 配置和项目业务输出需在现场联调确认。
对应改动应核对两次并发执行不共享图、请求创建后修改原输入无效、取消/超时/加载失败/启动拒绝有明确结果。若还要求批次、后处理、MES 或客户结果,必须另外验证负责这些阶段的宿主,不能将裸图完成当作业务交付。
