Skip to content

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。调用会实际执行图内节点,须先确认对应设备与数据操作范围。

csharp
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 或客户结果,必须另外验证负责这些阶段的宿主,不能将裸图完成当作业务交付。

基于 MIT License 发布。