Skip to content

TCP 监听、协议分发与消息记录 ​

ColorVision.SocketProtocol 为桌面宿主提供 TCP 监听、JSON/Text 指令分发和收发记录。通过 帮助 → 通信(Alt+H 后按 C)打开“Socket 连接管理器”。启用服务后,也可点击状态栏的 Socket 服务图标进入。MES、PLC 和客户设备的业务字段、权限及动作约束由各项目协议负责。

打开窗口后焦点位于消息搜索框,Tab / Shift+Tab 在窗口内循环。Ctrl+F 回到搜索,Esc 有筛选时先清除筛选,无筛选时关闭窗口;关闭仍只释放窗口订阅,不停止通信服务。

配置与启用服务 ​

配置影响本机监听和现有客户端连接,操作前应确认允许中断当前通信。默认地址 0.0.0.0 面向本机所有 IPv4 网卡;只需本机通信时使用明确的 loopback 地址。模块没有内置 TLS、鉴权、自动重连或心跳协议,设备动作仍需项目自己的权限与流程校验。

  1. 打开“Socket 连接管理器”。已有服务运行时,先关闭右上角启用开关,检查最后错误及端口释放情况。
  2. 点击“服务设置”,调整地址、端口、缓冲区和解析模式。统一设置中“通信协议”也绑定同一个 SocketConfig。
  3. 开启服务。窗口开关会保存配置;确认服务状态进入运行,并分别检查实际监听与客户端数量。出现错误时查看窗口中的错误详情。
配置项默认值与含义
IsServerEnabledfalse;赋值触发启停事件,启用不等于监听成功
IPAddress0.0.0.0;启动监听时由 IPAddress.Parse 解析
ServerPort6666;设置值限制到 0..65535
SocketBufferSize10240 字节;每次读取的缓冲区至少为 1024 字节
SocketPhraseTypeJson;另支持 Text

SocketInitializer 在应用启动时读取启用配置,随后只订阅 ServerEnabledChanged。地址、端口、缓冲区和模式由 SocketServerSettings.Capture 在每次服务启动时形成快照,该次服务的客户端沿用它。更改这些字段后需停止并重新启用服务;保存配置不会更新已运行的监听或连接。

窗口的监听地址和模式文字来自当前配置,可能与仍在运行的旧快照不同。SocketManager.IsConnect 只表示 ServerState == Running,状态栏“已连接”也采用这一判断;它不表示已有客户端或业务通信正常。

关闭窗口、停止服务与应用退出 ​

动作完成范围
关闭管理窗口解除该窗口的消息订阅与筛选视图;监听和客户端继续存在
关闭启用开关 / StopServer()请求关闭该次监听及客户端资源并投递状态;不等待在途业务 handler 完成,接口也没有取消令牌
应用退出 / ShutdownExisting禁止再次创建或启动管理器,在共用期限内等待已跟踪 worker;主程序给出 2 秒预算,超时或资源清理异常返回 false

StartServer / StopServer 是 void 请求入口;应检查最终 ServerState、错误和实际端口。停止失败仍显示错误,不能仅凭配置已禁用判断资源释放成功。应用退出的等待结果只覆盖已跟踪工作,业务副作用、回滚和异步结果日志落盘不属于该保证。实现位于 SocketServerLifecycle、SocketManagerApplicationLifetime 和 SocketWorkerTracker。

查看与设置防火墙 ​

顶部“防火墙 · 专用”和“防火墙 · 公用”分别显示规则匹配结果;将鼠标停在卡片上可查看规则名、远程地址范围和相反动作规则提示。

显示读取依据
已允许存在对应网络类型的允许规则,未匹配到阻止规则
可能被阻止匹配到阻止规则,即使同时存在允许规则也显示此状态
未放行未找到对应网络类型的应用入站允许规则
无法读取防火墙策略对象不可用或读取失败;不提供放行按钮

WindowsFirewallStatusReader 只枚举已启用的入站应用规则,按当前可执行文件完整路径匹配,再区分专用/公用网络。它没有检查实际活动网络类型、规则端口/协议、全局策略或真实连通性;因此“已允许”不证明端口可达,“未放行”也不证明系统一定阻止连接。状态在管理器创建及放行操作后读取;外部更改规则不会自动刷新此处。

需要修改系统规则时:

  1. 确认应允许的程序与网络类型,在对应卡片出现“放行”时点击。该操作会添加当前程序的入站允许规则,并解除同一程序在所选网络类型上的冲突阻止规则;其它程序、出站规则和其它网络类型的限制保留。操作会写入 Windows 防火墙,需具备相应管理授权。
  2. 请求通过本机 ColorVisionServiceHost 执行,客户端不会在此自动安装或修复服务。不可用、版本过旧或票据失败的排查见服务主机。
  3. 查看响应并重新尝试连接或取图。服务和客户端都会重新读取规则;仍有阻止规则或规则读取失败时不会报告放行完成。旧版服务只创建允许规则时,客户端也会提示核验失败。

后端 FirewallCommandService 通过 Windows 防火墙 COM 接口创建或复用允许规则,使用任意协议,不限定 Socket 端口,因此也适用于宿主进程的 GigE 相机收帧。规则名包含可执行文件完整路径摘要,避免同名程序不同安装目录互相覆盖;不会按显示名删除旧规则。匹配到的入站阻止规则若只属于所选网络类型,则禁用;若还属于其它网络类型,则仅从其范围中移除本次选择的类型。显式阻止优先于允许,所以仅添加允许规则无法解除冲突。

规则写入后会重新读取并检查允许规则与剩余阻止规则。明确设置“阻止所有入站连接”的所选网络会直接报告策略限制,不改变全局防火墙设置。操作失败没有自动回滚,会提示已处理数量和可能保留的变更;组织策略、其它端口规则和实际连通性仍需现场核对,应用规则核验成功不等于网络已连通。客户端等待 15 秒,超时后命令仍可能执行,处理方式见客户端超时与服务停止。

查询和查看消息 ​

打开窗口时,SocketMessageManager.LoadAll 按消息 ID 排序加载记录。“消息设置”中默认查询数量为 100、排序为 Desc;非正参数回退到配置值,最终加载数量限制在 1~1000 条。实时列表最多保留 1000 条,新增时按当前排序从旧记录一端移除超额行;只裁剪内存列表,数据库历史仍可查询。高级查询的加载范围由其查询条件决定,后续实时新增仍执行上述列表上限。

  1. 点击“查询”或按 F5,按消息设置重新加载列表。需要数据库条件查询时选择“高级查询”,条件与整表操作见通用查询。
  2. 用搜索框与“全部 / 接收 / 发送”筛选。搜索不区分大小写,只匹配当前已加载记录的客户端端点、EventName、MsgID、响应码和 ContentPreview,不会搜索数据库全文。预览按最多 96 个 UTF-16 code unit 的前缀生成;截断规则见 SQLite 正文存储。
  3. 选中一条记录,在详情区查看端点、事件、消息 ID、响应码和按 ID 加载的完整正文。默认“格式化查看”仅改变 JSON 显示,纯文本保持原文;“复制原文”和“格式化复制”按各自方式复制,不修改存储内容。
  4. 使用“重置筛选”或 Esc 清除关键词与方向,Ctrl+F 定位搜索框。默认启用“自动滚动”;多窗口共享消息集合,但筛选各自独立。

实时消息正文成功落库后即从列表对象释放,只保留短预览;查看详情、复制和重发按 ID 加载完整正文。已加载正文随对应行留在内存中,行被淘汰且没有其它引用后可回收。

操作影响范围
清空消息仅清空共享的内存列表;数据库记录仍在,“查询”或 F5 可重新加载
右键“删除” / 非文本框中按 Delete按所选 ID 删除数据库记录并移出列表,没有额外确认步骤;失败记入日志
打开数据库在资源管理器定位 SocketMessages.db,不会打开 SQL 编辑器
数据库维护打开宿主提供的维护窗口;未找到 ISocketDatabaseCleanupWindowLauncher 时提示不可用。具体动作见数据库维护
右键“重发”将原始正文写给客户端,可能触发业务动作;目标规则见下文

默认数据库是 %APPDATA%/ColorVision/Config/SocketMessages.db。列表预览与完整正文分开读取;旧 TEXT 迁移、备份、锁和空间回收统一见 SQLite 存储与维护,与 TCP 启停是独立操作。

JSON 指令与扩展处理器 ​

  1. 在 dispatcher 构造前已加载的程序集里实现 ISocketJsonHandler,提供可用的无参构造函数。
  2. 为 EventName 指定唯一、稳定且大小写准确的值。
  3. 在 Handle(NetworkStream stream, SocketRequest request) 中返回 SocketResponse,明确填写业务结果与关联字段。
  4. 用收发记录核对实际请求、响应和业务结果。
模型字段类型与责任
共同字段 Version、MsgID、EventName、SerialNumberstring;由调用方和 handler 约定、填写
请求 Paramsstring;包含 JSON 参数时需作为字符串编码,不能直接替换为 JSON 对象
响应 Code、Msg、Dataint、string、dynamic;业务成功/失败码与数据由 handler 定义

以下仅展示字段形状,Example.Echo 需由接入方实现,并非内置指令:

json
{
  "Version": "1.0",
  "MsgID": "example-1",
  "EventName": "Example.Echo",
  "SerialNumber": "demo",
  "Params": "{\"text\":\"hello\"}"
}

SocketJsonDispatcher 构造时从 AssemblyService 一次性发现处理器,没有随模块加载自动刷新。重复 EventName 保留先发现者,匹配区分大小写。返回 404 时先核对事件名称和程序集是否在扫描前加载。

dispatcher 不统一回填响应关联字段。内置空请求/空事件错误 400 与找不到 handler 的 404 只设置 Code/Msg;JSON 解析或业务处理等异常由 SocketManager 生成 Code=-1,尝试保留已解析请求的关联字段。三者不能视作相同的关联保证。

主程序执行流程并返回 POI:FlowRunPoi

Engine 内置 FlowRunPoiSocketHandler,通过同一 JSON 监听端口调用,不需要加载客户项目。实现位于 Engine/ColorVision.Engine/Services/Flow/,复用主工作区的模板选择、前处理、执行、后处理及最终化;运行会切换主工作区的流程,并可能采集设备、写入业务数据库或执行已配置的前后处理。调用前需启用 Socket 服务的 JSON 模式、加载流程模板、连接 MySQL,并满足所选流程的设备和服务依赖。

按流程名称请求:

json
{"Version":"1.0","MsgID":"poi-1","EventName":"FlowRunPoi","SerialNumber":"sample-1","Params":"{\"FlowName\":\"白画面\"}"}

也可将 Params 换成 "{\"FlowId\":42}"。FlowName 和 FlowId 必须只填一项:名称去除首尾空白后忽略大小写精确匹配;FlowId 是模板实际 ID,支持本地模板的负数 ID,不能为 0,也不是列表位置。同名模板必须用唯一 ID 定位,不会自动选择第一项。未知参数返回 400。

一次请求等待本次流程及后处理完成后返回一条最终响应,没有提前成功响应。主会话占用、模板切换失败或启动条件不满足时拒绝执行,不排队、不重试,也不替换正在运行的流程。继续使用主程序“停止”操作取消运行;本指令不额外设置整图超时,调用方需为完整流程和后处理预留等待时间,不能将网络等待超时当作流程已停止。

成功响应的 Data 包含 FlowId、FlowName、BatchId、ExecutionSerialNumber、Status、TotalTime(引擎返回的毫秒数)和 Poi 数组。每个点包含 AlgorithmResultId、AlgorithmName、PoiId、Name、PixelX/PixelY/Width/Height,以及 X/Y/Z/x/y/u/v/CCT/Wave。同一批次所有 POI_XYZ 算法的点位按结果主表和明细 ID 排序保留,算法与点位身份不会因为同名而合并。每条明细必须包含大小写精确的有限 X/Y/Z。点位 JSON 有重复字段或 X/Y/Z 缺失、无效时返回 500,整批 Poi 为空。有效点沿用 PoiResultCIExyuvData 的 CIE 数值归一化规则;不包含仅亮度 POI_Y、文件型 POI 或其它算法类型。

Version/MsgID/EventName/SerialNumber 保留请求关联值;外层 SerialNumber 用于请求关联,实际流程使用共享会话生成的批次编号,由 Data.ExecutionSerialNumber 返回。结果读取使用本次运行捕获的批次 ID,不查询“最新一次”或全局当前批次。MySQL 不可用时拒绝启动;读取失败和无点位分别报告,均不回退到历史 POI。

Code含义
200流程最终成功或带后处理警告成功,且读取到 POI;Status 区分两者
400参数格式错误、选择条件冲突或缺失
404找不到流程模板
409模板身份不唯一,或主会话拒绝启动
422流程已完成,但本批次无 POI_XYZ 点位
499 / 504流程已取消 / 流程报告超时
500流程或必需后处理失败、执行异常、POI 查询或解析失败
503主程序或 MySQL 结果批次不可用

已取得最终执行结果的失败响应保留 Data 中的批次身份和状态,Poi 为空;启动前拒绝时 Data 为空。 设备采集、MySQL 明细可见性和对端收包需现场联调。TCP 消息边界见下节。

独立 net48/x64 调用逻辑、WPF 窗口及兼容命令行示例位于 SDK/ColorVision.FlowPoi.Client.Net48/:客户端仅依赖 Newtonsoft.Json,提供 RunByNameAsync、RunByIdAsync,每次建立一条连接,按 EventName + MsgID 匹配完整 JSON 响应。600 秒默认超时和取消只终止客户端等待,不自动重发,也不保证主程序流程已停止。线上 X/x、Y/y 分别映射为三刺激值和 ChromaticityX/ChromaticityY。窗口支持按名称/ID 执行、取消等待、离线样例与 JSON/CSV 导出,FlowPoiResponse.Parse 复用联机校验解析离线响应。现场操作和独立编译前提见该目录 README.md,客户报文与字段手册为 API.md;Scripts/package_flow_poi_demo.ps1 只生成包含 Binaries/Source 的本地客户 ZIP,不上传。

Text 分发与 TCP 消息边界 ​

SocketTextDispatcher 构造时发现 ISocketTextDispatcher。当前实现只调用发现顺序中的第一个 handler:返回非空白字符串时立即返回,空白时也立即返回 null,不会尝试后续处理器。没有 handler 时返回字面字符串 No Dispatcher Hanle。这是多处理器路由的实现缺口,新增第二个处理器不能作为后备路由,扫描顺序也没有业务优先级约定。

HandleClientCore 将每次 NetworkStream.Read 的字节段直接按 UTF-8 解码,再按服务快照进入 JSON 或 Text 分发。当前没有跨读取的帧累积、长度协议或多消息拆分;大包、粘包、半包及跨读取分隔的 UTF-8 字符存在处理缺口。接入协议需要可靠消息边界时必须实现并验证分帧,不能假定一次 write 对应一次 read。

发送记录与重发结果 ​

正常 JSON/Text 及错误响应路径均先调用 MessageManager.AddMessage 将 Sent 记录入队,再写入网络;接收记录入队后即继续业务分发。有 Sent 不证明网络写入成功或对端已执行;ResponseCode 是生成的响应内容,不是对端 ACK。接收行按读取片段登记,也不能直接用于统计业务操作次数。

AddMessage 复制消息元数据和正文引用,分配进程内 RecordSequence 后进入单个后台写入队列;调用方不等待存储锁、SQLite 提交或 UI。后台按入队顺序在同一事务内写入元数据和压缩正文,成功提交后才以 Background 优先级投递列表更新。队列为内存队列,不是持久化日志;数据库持续不可写时待写消息会积压,进程强制结束可能丢失未提交记录。数据库及 UI 发布异常被捕获记入日志,单条失败不终止后续写入;方法返回不证明已落库。JSON 正常分支出错后进入异常分支,还可能再次登记同一接收内容。

清空消息立即清空内存列表,并抑制清空前已入队记录的后续列表更新;这些记录仍会落库。重新查询和高级查询/整表操作先等待此前入队的写入,再读取或修改数据库,并使对应的旧列表更新失效;期间协议消息仍可入队,查询之后的新记录仍会实时显示。这不是数据库保留策略。

管理器释放时停止接收新记录,等待已接收记录写完后释放数据库,不再追加列表。应用退出先停止 TCP 服务,再用原有 Socket 关闭期限的剩余时间等待消息队列;超时会明确记录日志并返回未完成,后台继续排空,但不能保证进程退出前全部提交。UI Dispatcher 退出本身不会阻止后台落库。已提交记录仍可在下次查询或启动时读取。

回包派发与界面刷新计时 ​

INFO 结构化日志以进程内 RecordSequence 关联协议派发、后台落库和 UI 更新;数据库 ID 仅在提交后可用。跨进程排查还应核对日志会话和时间,EventName / MsgID 只作补充,不能假设客户 MsgID 唯一:

事件字段与边界
SocketMessageTiming提交后给出 MessageId;PersistenceQueueMs 是入队至后台开始执行的间隔,StorageGateWaitMs 是存储锁排队,StorageWriteMs 是事务写入/正文压缩,进一步分成 BeginTransactionMs(包括取得连接及开始事务)、InsertMs(插入消息)、PayloadSaveMs(压缩正文并更新)和 CommitMs(提交事务)。这些子项已包含在 StorageWriteMs 中,PersistMs 包含后台前缀准备、存储锁排队和提交,不包含 PersistenceQueueMs。后面三个字段相互重叠;PersistenceAwaited=false / UiUpdateAwaited=false 表示协议调用方没有等待落库或界面追加
SocketReceiveDispatchTimingJSON 正常解析路径中,DecodeAndDeserializeMs 包含字节解码、原始消息日志及反序列化;RecordMessageMs 是消息快照及入队调用耗时,不含数据库写入;二者之和为 ReceiveToDispatchMs,不含 handler 内部执行/等待。DispatchRequestedAt 位于诊断日志写出之前,不是实际 handler 已开始的证明
SocketMessageUiTimingUiQueueMs 是后台 UI 投递到开始执行的间隔,UiUpdateMs 是列表追加/集合通知耗时;两者发生在独立 UI 路径,不能再次相加到同步回包派发或 PG 耗时

UI 仍可能因其它绘图或用户发起的数据库查询延迟业务 handler 的 Dispatcher 调用;异步记录移除了收发线程等待落库和列表追加的依赖,不承诺消除所有调度或磁盘抖动。

重新发送一条记录 ​

重发可能触发外部业务动作。操作前应核对正文、当前连接和重复执行影响;原端点不存在且有多个连接时,界面没有供用户指定接收方的步骤。

SocketManagerWindow.ResendMessageToClient 的顺序是:

  1. 加载所选记录的原始正文。Received 和 Sent 行都可重发,内容直接发给客户端,不会重新进入本地 handler。
  2. 查找原记录端点文字包含的可写客户端远端地址;找不到则使用客户端集合中第一个可写连接。没有可用连接时提示未连接。
  3. 将 UTF-8 正文写入所选连接,再追加一条 Sent。沿用原 EventName/MsgID,使用当前时间,不复制 ResponseCode,不修改原记录。
  4. 显示重发结果。成功提示只表示该网络写入调用返回,不等待对端确认,也不保证新增记录持久化。

新记录的端点优先取当前连接远端,可能回退到本地端点或原记录文字,不能独立证明实际接收方。重发没有生成新的业务请求 ID;重复执行的幂等性由具体协议负责。

排查常见问题 ​

现象检查顺序
无法连接端口启用状态 → 最后错误与实际监听 → 地址/端口 → 当前网络和系统规则;仅看防火墙卡片不足以判断
修改端口或模式后仍用旧值确认旧服务已停止,再启用以捕获新快照;配置文字与运行状态分别检查
能连接但没有响应检查模式、JSON 事件/程序集或 Text 首个 handler,再检查读取片段与分帧
搜索不到某条消息先重置筛选,再核对查询数量/排序;关键词只搜索元数据与预览,正文读取失败另查存储日志
清空后记录又出现“清空消息”只影响内存列表,查询会重新读取数据库;删除单条和整表操作另有入口
有 Sent 或重发成功,对端没有结果核对网络写入异常、当前目标和业务回执;检查是否因端点未匹配而选到其它客户端
升级后有列表、详情却为空检查 gzip 正文与旧 TEXT 迁移情况,按 SQLite 维护主题处理

实现与验证 ​

模块工程 UI/ColorVision.SocketProtocol/ColorVision.SocketProtocol.csproj 同时面向 net8.0-windows7.0 和 net10.0-windows7.0,依赖 ColorVision.UI、ColorVision.Database、log4net、Newtonsoft.Json。交付时应匹配宿主目标框架与依赖;项目可编译不替代真实监听、协议处理和业务响应验证。

真实防火墙 COM 写入和现场连通性应在获授权环境核对。

用隔离客户端和临时库核查 JSON 大小写/重复名、Text 分发、TCP 分帧、发送失败状态与重发回执。

基于 MIT License 发布。