Equipment Software on 纪伟的个人博客

设备通信与协议编程（十一）：OPC UA 信息模型、订阅与互操作边界

Wed, 05 Aug 2026 10:00:00 +0800

串口、Modbus 和厂商 TCP 协议主要解决“如何交换字段”，OPC UA 更进一步：设备把对象、变量、方法、事件和它们之间的关系组织为可浏览的信息模型，客户端通过标准服务访问。

OPC UA 不是一个简单的“统一寄存器协议”。真正的互操作来自一致的信息模型、profile、安全配置和语义约定。

1. AddressSpace 是带类型的图

服务器向客户端暴露的 AddressSpace 由 Node 构成，Node 通过 Reference 相连。常见 NodeClass 包括 Object、Variable、Method、ObjectType、VariableType、ReferenceType 和 DataType。

1
2
3
4
5


Machine (Object)
├── State (Variable)
├── Temperature (Variable)
├── Start (Method)
└── Alarm (Event source)

Variable 不只是值，还可带 DataType、ValueRank、AccessLevel、工程单位、量程和时间戳。客户端应读取并验证这些元数据，而不是只把所有值转成字符串。

2. NodeId、BrowseName 与 DisplayName

标识	用途	稳定性注意
NodeId	在服务器 AddressSpace 中标识 Node	namespace index 可能随配置变化
ExpandedNodeId	可携带 namespace URI 和 server index	更适合跨地址空间表达
BrowseName	浏览路径中的限定名	不保证全局唯一
DisplayName	面向用户的本地化文本	不应作为程序主键

客户端配置应优先保存 namespace URI 与标识符的组合，并在连接后解析当前 namespace index。把 ns=2;s=Machine.State 永久写死，服务器新增 namespace 后可能指向错误模型。

3. 类型模型带来的价值

ObjectType 和 VariableType 允许服务器声明设备类型及其实例结构。Companion Specification 则为机器人、分析仪器、机床等领域定义共同语义。

互操作的层次可分为：

能建立安全连接；
能调用 Read、Write、Browse 等服务；
能理解相同 DataType 与单位；
能识别相同设备类型、状态和方法语义。

只达到前两层，往往仍需要项目级点表和适配代码。

4. 从发现到会话

客户端通常经历：

1
2
3


发现服务器/端点 → 选择 Endpoint 与安全策略
→ 建立 SecureChannel → 创建并激活 Session
→ 浏览、读写、调用或创建订阅

Endpoint 描述安全模式、SecurityPolicy、传输 profile 和用户令牌类型。客户端不能仅按 URL 选第一个端点，也不能为了“先连上”自动信任未知证书。

SecureChannel 保护消息通道；Session 管理客户端与服务器的逻辑交互上下文。两者生命周期相关但不是同一个概念。

5. Read/Write 的质量与时间戳

读取 Variable 得到的 DataValue 可包含：

Value；
StatusCode；
SourceTimestamp；
ServerTimestamp。

显示数值前先判断 StatusCode。Good、Uncertain 和 Bad 表达数据质量；一个缓存的旧值即使类型正确，也不应被当成当前可信测量。

SourceTimestamp 表示数据源产生值的时间，ServerTimestamp 表示服务器处理该值的时间；具体提供哪些字段取决于服务器与请求参数。

6. MonitoredItem 与 Subscription

客户端创建 MonitoredItem 监视 Variable 的值变化或 Object 的事件，再把它们归入 Subscription。几个周期不能混为一谈：

参数	含义
SamplingInterval	服务器对 MonitoredItem 采样的请求间隔
PublishingInterval	Subscription 尝试发布 NotificationMessage 的周期
QueueSize	MonitoredItem 可缓存的通知数量
DiscardOldest	队列满时丢旧值还是拒绝新值
KeepAlive/Lifetime	无通知和通信中断时维持订阅的机制

服务器可根据能力修订请求值，客户端必须读取 revised 值。采样 10 ms、发布 100 ms 可能在一次 NotificationMessage 中携带多个变化；QueueSize 为 1 则只保留一个候选通知，不能还原全部中间过程。

7. 确认、重发与数据不丢失的边界

客户端通过 Publish 请求接收 NotificationMessage 并确认序列号；在服务器重传队列仍保留消息时，可用 Republish 请求缺失消息。普通订阅能跨越短暂通信中断，但可靠性受 Subscription lifetime、MonitoredItem 队列和重传队列限制。

OPC UA Part 4 还定义了可选的 durable Subscription 能力，用于更长中断甚至服务器重启场景。客户端必须先确认服务器 profile 和能力，不能假设所有服务器都支持持久订阅。

8. Deadband 与数据量

DataChangeFilter 可按状态、值或时间戳触发；Deadband 可减少微小变化通知。但设置前要确认：

数据类型是否支持相应 deadband；
百分比 deadband 依赖 EURange；
过滤发生在服务器侧，不等于改变设备采样；
报警、审计和控制反馈不能因错误过滤而丢失关键变化。

订阅不是“越快越好”。应按变量变化速度、业务延迟、服务器资源和网络预算分组。

9. 安全配置

生产客户端至少应做到：

选择满足组织要求且双方均支持的 MessageSecurityMode 与 SecurityPolicy；避免规范已标记为过时的 Basic128Rsa15 和 Basic256，并根据服务器 profile 与组织要求在 Basic256Sha256、Aes128_Sha256_RsaOaep、Aes256_Sha256_RsaPss 等未过时策略中选择，而不是硬编码一个通用“基线”；
验证服务器应用证书、主机名/应用 URI、有效期和信任链；
将首次信任作为受控部署步骤，而不是运行时自动接受；
使用最小权限的用户身份；
管理证书续期、吊销列表与私钥权限；
禁止将测试环境的匿名或 None 策略直接复制到生产。

OPC UA 的安全能力需要正确配置才能生效。网络隔离仍有价值，但不能替代端点身份验证和权限控制。

10. Client/Server 与 PubSub

本文讨论的是 Client/Server 模型：客户端主动建立 Session，调用服务并维护 Subscription。OPC UA PubSub 是另一套发布/订阅模型，可通过不同消息映射分发 DataSet，不使用同样的 Session/MonitoredItem 关系。

选择时考虑拓扑、发现、安全、可靠性和实时需求，而不是因为两者都叫“订阅”就混用配置概念。

11. C# 接入策略

OPC Foundation 维护 OPC UA .NET Standard 开源栈。生产接入时应固定经过验证的包版本，并在升级时回归：

Endpoint 选择与证书验证；
自定义 DataType 编解码；
Session 重连与 Subscription 转移/重建；
revised 采样和发布参数；
序列号缺口、Republish 与数据质量；
服务器限制和 profile 差异。

将 SDK 封装在适配层，向业务暴露类型化设备能力和带质量的状态快照，不要让 ViewModel 到处持有 NodeId 和 SDK Session。

12. 小结

OPC UA 的核心不是“能读一个点”，而是用标准 AddressSpace、类型和服务表达设备语义。客户端必须正确处理 Node 标识、DataValue 质量、订阅队列、安全端点和服务器能力；只有模型语义也达成一致，连接成功才会变成真正的互操作。

参考资料

设备通信与协议编程（十）：抓包、记录回放与协议契约测试

Tue, 04 Aug 2026 10:00:00 +0800

设备通信问题常常只在现场、特定固件或某个故障窗口出现。若日志只有“通信失败”，开发者只能反复猜测。可维护的通信模块应把原始证据、解析结果、请求关联和设备状态串成一条可回放链路。

1. 先明确要观察哪一层

层次	证据	常用工具
电气信号	电压、边沿、时序、干扰	示波器、逻辑分析仪
总线/链路	UART 字节、CAN 帧、EtherCAT datagram	串口/CAN/工业网络分析仪
网络	TCP 段、连接、重传、TLS 握手	Wireshark、`tcpdump`
应用协议	帧、命令、事务 ID、错误码	内置 dissector（Modbus/TCP、EtherCAT、CAN 等）、专有协议自研 dissector、结构化日志
业务	设备状态、流程步骤、Recipe	业务审计与状态快照

Wireshark 看不到 USB 串口芯片另一侧的真实 RS-485 电气波形；示波器也不知道某个功能码的业务含义。工具必须匹配问题层次。

2. 原始数据日志要可重建

对每个收发块至少记录：

1
2


Timestamp, Direction, DeviceId, ConnectionGeneration,
ChunkSequence, ByteCount, RawBytes, TransportMetadata

随后记录解析事件：

1
2


FrameSequence, Command, TransactionId, ParseResult,
ChecksumResult, PayloadSummary, CorrelationId

“块序号”与“帧序号”必须分开，因为一块可能含多帧，一帧也可能跨多块。时间戳注明来源和精度：墙上时间方便跨系统关联，单调时钟适合计算持续时间，硬件时间戳适合分析总线时序。

3. 十六进制日志的边界

原始字节很有价值，也可能包含 Recipe、序列号、账户或工艺数据。生产日志应：

默认限制每条记录的最大字节数；
对已知敏感字段脱敏，而不是事后搜索字符串；
保留原始总长度与截断标志；
使用二进制归档保存完整证据，并实施访问控制和保留周期；
不在实时回调中同步格式化大型 hex 字符串。

为了可读性，显示层可输出 AA 01 00 02；存储层更适合保存原始 byte 或 Base64，避免文本解析歧义。

4. 网络抓包如何不误判

TCP 抓包中，一个应用帧可能跨多个 TCP segment，也可能多个帧位于同一 segment。分析时应让 Wireshark 重组 TCP 流，再按应用协议长度解析，不能把 packet 边界当 message 边界。

常用流程：

1
2
3
4
5


# Windows 上先列出捕获接口；接口编号因机器而异。
tshark -D

# 只示意捕获过滤器，先替换接口编号、设备地址和端口。
tshark -i 3 -f "host 192.0.2.10 and tcp port 5000" -w device-session.pcapng

Windows 上实时捕获常规网络接口需要安装并加载 Npcap（Wireshark 安装器可一并安装）；否则 tshark -D 可能仍显示部分 extcap 等接口，但无法正常捕获本机常规网卡流量。

192.0.2.0/24 是文档示例网段。真实环境应先确认捕获权限、接口位置和数据合规要求。TLS 会隐藏应用载荷；不要为了抓包在生产环境关闭证书验证或加密。

5. 记录格式要版本化

可回放记录不应只是程序日志。建议文件头包含：

1
2
3
4
5
6
7


FormatVersion
ProtocolName / ProtocolVersion
CaptureStartUtc
ClockFrequency / TimestampOrigin
DeviceIdentity / FirmwareVersion
TransportConfiguration
PayloadEncoding

每条记录使用相对单调时间、方向、连接世代和原始数据。格式版本不兼容时明确拒绝，避免新回放器悄悄误解旧数据。

6. 回放的三种时间模式

模式	行为	用途
Step	测试代码逐条推进	确定性单元测试
Accelerated	保留顺序、压缩间隔	快速回归长会话
Real-time	尽量复现原间隔	超时、拥塞与竞态分析

回放器默认不应连接真实设备或执行真实输出。把传输接口替换为内存端点，并通过显式开关才能进入硬件测试环境。

7. 模拟器不是返回固定成功

有效模拟器应复现协议和状态机，而不是每条命令都返回 OK。至少支持：

正常请求/响应与主动事件；
分片、粘包、乱序事件和迟到响应；
CRC 错误、非法长度、未知命令；
设备 Busy、Faulted、NotReady；
执行后断线、重启和会话世代变化；
可控的虚拟时间。

模拟器越靠近传输层，越能测试真实解析器；越靠近业务能力层，越适合流程测试。两者用途不同，可以同时保留。设备行为模拟器与实机/HIL 测试梯度见《设备软件架构与控制模型（七）：实机、模拟器与 HIL》。

8. 契约测试

同一组协议向量应同时验证编码器、解码器和设备模拟器：

1
2
3
4


请求对象 → 编码 → 期望字节
原始字节 → 解码 → 期望对象
编码结果 → 解码 → 等价对象
错误字节 → 明确的拒绝原因

向量来源按可信度排序：标准规范示例、设备厂商确认样例、经人工标注的实机抓包、人工构造边界样例。不要把一次未知是否正确的现场抓包直接封为“黄金数据”。

9. 模糊测试与不变量

解析器适合做基于属性的测试。对任意 byte 输入，应满足：

不越界、不死循环、不无限分配；
每次返回要么需要更多数据，要么消费至少一个字节；
帧长永不超过契约上限；
错误输入不会产生未经验证的业务命令；
取消和关闭后没有后台任务泄漏。

模糊测试发现崩溃后，把最小化输入加入永久回归语料。

10. 现场问题闭环

一次完整问题包应包含：软件版本、设备身份与固件、配置快照、单调时间线、原始通信记录、解析日志、状态转换和复现步骤。修复后用同一记录回放，并增加一个能在旧版本失败、在新版本通过的自动化测试。

这比“多打一些日志再去现场”更重要：证据必须能驱动可重复验证。

11. 小结

协议诊断的关键是保持层次和可重建性：原始块、完整帧、请求关联和业务状态分别记录，再用版本化回放格式、真实状态模拟器和契约测试形成闭环。这样现场偶发故障才会变成可重复的软件输入。

参考资料

设备通信与协议编程（九）：EtherCAT 周期通信、分布式时钟与软件边界

Mon, 03 Aug 2026 10:00:00 +0800

EtherCAT 使用标准以太网物理层，却不是“把设备接到交换机后用 TCP 发命令”。它面向确定性的周期过程数据：MainDevice 构造帧，SubDevice 在帧经过时直接读取或写入对应数据区域，并由专用控制器完成高速处理。

本文讨论上位机开发者需要理解的模型，不替代主站协议栈、设备 ESI 和 ETG 规范。

1. 为什么普通以太网直觉会失效

EtherCAT 帧使用 EtherType 0x88A4，通常不经过 TCP/IP。一个帧可携带多个 EtherCAT datagram；SubDevice 在帧流经时“on the fly”处理相关数据，末端再利用全双工链路返回 MainDevice。

因此常规企业交换网络、Socket API 和 IP 地址不是其周期数据路径。拓扑、网卡、驱动与主站栈必须按 EtherCAT 系统设计。

2. 过程映像与周期交换

主站启动时根据配置把各 SubDevice 的过程数据映射到逻辑过程映像。实时任务通常按固定周期执行：

1
2


读取上一周期输入 → 执行控制算法 → 写入输出过程映像
→ 发送/接收 EtherCAT 帧 → 检查 Working Counter 与状态

PDO 表示周期过程数据映射；参数和诊断常通过 mailbox 协议访问，例如 CAN application protocol over EtherCAT（CoE，复用上一篇 CANopen 的对象字典与 SDO/PDO 机制）中的 SDO。周期 PDO 与非周期邮箱流量应分别预算。

3. EtherCAT State Machine

典型状态包括：

1

INIT → PRE-OP → SAFE-OP → OP

INIT：基础初始化，尚无邮箱或过程数据通信；
PRE-OP：可进行邮箱通信和参数配置；
SAFE-OP：输入过程数据可用，输出保持安全行为；
OP：输入和输出过程数据均进入运行状态。

具体转换条件、错误确认和安全输出由设备实现及 profile 决定。总线进入 OP 也不等于设备业务状态已 Ready。

4. Working Counter 不是业务成功码

每个 datagram 带 Working Counter（WKC），SubDevice 成功执行相关内存操作时按规则更新。主站将实际 WKC 与配置期望值比较，可发现节点缺失或操作未被处理。

WKC 正确只能证明本周期总线访问符合预期，不能证明伺服已到位、气缸已动作或工艺已经完成。这些仍要通过状态字、反馈量和设备状态机判断。

5. Distributed Clocks

Distributed Clocks（DC）让支持 DC 的 SubDevice 本地时钟对齐到共同系统时间，并补偿传播延迟。动作可由本地 SYNC 信号触发，而不是依赖帧恰好到达的时刻，从而降低通信抖动对同步动作的影响。

ETG 资料给出可达到显著低于 1 µs 的同步抖动，但这是协议与合格实现的能力描述，不是任意 PC、拓扑和配置下自动获得的端到端控制精度。实际系统还受控制任务抖动、采样、驱动器和机械响应影响。

6. MainDevice 可以用普通网卡，不等于普通应用就实时

ETG 说明 MainDevice 可使用标准 Ethernet MAC；但周期是否确定还取决于：

主站协议栈和网卡驱动路径；
实时操作系统或实时扩展；
CPU 隔离、调度优先级和中断配置；
内存分配、GC、日志和其他任务干扰；
周期、SubDevice 数量与过程数据规模。

在 Windows/WPF 线程里用普通定时器每 1 ms 调一次 SDK，不等于建立了 1 ms 硬实时控制。

7. 推荐的软件分层

1
2
3
4
5
6
7


UI / Recipe / 流程编排
 ↓ 非实时命令、状态快照
实时控制进程或主站运行时
 ↓ 固定过程映像、无阻塞周期任务
EtherCAT 主站栈与网卡驱动
 ↓
SubDevices

实时侧避免动态分配、阻塞 I/O、同步日志和不可控回调。上位机通过共享内存、IPC 或厂商 API 获取降采样状态，并携带周期号、DC 时间和质量状态；UI 卡顿不能阻塞总线周期。

8. ESI、ENI 与配置治理

ESI（EtherCAT SubDevice Information）是厂商提供的 XML 设备描述，包含身份、对象、过程数据映射和同步能力。配置工具基于网络扫描和 ESI 生成主站配置；部分生态将最终网络配置表示为 ENI。

生产系统应版本化保存：

ESI 文件及校验值；
设备型号、产品码、修订号与序列号规则；
PDO 映射、周期和 DC 参数；
主站栈、驱动和网卡版本；
配置变更的验证记录。

现场设备修订变化时，不能只看节点顺序相同就直接运行。

9. 诊断指标

至少观察：

MainDevice 与各 SubDevice 状态；
期望/实际 WKC；
丢周期、周期超时与任务执行时间分布；
DC 偏差和同步状态；
各端口链路错误计数；
mailbox 超时和设备错误码；
拓扑变化与设备身份不匹配。

日志应放在非实时路径，通过预分配环形缓冲传递摘要；不要在周期回调里格式化大段字符串。Wireshark 自带 EtherCAT 协议解析器，可直接查看帧中的 Working Counter 与命令明细。

10. 小结

EtherCAT 的价值在于高效的 on-the-fly 过程数据交换和分布式同步，但实时性是整条系统链路的属性。上位机应把硬实时周期与 UI、日志、流程编排隔离，并用 WKC、DC 和状态反馈分别判断总线健康、同步质量与业务结果。

参考资料

设备通信与协议编程（八）：CAN 与 CANopen 的报文、对象字典和实时性边界

Sun, 02 Aug 2026 10:00:00 +0800

CAN 与 CANopen 经常被连在一起说，但它们不是同一层：CAN 定义总线访问、帧和错误处理等机制；CANopen 在其上定义对象字典、通信对象、网络管理和设备配置。只会收发 CAN ID，不等于已经实现 CANopen 节点。

1. CAN 帧表达的是什么

经典 CAN 数据帧的有效载荷最多 8 byte，位速率上限为 1 Mbit/s；CAN FD 将单帧有效载荷扩展到最多 64 byte，并允许帧内切换到更快的位速率。设备、控制器、收发器和分析工具必须共同支持相应模式。

CAN 标识符用于仲裁并由系统赋予消息语义，它不是内建的节点地址。标准帧使用 11 bit 标识符，扩展帧使用 29 bit 标识符。

2. 非破坏性仲裁

多个节点同时发送时，标识符逐 bit 仲裁；显性位会覆盖隐性位，失去仲裁的节点停止发送而不破坏获胜帧。对同一帧格式而言，数值更小的标识符通常具有更高总线优先级。

这提供优先级调度，却不自动保证每条消息的截止时间。实时性还取决于：

总线负载与最高优先级报文频率；
位填充、错误帧和重传；
驱动与应用调度延迟；
网关转发和接收队列；
标识符分配是否造成低优先级饥饿。

3. CAN 的可靠性不等于端到端成功

CAN 控制器提供 CRC、位监测、确认、错误计数和故障隔离等机制。它们提高链路可靠性，但应用仍需处理：

消息过期或重复；
接收队列溢出；
节点复位后的状态恢复；
“帧已被总线确认”但业务未执行；
网关另一侧的失败。

关键命令仍要定义序列、状态确认或幂等策略。

4. CANopen 的对象字典

对象字典（Object Dictionary，OD）是 CANopen 设备的核心数据模型。对象使用 16 bit index 和 8 bit sub-index 寻址，包含通信参数、设备参数和过程数据。与 Modbus 寄存器映射的对照见本系列第 7 篇。

1
2
3
4
5


Index 0x1000 Device type
Index 0x1018 Identity object
Index 0x1000-0x1FFF Communication profile area
Index 0x2000-0x5FFF Manufacturer-specific area
Index 0x6000-0x9FFF Standardized device-profile area

精确对象及访问权限应以设备 EDS/XDD 和适用的 CiA profile 为准，不能把示例索引当作所有设备都支持的寄存器表。

5. SDO 与 PDO

通信对象	主要用途	特点
SDO	读取/写入对象字典、配置设备	请求/响应，可传较长数据，开销较大
PDO	交换实时过程数据	映射预先配置的 OD 项，帧短、无逐条应用确认

PDO 可由事件、定时器或 SYNC 触发。它适合周期数据，不适合拿来临时读取任意对象。SDO 适合配置，但不应挤占高优先级实时流量。

6. NMT、Heartbeat 与 EMCY

CANopen Network Management（NMT）管理节点状态，例如 Initialization、Pre-operational、Operational 和 Stopped。节点进入 Operational 不代表机械系统已经安全 Ready；设备 profile 和应用状态机仍在更高层。

Heartbeat 用于观察节点是否持续存活，超时阈值应大于生产周期并考虑总线拥塞。Emergency（EMCY）用于报告紧急错误状态，但它不是可靠事件队列；上位机收到后应读取设备诊断对象并与状态机对账。

7. 上位机的软件边界

通用 PC 应用通常通过 USB-CAN、PCIe-CAN 或以太网网关接入。适配层至少应暴露：

1
2
3


Frame(timestamp, channel, id, flags, data)
BusState(error counters, bus-off, overflow)
SendAsync(frame)

不要只暴露 byte[]。时间戳来源、是否为硬件时间戳、接收溢出、错误帧和 bus-off 状态都关系到诊断结论。

CANopen 层再把 PDO/SDO/NMT 转成类型化能力，业务层不应直接拼 COB-ID 和字节偏移。

8. Bus-off 与恢复

错误计数达到协议条件后，节点可能进入 bus-off 并停止参与总线。自动恢复策略要符合控制器、设备和系统安全要求：

记录错误计数、总线状态与最近报文；
停止依赖该节点的流程并进入安全状态；
修复或等待物理故障消失；
按设备规则复位通信和应用状态；
重新确认节点身份、PDO 映射与运行状态。

反复自动复位可能掩盖终端、电磁干扰或波特率配置问题。

9. 验证与诊断

用总线分析仪确认 nominal/data bitrate、帧格式与实际负载；
验证高优先级流量下低优先级消息的最坏延迟；
注入错误、断开终端、制造队列溢出并观察恢复；
对照 EDS/XDD 验证对象类型、访问权限和 PDO 映射；
区分适配器接收时间、驱动时间和硬件总线时间。

10. 小结

CAN 提供带优先级仲裁和错误隔离的共享总线，CANopen 提供可互操作的设备对象与通信模型。工程设计不能停留在“这个 CAN ID 是什么”，而要同时管理对象字典、网络状态、实时流量预算和故障恢复。

参考资料

设备通信与协议编程（七）：Modbus RTU/TCP、功能码与寄存器映射

Sat, 01 Aug 2026 10:00:00 +0800

Modbus 看起来只是“读写寄存器”，真正的工程问题却集中在地址表示、数据类型、字节顺序、轮询一致性和异常响应上。若这些契约没有写清，两个都声称兼容 Modbus 的程序仍可能完全无法互通。

本文以 Modbus Application Protocol V1.1b3 和 Serial Line Protocol V1.02 为边界。

1. 先区分 PDU、ADU 和传输

Modbus 的核心协议数据单元（PDU）由功能码和数据组成：

1

PDU = Function Code + Data

不同传输再包一层 ADU：

1
2


RTU ADU = Server Address + PDU + CRC
TCP ADU = MBAP Header + PDU

Modbus TCP 的 MBAP 头包含 Transaction Identifier、Protocol Identifier、Length 和 Unit Identifier。TCP 传输不附加 RTU CRC；TCP 校验和也不提供应用层身份认证。TCP 传输默认使用 502 端口；Modbus 报文实现指南将其规定为强制默认监听端口。

2. 四类数据模型

数据块	单元	常用功能码
Coils	1 bit，可读写	01 (0x01)、05 (0x05)、15 (0x0F)
Discrete Inputs	1 bit，只读	02 (0x02)
Input Registers	16 bit，只读	04 (0x04)
Holding Registers	16 bit，可读写	03 (0x03)、06 (0x06)、16 (0x10)、22 (0x16)、23 (0x17)

只读/可写是协议数据模型语义，具体设备仍可能对某些地址施加额外限制。

3. 地址为什么总差 1

协议 PDU 中的起始地址是从 0 开始的 16 位地址。设备手册常用 40001、400001 或“寄存器 1”等人类表示法标记 holding register；这些前缀和基数不直接在线路上传输。

例如手册中的 40001 经常对应 PDU 地址 0，但这不是所有厂商文档的强制格式。接入前必须记录：

1

手册标号 | 数据块 | PDU 地址 | 读写功能码 | 数据类型 | 单位 | 缩放 | 字节/字顺序

不要在代码中到处写 address - 1；在设备映射层一次性转换。

4. 16 位寄存器不等于业务类型

规范定义寄存器是 16 bit，并规定多字节量在 PDU 中高位字节先传。设备把 float32、int32、ASCII 或位域放入多个寄存器时，寄存器之间的字顺序通常是厂商约定，不能仅凭 Modbus 标准推断。

同一个浮点数可能采用：

1
2
3
4


AB CD // 高字在前
CD AB // 低字在前
BA DC // 每字节交换
DC BA // 字与字节都交换

应使用手册给出的已知值或设备模拟器验证，代码中以明确枚举表达顺序。

5. 构造读 Holding Registers 请求

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


using System.Buffers.Binary;

public static byte[] BuildReadHoldingRegisters(
 byte serverAddress,
 ushort startAddress,
 ushort quantity)
{
 if (quantity is < 1 or > 125)
 throw new ArgumentOutOfRangeException(nameof(quantity));

 // 读请求必须发给单播服务器地址；0 是广播地址，不产生响应。
 if (serverAddress is < 1 or > 247)
 throw new ArgumentOutOfRangeException(nameof(serverAddress));

 if (startAddress + quantity > 0x1_0000)
 throw new ArgumentOutOfRangeException(nameof(startAddress));

 var frame = new byte[8];
 frame[0] = serverAddress;
 frame[1] = 0x03;
 BinaryPrimitives.WriteUInt16BigEndian(frame.AsSpan(2), startAddress);
 BinaryPrimitives.WriteUInt16BigEndian(frame.AsSpan(4), quantity);

 ushort crc = ModbusCrc16.Compute(frame.AsSpan(0, 6));
 frame[6] = (byte)crc; // RTU CRC 低字节先发送
 frame[7] = (byte)(crc >> 8);
 return frame;
}

ModbusCrc16 沿用本系列第 4 篇《校验和与 CRC 的能力边界》中的实现。串行链路中的地址 0 用于广播，1—247 是单播服务器地址；读请求需要响应，因此示例拒绝地址 0。读取数量上限来自功能码 03 的规范；其他功能码有各自限制，不应复用一个全局“最大寄存器数”。

6. 正常响应与异常响应

功能码 03 的正常响应包含字节数和寄存器数据。客户端必须同时验证：

Server/Unit 地址与事务 ID 是否匹配当前请求；
功能码是否为期望值；
字节数是否等于寄存器数量乘 2；
RTU CRC 或 TCP MBAP 长度是否正确；
整帧没有多余或缺失数据。

异常响应把原功能码最高位置 1，例如 0x03 变为 0x83，随后携带异常码。常见异常码：01 非法功能、02 非法数据地址、03 非法数据值、04 服务器设备故障（V1.1b3 第 7 节）。异常码表示服务器明确拒绝或无法处理请求，不应与本地超时、CRC 错误混为一类。

7. RTU 的时间边界

Modbus RTU 使用字符间隔和帧间静默识别边界。串行线路指南对不高于 19200 bit/s 的链路以字符时间描述 t1.5 和 t3.5；更高速率建议使用固定的 750 µs 与 1.750 ms。RS-485 电气层与半双工约束见本系列第 1 篇。

普通桌面操作系统和托管定时器不适合用“每字节启动一个高精度定时器”硬凑边界。更稳健的方案是：

由串口接收循环累积字节；
使用协议允许的完整长度和 CRC 尽快验证；
把时间间隔作为帧结束/失效条件；
若需要严格实时主站，由实时控制器或成熟协议栈承担。

8. 轮询与一致性

Modbus 没有通用订阅机制，主站通常轮询。优化时应：

合并连续地址，但不要跨越设备声明的非法区；
按变化速度设置不同轮询周期；
限制单设备在途请求数，RTU 通常一次一个；
给每个值附带采集时间与质量状态；
多寄存器业务值一次读完，避免跨轮询拼接撕裂数据。

读取多个寄存器不必然意味着设备内部快照一致；需要一致性保证时必须查设备手册。超时与重试设计见本系列第 6 篇。

9. 写入与安全

写单寄存器、写多寄存器和读写多寄存器的原子性边界由设备实现与功能码契约决定。关键动作应在业务层检查设备状态、权限、范围和互锁，不能因为 Modbus 返回成功就绕过安全逻辑。

传统 Modbus 不提供认证和加密。Modbus Organization 另有基于 TLS 与 X.509 的 Modbus Security Protocol；生产网络应结合设备支持、网络分区和访问控制选择方案。

10. 小结

Modbus 的难点不在功能码本身，而在地址映射和业务类型契约。明确 PDU 地址、数据块、功能码、缩放、单位、字顺序和错误分类，再谈轮询优化，才能避免“读到了数但解释错了”的隐蔽故障。

参考资料

Modbus Organization：Specifications and Implementation Guides

设备通信与协议编程（六）：超时、重连与幂等性设计

Fri, 31 Jul 2026 10:00:00 +0800

设备通信最危险的失败不是明确返回错误，而是：命令已发出，连接随后中断，上位机不知道设备是否执行。简单地“超时就重试”可能让运动轴重复移动、阀门重复动作或配方重复下发。

本篇建立一套与串口、TCP 都适用的故障模型。

1. 把一次调用拆成阶段

1

排队 → 编码 → 发送 → 设备接收 → 设备执行 → 响应发送 → 客户端接收

客户端观察到超时，只能证明最后期限内没有得到期望响应，不能反推出失败发生在哪一步。尤其在“执行完成、响应丢失”时，无条件重试会重复副作用。

2. 三类结果

结果	含义	典型处理
已成功	收到可验证的成功响应	提交上层状态
已失败	收到明确拒绝，且设备保证未执行	修正参数或进入故障处理
未知	超时、断线、响应无法关联	查询状态、对账或人工确认

把“未知”强行映射成失败，是许多重复动作事故的根源。API 可以显式返回 Outcome.Unknown，迫使上层选择恢复策略。

3. 幂等键与命令语义

幂等不是“重试次数小”。同一个逻辑操作重复提交后，设备端应识别它并返回原结果，而不是再次执行。

常见设计：

1
2


去重键 = StableClientId + CommandId
校验属性 = Operation + Parameters

StableClientId 来自持久配置或已认证的客户端身份，不能使用每次重连都会变化的传输 Session ID。客户端生成的 CommandId 在该身份范围内保持唯一，设备在约定窗口内保存去重键、操作参数与结果：重复请求的操作和参数完全相同则重放原结果；同一去重键携带不同内容必须拒绝。若要求跨设备重启重试，设备端去重记录也必须按协议要求持久化；仅在内存中保存无法覆盖重启窗口。

并非所有命令天然幂等：

SetPosition(100) 可能是幂等的，但仍受坐标系和会话状态影响；
MoveRelative(+10) 通常不是幂等的；
Start() 在已运行时是否成功，必须由契约定义；
“写配置”若伴随闪存计数或触发重启，也不能只看最终值。

4. 没有设备端幂等支持怎么办

可按风险从低到高选择：

重连后查询设备状态，确认目标是否已达到；
使用设备提供的任务号、事件号或最后命令记录对账；
将非幂等动作改造成“设置绝对目标 + 查询完成状态”；
无法证明安全时停止自动恢复，要求人工确认。

客户端本地去重无法覆盖“设备执行后客户端崩溃”的窗口，不能替代设备端协议支持。

5. 重试策略

只有同时满足以下条件时才自动重试：

错误被判定为瞬时；
操作天然幂等或具有端到端幂等键；
剩余截止时间足够；
重试不会违反设备状态机和安全约束。

退避可使用带抖动的指数策略，并设置最大间隔、最大次数和总体截止时间。所有客户端若固定每秒同时重连，会在设备恢复瞬间形成惊群。

协议错误、认证失败、参数非法和安全互锁通常不是“多试几次”能解决的。

6. 重连是新会话

连接恢复后，不要直接把状态标为 Ready。稳健流程通常是：

1
2


断线 → 取消旧请求 → 退避 → 建连 → 握手 → 身份核对
 → 能力/版本核对 → 查询设备状态 → 必要的重新同步 → Ready

每次连接分配 ConnectionGeneration。接收、超时和回调都携带世代号，旧连接迟到的完成事件不能改变新连接状态。

串口重开前还可能需要等待线路静默或丢弃残留输入；TCP 重连则得到新的字节流，旧连接的事务 ID 不能无条件沿用。

7. 超时预算而不是孤立超时

一次业务操作可能经过队列、发送、设备执行和响应。用单调时间计算每一步剩余预算：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


public sealed class Deadline
{
 private readonly TimeProvider _timeProvider;
 private readonly long _startedAt;
 private readonly TimeSpan _budget;

 public Deadline(TimeProvider timeProvider, TimeSpan budget)
 {
 _timeProvider = timeProvider;
 _startedAt = timeProvider.GetTimestamp();
 _budget = budget;
 }

 public TimeSpan Remaining
 {
 get
 {
 TimeSpan value = _budget - _timeProvider.GetElapsedTime(_startedAt);
 return value > TimeSpan.Zero ? value : TimeSpan.Zero;
 }
 }
}

TimeProvider.GetTimestamp() 提供单调时间戳，避免墙上时钟校准造成跳变；测试中还可以注入可控的时间提供器。

8. 熔断与限流放在哪里

设备通常是低并发、强状态资源。比通用 HTTP 客户端更重要的是：

有界命令队列，满时明确拒绝或合并；
同一设备的并发度符合协议能力；
连续失败后进入 Faulted，避免无限轰炸设备；
恢复探测只允许少量安全命令；
急停和安全回路不依赖普通应用重试链路。

熔断器不能代替设备状态机，也不能把未知结果变成失败。设备级故障闭环见《设备软件架构与控制模型（六）：故障处理、报警与安全恢复》。

9. 可观测性

一次操作至少关联这些字段：

1
2


DeviceId, ConnectionGeneration, CommandId, Operation,
Attempt, QueueDuration, RoundTripDuration, Outcome, ErrorCategory

指标应区分连接失败、协议坏帧、设备拒绝、业务超时和未知结果。只统计一个“通信失败率”，无法指导恢复。

10. 测试故障窗口

模拟器应能在每个阶段注入故障：收到命令前断开、执行前断开、执行后响应前断开、发送半帧、重复响应、迟到响应、重启后去重表丢失。然后验证：

非幂等动作不会自动重复；
旧世代响应不能完成新请求；
队列和等待表最终清空；
未知结果被显式上报；
停止信号能中断退避和重连。

11. 小结

超时只是观察，不是结论；重连是新会话，不是恢复旧 socket；重试只有在端到端幂等成立时才安全。把“未知结果”建模出来，并通过查询、对账和连接世代恢复，设备软件才能在最棘手的故障窗口中保持可控。

参考资料

设备通信与协议编程（五）：TCP 设备协议与请求响应模型

Thu, 30 Jul 2026 10:00:00 +0800

把设备从串口换成 TCP，并不会自动获得消息边界、请求关联、心跳或重连语义。TCP 提供可靠、有序的双向字节流；设备应用协议仍要定义一条消息如何编码，以及连接中断后业务处于什么状态。

1. TCP 保证什么，不保证什么

RFC 9293 定义的 TCP 关键性质包括可靠、有序、字节流传输。它不保证：

一次 Send 对应对端一次 Receive；
应用命令执行且持久化；
连接空闲时设备一定仍在线；
自动区分请求、响应和设备事件；
断线重连后延续旧会话状态。

“没有丢字节”与“业务操作成功”是两个层次。

2. 在字节流上建立帧

TCP 接收端必须复用本系列《设备通信与协议编程（三）：二进制协议帧、消息边界与版本兼容》建立的增量解析模型。长度前缀是常见选择：先读固定头、验证长度上限，再累积载荷。不要用 NetworkStream.DataAvailable 判断消息结束；它只表示此刻是否有可立即读取的数据。

同样不要假设 ReadAsync 会填满缓冲区。需要固定长度时应循环读取：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


public static async ValueTask ReadExactlyAsync(
 Stream stream,
 Memory<byte> buffer,
 CancellationToken cancellationToken)
{
 int offset = 0;
 while (offset < buffer.Length)
 {
 int count = await stream.ReadAsync(buffer[offset..], cancellationToken);
 if (count == 0)
 throw new EndOfStreamException("Peer closed the connection.");

 offset += count;
 }
}

.NET 的 Stream.ReadExactlyAsync 已提供类似能力；手写版本用于说明循环读取的不变量。

3. 连接生命周期

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


using System.Net.Sockets;

public static async Task RunSessionAsync(
 string host,
 int port,
 CancellationToken cancellationToken)
{
 using var client = new TcpClient();
 await client.ConnectAsync(host, port, cancellationToken);
 await using NetworkStream stream = client.GetStream();

 // 在这里完成协议握手，再启动唯一的接收循环。
 await ReceiveFramesAsync(stream, cancellationToken);
}

static async Task ReceiveFramesAsync(
 Stream stream,
 CancellationToken cancellationToken)
{
 var buffer = new byte[4096];
 while (true)
 {
 int count = await stream.ReadAsync(buffer, cancellationToken);
 if (count == 0)
 return;

 // 把 buffer[0..count] 交给增量帧解码器。
 }
}

TcpClient.Connected 只反映最近一次 I/O 已知的状态，不能作为当前在线证明。真正发现失效通常依赖读写结果、协议心跳或业务超时。

4. 请求/响应协调器

若协议支持并发请求，每条请求应携带事务 ID（例如第 3 篇帧结构中的 Sequence 字段）。客户端维护：

1

transactionId → TaskCompletionSource<Response>

接收循环解析完整响应后完成对应任务；设备事件则进入独立事件通道。实现时要保证：

注册等待项发生在发送前，避免响应过快造成竞态；
超时、取消、断线都会从表中移除等待项；
事务 ID 有界且可回绕，不与在途请求重复；
未知或重复响应会记录并丢弃，不完成错误请求；
断线时一次性失败当前连接世代的全部等待项。

不支持事务 ID 的协议通常只能串行执行请求。

5. 发送也需要单一所有者

多个任务同时向同一 NetworkStream 写入时，即使每次写都成功，两个应用帧仍可能在调用层交错。用发送队列或锁保证“一帧编码完成后整体写入”。大帧要考虑背压，不要让无限队列吞掉内存。

高频小消息是否启用 Nagle 算法要通过协议时延和吞吐测试决定。NoDelay = true 不是设备通信的通用必选项。Nagle 与 TCP_NODELAY 的机制与参数详见《TCP/IP（九）：TCP 进阶——SACK、Nagle、keepalive 与端口复用》。

6. 超时分层

至少区分：

超时	含义
连接超时	TCP 建连在预算内未完成
写入超时	数据未能在预算内交给传输栈
首字节/完整帧超时	对端未及时开始或完成响应
业务超时	设备操作本身未在预期时间完成
空闲心跳超时	长期无业务时检测会话可用性

一个总的 Timeout = 3000 无法告诉运维究竟慢在哪里。超时预算还应由上层截止时间向下传递，避免每层各等三秒。

7. TCP keepalive 与应用心跳

TCP keepalive 是实现可选的连接探测机制，RFC 9293 要求默认关闭且默认探测间隔不得短于两小时。操作系统允许调整时，它仍主要判断传输连接，不了解设备业务线程是否卡死。keepalive 机制与参数调优同样见《TCP/IP（九）》。

应用心跳可以携带协议版本、设备状态和会话世代，但会增加负载。若正常业务本就持续往返，可直接以业务响应作为活性证据，避免重复心跳。

8. 安全边界

原始 TCP 不提供机密性和对端身份。跨越不可信网络时应使用 TLS、VPN 或协议规定的安全层，并验证证书和设备身份。不要自创“异或加密”。

即使在隔离网络，解析器仍应限制帧长、并发请求数、发送队列和日志载荷，防止故障设备拖垮上位机。

9. 小结

TCP 解决可靠有序字节流，设备协议负责消息、事务和业务结果。稳定客户端需要唯一接收循环、明确帧边界、可关联的请求响应、有界发送队列和分层超时。下一篇将在此基础上处理断线、迟到响应和“操作到底执行了没有”的灰色状态。

参考资料

设备通信与协议编程（四）：校验和与 CRC 的能力边界

Wed, 29 Jul 2026 10:00:00 +0800

设备协议里常见“校验和不对”“CRC 失败”，但 CRC 不是某个唯一算法，校验通过也不等于消息可信。真正落地时，必须同时确定算法参数、覆盖范围、字节顺序和错误后的恢复行为。

1. 校验到底解决什么

校验字段用于发现传输、存储或组帧过程中的偶发错误。常见方法包括：

方法	特点	适用边界
XOR	极易实现，检测能力有限	简单遗留协议
加法和	可检测部分错误，容易碰撞	资源受限或既有协议
Fletcher / Adler	计算便宜，能力取决于参数与报文长度	软件数据完整性场景
CRC	对特定错误模式有可分析的检测能力	串口、总线、文件和网络帧
密码学 MAC	同时验证完整性与共享密钥持有者	需要抵抗主动攻击的场景

CRC 的检测能力取决于位宽、多项式和受保护消息的最大长度。设计良好的 n 位 CRC 可保证检出长度不超过 n bit 的突发错误；能否保证检出全部单比特、双比特或奇数个 bit 错误，还要检查具体多项式及码字长度。2⁻ⁿ 只能近似描述特定随机错误模型下的残余概率，不能当作所有链路和错误模式的固定漏检率。测试时应先声明目标消息长度和预期检测的错误类别，再选择多项式并注入验证。

CRC 不含秘密。攻击者修改数据后可以重新计算 CRC，因此它不是认证机制。

2. “CRC-16”信息不够

一个 CRC 实例至少由以下参数确定：

width（位宽，多项式隐含但单独列出更清晰）；
多项式（poly）；
初始值（init）；
输入、输出是否反射（refin/refout）；
输出异或值（xorout）；
校验值在线路上的字节顺序；
CRC 覆盖哪些字段。

两个协议都写“CRC-16”，结果仍可能完全不同。实现前应从设备协议或标准获得完整参数，并用规范测试向量核对，而不是挑一个搜索结果相似的函数。

3. Modbus RTU 的 CRC 示例

Modbus 串行线路规范定义 RTU 帧使用 CRC-16；CRC 字段在消息中先发送低字节，再发送高字节。下面函数返回数值形式的 CRC，序列化时再明确字节顺序：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


public static class ModbusCrc16
{
 public static ushort Compute(ReadOnlySpan<byte> data)
 {
 ushort crc = 0xFFFF;

 foreach (byte value in data)
 {
 crc ^= value;
 for (int bit = 0; bit < 8; bit++)
 {
 bool lsb = (crc & 1) != 0;
 crc >>= 1;
 if (lsb)
 crc ^= 0xA001;
 }
 }

 return crc;
 }

 public static void WriteLittleEndian(Span<byte> destination, ushort crc)
 {
 if (destination.Length < 2)
 throw new ArgumentException("CRC needs two bytes.", nameof(destination));

 destination[0] = (byte)crc;
 destination[1] = (byte)(crc >> 8);
 }
}

可用标准检查字符串验证核心实现：ASCII 123456789 的该 CRC 结果应为 0x4B37。这只证明参数化核心吻合；仍要用真实协议帧验证覆盖范围和线路字节序。

4. 覆盖范围要写成可执行规则

“对整帧做 CRC”仍然含糊。应明确类似规则：

1
2
3


CRC = Compute(Address || Function || Data)
CRC 字段自身不参与计算
发送顺序 = CRC low byte, CRC high byte

若协议含转义，还要说明 CRC 计算的是转义前原始字节还是线路上的转义后字节。若含长度字段，要说明长度是否参与计算。编码器和解码器应共享同一条规则，避免各自拼切片。

5. 校验失败后怎么办

校验失败意味着当前候选帧不可交付，但不一定说明端口已断开。恢复策略取决于定界方式：

固定长度帧：丢弃当前候选帧，再寻找下一同步点；
Magic + 长度：从后续可能的 Magic 重新扫描，同时限制扫描量；
静默间隔：丢弃该时间窗口内的消息；
TCP 长度帧：若头部已失去可信度，通常应关闭会话，避免无限错位解析。

不要把坏帧原样交给业务层“看看能不能用”，也不要在每个 CRC 错误后立刻重连。应记录计数、端口、方向、帧长度和有限的十六进制摘要，避免把整段敏感数据写入日志。

6. 表驱动与硬件实现

查表法能减少逐 bit 计算，硬件 CRC 外设则可进一步降低 CPU 占用。但它们必须与协议参数完全一致。不同 CPU 指令或硬件外设支持的多项式、反射和初值集合并不相同。

先以清晰的参考实现和测试向量建立正确性，再替换为表驱动或硬件加速版本；优化后对同一语料做逐帧差分测试。

7. 测试清单

空消息、单字节、全零、全 0xFF；
标准检查字符串和规范示例帧；
分别翻转每一个 bit，确认检测结果符合预期；
CRC 字节交换、覆盖范围少一个字节等常见错误；
编码后再解析的往返测试；
与设备抓包、厂商工具或另一独立实现交叉验证。

8. 小结

校验算法的名字不是完整契约。只有参数、覆盖范围和字节序全部一致，双方才会得到相同结果；CRC 的职责是检测偶发错误，而不是认证或加密。把参考向量固化为自动化测试，是避免设备现场反复猜算法的最低成本手段。

参考资料

设备通信与协议编程（三）：二进制协议帧、消息边界与版本兼容

Tue, 28 Jul 2026 10:00:00 +0800

串口和 TCP 都提供字节流或字节块，却不会替应用识别“这一条命令到哪里结束”。二进制协议设计的第一要务，是让接收端在拆包、粘包（一次读取返回半帧或多帧，见上一篇）、噪声和版本升级下仍能确定消息边界；TCP 传输下的完整请求/响应模型见本系列第 5 篇。

1. 一帧需要承担什么

一个常见帧结构如下：

1

Magic | Version | Flags | Command | Sequence | PayloadLength | Payload | Check

字段	作用
Magic	快速识别协议并在噪声后重新同步
Version	明确解析规则，不靠猜测
Flags	表示应答、错误、压缩等可选语义
Command	说明载荷类型
Sequence	关联请求与响应、识别迟到消息
PayloadLength	给出边界，并在分配前做上限检查
Check	检测传输或组帧错误，不等同于安全认证

字段不是越多越好。每个字段都应对应一个真实的演进、诊断或恢复需求。

2. 三种常见定界方式

2.1 固定长度

实现最简单且时间可预测，但浪费带宽、扩展困难。适合数据结构长期稳定且长度很小的周期报文。

2.2 长度前缀

头部携带载荷长度，适合二进制协议和 TCP。解析前必须满足：

1

0 <= PayloadLength <= MaxPayloadLength

最大长度必须来自协议契约，而不是当前机器可用内存。

2.3 分隔符与转义

文本协议常用换行，二进制链路可用特殊字节加 byte stuffing。若载荷也可能出现分隔符，就要转义；解析器必须定义转义字节本身、连续转义和截断转义如何处理。

“静默时间作为边界”只适用于明确规定该语义的协议，例如 Modbus RTU。普通异步程序不能依赖一次 Read 的停顿猜帧结束。

3. 端序必须逐字段定义

多字节整数在协议中应明确为 little-endian 或 big-endian。不要把 C# 结构体直接复制到线路上：运行时布局、填充、CPU 端序和版本演进都会让它失去可移植性。

1
2
3
4
5
6
7


using System.Buffers.Binary;

Span<byte> header = stackalloc byte[8];
header[0] = 0xA5;
header[1] = 1;
BinaryPrimitives.WriteUInt16BigEndian(header[2..], command);
BinaryPrimitives.WriteUInt32BigEndian(header[4..], payloadLength);

对应读取也使用 BinaryPrimitives.Read*Endian，让线路端序在代码里可见。

4. 增量解析器的状态

解析器面对的是任意切片，至少需要这几个状态：

1

寻找 Magic → 等待固定头 → 校验长度 → 等待完整载荷 → 校验并产出帧

关键不变量：

数据不足时返回“需要更多”，而不是把半帧判为错误；
数据非法时至少丢弃一个字节并继续寻找同步点；
产出一帧后继续解析缓冲区，处理粘连的下一帧；
累积缓冲区和单帧长度都有硬上限；
解析失败不会读取到缓冲区之外。

下面展示固定 8 字节头的最小解析函数。它只解析当前连续缓冲区，调用方负责保留未消费尾部：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


using System.Buffers.Binary;

public readonly record struct DeviceFrame(
 byte Version,
 ushort Command,
 ReadOnlyMemory<byte> Payload);

public enum ParseResult { NeedMoreData, Frame, InvalidData }

public static class FrameParser
{
 private const byte Magic = 0xA5;
 private const int HeaderSize = 8;
 private const int MaxPayloadLength = 1024 * 1024;

 public static ParseResult TryParse(
 ReadOnlyMemory<byte> input,
 out DeviceFrame frame,
 out int consumed)
 {
 frame = default;
 consumed = 0;
 var span = input.Span;

 if (span.Length == 0)
 return ParseResult.NeedMoreData;

 if (span[0] != Magic)
 {
 consumed = 1;
 return ParseResult.InvalidData;
 }

 if (span.Length < HeaderSize)
 return ParseResult.NeedMoreData;

 byte version = span[1];
 ushort command = BinaryPrimitives.ReadUInt16BigEndian(span[2..4]);
 uint length = BinaryPrimitives.ReadUInt32BigEndian(span[4..8]);

 if (version != 1 || length > MaxPayloadLength)
 {
 consumed = 1;
 return ParseResult.InvalidData;
 }

 int frameLength = checked(HeaderSize + (int)length);
 if (span.Length < frameLength)
 return ParseResult.NeedMoreData;

 // ToArray 让产出的帧不依赖调用方随后复用的接收缓冲区。
 frame = new DeviceFrame(version, command,
 input.Slice(HeaderSize, (int)length).ToArray());
 consumed = frameLength;
 return ParseResult.Frame;
 }
}

生产实现还要把校验字段纳入帧长，并决定错误后是丢一个字节、跳到下一个 Magic，还是重置整个会话。Magic 可能出现在载荷中，因此“直接跳到下一个 Magic”只是恢复启发式，不是正确性证明。

5. 请求、响应和异步事件

设备协议通常同时存在三类消息：

请求：主机发起操作；
响应：携带相同序列号或明确的关联字段；
事件：设备主动上报，不应被误配给当前请求。

只有一个在途请求时，也建议保留序列号。超时响应、重连前残留数据和日志关联都会用到它。序列号回绕时，要结合连接世代和有限的在途窗口判断，不能假设整数永不重复。命令合法性与排队执行的模型见《设备软件架构与控制模型（四）：状态机、命令队列与流程编排》。

6. 版本兼容策略

版本字段不是万能开关。更稳健的演进规则是：

固定头尽量稳定，新字段放在有长度的扩展区；
未识别的可选字段可以跳过，未识别的关键语义必须拒绝；
枚举预留未知值处理，不把未来值映射成当前默认值；
请求和响应都显式协商能力，不仅比较一个版本数字；
旧固件无法安全理解的命令，不要靠“尽量解析”冒险执行。

7. 安全与资源边界

二进制解析器直接处理不可信输入。即使设备位于内网，也应防御：

长度字段导致的超大分配；
整数加法溢出；
无限等待未完成帧；
垃圾输入导致 O(n²) 扫描；
压缩载荷解压炸弹；
日志直接输出敏感载荷。

CRC 只能检测偶发错误，不能证明发送者身份，也不能阻止恶意篡改。需要安全边界时使用经过评审的认证与加密方案。

8. 测试矩阵

最少覆盖：空输入、逐字节输入、头部截断、载荷截断、两帧粘连、Magic 错误、未知版本、长度为零、最大合法长度、超过上限、校验错误、随机噪声后恢复和序列号回绕。

属性测试或模糊测试尤其适合解析器：对任意输入，函数都不应越界、挂死或无界分配；成功产出的帧再编码后应满足约定的不变量。与模拟器/回放环境的整体测试梯度见《设备软件架构与控制模型（七）：实机、模拟器与 HIL》。

9. 小结

可靠协议帧的核心是明确边界和失败语义。长度、端序、版本、序列号与资源上限必须写进契约；解析器要按任意分片增量工作，而不是依赖底层读取次数。下一篇将继续讨论校验和与 CRC 的能力边界。

参考资料

设备通信与协议编程（二）：C# 串口生命周期、缓冲区与异步接收

Mon, 27 Jul 2026 10:00:00 +0800

C# 的 SerialPort API 很容易打开端口，却不容易写出可停止、可重连、不会丢边界的长期运行通信模块。本篇以 .NET 10 和 System.IO.Ports 包为基线，重点讨论端口所有权、单一接收循环、发送串行化与取消操作。

1. 串口对象不是协议客户端

建议把通信栈拆成四层：

1

业务命令 → 请求/响应协调器 → 编解码器 → 串口传输

SerialPort 只负责传输字节。不要让 UI 直接调用 ReadLine，也不要在 DataReceived 里解析业务、更新控件和重试命令。否则端口生命周期、线程上下文与协议状态会纠缠在一起。把厂商差异挡在业务之外的做法见《设备软件架构与控制模型（二）：硬件抽象层与设备适配器》。

项目需显式引用包：

1

dotnet add package System.IO.Ports

包版本应与项目目标框架和组织依赖策略匹配，不要从文章复制一个未来会过期的固定版本号。

2. 配置必须来自设备契约

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


using System.IO.Ports;

var port = new SerialPort("COM3")
{
 BaudRate = 115200,
 DataBits = 8,
 Parity = Parity.None,
 StopBits = StopBits.One,
 Handshake = Handshake.None,
 ReadTimeout = 1000,
 WriteTimeout = 1000
};

这些值不是通用默认答案。尤其不要在没有接线依据时随意启用 RtsEnable、DtrEnable 或硬件流控。

端口名也不应永久写死。Windows 上同一 USB 设备换插口后可能获得不同 COM 号，生产软件可同时记录 VID/PID、序列号和用户确认结果。

3. 选择一种接收所有权模型

官方文档明确说明：DataReceived 不保证每收到一个字节都触发，事件可能延迟，并在辅助线程上执行。因此事件只能表示“现在可能有数据可读”，不能表示“一帧到达”。

对新代码，更容易推理的模型是：打开端口后由一个后台任务持续读取 BaseStream，所有收到的字节都交给同一个解码器。不要同时使用 SerialPort.Read*、DataReceived 和 BaseStream.ReadAsync 争抢同一输入流。

4. 一个可控的传输骨架

下面示例只负责字节传输，不假装解决协议边界：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92


using System.IO.Ports;

public sealed class SerialTransport : IAsyncDisposable
{
 private readonly SerialPort _port;
 private readonly SemaphoreSlim _writeLock = new(1, 1);
 private CancellationTokenSource? _lifetime;
 private Task? _receiveTask;

 public SerialTransport(string portName, int baudRate)
 {
 _port = new SerialPort(portName, baudRate, Parity.None, 8, StopBits.One)
 {
 Handshake = Handshake.None
 };
 }

 public void Open(Func<ReadOnlyMemory<byte>, ValueTask> onBytes)
 {
 if (_lifetime is not null)
 throw new InvalidOperationException("Transport is already open.");

 _port.Open();
 _lifetime = new CancellationTokenSource();
 _receiveTask = ReceiveLoopAsync(onBytes, _lifetime.Token);
 }

 private async Task ReceiveLoopAsync(
 Func<ReadOnlyMemory<byte>, ValueTask> onBytes,
 CancellationToken cancellationToken)
 {
 var buffer = new byte[4096];

 while (!cancellationToken.IsCancellationRequested)
 {
 int count;
 try
 {
 count = await _port.BaseStream.ReadAsync(buffer, cancellationToken);
 }
 catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
 {
 break;
 }

 if (count == 0)
 throw new EndOfStreamException("Serial stream ended.");

 // onBytes 必须在返回前消费或复制数据，不能保存这段可复用缓冲区。
 await onBytes(buffer.AsMemory(0, count));
 }
 }

 public async ValueTask WriteAsync(
 ReadOnlyMemory<byte> bytes,
 CancellationToken cancellationToken)
 {
 await _writeLock.WaitAsync(cancellationToken);
 try
 {
 await _port.BaseStream.WriteAsync(bytes, cancellationToken);
 await _port.BaseStream.FlushAsync(cancellationToken);
 }
 finally
 {
 _writeLock.Release();
 }
 }

 public async ValueTask DisposeAsync()
 {
 var lifetime = Interlocked.Exchange(ref _lifetime, null);
 if (lifetime is null)
 return;

 await lifetime.CancelAsync();
 _port.Close(); // 同时解除部分平台上无法及时响应取消的阻塞 I/O。
 // 注意：§2 的 ReadTimeout 只约束同步 Read*（超时抛 TimeoutException）；
 // Windows 实现上 BaseStream.ReadAsync 不按 ReadTimeout 超时，
 // 接收循环的退出依赖取消令牌与这里的 Close()。

 if (_receiveTask is not null)
 {
 try { await _receiveTask; }
 catch (Exception) when (lifetime.IsCancellationRequested) { }
 }

 lifetime.Dispose();
 _writeLock.Dispose();
 _port.Dispose();
 }
}

这个骨架仍需由调用方定义：异常如何上报、断线后是否重建对象、关闭超时多久，以及回调过慢时采用有界队列还是背压。关闭时若仍有写入在途，直接释放 _writeLock 会让其 Release 抛出 ObjectDisposedException——生产实现应先等待写入静默、设置关闭宽限，或让锁的生命周期跟随最后一个写入者。

5. 缓冲区和消息边界

一次 ReadAsync 可能返回半帧、一帧或多帧。正确的数据流是：

1

任意字节块 → 累积缓冲区 → 帧解码器 → 完整消息

解码器必须保留未完成尾部，并限制最大帧长。否则错误长度字段可能让程序无限等待或持续扩容。若回调把 ReadOnlyMemory<byte> 放入队列，必须先复制，因为读取循环下一次会覆盖底层数组。

6. 请求/响应不能靠多个线程同时读

串口协议常规定“发一条命令，等一条应答”。不要让每个请求各自读取端口；应该只有一个接收循环，再由协调器按序列号、命令字或当前在途请求分发响应。

没有事务 ID 的半双工协议通常只能保留一个在途请求。超时后迟到的旧响应可能被误认作下一请求的响应，因此恢复策略往往需要清空输入、等待静默窗口或重新建立会话，而不只是立即重发。

7. 关闭、拔插与重连

把以下状态区分开：

主动停止：取消任务，不应记为通信故障；
端口被拔出：读取或写入可能抛出 IOException、UnauthorizedAccessException 等；
端口被占用：Open 失败，应提示占用而不是无限重试；
协议超时：物理端口仍可能正常，不能直接等同于“串口断开”。

重连应创建新的传输会话并重新执行设备握手。指数退避要设置上限和抖动，同时允许用户立即停止；不要在异常回调里递归调用 Open。

8. 如何验证

没有实机时，可用成对虚拟串口或 USB 转串口回环测试：

分别测试 1 字节、半帧、多帧合并和超长垃圾输入；
在读取期间拔出设备，确认任务能退出且资源释放；
并发调用 WriteAsync，确认帧不会交错；
让消费回调故意变慢，观察内存是否无界增长；
重连后验证旧请求不会收到新会话的响应。

9. 小结

稳定串口模块的核心不是 Open()，而是明确所有权：一个端口对象、一个接收循环、一个解码器、串行化写入，以及可取消的生命周期。下一篇将在这条字节流之上实现真正的二进制帧边界。

参考资料

设备通信与协议编程（一）：RS-232、RS-485、UART 与 USB 虚拟串口

Sun, 26 Jul 2026 10:00:00 +0800

设备接上电脑、系统里出现一个 COM 口，并不意味着它“使用 RS-232 协议”。工程现场常把 UART、RS-232、RS-485 和 USB 虚拟串口混为一谈，结果是线缆、电平、拓扑和软件协议同时排错，越查越乱。

本文先建立分层模型。读完后，你应该能回答：设备两端的电气接口是什么、字节怎样传输、谁定义一帧消息，以及上位机究竟在操作哪一层。

1. 先把四个名字放回各自层次

名称	主要解决的问题	典型位置
UART	字节如何串行化，波特率、数据位、校验位、停止位如何组织	MCU 外设或串口控制器
RS-232	单端电气信号、连接器与点对点连接	仪器、调试口、旧式 PC 串口
RS-485	差分电气信号与多节点总线能力	工业现场总线、远距离设备链路
USB CDC ACM / 厂商驱动	USB 设备如何向主机呈现串口式接口	USB 转串口芯片、设备 USB 口

UART 不是线缆标准，RS-485 也不是完整应用协议。它们约定字符传输或电气信号层面的机制；命令字、长度、CRC、地址和应答规则仍由 Modbus RTU 或厂商协议定义——上层协议的具体形态见本系列《设备通信与协议编程（七）：Modbus RTU/TCP》，隔离厂商差异的分层做法见《设备软件架构与控制模型（二）：硬件抽象层与设备适配器》。

2. UART 帧不是应用协议帧

常见的 115200 8N1 表示：

名义波特率为 115200；
每个字符含 8 个数据位；
无校验位（None）；
1 个停止位。

若再计入 1 个起始位，一个 8N1 字符通常在线路上占 10 bit。因此 115200 bit/s 的理论上限约为 11520 byte/s，尚未扣除应用协议头、校验、应答间隔和系统调度延迟。波特率不等于有效载荷吞吐率。

“UART 帧”描述一个字符的起止与校验；“应用协议帧”可能由几十个 UART 字符组成。上位机解析消息边界时，不能把一次驱动回调或一次 Read 当成一帧。

3. RS-232：点对点、单端、全双工

RS-232 通常以发送、接收和信号地构成点对点链路。它使用相对于信号地的单端电压，不能把 MCU 的 3.3 V TTL UART 引脚直接接到 RS-232 接口；中间需要匹配的电平转换器。

常见误区有三个：

DB9 只是常见连接器，针脚定义仍要查设备手册；不能只看插头形状。
“能收到乱码”往往说明路径已部分连通，应继续核对波特率、数据位、校验和地线。
RTS/CTS、DTR/DSR 等握手线是否使用取决于双方设计；软件打开硬件流控前要确认实际接线。

4. RS-485：差分总线不是自动多机协议

RS-485 通过两根线之间的差分电压传输信号，抗共模干扰能力更适合工业环境。常见的两线制链路是半双工：同一时刻只有一个方向驱动总线；四线制可实现全双工，但设备和布线都必须支持。

多节点能力只说明多个收发器可以挂在总线上，不会自动解决以下问题：

节点地址如何分配；
谁可以发言，如何避免冲突；
应答超时与重试规则；
帧边界、端序和校验算法。

这些都属于更高层协议。工程上还要按收发器、线缆长度和速率设计终端匹配、偏置与接地，不能机械地在每个节点都并联终端电阻。

5. USB 虚拟串口：软件像串口，链路不是 UART

USB CDC ACM 或 USB 转串口驱动可以在操作系统中暴露 COMx、/dev/ttyACM* 或 /dev/ttyUSB*。应用仍能使用串口 API，但底层数据经 USB 事务和驱动缓冲传输。

因此：

“波特率”可能被设备真实采用，也可能只是驱动传给设备的配置提示；
拔插会使设备节点消失并重新枚举，端口名不一定稳定；
USB 包边界、串口 Read 返回边界和应用消息边界互不等价；
VID/PID 只能识别产品类型，多个同型号设备还需序列号或物理端口路径区分。

6. 排错时沿层次向上走

推荐按下面顺序定位：

物理与电气层：接口类型、电平、A/B 极性、地线、终端和供电是否正确。
系统与驱动层：设备是否枚举、驱动是否加载、端口是否被其他进程占用。
字符层：波特率、数据位、校验位、停止位、流控是否一致。
协议层：地址、命令、长度、端序、转义、校验和超时是否匹配。
业务层：设备当前状态是否允许该命令，参数是否越界。

先用逻辑分析仪、示波器或串口分析工具确认线上确实有字节，再讨论 JSON、CRC 或业务状态，能显著缩短排错路径。

7. 选型边界

场景	更自然的选择
板内 MCU 与外设	UART、SPI 或 I²C，取决于距离、速率和布线
单台仪器、短距离维护口	RS-232 或 USB 虚拟串口
多节点、较长距离、强干扰环境	RS-485 加明确的上层协议
高带宽图像、持续大数据	USB、GigE Vision 等，不应强行套串口
多轴硬实时同步	CANopen、EtherCAT 等工业网络，而非普通串口轮询

选择接口时不要只比较标称速率，还要评估确定性、隔离、连接器可靠性、驱动维护、诊断能力和设备生命周期。

8. 小结

UART 定义字符传输，RS-232/RS-485 主要定义电气接口，USB 虚拟串口提供操作系统抽象，真正的消息语义属于应用协议。把这几层分开，是后续编写串口接收循环、二进制帧解析器和故障恢复逻辑的前提。

参考资料

C# 原生互操作与设备 SDK（八）：C++ ABI 与跨平台封装

Sat, 25 Jul 2026 10:00:00 +0800

很多设备 SDK 的核心由 C++ 编写，却不适合把类、异常、std::string 和 STL 容器直接暴露给 C#。C++ 没有覆盖 MSVC、GCC、Clang 和所有 .NET 支持平台的统一 ABI；编译器版本、运行库和构建选项变化，也可能改变名称修饰与对象布局。

更稳定的边界是保留 C++ 实现，在外面导出一层窄 C ABI。本文给出完整设计原则，并说明怎样让同一托管适配器连接 Windows .dll、Linux .so 和 macOS .dylib。

1. 为什么不直接导出 C++ 类

下面的接口对同一工具链内的 C++ 调用者很自然：

1
2
3
4
5
6


class Camera
{
public:
 virtual ~Camera();
 std::vector<std::byte> Capture(const std::string& recipe);
};

跨 ABI 时却产生一串隐含约定：

类名和方法名如何修饰；
this 怎样传递、虚表怎样布局；
std::string/std::vector 使用哪个标准库实现；
对象由哪个运行库分配和释放；
C++ 异常怎样传播；
编译器、调试/发布运行库和迭代器调试选项是否一致。

把这些内部细节复制到 P/Invoke 签名不是稳定集成。Microsoft 的 .NET ABI 指南也建议通过 extern "C" 导出 C 函数来连接 C++。

2. 用不透明句柄隐藏 C++ 对象

公共头文件只暴露 C 能表达的类型：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


#pragma once
#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
#define DEVICE_EXTERN extern "C"
#else
#define DEVICE_EXTERN
#endif

#ifdef _WIN32
// 按 SDK 构建方视角书写；完整的 SDK 头文件通常再用构建宏在 dllexport 与 dllimport 间切换。
#define DEVICE_EXPORT DEVICE_EXTERN __declspec(dllexport)
#else
#define DEVICE_EXPORT DEVICE_EXTERN __attribute__((visibility("default")))
#endif

typedef struct device_context device_context;

typedef struct device_open_options {
 uint32_t struct_size;
 uint32_t api_version;
 int32_t device_index;
 uint32_t reserved;
} device_open_options;

DEVICE_EXPORT int32_t device_open(
 const device_open_options* options,
 device_context** out_context);

DEVICE_EXPORT int32_t device_capture(
 device_context* context,
 const uint8_t* recipe_utf8,
 size_t recipe_length,
 uint8_t* output,
 size_t capacity,
 size_t* out_required);

DEVICE_EXPORT int32_t device_close(device_context* context);

device_context 的定义只存在于 C++ 实现文件中。C# 看到的只是一个不透明句柄，再用 SafeHandle 管理。这样可以修改内部类、容器和继承关系，而不改变公开布局。

3. 异常不能穿过 C 边界

C++ 包装函数要在边界内捕获异常并转换为稳定错误码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


#include "device_api.h"
#include "camera.hpp"
#include <new>

struct device_context
{
 explicit device_context(int32_t index) : camera(index) {}
 Camera camera;
};

int32_t device_open(
 const device_open_options* options,
 device_context** out_context)
{
 if (options == nullptr || out_context == nullptr)
 return -1;
 if (options->struct_size < sizeof(device_open_options))
 return -2;

 *out_context = nullptr;

 try
 {
 auto* context = new device_context(options->device_index);
 *out_context = context;
 return 0;
 }
 catch (const std::bad_alloc&)
 {
 return -3;
 }
 catch (...)
 {
 return -100;
 }
}

int32_t device_close(device_context* context)
{
 try
 {
 delete context;
 return 0;
 }
 catch (...)
 {
 return -100;
 }
}

不要让 C++ 异常越过 C 函数进入 .NET。若需要错误文本，可提供“调用者缓冲区 + 长度”的错误查询函数，并定义错误信息是按线程、按 context 还是按最近调用保存，避免全局字符串在并发下相互覆盖。

析构函数原则上也不应抛异常；包装层的 catch (...) 是边界兜底，不是用来掩盖不可恢复的资源损坏。

4. ABI 从第一版就为演进留位置

公开结构加入 struct_size 与 api_version，可以让新库识别旧调用者实际提供了多少字段。常见兼容策略是：

只在结构尾部追加字段；
保留并清零 reserved 字段；
不改变已发布字段的类型、偏移和含义；
新能力用新函数或能力查询暴露；
不复用已经发布的错误码和枚举值；
提供 device_get_api_version 与运行时版本信息。

“DLL 文件名没变”不代表 ABI 兼容。应保存公共头文件基线，并在 CI 中对导出符号、结构大小和兼容样例做回归。

5. 内存始终回到分配它的模块

优先让调用者提供输出缓冲区。必须返回动态内存时，C API 应成对提供分配与释放：

1
2
3
4
5
6


DEVICE_EXPORT int32_t device_create_blob(
 device_context* context,
 uint8_t** out_data,
 size_t* out_length);

DEVICE_EXPORT void device_free(void* memory);

C# 复制数据后调用 device_free。不要要求调用者猜测内部使用 new[]、malloc、COM 任务分配器还是特定 CRT 堆。

同理，字符串使用 UTF-8 字节加显式长度可以避开 wchar_t 在平台间宽度不同的问题。若必须以零结尾，要写清长度是否包含终止符。

6. 托管声明保持同一逻辑库名

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


using System.Runtime.InteropServices;

internal static partial class DeviceNative
{
 private const string LibraryName = "device_bridge";

 // DeviceOpenOptionsNative 遵循本系列（三）的 *Native 布局约定（Sequential + struct_size）。
 [LibraryImport(LibraryName, EntryPoint = "device_open")]
 internal static partial int Open(
 in DeviceOpenOptionsNative options,
 out SafeDeviceHandle handle);

 [LibraryImport(LibraryName, EntryPoint = "device_close")]
 internal static partial int CloseRaw(nint handle);
}

构建系统分别产出：

1
2
3
4


runtimes/
├── win-x64/native/device_bridge.dll
├── linux-x64/native/libdevice_bridge.so
└── osx-arm64/native/libdevice_bridge.dylib

NuGet/RID 资产或自定义 DllImportResolver 负责把逻辑名映射到当前平台文件。每个产物仍需在对应 OS、架构和运行库环境中测试，不能因为 C API 相同就只测试 Windows。

7. C 包装层不等于最低公分母

稳定 C ABI 可以继续表达现代能力：

不透明句柄表达对象；
结构 + struct_size 表达可演进参数；
函数指针 + context 表达事件；
调用者缓冲区表达高吞吐数据；
明确错误码和查询函数表达诊断；
能力位或查询函数表达可选特性。

边界应该窄，但不应把所有错误压成一个 false，也不应让上层通过几十次 getter 拼出一份本可原子返回的状态快照。

8. 何时考虑其他桥接方式

C++/CLI：适合 Windows 内部已有大量 C++ 类且团队能维护 .vcxproj 的场景；现代 .NET 的 C++/CLI 支持仅限 Windows，不能作为跨平台桥。
COM：适合已有稳定 COM 契约、注册与版本治理体系的 Windows 组件。
独立进程/RPC：适合 SDK 崩溃隔离、位数隔离、许可隔离或跨机器部署，但引入序列化、进程管理和故障恢复成本。
C ABI：通常是跨平台、跨语言、部署在同一进程中的默认选择。

选择不是只看调用方便程度，还要评估故障是否会拖垮主进程、厂商库能否重入、升级是否需要独立回滚，以及许可是否允许重新封装。

9. 发布前验证矩阵

维度	最低验证
编译器	每个受支持工具链构建公开头文件与桥接库
OS/架构	每个声明支持的 RID 加载并运行冒烟测试
ABI	导出名、调用约定、结构大小和偏移断言
版本	旧托管适配器连接新库，新适配器识别旧库
错误	空指针、缓冲区不足、设备断连、异常转换
资源	重复打开关闭、失败注入、句柄和内存泄漏
并发	多线程调用、回调与关闭竞争、重入限制

跨平台不是“能编译三份文件”，而是每个承诺的平台都拥有可重复的构建、打包和测试证据。

总结

C++ 实现可以保持复杂，公开 ABI 应保持简单、明确、可演进。用 extern "C"、不透明句柄、定宽类型、显式长度、配对释放和错误码建立稳定边界，再由 LibraryImport、SafeHandle 和托管适配器恢复面向对象语义，是设备 SDK 长期维护成本较低的组合。

至此，本系列从 P/Invoke 入口一路走到类型、布局、内存、加载、回调、句柄和跨平台桥接。下一阶段可以在这层可靠边界之上展开串口、TCP、Modbus、CAN 与工业协议编程。

参考资料

C# 原生互操作与设备 SDK（七）：SafeHandle 与资源生命周期

Fri, 24 Jul 2026 10:00:00 +0800

把设备句柄保存为 nint 很方便，也把所有风险留给调用者：忘记关闭会泄漏资源，并发关闭可能让调用使用失效句柄，异常路径又容易跳过清理。手写终结器并不能可靠解决这些问题。

SafeHandle 把非托管句柄的所有权、有效值和释放动作封装成受运行时支持的资源类型。本文说明怎样为设备 SDK 正确派生它，以及它能保证什么、不能保证什么。

1. 先确认句柄契约

1
2
3
4
5


typedef void* device_handle;

int32_t device_open(int32_t index, device_handle* out_handle);
int32_t device_get_position(device_handle handle, double* out_mm);
int32_t device_close(device_handle handle);

本篇假设 device_close 返回状态码（0 表示成功）；第一篇的最小示例曾把它简化为 void，真实 SDK 一律以头文件为准。

接入前必须确认：

无效句柄是空指针、-1，还是另一个哨兵；
device_close 能否重复调用；
关闭是否会阻塞，是否要求特定线程；
关闭前是否必须停止采集、注销回调或等待任务；
句柄能否被多个线程并发调用；
子资源是否必须早于父句柄释放。

SafeHandle 只负责句柄释放，不会自动推导这些会话规则。

2. 为每种释放函数定义独立类型

若空指针和 -1 都表示无效，可继承 SafeHandleZeroOrMinusOneIsInvalid：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


using Microsoft.Win32.SafeHandles;
using System.Runtime.InteropServices;

public sealed class SafeDeviceHandle
 : SafeHandleZeroOrMinusOneIsInvalid
{
 // LibraryImport 通过 out/返回值创建 SafeHandle 时需要 public 无参构造函数。
 public SafeDeviceHandle() : base(ownsHandle: true)
 {
 }

 protected override bool ReleaseHandle()
 {
 return DeviceNative.CloseRaw(handle) == 0;
 }
}

internal static partial class DeviceNative
{
 [LibraryImport("device_sdk", EntryPoint = "device_close")]
 internal static partial int CloseRaw(nint handle);
}

若只有零无效，应直接继承 SafeHandle 并实现准确的 IsInvalid。文件句柄、内存映射句柄和设备会话可能分别要求 CloseHandle、UnmapViewOfFile、device_close，不能为了复用而共用一个“万能句柄类”。

3. 让 P/Invoke 直接产生 SafeHandle

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


internal static partial class DeviceNative
{
 [LibraryImport("device_sdk", EntryPoint = "device_open")]
 internal static partial int Open(
 int index,
 out SafeDeviceHandle handle);

 [LibraryImport("device_sdk", EntryPoint = "device_get_position")]
 internal static partial int GetPosition(
 SafeDeviceHandle handle,
 out double millimeters);
}

在 .NET 8 及以上，源生成互操作通过返回值、ref 或 out 创建 SafeHandle 派生类型时，该类型必须具有 public 无参构造函数。

封装打开过程时，失败路径也要释放 SDK 可能写出的有效句柄：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


public static class DeviceSessionFactory
{
 public static DeviceSession Open(int index)
 {
 int status = DeviceNative.Open(index, out SafeDeviceHandle handle);
 if (status != 0)
 {
 handle?.Dispose();
 throw new DeviceSdkException("device_open", status);
 }

 // 源生成封送下 handle 不会为 null；null 检查是防御式写法。
 if (handle is null || handle.IsInvalid)
 {
 handle?.Dispose();
 throw new InvalidOperationException("SDK returned an invalid handle");
 }

 return new DeviceSession(handle);
 }
}

4. SafeHandle 保护单次原生调用

当 P/Invoke 参数直接声明为 SafeDeviceHandle 时，运行时会在调用期间保持安全句柄存活，避免另一个线程的 Dispose 在原生调用尚未返回时立即释放底层句柄。这比先调用 DangerousGetHandle() 再传 nint 更可靠。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


public sealed class DeviceSession(SafeDeviceHandle handle) : IDisposable
{
 private readonly SafeDeviceHandle _handle = handle;

 public double GetPosition()
 {
 int status = DeviceNative.GetPosition(_handle, out double millimeters);
 if (status != 0)
 {
 throw new DeviceSdkException("device_get_position", status);
 }

 return millimeters;
 }

 public void Dispose() => _handle.Dispose();
}

这项保证只覆盖 P/Invoke 调用期间。它不代表设备允许并发命令，也不阻止业务层在“准备动作”和“真正调用”之间发生关闭。会话仍需用状态机、命令队列或锁定义并发语义。

5. ReleaseHandle 必须短小且不抛异常

ReleaseHandle 可能从显式 Dispose 或运行时清理路径进入。实现应：

只调用可靠的原生释放函数；
不抛异常；
不依赖普通业务对象仍然存活；
不做 UI、网络、复杂日志或长时间等待；
以返回值报告是否成功，但不能指望调用者在终结阶段恢复。

如果关闭设备必须先执行异步停止、保存或注销回调，应在上层 DisposeAsync/显式 StopAsync 中完成受控关闭，最后再释放 SafeHandle。ReleaseHandle 只作为底层资源兜底，不能承担完整停机流程。

6. Danger 前缀的方法确实危险

DangerousGetHandle 暴露原始值，却不自动延长句柄寿命。只有第三方 API 无法直接接受 SafeHandle 时，才考虑配合 DangerousAddRef/DangerousRelease 建立严格的 try/finally：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


bool addedRef = false;
try
{
 handle.DangerousAddRef(ref addedRef);
 nint raw = handle.DangerousGetHandle();
 LegacyCall(raw);
}
finally
{
 if (addedRef)
 {
 handle.DangerousRelease();
 }
}

优先修改 P/Invoke 声明直接接收 SafeHandle。手工引用计数代码越多，越容易在异常和并发路径上失衡。

7. 句柄所有权不能重复

同一个原始句柄不能由两个 ownsHandle: true 的对象分别拥有，否则会重复关闭。包装已有句柄时要明确：

所有权转移：新 SafeHandle 负责释放，旧所有者不再关闭；
借用：包装对象不拥有句柄，但必须保证真实所有者覆盖全部使用期；
共享：需要 SDK 明确支持的引用计数或复制句柄机制，不能自行假设。

若原生 API 接管了句柄所有权，可在成功后调用 SetHandleAsInvalid()，防止托管侧再次释放；只有文档明确说明“成功后接管”时才能这样做。

8. 关闭顺序与回调协同

典型设备会话的关闭顺序是：

阻止新命令进入；
请求采集/运动停止并确认物理状态；
注销回调并等待在途回调退出；
释放子资源；
Dispose 主设备 SafeHandle；
发布已关闭状态。

顺序必须以 SDK 契约为准。若先关闭主句柄再注销回调，原生线程可能访问已释放设备；若先释放回调 context，而注销仍有在途调用，则会形成 use-after-free。

总结

SafeHandle 是原生句柄的默认托管表示：它集中定义无效值和释放函数，并保护单次 P/Invoke 调用期间的句柄寿命。但它不是设备状态机，也不会自动处理异步停机、回调屏障和线程安全。把底层释放交给 SafeHandle，把完整关闭协议留在会话层。

下一篇把系列收束到 SDK 设计端：如何用稳定 C ABI 桥接 C++ 实现，并同时交付 Windows DLL 与 Linux .so。

参考资料

C# 原生互操作与设备 SDK（六）：回调、原生线程与事件

Thu, 23 Jul 2026 10:00:00 +0800

设备 SDK 常通过回调上报图像到达、运动完成、报警和连接变化。注册成功只完成了第一步：原生库可能在任意线程、任意时刻调用函数指针，并继续使用注册时传入的上下文。委托被 GC 回收、设备句柄已关闭、缓冲区已失效或异常穿过 ABI 边界，都可能导致进程级崩溃。

本文建立回调的完整生命周期，并用非托管函数指针（C# 9/.NET 5 起可用）在 .NET 10 环境下演示一条可验证的实现路径。

1. 先读清原生回调契约

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


#include <stddef.h>
#include <stdint.h>

typedef void (*device_event_callback)(
 void* context,
 int32_t event_code,
 const uint8_t* payload,
 size_t payload_length);

int32_t device_register_callback(
 device_handle handle,
 device_event_callback callback,
 void* context);

int32_t device_unregister_callback(device_handle handle);

头文件之外还要确认：

回调使用哪种调用约定；
SDK 是同步回调还是由内部线程异步回调；
是否可能并发、重入或在注销期间继续进入；
payload 只在本次回调有效，还是可由调用者释放；
注销返回时是否保证所有在途回调结束；
关闭设备句柄前必须执行什么顺序。

2. 使用函数指针表达精确 ABI

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;

internal static partial class DeviceNative
{
 [LibraryImport("device_sdk", EntryPoint = "device_register_callback")]
 internal static unsafe partial int RegisterCallback(
 nint handle,
 delegate* unmanaged[Cdecl]<nint, int, byte*, nuint, void> callback,
 nint context);

 [LibraryImport("device_sdk", EntryPoint = "device_unregister_callback")]
 internal static partial int UnregisterCallback(nint handle);
}

delegate* unmanaged[Cdecl]<...> 表达的是非托管函数指针，参数顺序与原生 typedef 一一对应。若 SDK 不是 cdecl，两侧必须同时改为真实调用约定。

3. 用 UnmanagedCallersOnly 暴露静态入口

实例方法带有隐含的 this，不能直接作为普通 C 回调。可以暴露一个静态入口，把实例放在 context 中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80


using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
using System.IO;
using System.Threading.Channels;

internal static class DeviceCallbackBridge
{
 [UnmanagedCallersOnly(CallConvs = new[] { typeof(CallConvCdecl) })]
 public static unsafe void OnEvent(
 nint context,
 int eventCode,
 byte* payload,
 nuint payloadLength)
 {
 try
 {
 var handle = GCHandle.FromIntPtr(context);
 if (handle.Target is not DeviceEventSink sink)
 {
 return;
 }

 if (payloadLength > sink.MaxPayloadLength ||
 (payload == null && payloadLength != 0))
 {
 CallbackFailureLog.Write(
 new InvalidDataException("Invalid callback payload"));
 return;
 }

 int length = checked((int)payloadLength);
 byte[] copy = new ReadOnlySpan<byte>(payload, length).ToArray();
 sink.TryPublish(new NativeDeviceEvent(eventCode, copy));
 }
 catch (Exception exception)
 {
 CallbackFailureLog.Write(exception);
 }
 }
}

public sealed record NativeDeviceEvent(int Code, byte[] Payload);

public sealed class DeviceEventSink
{
 private readonly Channel<NativeDeviceEvent> _events =
 Channel.CreateBounded<NativeDeviceEvent>(64);

 public DeviceEventSink(nuint maxPayloadLength)
 {
 if (maxPayloadLength == 0 || maxPayloadLength > int.MaxValue)
 {
 throw new ArgumentOutOfRangeException(nameof(maxPayloadLength));
 }

 MaxPayloadLength = maxPayloadLength;
 }

 public nuint MaxPayloadLength { get; }

 public ChannelReader<NativeDeviceEvent> Events => _events.Reader;

 public bool TryPublish(NativeDeviceEvent deviceEvent) =>
 _events.Writer.TryWrite(deviceEvent);
}

internal static class CallbackFailureLog
{
 public static void Write(Exception exception)
 {
 try
 {
 Console.Error.WriteLine(exception);
 }
 catch
 {
 // 回调边界不能因诊断失败再次抛出。
 }
 }
}

这里使用有界通道，队列已满时 TryWrite 会失败；生产代码应记录丢弃计数或根据事件类型采用受控降载策略，不能静默假装事件已经处理。

UnmanagedCallersOnly 方法必须是静态方法，签名只能使用本系列（三）定义的 blittable 类型。异常绝不能穿过原生边界；回调入口要捕获全部异常，并把故障写入不再抛出的最小日志通道。

示例立即复制 payload，因为没有契约允许回调返回后继续读取该指针。最大长度由创建 DeviceEventSink 时结合设备数据模型配置，避免损坏的 SDK 值触发超大分配，又不武断限制合法图像或波形大小。

4. 上下文句柄必须活到最后一次回调结束

注册时用普通 GCHandle 保持托管对象可达。这里固定的是对象的生命周期，不是内存地址；默认 GCHandleType.Normal 仍允许 GC 移动对象：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


public sealed unsafe class CallbackRegistration : IDisposable
{
 private readonly nint _device;
 private GCHandle _context;
 private bool _registered;

 public CallbackRegistration(nint device, DeviceEventSink sink)
 {
 _device = device;
 _context = GCHandle.Alloc(sink);

 int status = DeviceNative.RegisterCallback(
 device,
 &DeviceCallbackBridge.OnEvent,
 GCHandle.ToIntPtr(_context));

 if (status != 0)
 {
 _context.Free();
 throw new DeviceSdkException("device_register_callback", status);
 }

 _registered = true;
 }

 public void Dispose()
 {
 if (!_registered)
 {
 return;
 }

 int status = DeviceNative.UnregisterCallback(_device);
 if (status != 0)
 {
 throw new DeviceSdkException("device_unregister_callback", status);
 }

 // 只有 SDK 保证注销返回后无在途回调，才能在这里释放。
 _context.Free();
 _registered = false;
 }
}

如果注销不等待在途回调，这个简化版本不安全。需要增加计数/屏障，或调用 SDK 提供的同步停止函数，按“停止产生新回调 → 等待已有回调退出 → 释放 context → 关闭设备”的顺序执行。

异常路径也要设计：如果注销失败，立即释放 GCHandle 可能形成悬空上下文；无限保留则泄漏。应根据厂商契约决定重试、强制停止或把会话转入不可恢复状态，而不是在 finally 中盲目释放。

5. 回调线程不等于 UI 线程

相机或运动控制 SDK 常从内部原生线程调用。回调中应只做有界、非阻塞工作：

复制必要数据和时间戳；
写入 Channel<T>、无界风险受控的队列或专用调度器；
立即返回，让 SDK 线程继续工作；
在消费者侧解析、记录、更新状态并切换到 UI Dispatcher。

不要在回调里等待 UI、获取长时间持有的业务锁、同步调用关闭设备，或执行不可控的磁盘/网络 I/O。否则不仅丢帧，还可能与 SDK 内部锁形成死锁。锁与死锁的通用机制见《线程安全的本质：从 CPU 缓存到内存模型，锁到底在保证什么》。

6. 委托回调仍然可用，但必须扎根

旧 API 或不适合函数指针的场景可以声明委托：

1
2
3
4
5
6


[UnmanagedFunctionPointer(CallingConvention.Cdecl)]
internal unsafe delegate void DeviceEventCallback(
 nint context,
 int eventCode,
 byte* payload,
 nuint payloadLength);

如果原生代码只在一次同步调用期间使用委托，可在调用后用 GC.KeepAlive(callback) 保证其活到调用结束。如果原生库保存函数指针，就必须把委托存入与注册同寿命的字段，不能只依赖局部变量、GC.KeepAlive 或“目前 GC 还没发生”。

7. 回调测试要覆盖时间窗口

至少验证：

注册失败时 context 不泄漏；
回调在工作线程、并发和重入时仍正确；
空载荷、最大载荷和非法长度受到保护；
回调处理异常不会越过 ABI；
注销与回调竞争时没有 use-after-free；
关闭设备后不会再向已释放队列或 UI 发布；
多次启动/停止不会重复注册。

模拟原生线程的测试应主动随机化回调时序，而不是只在单线程中顺序调用入口。

总结

回调是一段跨线程、跨 GC、跨 ABI 的长期租约。函数签名正确只是起点；托管目标、委托或 GCHandle 必须保持到最后一次回调结束，载荷要在有效期内复制，异常不能穿过边界，耗时工作应转移到托管队列。

下一篇用 SafeHandle 管理设备句柄，让关闭时机和调用期间的存活保证进入类型系统。

参考资料

C# 原生互操作与设备 SDK（五）：调用约定、位数与 DLL 加载诊断

Wed, 22 Jul 2026 10:00:00 +0800

“DLL 明明就在目录里，为什么仍然提示找不到？”这是设备 SDK 接入中最常见、也最容易误诊的问题。报错里的库名只是加载链入口；真正失败的可能是进程位数、二级依赖、导出符号、调用约定或搜索路径。

本文建立一套从文件、架构、依赖、导出到 ABI 的诊断顺序，并说明如何用 NativeLibrary 管理多平台库选择。

1. 调用约定必须与头文件一致

调用约定（Calling Convention）规定参数如何传递、栈如何清理以及返回值如何交付。现代 64 位平台往往统一了许多历史差异，但声明仍应匹配原生构建约定，尤其是 Windows x86 和回调函数。

LibraryImport 可配合 UnmanagedCallConv 显式声明 cdecl：

1
2
3
4
5
6
7
8
9


using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;

internal static partial class DeviceNative
{
 [LibraryImport("device_sdk", EntryPoint = "device_open")]
 [UnmanagedCallConv(CallConvs = new[] { typeof(CallConvCdecl) })]
 internal static partial int Open(int index, out nint handle);
}

旧式 DllImport 则使用 CallingConvention 属性：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


using System.Runtime.InteropServices;

internal static class LegacyNative
{
 [DllImport(
 "device_sdk",
 EntryPoint = "device_open",
 ExactSpelling = true,
 CallingConvention = CallingConvention.Cdecl)]
 internal static extern int Open(int index, out nint handle);
}

不要根据函数名或别的 SDK 猜 Cdecl/StdCall。先看导出宏、函数指针 typedef、项目设置和厂商支持的目标平台。

2. 进程架构决定可加载的库

64 位操作系统可以运行 32 位进程，但单个进程不能把 32 位和 64 位机器代码混装。先输出当前进程信息：

1
2
3
4
5
6


using System.Runtime.InteropServices;

Console.WriteLine($"OS: {RuntimeInformation.OSDescription}");
Console.WriteLine($"OS architecture: {RuntimeInformation.OSArchitecture}");
Console.WriteLine($"Process architecture: {RuntimeInformation.ProcessArchitecture}");
Console.WriteLine($"64-bit process: {Environment.Is64BitProcess}");

检查的是进程架构，不是只看操作系统或 CPU。若 SDK 只有 x86 版本，应用必须以 x86 运行；若同时有 x64 和 Arm64，部署时要按 Runtime Identifier（RID）选择对应资产。

BadImageFormatException 常见于架构不匹配，但也可能表示文件损坏或目标根本不是当前平台可加载的动态库，因此仍要查看文件头。

3. 主库存在不代表依赖完整

设备 SDK 经常形成依赖链：

1
2
3
4
5


DeviceAdapter.dll
└── device_sdk.dll
 ├── vendor_runtime.dll
 ├── camera_transport.dll
 └── Microsoft Visual C++ Runtime / system libraries

当 vendor_runtime.dll 缺失时，.NET 仍可能把入口库报告为加载失败。还要检查：

依赖库是否部署在加载器能找到的位置；
依赖版本和架构是否一致；
Linux 的 SONAME、macOS install name 是否匹配；
运行账户是否有读取/执行权限；
厂商驱动或运行时是否必须单独安装。

不要通过把一堆未知 DLL 复制进系统目录来“试到能跑”。这会隐藏版本来源并污染整机环境。

4. 导出名以二进制为准

头文件中的 C++ 函数可能被名称修饰（Name Mangling），宏也可能改变导出名。常用检查命令如下：

Windows 的 Visual Studio Developer Command Prompt：

1
2


dumpbin /headers device_sdk.dll | findstr machine
dumpbin /exports device_sdk.dll

Linux：

1
2
3


file libdevice_sdk.so
ldd libdevice_sdk.so
readelf -Ws libdevice_sdk.so

macOS：

1
2
3


file libdevice_sdk.dylib
otool -L libdevice_sdk.dylib
nm -gU libdevice_sdk.dylib

这些命令应在库所在目录执行。dumpbin 随 Visual Studio C++ 工具链提供；ldd 会触发动态加载器解析，不能对来源不可信的二进制随意运行。

若导出表中只有类似 ?Open@Device@@... 的符号，说明它暴露的是编译器相关 C++ ABI。长期方案通常是增加 extern "C" 的 C 包装层，而不是把修饰名硬编码进 C#。

5. 明确管理动态库选择

固定库名适合简单部署。若不同平台或 CPU 特性需要选择不同实现，可以为当前程序集注册一个解析器：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47


using System.Reflection;
using System.Runtime.InteropServices;

internal static partial class DeviceNative
{
 private const string LibraryName = "device_sdk";

 static DeviceNative()
 {
 NativeLibrary.SetDllImportResolver(
 typeof(DeviceNative).Assembly,
 ResolveLibrary);
 }

 private static nint ResolveLibrary(
 string libraryName,
 Assembly assembly,
 DllImportSearchPath? searchPath)
 {
 if (libraryName != LibraryName)
 {
 return 0; // 交回默认解析流程
 }

 string fileName = OperatingSystem.IsWindows()
 ? "device_sdk.dll"
 : OperatingSystem.IsLinux()
 ? "libdevice_sdk.so"
 : OperatingSystem.IsMacOS()
 ? "libdevice_sdk.dylib"
 : throw new PlatformNotSupportedException();

 string architecture = RuntimeInformation.ProcessArchitecture
 .ToString()
 .ToLowerInvariant();
 string path = Path.Combine(
 AppContext.BaseDirectory,
 "native",
 architecture,
 fileName);

 return NativeLibrary.Load(path);
 }

 [LibraryImport(LibraryName, EntryPoint = "device_open")]
 internal static partial int Open(int index, out nint handle);
}

这段代码定义的是项目自己的部署布局，发布过程必须把文件放到对应目录。每个程序集只能注册一个 DllImportResolver，应集中管理，不能让多个 SDK 初始化器互相争抢。

NuGet 包可以把平台资产放在 runtimes/{rid}/native/ 下，由恢复与发布流程按 RID 选择。实际支持的 RID 应由构建和测试矩阵决定，不要根据字符串临时拼出一个未测试的平台。适配器层如何把这类平台差异挡在业务之外，见《设备软件架构与控制模型（二）：硬件抽象层与设备适配器》。

6. 搜索路径也是安全边界

动态加载器搜索当前目录、应用目录、系统目录或环境变量的规则因平台和配置而异。把可写目录加入全局 PATH，或从当前工作目录加载同名 DLL，可能让攻击者或误操作放入错误二进制。

更稳妥的策略是：

SDK 文件随应用或受控安装器部署；
使用明确的应用内路径或 RID 资产；
校验安装包来源、签名或摘要；
记录实际加载的文件版本与路径；
不从用户上传目录、临时目录和网络共享自动加载原生库。

7. 按固定顺序定位问题

记录操作系统、进程架构和 .NET 版本；
确认入口文件真实存在且格式、架构正确；
检查所有原生依赖及驱动前置条件；
核对实际导出名；
对照头文件确认调用约定和完整签名；
用最小控制台程序调用无副作用的版本查询函数；
最后才接入复杂 UI、服务容器和设备流程。

这个顺序把“无法加载”“找不到符号”和“调用后损坏”分开，避免在 ABI 错误上反复调整文件路径。

总结

原生库加载是一条依赖链，不是一次文件查找。进程架构、依赖库、导出符号、调用约定和搜索路径必须逐层确认；NativeLibrary 能让选择逻辑显式化，但不能修复错误 ABI。

下一篇讨论反向调用：当厂商 SDK 从原生线程回调 C# 时，如何管理函数指针、对象寿命与线程切换。

参考资料

C# 原生互操作与设备 SDK（四）：字符串、数组、指针与 Marshalling

Tue, 21 Jul 2026 10:00:00 +0800

互操作中的数据错误通常不在“能不能转换”，而在“谁分配、谁释放、能写多少、指针能留多久”。同一个 char* 可能表示只读输入、调用者提供的输出缓冲区、库分配的返回值，或只在下一次 SDK 调用前有效的借用视图。

本文把字符串、数组、ref/out 和指针放回完整契约中讨论。示例以 UTF-8 C API 为主，目标环境为 .NET 10。

1. 先为每个指针写五项契约

看到 T*、void* 或 char* 时，先记录：

方向：输入、输出还是输入输出；
长度：固定、以零结尾、由参数给出，还是由返回值给出；
分配者：调用者、SDK 还是操作系统；
生命周期：仅本次调用、直到下一次调用、直到显式释放，还是与句柄同寿命；
可变性与线程：原生代码能否写入，是否会跨线程保留指针。

缺少任一项，都不应急着写 P/Invoke 声明。

2. 只读输入字符串显式指定编码

原生接口：

1

int32_t device_set_name(device_handle handle, const char* utf8_name);

若函数只在调用期间读取字符串，LibraryImport 可以生成 UTF-8 转换：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


using System.Runtime.InteropServices;

internal static partial class DeviceNative
{
 [LibraryImport(
 "device_sdk",
 EntryPoint = "device_set_name",
 StringMarshalling = StringMarshalling.Utf8)]
 internal static partial int SetName(nint handle, string name);
}

这不允许原生库保存收到的指针。若 API 会在返回后继续使用它，就必须按 SDK 约定分配稳定内存，并在注销或关闭后释放。

3. 输出文本优先采用调用者缓冲区

一个边界清晰的 C API 会同时接收缓冲区和容量，并返回实际所需长度：

1
2
3
4
5


int32_t device_get_name(
 device_handle handle,
 char* utf8_buffer,
 size_t capacity,
 size_t* out_required);

下面的示例约定：out_required 包含结尾零；以空缓冲区查询长度时返回成功；若第二次调用期间名称变长，函数返回可识别的“缓冲区不足”状态并更新长度。其他 SDK 可能采用不同约定，必须相应调整封装。

托管声明保留原始指针语义：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


using System.Runtime.InteropServices;

internal static partial class DeviceNative
{
 [LibraryImport("device_sdk", EntryPoint = "device_get_name")]
 internal static unsafe partial int GetName(
 nint handle,
 byte* buffer,
 nuint capacity,
 out nuint required);
}

封装层可以先询问长度，再固定缓冲区调用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


using System.Text;

public static class DeviceNameReader
{
 public static unsafe string ReadName(nint handle)
 {
 int status = DeviceNative.GetName(handle, null, 0, out nuint required);
 if (status != 0)
 {
 throw new DeviceSdkException("device_get_name(size)", status);
 }

 if (required == 0)
 {
 throw new InvalidDataException("SDK returned an invalid name length");
 }

 var buffer = GC.AllocateUninitializedArray<byte>(
 checked((int)required),
 pinned: true); // 分配在固定对象堆（POH）上，内存在 GC 下保持固定

 // pinned: true 保证内存固定，fixed 在这里只负责取得指向它的指针。
 fixed (byte* pointer = buffer)
 {
 status = DeviceNative.GetName(
 handle,
 pointer,
 (nuint)buffer.Length,
 out required);
 }

 if (status != 0)
 {
 throw new DeviceSdkException("device_get_name(data)", status);
 }

 if (required > (nuint)buffer.Length)
 {
 throw new InvalidDataException("SDK returned an invalid name length");
 }

 int used = checked((int)required);
 int terminator = Array.IndexOf(buffer, (byte)0, 0, used);
 if (terminator < 0)
 {
 throw new InvalidDataException("SDK returned a non-terminated name");
 }

 return Encoding.UTF8.GetString(buffer, 0, terminator);
 }
}

真实封装还应识别“缓冲区不足”状态并按更新后的所需长度重试，避免名称在两次调用间变化造成误判。

4. 不要用 Out string 充当可写缓冲区

托管字符串不可变。把按值字符串标成 [Out] string 让原生代码写入，可能破坏运行时假设；Microsoft 的互操作建议明确反对这种写法。

StringBuilder 可用于某些旧 API，但封送过程通常需要额外分配和复制，而且容量与结尾零仍容易出错。新设计优先使用显式字节/字符缓冲区加长度；旧接口则严格按官方签名处理。

5. 数组必须与元素数量一起传递

原生数组本质上通常只是首元素指针，长度不会自动跟随：

1
2
3
4
5


int32_t device_read_samples(
 device_handle handle,
 double* out_samples,
 size_t capacity,
 size_t* out_count);

如果原生代码只在调用期间写入，可固定托管数组：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


using System.Runtime.InteropServices;

internal static partial class SampleReader
{
 [LibraryImport("device_sdk", EntryPoint = "device_read_samples")]
 private static unsafe partial int ReadSamplesNative(
 nint handle,
 double* samples,
 nuint capacity,
 out nuint count);

 internal static unsafe int ReadSamples(
 nint handle,
 Span<double> destination)
 {
 fixed (double* pointer = destination)
 {
 int status = ReadSamplesNative(
 handle,
 pointer,
 (nuint)destination.Length,
 out nuint count);

 if (status != 0)
 {
 throw new DeviceSdkException("device_read_samples", status);
 }

 if (count > (nuint)destination.Length)
 {
 throw new InvalidDataException("SDK returned an invalid sample count");
 }

 return checked((int)count);
 }
 }
}

fixed 的保证只覆盖代码块。若 SDK 异步保留指针，必须使用拥有明确释放时机的固定内存或非托管内存，并避免长期固定大对象造成 GC 压力。

6. ref、out 和指针的层级要一致

C 参数	常见 C# 表达	含义
`int32_t value`	`int value`	按值输入
`const int32_t* value`	`in int value` 或指针	指向只读单值
`int32_t* out_value`	`out int value`	输出一个单值
`int32_t* values` + 长度	数组/`Span<T>` 固定后的指针	连续元素
`device_handle* out_handle`	`out nint handle`	输出一个句柄
`void** out_buffer`	`out nint buffer`	输出一根指向内存的指针

ref/out 只是表达一层间接寻址，不能自动推导数组长度、分配器或所有权。

7. 谁分配，谁提供释放方式

如果 SDK 返回自己分配的内存，应该同时提供释放函数：

1
2
3
4


int32_t device_create_report(device_handle handle,
 uint8_t** out_data,
 size_t* out_length);
void device_free(void* memory);

托管侧复制完后在 finally 中调用同一库的释放函数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


using System.Runtime.InteropServices;

internal static partial class DeviceReportReader
{
 [LibraryImport("device_sdk", EntryPoint = "device_create_report")]
 private static partial int CreateReportNative(
 nint handle,
 out nint data,
 out nuint length);

 [LibraryImport("device_sdk", EntryPoint = "device_free")]
 private static partial void Free(nint memory);

 public static byte[] CreateReport(nint handle)
 {
 nint memory = 0;
 try
 {
 int status = CreateReportNative(
 handle,
 out memory,
 out nuint length);
 if (status != 0 || memory == 0)
 {
 throw new InvalidOperationException(
 $"device_create_report failed: {status}");
 }

 byte[] managed = new byte[checked((int)length)];
 Marshal.Copy(memory, managed, 0, managed.Length);
 return managed;
 }
 finally
 {
 if (memory != 0)
 {
 Free(memory);
 }
 }
 }
}

不能看到 malloc 就随意改用 Marshal.FreeHGlobal，也不能用托管分配器释放 DLL 内部堆上的内存。Windows 上不同 CRT/模块之间混用分配器尤其容易造成堆损坏。

8. 借用指针不要包装成永久对象

有些 SDK 返回指向内部缓存的指针，并注明“直到下一次调用有效”。此时应在有效窗口内立即复制，并序列化可能使缓存失效的调用。把它转换成 Span<T> 或 ReadOnlySpan<T> 不会延长原生内存寿命；Span 只描述一段内存，不拥有它。

如果指针与设备句柄同寿命，读取期间还必须确保句柄不会并发关闭。后续 SafeHandle 文章会处理这项约束。

总结

Marshalling 不是类型转换清单，而是跨边界的数据契约。编码、容量、实际长度、可写性、保留时间和释放函数必须同时明确。优先使用调用者缓冲区和显式长度；对于 SDK 分配的内存，始终由匹配的 SDK 函数释放。

下一篇进入加载阶段：调用约定、进程位数、导出符号和依赖库如何系统诊断。

参考资料

C# 原生互操作与设备 SDK（三）：StructLayout、内存布局与对齐

Mon, 20 Jul 2026 10:00:00 +0800

函数参数的基础类型都正确，结构体仍可能读出离谱数据。原因是 ABI 不只规定字段类型，还规定字段顺序、对齐、填充、整体大小，以及结构是按值传递还是通过指针传递。

本文从一份可计算的布局开始，说明 StructLayout、Pack、联合体和 blittable 类型的边界，并建立“原生侧与托管侧同时验证”的方法。

1. 字段之间可能存在填充

考虑以下 C 结构：

1
2
3
4
5
6
7
8
9


#include <stdint.h>

typedef struct device_status {
 uint32_t struct_size;
 int32_t state;
 double position_mm;
 uint8_t flags;
 uint8_t reserved[7];
} device_status;

在常见的自然对齐规则下，各字段偏移依次为 0、4、8、16、17，整体为 24 字节。这个结果不是靠字段大小相加猜出的，而是由目标 ABI 和编译选项决定。

对应的 C# 声明可以写为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential)]
public unsafe struct DeviceStatusNative
{
 public uint StructSize;
 public int State;
 public double PositionMillimeters;
 public byte Flags;
 public fixed byte Reserved[7];
}

LayoutKind.Sequential 保持字段声明顺序，并由运行时按平台规则放置字段。fixed byte Reserved[7] 是经典的定长缓冲写法；现代 .NET（C# 12+）也可用 [InlineArray] 自定义结构体表达定长内联数组，但用于互操作时仍要验证整体大小与字段偏移。不要因为看到“结构体大小不对”就立即添加 Pack = 1；只有原生头文件确实使用紧凑布局或 #pragma pack 时，托管侧才应使用相同设置。

2. 用大小与偏移断言验证布局

对布局敏感的结构，应在测试中固定预期：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;

if (Unsafe.SizeOf<DeviceStatusNative>() != 24)
{
 throw new InvalidOperationException("Unexpected DeviceStatusNative size");
}

if (Marshal.OffsetOf<DeviceStatusNative>(
 nameof(DeviceStatusNative.PositionMillimeters)).ToInt32() != 8)
{
 throw new InvalidOperationException("Unexpected position field offset");
}

原生侧也应使用同一构建链验证：

1
2
3
4
5


#include <stddef.h>

_Static_assert(sizeof(device_status) == 24, "device_status size mismatch");
_Static_assert(offsetof(device_status, position_mm) == 8,
 "position_mm offset mismatch");

如果 SDK 支持多个编译器和架构，不应把未经验证的 24 写成普遍真理，而应在每个受支持目标上执行这些检查。

3. Pack 是 ABI 约定，不是修复按钮

Pack 控制字段对齐的上限。下面的声明只有在原生侧明确采用 1 字节打包时才正确：

1
2
3
4
5
6


[StructLayout(LayoutKind.Sequential, Pack = 1)]
public struct PackedHeader
{
 public byte Version;
 public uint PayloadLength;
}

紧凑布局可能减少空间，也可能产生未对齐访问并改变调用 ABI。常见错误是厂商示例在一个头文件中 #pragma pack(push, 1) 后未被注意，或者托管侧随意设置 Pack = 1 来“对齐数值”。正确做法是追踪头文件的 push/pop 范围和项目编译选项。

4. 联合体使用 Explicit 布局

C 联合体让多个字段共享同一段内存：

1
2
3
4


typedef union device_value {
 int32_t int_value;
 double double_value;
} device_value;

C# 用 LayoutKind.Explicit 和相同的 FieldOffset 表达：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Explicit)]
public struct DeviceValueNative
{
 [FieldOffset(0)]
 public int IntValue;

 [FieldOffset(0)]
 public double DoubleValue;
}

读取哪个字段必须由联合体外部的类型标签决定。重叠字段只复刻存储，不会自动验证当前分支。

5. 固定数组与指针字段含义不同

这两个 C 字段不是一回事：

1
2


char serial_inline[32]; /* 32 字节就在结构体内部 */
const char* serial_ptr; /* 结构体里只有一个指针 */

内联数组需要固定缓冲区或相应的字段封送；指针字段则用 nint/指针表达，并另行定义指向内存的长度、编码和生命周期。把指针误写成 [MarshalAs(UnmanagedType.ByValArray)] 会直接改变结构布局。

6. blittable 让双方共享位表示

blittable 类型在托管和非托管表示之间具有相同的位级布局，通常可以固定后直接传递，避免逐字段转换。定宽整数、浮点数、指针以及只包含这类字段的顺序结构更容易做到 blittable。

以下内容会引入额外规则或转换：

bool 和 char 的表示依赖封送设置；
string、普通托管数组和对象引用需要转换或固定；
带自动布局的类型不能作为稳定 ABI；
关闭运行时封送后，受支持集合与默认规则会变化。

“C# unmanaged 泛型约束”和“启用运行时封送时的 blittable”概念接近但不完全等价，尤其要关注 bool 与 char。不要在文章或代码评审中把两者当同义词。

7. 按值和按引用必须照抄签名

1
2


int device_apply(device_status status); /* 按值复制 */
int device_query(device_status* out_status); /* 传指针 */

对应 C# 签名分别是值参数和 out/指针参数。结构较大并不意味着原生 API 一定按引用传递，也不能因为 C# 中 struct 是值类型，就给原生指针参数省略 ref 或 out。

对于带 struct_size 或 version 字段的 API，调用前要按厂商约定初始化：

1
2
3
4


var status = new DeviceStatusNative
{
 StructSize = (uint)Unsafe.SizeOf<DeviceStatusNative>()
};

这类字段常用于在新旧结构版本间协商可访问范围，不能留为默认零值。

8. 布局审查清单

使用了哪套头文件、编译器、架构和打包选项；
每个字段的原生大小、托管大小和偏移是否一致；
原生 bool、枚举、long 和 wchar_t 是否已显式确认；
固定数组、指针、柔性数组成员是否被正确区分；
结构是按值、指针还是指针的指针传递；
是否含版本/大小字段，谁负责初始化；
原生与托管测试是否同时断言 sizeof 和关键 offsetof。

总结

结构体互操作不是“加一个 StructLayout”就结束。字段顺序、自然对齐、显式打包、联合体、内联数组和传递方式必须共同匹配。最可靠的办法是在两侧写大小与偏移断言，让 ABI 漂移在测试阶段失败。

下一篇讨论结构之外最复杂的边界：字符串、数组、ref/out、指针与内存所有权。

参考资料

C# 原生互操作与设备 SDK（二）：C# 类型与 C ABI

Sun, 19 Jul 2026 10:00:00 +0800

互操作签名最危险的错误往往没有编译提示：C# 和 C 都存在名为 long、bool、char 的类型，但名称相同不代表大小、编码或 ABI 表示相同。一个字段宽度错了，后续参数就可能全部错位。

本文建立从原生头文件到 C# 声明的核对方法。目标不是背一张万能映射表，而是根据平台、编译器和头文件选择位宽明确的托管类型。

1. 优先从定宽类型开始

现代 C 接口如果使用 <stdint.h>，映射最直接：

C 类型	位宽	C# 类型
`int8_t` / `uint8_t`	8	`sbyte` / `byte`
`int16_t` / `uint16_t`	16	`short` / `ushort`
`int32_t` / `uint32_t`	32	`int` / `uint`
`int64_t` / `uint64_t`	64	`long` / `ulong`
`float`	通常 32	`float`
`double`	通常 64	`double`

对于设备寄存器、协议字段和文件格式，定宽整数同时表达了范围和二进制布局。若厂商公开接口仍使用 short、int、long，应查目标平台 ABI 和编译器文档，不能只按名称映射。

2. C/C++ long 不是 C# long

C# long 固定为 64 位。C/C++ long 至少 32 位，但常见 64 位 ABI 并不统一：64 位 Windows 仍是 32 位，而许多 64 位 Unix 系统是 64 位。

因此跨平台 C 接口应优先导出 int32_t、int64_t 等定宽类型。无法修改旧 SDK 时，Windows 的原生 long 通常映射为 C# int；目标是 Linux/macOS 时必须按该库实际构建 ABI 重新确认，不能共享一份未经验证的声明。.NET 6+ 为这种场景提供了 System.Runtime.InteropServices.CLong/CULong，按目标平台自动以正确宽度承载 C long/unsigned long。

3. 指针大小跟随进程架构

以下类型表达的是地址或与地址同宽的整数：

原生含义	C# 表达
`void*`、不透明句柄	`nint` / `IntPtr`，资源句柄优先用 `SafeHandle`
`const void*`	`nint` 或 `void*`，同时在封装层保持只读语义
`size_t`	`nuint` / `UIntPtr`
`ptrdiff_t`、`intptr_t`	`nint`
`uintptr_t`	`nuint`

nint 与 nuint 随进程位数变化。它们不是“任意大整数”，也不表示内存所有权；一个返回指针究竟是借用、转移还是句柄，仍要看 API 契约。

4. bool 必须先认清原生定义

常见布尔表示至少有三种：

C99 _Bool 或 C++ bool 通常占 1 字节；
Win32 BOOL 是 4 字节有符号整数，零为假、非零为真；
COM VARIANT_BOOL 是 2 字节，VARIANT_TRUE 为 -1。

.NET 运行时封送启用时，C# bool 默认按 4 字节 Win32 BOOL 处理。它不能直接代表原生 C++ bool。一种显式声明是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


using System.Runtime.InteropServices;

internal static class LegacyNative
{
 [DllImport(
 "device_sdk",
 EntryPoint = "device_is_ready",
 ExactSpelling = true)]
 [return: MarshalAs(UnmanagedType.I1)]
 internal static extern bool IsReady(nint handle);
}

对于新设计的 C ABI，更稳妥的做法是导出 uint8_t 或 int32_t，C# 也使用 byte 或 int，再在封装层转换为布尔值。这样签名不依赖默认封送规则：

1
2
3
4
5
6
7
8
9


using System.Runtime.InteropServices;

internal static partial class DeviceNative
{
 [LibraryImport("device_sdk", EntryPoint = "device_is_ready")]
 private static partial byte IsReadyRaw(nint handle);

 internal static bool IsReady(nint handle) => IsReadyRaw(handle) != 0;
}

5. char 首先是整数，编码另行约定

在 .NET 支持的常见目标平台上，C 的 char 占 1 个 8 位字节，但它是有符号还是无符号由实现决定；C# char 则是 16 位 UTF-16 代码单元。以下映射更可靠：

原生单字节数值或原始字节：byte / sbyte；
UTF-8 文本：byte*、字节缓冲区，或显式 UTF-8 字符串封送；
Windows UTF-16 wchar_t*：显式 UTF-16 字符串封送；
Unix wchar_t*：不能假设是 UTF-16，应按平台定义处理。

不要用 C# char 表达任意原生 char，也不要把“ANSI”理解成一种固定的跨平台编码。

6. 枚举的语义和底层宽度都要固定

C# 枚举默认以 int 为底层类型，但 C/C++ 枚举的 ABI 宽度可能受编译器、选项和枚举值范围影响。设备 SDK 若把枚举放入公开结构或函数参数，最好由 C 边界固定为 int32_t：

1
2
3
4
5


typedef int32_t device_state;

#define DEVICE_STATE_OFFLINE 0
#define DEVICE_STATE_READY 1
#define DEVICE_STATE_BUSY 2

1
2
3
4
5
6


public enum DeviceState : int
{
 Offline = 0,
 Ready = 1,
 Busy = 2
}

解析返回值时还要允许未知数字。原生库升级后可能新增状态，托管代码不应因为 Enum.IsDefined 为假就丢失原始值。

7. 句柄不是普通整数

厂商有时把句柄声明为 void*，有时是 uint32_t，还有时是结构体指针。三者不能凭名称互换：

指针型句柄用 nint 或 SafeHandle；
明确定宽的数字 ID 用对应整数；
Windows HANDLE 是指针大小，不应写成固定 32 位整数；
只有文档明确指定的无效值才可作为失败判断，例如空指针或 -1。

后续文章会用 SafeHandle 把“何时关闭、由谁关闭、调用期间能否关闭”纳入类型系统。

8. 用大小断言把猜测变成测试

对于公开结构，最好让原生侧和托管侧各自输出或断言大小、对齐和偏移。纯托管的基础检查可以写成：

1
2
3
4
5
6


using System.Runtime.CompilerServices;

Console.WriteLine($"Process pointer size: {IntPtr.Size}");
Console.WriteLine($"int: {Unsafe.SizeOf<int>()}");
Console.WriteLine($"long: {Unsafe.SizeOf<long>()}");
Console.WriteLine($"nint: {Unsafe.SizeOf<nint>()}");

这只能证明托管一侧，不能替代用同一套头文件和编译选项得到的原生 sizeof、alignof 与 offsetof。

总结

互操作类型映射的原则是按 ABI 含义和位宽选择类型，而不是按名称翻译。定宽整数、显式布尔表示、指针大小整数和清晰的句柄契约，可以消除大量“在一台机器上恰好能跑”的问题。

下一篇进入组合类型：结构体的字段顺序、填充、对齐、联合体和 blittable 边界。

参考资料

C# 原生互操作与设备 SDK（一）：P/Invoke、DllImport 与 LibraryImport

Sat, 18 Jul 2026 10:00:00 +0800

设备厂商常把 SDK 交付为 C/C++ 头文件、动态库和少量示例。C# 程序不能仅凭函数名调用这些二进制接口：双方还必须对参数布局、调用约定、字符串编码、资源所有权和错误模型达成完全一致的约定，这份约定就是应用二进制接口（Application Binary Interface，ABI）。

本文以 .NET 10 为环境，从一个最小 C 接口出发，说明 P/Invoke 的工作模型，以及 LibraryImport 和 DllImport 各自适合什么场景；运行时手动选择库文件的加载方式见本系列《C# 原生互操作与设备 SDK（五）：调用约定、位数与 DLL 加载诊断》。业务侧的硬件抽象方法见《设备软件架构与控制模型（二）：硬件抽象层与设备适配器》；本系列聚焦适配器下面的二进制边界。

1. P/Invoke 连接的是 ABI，不是源代码

假设厂商头文件给出以下 C API：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


#include <stdint.h>

#ifdef _WIN32
#define DEVICE_API __declspec(dllimport)
#else
#define DEVICE_API
#endif

typedef void* device_handle;

DEVICE_API int32_t device_open(int32_t index, device_handle* out_handle);
DEVICE_API int32_t device_get_position(device_handle handle, double* out_mm);
DEVICE_API void device_close(device_handle handle);

device_open 的托管声明不能只做到“看起来像”。必须逐项回答：

动态库的逻辑名称和导出符号是什么；
int32_t 是否映射为 32 位有符号整数；
device_handle 是整数、指针还是需要释放的资源；
device_handle* 是输出一个句柄，还是传入句柄数组；
返回值是 SDK 状态码，还是操作系统最后错误；
Windows 导出是否使用了非默认调用约定。

任何一项不匹配，都可能表现为错误值、找不到入口点，甚至栈或堆损坏。

2. .NET 7 及以上优先使用 LibraryImport

LibraryImportAttribute 让源生成器在编译期生成封送代码。声明方法必须是 static partial，包含它的类型也要是 partial：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


using System.Runtime.InteropServices;

internal static partial class DeviceNative
{
 private const string LibraryName = "device_sdk";

 [LibraryImport(LibraryName, EntryPoint = "device_open")]
 internal static partial int Open(int index, out nint handle);

 [LibraryImport(LibraryName, EntryPoint = "device_get_position")]
 internal static partial int GetPosition(nint handle, out double millimeters);

 [LibraryImport(LibraryName, EntryPoint = "device_close")]
 internal static partial void Close(nint handle);
}

库名不写扩展名时，运行时会按平台尝试相应变体，例如 Windows 的 .dll、Linux 的 .so 和 macOS 的 .dylib；Unix 平台还可能尝试 lib 前缀。绝对路径则按原样处理，不会追加这些变体。

LibraryImport 的优势不是让错误签名变安全，而是让许多封送步骤可在编译期生成，便于分析器检查，也更适合 Native AOT。使用它需要在工程文件中设置 <AllowUnsafeBlocks>true</AllowUnsafeBlocks>，否则构建会报 SYSLIB1062 错误。头文件仍然是签名、布局和调用约定的最终依据。

3. DllImport 仍有适用场景

DllImportAttribute 由运行时建立 P/Invoke 存根，在旧版 .NET、源生成器尚不支持的封送方式，或分析器明确建议保留时仍然合理：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


using System.Runtime.InteropServices;

internal static class LegacyNative
{
 [DllImport(
 "device_sdk",
 EntryPoint = "device_get_position",
 ExactSpelling = true)]
 internal static extern int GetPosition(nint handle, out double millimeters);
}

面向 .NET 7 及以上的新代码，可启用分析器并关注 SYSLIB1054：它会标出可用源生成器改写的 DllImport；迁移过程中若封送配置不被源生成器支持，SYSLIB1051/SYSLIB1052 会明确指出，此时保留 DllImport 即可。不要为了形式统一而忽略分析器给出的限制。

4. SDK 状态码和系统最后错误是两条通道

许多设备 SDK 用返回整数表示自身错误，例如 0 成功、负数失败。这与 Windows GetLastError 或 Unix errno 不是一回事：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


public static double ReadPosition(nint handle)
{
 int status = DeviceNative.GetPosition(handle, out double position);
 if (status != 0)
 {
 throw new DeviceSdkException("device_get_position", status);
 }

 return position;
}

public sealed class DeviceSdkException(string operation, int status)
 : Exception($"{operation} failed with SDK status {status}")
{
 public int Status { get; } = status;
}

只有头文件明确说明函数通过系统最后错误报告细节时，才设置 SetLastError = true，并在判断失败后立即读取缓存值：

1
2


[LibraryImport("device_sdk", EntryPoint = "device_wait", SetLastError = true)]
internal static partial int Wait(nint handle, uint timeoutMilliseconds);

调用方沿用本篇"0 成功、非 0 失败"的约定：

1
2
3
4
5
6


int result = DeviceNative.Wait(handle, 1_000);
if (result != 0)
{
 int nativeError = Marshal.GetLastPInvokeError();
 throw new InvalidOperationException($"device_wait failed: {nativeError}");
}

这里沿用示例约定，把非零返回值视为失败；GetLastPInvokeError 提供的是系统错误细节，不能替代 SDK 状态码。真实项目必须照抄厂商约定，不能根据 Win32 API 的习惯猜测。

5. 把原生声明限制在最薄的一层

推荐把代码分成三层：

DeviceNative 精确复刻头文件，不加入业务语义；
DeviceSession 管理句柄、错误转换、单位和线程限制；
上层 IDevice、IAxis 等能力接口服务于流程和测试。

这样升级 SDK 时，可以先用头文件和导出表审查第一层，再验证适配器，不必让 nint、错误码和厂商枚举扩散到界面与业务流程。

6. 首次接入按故障类型定位

异常或现象	常见原因	首要检查
`DllNotFoundException`	主库不存在或其依赖缺失	部署目录、依赖库、搜索路径
`EntryPointNotFoundException`	导出名、大小写或名称修饰不匹配	头文件和实际导出表
`BadImageFormatException`	进程与库架构不匹配，或文件并非有效动态库	x86/x64/Arm64 与文件格式
返回值偶发错误	参数类型、布局、编码或生命周期不匹配	原生签名逐字段对照
调用后崩溃	调用约定、缓冲区、回调或所有权错误	最小化签名并启用原生调试

先用只含一次调用的控制台程序建立最小闭环，再接入 UI、DI 和状态机。能够加载动态库只证明加载阶段成功，不证明 ABI 声明正确。

总结

P/Invoke 的核心是让托管声明与原生 ABI 精确一致。现代 .NET 项目优先考虑 LibraryImport，在不支持的场景保留 DllImport，需要运行时选择库或符号时再使用 NativeLibrary。无论入口方式如何变化，头文件、实际导出和资源契约始终是事实来源。

下一篇将逐一处理最容易写错的类型：整数、布尔、枚举、句柄和指针。

参考资料

设备软件架构与控制模型（八）：日志、诊断、审计与升级

Fri, 17 Jul 2026 10:00:00 +0800

设备交付以后，开发者面对的通常不是一个可调试的异常，而是一句话：“昨天夜班偶尔停了一次，重启后好了。”如果软件没有把命令、状态、设备观测和配置版本关联起来，现场只能靠猜；如果升级又缺少兼容检查和回退路径，一次修复还可能制造更大的停机。

本系列最后一篇把可维护性视为架构能力：日志、指标、追踪、报警和审计各自记录不同事实，诊断包把证据安全地带离现场，升级流程则让软件、Recipe、固件和数据结构能够协同演进。

1. 五类信息各司其职

类型	回答的问题	典型内容
日志（Log）	某个时刻发生了什么	命令接收、设备响应、异常与上下文
指标（Metric）	一段时间内系统怎样变化	周期时间、失败数、队列深度、温度趋势
追踪（Trace）	一次操作经过了哪些组件	UI 命令 → 流程 → 轴/相机 → 数据保存
报警（Alarm）	现在需要人采取什么行动	联锁未满足、位置未知、关键设备失联
审计（Audit）	谁在何时改变了受控对象	Recipe 发布、权限变更、维护复位、升级

日志不是审计日志，异常也不自动成为报警。把所有内容写进一个文本文件，会同时损害检索、保留策略和访问控制。

.NET 原生提供 ILogger、System.Diagnostics.Metrics 和 ActivitySource；OpenTelemetry 可以收集这些信号并导出到不同后端。是否部署集中式平台取决于现场网络和运维条件，但应用内部的事件结构与关联方式应尽早统一。半导体设备侧分级报警与可观测性落地的领域实践见《半导体设备软件（七）：日志、报警与可观测性》。

2. 从一次操作的关联 ID 开始

每个外部命令生成或接收一个 CorrelationId，长流程再分配 RunId 和步骤 ID。它们应贯穿日志、状态转换、设备调用和结果数据：

1
2
3
4
5
6


CorrelationId = 01J5Z...
RunId = RUN-20260817-0042
CommandId = CMD-018827
Step = Capture.TopCamera
Device = Camera.Top
Recipe = Product-A-Scan@17

关联 ID 用于串起证据，不代表鉴权或幂等。外部传入的值要校验长度和字符范围，日志中也不能无条件信任用户输入。

结构化日志保留字段语义，便于查询和聚合：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


using Microsoft.Extensions.Logging;

public static partial class EquipmentLog
{
 [LoggerMessage(
 EventId = 2101,
 Level = LogLevel.Information,
 Message = "Command {CommandId} started on {DeviceId} for run {RunId}")]
 public static partial void CommandStarted(
 ILogger logger,
 string commandId,
 string deviceId,
 string runId);

 [LoggerMessage(
 EventId = 2102,
 Level = LogLevel.Error,
 Message = "Command {CommandId} failed with fault {FaultKind} ({VendorCode})")]
 public static partial void CommandFailed(
 ILogger logger,
 string commandId,
 string faultKind,
 string? vendorCode,
 Exception exception);
}

LoggerMessage 源生成器可以在编译时生成高效日志代码并提供诊断。事件 ID 要稳定，消息模板字段名也应保持一致；否则仪表盘和现场脚本会随着文字修改失效。

3. 日志要能解释状态转换

有用的状态日志至少包含：

旧状态、新状态和触发事件；
命令、运行和设备标识；
守卫条件拒绝的明确原因；
设备返回的原始码和稳定故障分类；
Recipe、校准、软件和固件版本；
使用单调计时测得的持续时间。

不要在高频循环中无条件记录每次采样。可以把原始数据送入专门数据管线，把日志保留给状态变化和异常；趋势使用指标，特定故障前后的短窗口再通过环形缓冲保存。日志量控制不能简单丢弃所有 Information，应保证命令开始、状态转换和失败证据能够关联。

墙上时间用于跨系统对齐和审计，持续时间则应使用单调计时来源，例如 Stopwatch 或 TimeProvider.GetTimestamp()，避免系统时间校准造成负耗时。

4. 指标关注可行动的趋势

设备软件常见指标包括：

命令和流程的成功数、失败数与耗时分布；
当前命令队列深度、丢弃或等待次数；
设备断连次数和恢复耗时；
报警发生次数、持续时间和重复量；
数据采集速率、处理积压与磁盘剩余空间；
设备温度、压力等健康信号。

标签维度必须受控。把 RunId、序列号或完整错误消息作为指标标签，会产生近乎无限的时间序列；这些高基数字段应该进入日志或追踪。指标适合发现“最近一小时相机断连增加”，日志再回答具体是哪几次。

阈值不要凭经验写成通用常数。先采集基线，再结合设备规格、工艺窗口和响应流程定义报警条件，并记录适用版本。

5. 诊断包保存足够但不过量的证据

现场导出的诊断包可以包含：

软件、操作系统、驱动、固件和硬件标识；
当前状态快照与最近状态转换；
生效的 Recipe/配置/校准版本及摘要；
故障前后受限时间窗口内的日志与关键遥测；
活动报警、原始错误码和通信统计；
存储、内存和线程等运行健康信息；
清单文件、生成时间和文件摘要。

默认不要包含凭据、私钥、访问令牌、完整客户数据和无限量原始图像。导出前执行脱敏，诊断包设置访问权限和保留期限；跨组织传输时按双方的数据规则处理。生成诊断包本身也要有容量上限，避免磁盘已满时再次写入大量数据。

6. 审计记录受控变更

以下动作通常值得审计：

登录、角色和权限变更；
Recipe 的创建、审核、发布、激活和停用；
校准与设备常数更新；
报警禁用、阈值和优先级修改；
维护模式、强制输出和故障复位；
软件、驱动和固件升级。

审计事件记录操作者身份、动作、对象、旧值/新值或版本、时间、理由和结果。仅写“修改成功”无法还原变化。审计存储应限制修改和删除，并将时间同步异常本身纳入监控；具体保存期限由行业、合同和组织制度决定，不能从通用架构直接给出一个年限。

7. 升级是一项受控设备变更

一次升级可能同时改变应用、数据库、Recipe Schema、厂商 SDK 和控制器固件。升级包至少应明确：

来源、版本、摘要或数字签名；
支持的操作系统、架构、驱动和固件组合；
配置与数据结构的迁移路径；
升级前检查、预计停机和空间需求；
安装后健康检查与验收步骤；
可回退组件、回退前提和不可逆步骤。

“复制新文件覆盖旧目录”会让旧 DLL、配置和新程序混杂。更稳健的方式是部署到独立版本目录，停止控制入口，备份受控数据，执行迁移，再切换启动目标。切换是否能做到原子性取决于操作系统和部署机制，不能只凭重命名目录就假定整个升级事务原子。

数据库或固件迁移可能不可逆。此时所谓回退不能只恢复旧可执行文件，还必须有向前修复、数据备份恢复或整机维护方案。升级前应阻止新任务，等待当前任务到安全检查点，并记录设备实际状态。

8. 用健康检查决定是否接管设备

进程启动成功不等于升级成功。自动验证至少包括：

读取应用版本和部署清单；
加载并验证配置；
检查数据结构版本；
建立设备会话并核对身份/固件；
验证关键联锁和只读状态；
在允许条件下执行受控自检；
确认日志、数据和磁盘路径可写；
最后才允许进入 Ready。

验证失败时，系统应保持不可生产状态并输出可诊断原因，而不是为了“服务已启动”强行忽略。对无人值守设备，还要验证 Windows Service、看门狗或外部监管器的重启策略不会形成无限崩溃循环。

9. 可维护性从设计阶段开始

日志字段、故障分类、配置摘要、命令 ID 和版本清单都依赖前几篇建立的边界。若 UI 直接调用 SDK、流程没有唯一 RunId、Recipe 可以运行中被修改，再先进的日志平台也只能收集互相矛盾的信息。

可以用一次“离线故障演练”检验体系：不给开发者远程调试权限，只提供诊断包、操作时间和现象描述，看能否还原使用的版本、命令路径、设备状态、首个根因和恢复动作。无法回答的问题，就是下一轮需要补充的可观测性需求。

总结

日志记录离散事实，指标显示趋势，追踪串起一次操作，报警要求人采取行动，审计保护受控变更。诊断包把这些证据以安全、有限的方式带离现场；升级则是一条包含兼容检查、迁移、验证和回退边界的设备变更流程。

至此，系列从职责边界出发，依次建立 HAL、生命周期、状态机与队列、Recipe、故障恢复、测试和可维护性闭环。它们共同指向同一个原则：上位机架构的核心不是界面有多少功能，而是每个命令、状态、参数、故障和资源都有清晰且可验证的所有者。

参考资料

设备软件架构与控制模型（七）：模拟器、集成测试与 HIL

Thu, 16 Jul 2026 10:00:00 +0800

设备软件测试最现实的困难是硬件稀缺：开发机旁没有整机，实验设备不能随时制造故障，运动和加热又会让测试变慢甚至带来风险。结果往往是单元测试只覆盖工具类，真正重要的状态机、恢复流程和设备协同只能等到现场联调。

解决办法不是用 Mock 把所有 SDK 调用设成成功，而是建立逐级增加真实性的测试体系：纯逻辑模型验证规则，行为模拟器提供时间和故障，协议回放保护边界，最后用 Hardware-in-the-Loop（HIL）验证真实接口、时序和接线。

1. 按风险建立测试梯度

设备软件可以采用以下测试层次：

层次	主要对象	速度与环境	擅长发现的问题
纯逻辑测试	转换函数、校验器、计算模型	毫秒级，无 I/O	状态规则、边界值、算法错误
组件测试	流程执行器 + Fake/Simulator	快，可并行	超时、取消、恢复和资源竞争
协议/契约测试	适配器 + 模拟服务或回放	中等	报文解析、兼容性、错误映射
软件集成测试	完整进程 + 虚拟设备	中等	DI、配置、持久化、进程生命周期
HIL	上位机 + 真实控制器/仿真负载	慢，受实验台约束	驱动、接线、时序和真实固件差异
整机验收	完整设备与受控工况	最慢	端到端功能、性能和安全验证

层次越高越接近现场，但覆盖组合越困难。HIL 不应替代低层测试；它应该聚焦只有真实接口才能发现的风险，而不是重复一万组 Recipe 边界值。

2. Fake、Stub、Mock 和 Simulator 各有用途

这些测试替身解决的问题不同：

Stub 为特定输入返回预设结果，适合简单分支；
Mock 重点验证交互是否发生，适合边界协作；
Fake 是可工作的轻量实现，例如内存仓储；
Simulator 模拟状态随命令和时间变化，并能够注入设备故障。

设备流程通常更需要 Simulator。一个始终立即成功的 IAxis 无法发现“移动尚未完成就开始采集”、取消后轴继续移动、回零前误用绝对坐标等问题。

下面的最小模拟轴保留了位置、运动耗时和故障注入：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94


public sealed class SimulatedAxis(TimeProvider timeProvider) : IAxis
{
 private readonly object _sync = new();
 private Millimeters _position = new(0);
 private CancellationTokenSource? _activeMove;

 public bool FailNextMove { get; set; }

 public ValueTask<AxisSnapshot> ReadAsync(
 CancellationToken cancellationToken)
 {
 cancellationToken.ThrowIfCancellationRequested();
 lock (_sync)
 {
 return ValueTask.FromResult(new AxisSnapshot(
 _position,
 IsMoving: _activeMove is not null,
 IsServoOn: true,
 PositiveLimit: false,
 NegativeLimit: false,
 FaultCode: null));
 }
 }

 public async ValueTask MoveAbsoluteAsync(
 Millimeters target,
 MillimetersPerSecond speed,
 CancellationToken cancellationToken)
 {
 if (speed.Value <= 0)
 {
 throw new ArgumentOutOfRangeException(nameof(speed));
 }

 if (FailNextMove)
 {
 FailNextMove = false;
 throw new DeviceFaultException("DriveFault", "SIM-001");
 }

 var moveCancellation =
 CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);

 lock (_sync)
 {
 if (_activeMove is not null)
 {
 moveCancellation.Dispose();
 throw new InvalidOperationException("The axis is already moving.");
 }

 _activeMove = moveCancellation;
 }

 try
 {
 double seconds = Math.Abs(target.Value - _position.Value) /
 speed.Value;
 await Task.Delay(
 TimeSpan.FromSeconds(seconds),
 timeProvider,
 moveCancellation.Token);
 lock (_sync)
 {
 _position = target;
 }
 }
 finally
 {
 lock (_sync)
 {
 if (ReferenceEquals(_activeMove, moveCancellation))
 {
 _activeMove = null;
 }

 moveCancellation.Dispose();
 }
 }
 }

 public ValueTask StopAsync(
 AxisStopMode mode,
 CancellationToken cancellationToken)
 {
 cancellationToken.ThrowIfCancellationRequested();
 lock (_sync)
 {
 _activeMove?.Cancel();
 }

 return ValueTask.CompletedTask;
 }
}

这是教学版：它会阻止并发移动，并把停止简化为取消等待、保持起点位置，并没有模拟加速度、中间位置和停止距离。模拟器不是越逼真越好，而是要忠实实现测试关注的契约；未实现的行为应明确说明，避免团队把它误当数字孪生。

3. 把时间变成可控制依赖

真实等待会让超时和重试测试又慢又不稳定。.NET 8+ 内置 TimeProvider，Microsoft.Extensions.TimeProvider.Testing 包提供 FakeTimeProvider，可以在测试中推进虚拟时间。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


using Microsoft.Extensions.Time.Testing;

var clock = new FakeTimeProvider(
 new DateTimeOffset(2026, 8, 15, 0, 0, 0, TimeSpan.Zero));
var axis = new SimulatedAxis(clock);

ValueTask moving = axis.MoveAbsoluteAsync(
 new Millimeters(100),
 new MillimetersPerSecond(20),
 CancellationToken.None);

clock.Advance(TimeSpan.FromSeconds(5));
await moving;

AxisSnapshot snapshot = await axis.ReadAsync(CancellationToken.None);
if (snapshot.ActualPosition != new Millimeters(100))
{
 throw new InvalidOperationException("Simulation result is incorrect.");
}

包名是 Microsoft.Extensions.TimeProvider.Testing，命名空间是 Microsoft.Extensions.Time.Testing，两者不要混淆。虚拟时间只能控制使用同一个 TimeProvider 的代码；若业务中仍直接调用 DateTime.Now、Task.Delay 或 System.Threading.Timer，测试就会重新依赖真实时间。

4. 用故障脚本描述场景

仅有 FailNextMove 很快不够。可以把故障注入描述成脚本：

1
2
3
4
5
6
7
8


Given 轴已回零，当前位置 10 mm
When 收到移动到 100 mm 的命令
And 运动 40% 时通信中断
Then 上位机进入 PositionUnknown
And 不再接受后续绝对移动
And 保存目标、最后观测位置和控制器错误码
When 通信恢复并重新读取编码器
Then 根据回读和恢复策略决定重新回零或人工确认

脚本应覆盖命令前失败、执行中失败、执行完成但确认丢失这三个关键时间窗口。对于并发场景，还要控制事件顺序、重复和迟到，而不是依赖线程调度“碰巧复现”。

5. 契约测试保护真实与模拟实现

同一个 IAxis 可以有厂商适配器和模拟器，但实现同一接口不等于语义一致。为接口建立一组契约测试，分别运行在每个实现上：

未回零时绝对移动是否被拒绝；
超出软限位时是否在动作前失败；
返回完成时是否满足约定的到位条件；
取消后动作和状态如何变化；
重复停止和关闭是否幂等；
原始错误码是否保留。

真实硬件无法在普通 CI 中运行所有契约时，可以给测试打环境标签，在专用实验台定时执行；模拟器仍需在每次提交中执行相同的通用部分。

6. 记录回放用于协议和现场问题

记录回放（Record/Replay）能够把一次真实交互转成可重复输入。记录内容可包括时间间隔、请求字节、响应字节、连接事件和关键环境版本。回放有三种常见模式：

严格回放：请求必须与记录完全一致，适合协议回归；
状态回放：根据当前模拟状态生成响应，适合流程测试；
扰动回放：在原记录中插入延迟、丢包、断连或坏帧，适合鲁棒性验证。

回放数据要脱敏，特别是序列号、客户 Recipe、生产标识和访问凭据。还要记录协议/固件版本，否则几年后无法判断样本代表哪个实现。

7. HIL 验证软件无法伪造的部分

HIL 将真实控制器、I/O 模块或驱动器接到仿真负载上，让上位机面对真实通信栈和固件（半导体设备的领域化实践见《半导体设备软件（十）：仿真、单元测试与 Hardware-in-the-Loop》）。它适合验证：

驱动安装、位数和 SDK 依赖；
电平、接线、信号极性和抖动；
控制器扫描周期、缓冲和响应时序；
断电、复位、拔线和看门狗行为；
多设备同时运行时的资源与时序边界。

HIL 台必须有物理保护、运动范围和自动复位方案。测试脚本不能因为运行在“实验环境”就绕过急停和联锁。破坏性测试应使用专用工装，并由风险评估决定是否允许自动执行。

8. 测试断言最终事实

“调用过 MoveAbsoluteAsync 一次”只证明编排器发出了意图。更有价值的断言包括：

设备最终状态和实际位置；
Recipe 与校准快照是否绑定到运行记录；
失败后是否拒绝危险的后续命令；
补偿动作是否在正确前提下执行；
报警、诊断证据和审计事件是否完整；
重启后是否从可信检查点恢复。

交互次数仍有用，但它是验证边界协议的手段，不应代替业务结果。

总结

设备软件需要从纯逻辑、行为模拟、协议契约、完整软件、HIL 到整机验收的测试梯度。模拟器应表现时间、状态和失败，TimeProvider 让时间相关测试可控，契约测试防止真实与仿真实现语义漂移，HIL 则专注真实接口和时序风险。

下一篇将完成系列：建立日志、指标、追踪、审计和诊断包，并把软件升级设计成可验证、可回退的设备变更流程。

参考资料

设备软件架构与控制模型（六）：故障处理、报警与安全恢复

Wed, 15 Jul 2026 10:00:00 +0800

设备现场最常见的“恢复方案”是弹窗、重试和重启：捕获异常后提示用户，用户点击确定，程序再发一次命令；仍然失败就重启软件。这种做法偶尔能恢复通信，却无法证明机械位置、物料状态和安全条件已经恢复，反而可能覆盖最有价值的故障证据。

可靠的故障处理不是一个 catch 代码块，而是一条从检测、隔离、报警到恢复验证的闭环。本文讨论通用方法，不替代具体设备的风险评估、安全标准和操作规程；半导体设备异常恢复的领域实践见《半导体设备软件（六）：实时性、并发与异常恢复》。

1. 事件、提示、报警和故障不要混用

系统中出现的每条消息并不都需要操作员处理：

事件（Event）：值得记录的事实，例如连接建立、Recipe 激活、任务完成；
提示（Notification）：需要了解但通常不要求立即行动的信息，例如维护周期临近；
报警（Alarm）：需要人在规定时间内采取行动的异常条件；
故障（Fault）：设备或软件无法满足预期能力的状态，可能触发报警和联锁；
日志（Log）：供诊断使用的技术记录，数量通常远多于报警。

一次相机断连是故障；系统可以产生一条报警提醒操作员，并写入多条重连和驱动日志。若把每次重试都弹成报警，真正需要行动的信息会被报警洪泛淹没。

ISA-18.2 面向过程工业的报警管理，但其中的生命周期思想同样值得设备软件借鉴：报警需要经过识别、合理化、详细设计、运行监测和变更管理等阶段，而不是开发者看到异常就随手加一个红色弹窗。离散设备采用时仍应结合自身行业和风险边界。

2. 故障模型同时保存判断和证据

一条可操作的故障记录应包含稳定分类、来源、严重级别、时间和原始证据：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


public enum FaultSeverity
{
 Warning,
 Recoverable,
 Critical
}

public sealed record EquipmentFault(
 string FaultId,
 string Source,
 string Kind,
 FaultSeverity Severity,
 string OperatorMessage,
 string? VendorCode,
 DateTimeOffset OccurredAt,
 string CorrelationId,
 bool RequiresAcknowledgement,
 bool IsLatched);

注意"严重级别"和"可恢复性"其实是两个维度：Warning/Critical 描述影响程度，Recoverable 描述恢复方式。示例为保持简单混用在一个枚举里；生产代码中若两个维度都需要独立决策，应拆成两个属性分别建模。

Kind 应是软件长期维护的稳定分类，例如 CommunicationLost、InterlockOpen、PositionUnknown；VendorCode 保留厂商证据。面向操作员的消息说明“发生什么、影响什么、建议做什么”，技术堆栈和原始报文进入诊断记录，而不是全部塞进弹窗。

严重级别不应只根据异常类型决定。同一个读取超时，在非关键温度趋势采样中可能只是降级，在等待夹具到位的步骤中却可能使物料状态未知。

3. 先判断物理副作用，再决定重试

网络和 SDK 调用失败时，最重要的问题不是“能否再试一次”，而是第一次操作有没有发生：

结果	例子	处理重点
明确未执行	本地参数校验失败	修正输入后可以重新提交
明确已完成	控制器返回完成并通过回读确认	不应重复执行
执行中断	移动过程中驱动报警	先停止并确认位置
结果未知	命令发出后连接断开	先查询或进入人工确认，不能盲重试

读取状态通常比改变物理世界的命令更容易安全重试，但也要考虑设备和总线负载。写命令只有在协议提供幂等键、序列号或可查询结果时，才能可靠地去重。没有这些能力时，自动重试可能造成重复运动、重复出料或覆盖数据。

4. 恢复是一台独立状态机

不要在各层 catch 中零散地写复位命令。恢复流程本身应建模并保留检查点：

1
2
3
4
5
6
7


Detect
 → Contain（阻止新命令、隔离故障设备）
 → ReachSafeState（请求受控停止或依赖安全链）
 → Diagnose（采集状态、错误码和上下文）
 → Correct（重连、复位、重新初始化或人工维修）
 → Verify（回读、联锁、回零和试运行检查）
 → Resume / Abort

“复位命令返回成功”只是 Correct 阶段的一步。只有 Verify 重新证明必要条件，状态机才可以从 Faulted 回到 Ready。确认报警也只是说明操作员已经看见，不应自动清除故障条件。

恢复步骤需要声明：

是否自动执行，还是必须授权人员确认；
可执行的设备状态和安全前提；
超时及失败后的终止状态；
是否幂等，重复进入会不会造成额外动作；
成功判据采用什么独立回读；
是否需要重新回零、重新校准或报废当前物料。

5. 安全动作必须有独立保证

应用层的异常处理无法替代安全功能。GC 暂停、线程阻塞、操作系统故障和进程崩溃都可能让上位机不能及时执行。涉及人身或设备危险的联锁、急停和能量切断，需要按风险评估放在具备相应安全完整性的硬件、安全 PLC、驱动器或回路中。

上位机的责任是：不绕过安全条件、准确显示安全链状态、在触发后停止业务流程、保存上下文，并引导受控复位。软件中的 try/finally 可以释放资源，却不能证明继电器已经断开或气缸已经回到安全位置。

6. 降级比“全好或全坏”更实用

并非所有故障都要求整机停机。诊断相机不可用时，可以禁用高级诊断但保留手动维护；非关键温度传感器失效时，可以降低速度并禁止自动生产；关键联锁失效则必须阻止危险动作。

降级模式必须显式定义：

哪些功能仍可使用；
性能或质量承诺如何变化；
操作员需要看到什么持续提示；
多久后必须升级为停机；
恢复到正常模式需要哪些验证。

不要在异常处理中临时“忽略一次”，这会形成未记录的隐式降级。

7. 抑制报警洪泛，但不抹掉事实

断开一根总线可能让十个从设备同时报错。如果每个轮询周期都创建新报警，操作员无法找到根因。可以采用：

相同来源和故障键合并为一条活动报警；
记录首次发生、最近发生和重复次数；
基于因果关系抑制下游派生报警；
对抖动信号设置经过工程确认的延时和死区；
恢复后保留历史，而不是删除记录；
定期统计报警频率、持续时间和洪泛区间。

抑制只改变呈现和通知，不应删除底层事件。关键报警的停用、阈值和优先级变更也应纳入审计和测试。

8. 用故障注入验证恢复路径

正常路径跑一百次，不能证明恢复路径可靠。模拟器和硬件在环（Hardware-in-the-Loop，HIL）环境应能够注入：

命令发送前、发送后和完成确认前断连；
状态长时间不变化；
迟到、重复或乱序响应；
传感器抖动和不合理组合；
磁盘写满、日志后端不可用；
进程在检查点前后终止。

验证的不只是“抛出了预期异常”，还包括设备最终状态、是否继续接受命令、证据是否完整、报警是否可操作，以及重启后是否拒绝从未知状态继续。

总结

可靠故障处理先区分事件、报警和故障，再根据物理副作用判断能否重试。恢复是一条带安全前提、检查点和成功判据的状态机；确认消息、清除报警和修复故障是不同动作。安全链负责最后保障，上位机负责不绕过它并保存足够证据。

下一篇将搭建从纯软件模拟器到 HIL 的测试梯度，说明如何模拟时间、失败和设备动态，而不是只让 Mock 永远返回成功。

参考资料

设备软件架构与控制模型（五）：Recipe 与配置版本管理

Tue, 14 Jul 2026 10:00:00 +0800

设备软件中的“参数”看起来都像键值对，实际上承担着完全不同的责任。产品 Recipe、设备常数、校准结果、通信地址和用户偏好如果共用一份可随时编辑的 JSON，不仅难以追溯，还可能让一次运行前后使用了两套参数。

本文建立一套通用配置模型：先区分参数归属，再为 Recipe 设计验证、审批、激活和执行快照。重点不是选择 JSON、数据库还是某个配置中心，而是保证系统能够回答“当时究竟使用了什么”。半导体设备 Recipe 管理的领域实践见《半导体设备软件（三）：Recipe 配方管理与版本控制》。

1. 先按责任区分参数

常见参数至少分为以下几类：

类型	示例	谁负责变更	典型生命周期
Recipe	曝光时间、扫描速度、检测阈值	工艺或授权用户	随产品/工艺版本发布
设备配置	轴数量、相机型号、通信端点	设备工程师	安装或硬件变更时修改
设备常数	软限位、脉冲当量、机构偏置	调试与维护人员	受控维护后更新
校准结果	标定矩阵、零点、温度补偿系数	校准流程	与设备、时间和方法绑定
运行策略	超时、重试上限、数据保留策略	软件/运维人员	随软件或现场策略演进
用户偏好	窗口布局、曲线颜色	当前用户	可自由修改，不影响工艺事实
凭据与密钥	令牌、证书私钥	安全设施	不应作为普通配置明文保存

这种分类决定权限、验证和审计强度。校准数据不是普通 Recipe，操作员也不应通过“导入配方”覆盖运动软限位。凭据应进入操作系统或专用密钥存储，而不是为了方便一起导出。

2. Recipe 是受控版本，不是可变表单

编辑界面中的对象只是草稿。发布后的 Recipe 应成为不可变版本，至少包含：

稳定的 Recipe 标识；
业务版本和数据结构版本；
创建者、创建时间和变更说明；
适用的设备能力或软件版本范围；
完整参数内容；
对保存字节或规范化内容计算的摘要；
审核、发布和停用状态。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public sealed record CaptureRecipe(
 string RecipeId,
 int Revision,
 int SchemaVersion,
 TimeSpan Exposure,
 double ScanSpeedMillimetersPerSecond,
 int FrameCount,
 string CreatedBy,
 DateTimeOffset CreatedAt);

public sealed record RecipeSnapshot(
 CaptureRecipe Recipe,
 string Sha256,
 DateTimeOffset ActivatedAt);

C# record 和 init 属性有助于减少意外修改，但它们不会自动让内部集合深度不可变。若 Recipe 含列表或字典，应复制为只读/不可变结构，避免外部仍持有可变引用。

摘要也不能直接理解为数字签名。SHA-256 可以发现内容是否变化，却不能证明修改者身份；需要防篡改或跨组织验真时，还要使用带受控密钥的签名机制。若对 JSON 计算摘要，应对实际保存的字节求值，或先定义稳定的规范化格式，不能假设任意序列化结果的属性顺序和空白永远一致。

3. 验证分为四层

只检查数据类型远远不够。Recipe 验证可以分层执行：

结构验证：必填字段、类型、数据结构版本；
范围验证：曝光时间、速度和数量是否在单参数范围内；
关联验证：速度、采样率和缓存容量组合后是否可行；
设备验证：目标设备是否具备所需能力，当前校准是否有效。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


public static class CaptureRecipeValidator
{
 public static IReadOnlyList<string> Validate(CaptureRecipe recipe)
 {
 List<string> errors = [];

 if (recipe.Exposure <= TimeSpan.Zero ||
 recipe.Exposure > TimeSpan.FromSeconds(10))
 {
 errors.Add("Exposure must be within (0, 10s].");
 }

 if (recipe.ScanSpeedMillimetersPerSecond is <= 0 or > 500)
 {
 errors.Add("Scan speed must be within (0, 500] mm/s.");
 }

 if (recipe.FrameCount is < 1 or > 100_000)
 {
 errors.Add("Frame count must be within [1, 100000].");
 }

 return errors;
 }
}

示例中的上限只是演示，不能复制成真实设备指标。实际范围应来自机械、电气、控制器和工艺共同确认的能力模型，并与单位一起保存。

对于进程启动配置，.NET Options 模式支持强类型绑定和 ValidateOnStart；但运行中导入 Recipe 时仍应经过领域验证服务。配置框架验证通过，只说明对象满足应用配置规则，不代表它适用于当前硬件和工艺。

4. 激活采用“准备—切换”而不是边跑边改

Recipe 生效可以设计为两个阶段：

4.1 准备阶段

读取指定版本，并验证摘要；
执行结构、范围、关联和设备能力校验；
检查当前整机状态是否允许切换；
将参数转换为各设备可应用的设置；
生成完整、不可变的执行快照。

4.2 切换阶段

阻止新任务进入；
在安全状态下应用参数；
读取设备回读值或确认结果；
原子地替换“当前 Recipe 快照”的引用；
记录激活者、版本、摘要和结果。

这里的“原子替换”只针对上位机内存中的当前快照，不代表多个物理设备能像数据库事务一样同时提交。若相机参数应用成功而运动控制器失败，应进入受控故障状态，记录每个设备的实际结果，再由恢复策略决定重新应用、回到已知配置或要求人工处置。

5. 每次运行固定一份快照

流程启动时读取一次当前 Recipe，并把其版本和摘要写入任务上下文。后续每个步骤都使用同一份快照，即使管理员在运行期间发布了新版本，正在执行的任务也不应悄悄切换。

1
2
3
4
5
6
7
8


RunId: RUN-20260811-0042
RecipeId: Product-A-Scan
Revision: 17
SchemaVersion: 3
Sha256: 8F...C2
EquipmentConfigVersion: EQ-2026.08.3
CalibrationSet: CAL-CAMERA-20260801
SoftwareVersion: 2.6.0

这组信息把结果数据与其产生条件绑定起来。仅记录文件名不够，因为同名文件可能已经被覆盖；只保存“当前版本”也无法解释历史任务。

6. 迁移、兼容与回滚要分开

数据结构升级时，不要在反序列化失败后默默填默认值。应根据 SchemaVersion 选择显式迁移器，保留原始版本，并验证迁移结果。迁移后的 Recipe 是新版本还是运行时视图，要在审计规则中说清楚。

软件兼容性和工艺版本回滚也是两个问题：

新软件能否读取旧 Recipe，由兼容策略和迁移器决定；
旧软件能否读取新 Recipe，不能默认成立；
回滚 Recipe 只能恢复参数版本，不能撤销已经加工的工件或已经改变的设备状态；
校准或硬件变化后，旧 Recipe 即使格式兼容，也可能不再适用。

生产系统应保留最后一个经过验证的版本，但切换失败时不要盲目“自动回滚并继续生产”。先确认设备回读和物理状态，再决定能否恢复。

7. 权限与审计围绕动作设计

权限不应只有“能否打开配置页面”。至少区分查看、编辑草稿、验证、审核、发布、激活和停用。高风险参数可以要求双人复核或维护模式，但具体控制强度应来自风险评估。

审计记录需要回答：谁在何时基于哪个旧版本做了什么变更，验证结果如何，哪个设备在何时激活，以及激活是否成功。审计日志本身也要限制修改和删除权限，且不能把密钥或完整敏感配置写进去。

总结

Recipe、设备配置、校准和用户偏好虽然都表现为参数，却不能共享同一套生命周期。发布后的 Recipe 应不可变、可验证、可追溯；激活前完成准备，运行时固定快照；多设备应用失败时承认物理世界不具备通用事务回滚。

下一篇将把视角转向失败：如何区分事件、报警和故障，如何设计不会无限重试的恢复流程，以及为什么“清除报警”不等于问题已经消失。

参考资料

设备软件架构与控制模型（四）：状态机、命令队列与流程编排

Mon, 13 Jul 2026 10:00:00 +0800

设备接入增多以后，最危险的复杂度往往不是算法，而是“谁在什么时候可以做什么”。UI 可以点启动，远程接口也能启动；后台监控发现异常要停止；流程内部同时控制相机、光源和运动轴。若这些入口直接调用硬件，锁只能减少数据竞争，却不能保证业务顺序正确。

本篇把控制模型拆成三个互补部分：状态机决定命令是否合法，命令队列确定写操作的顺序，流程编排负责跨设备的长事务。三者职责不同，不能用一个不断增长的 switch 或一把全局锁替代。半导体设备状态机与任务调度的领域实践见《半导体设备软件（二）：设备状态机与任务调度》。

1. 状态机保护业务不变量

状态机由四个基本元素组成：

状态：系统对当前阶段的稳定判断；
事件：已经发生的输入或事实；
守卫条件：允许转换必须满足的条件；
动作：转换过程中产生的副作用。

例如设备只有在 Ready 且门联锁、气压和回零状态均满足时才能进入 Running。把规则集中到状态转换中，比在每个按钮里各写一遍判断可靠得多。

纯转换函数便于穷举测试：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


public enum MachineState
{
 Offline,
 Ready,
 Running,
 Paused,
 Faulted
}

public abstract record MachineEvent;
public sealed record StartRequested(bool InterlocksSatisfied) : MachineEvent;
public sealed record PauseRequested : MachineEvent;
public sealed record ResumeRequested : MachineEvent;
public sealed record FaultDetected(string Code) : MachineEvent;
public sealed record ResetCompleted : MachineEvent;

public static class MachineTransitions
{
 public static MachineState Apply(MachineState state, MachineEvent message) =>
 (state, message) switch
 {
 (MachineState.Ready, StartRequested { InterlocksSatisfied: true })
 => MachineState.Running,
 (MachineState.Running, PauseRequested)
 => MachineState.Paused,
 (MachineState.Paused, ResumeRequested)
 => MachineState.Running,
 (_, FaultDetected)
 => MachineState.Faulted,
 (MachineState.Faulted, ResetCompleted)
 => MachineState.Ready,
 _ => throw new InvalidOperationException(
 $"Event {message.GetType().Name} is invalid in {state}.")
 };
}

这个函数只决定目标状态，真正的硬件动作由命令处理器执行。若先把状态改成 Running，随后启动硬件失败，就会制造假状态。更稳健的顺序是：验证守卫条件，执行必要动作，确认结果，再提交状态转换；执行期间可以使用 Starting 之类的过渡状态防止重复命令。

2. 不要造“超级状态机”

整机、工位和单个设备的状态变化速度与责任不同。把所有组合塞进一个枚举，会迅速出现 RunningButCameraRecoveringAndDoorOpen 之类不可维护的状态。

可以采用分层模型：

1
2
3
4


整机状态：Offline / Ready / Running / Paused / Faulted
 ├─ 工位 A：Idle / Processing / Completed
 ├─ 工位 B：Idle / Processing / Completed
 └─ 设备健康：Camera Healthy，Axis Faulted，PLC Healthy

上层状态聚合下层事实，但不要简单复制全部状态。整机 Ready 的含义应由明确规则计算，例如所有必需设备健康、流程未占用、联锁满足且 Recipe 已验证。

3. 命令队列建立单一写入顺序

状态机回答“能不能做”，队列回答“先做哪个”。对拥有唯一写控制权的设备控制器，可以使用 System.Threading.Channels 建立有界异步队列：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


using System.Threading.Channels;

public interface IMachineCommand
{
 ValueTask ExecuteAsync(CancellationToken cancellationToken);
}

public interface ICommandFailureHandler
{
 ValueTask HandleAsync(
 IMachineCommand command,
 Exception exception,
 CancellationToken cancellationToken);
}

public sealed class CommandPump(ICommandFailureHandler failureHandler)
{
 private readonly Channel<IMachineCommand> _channel =
 Channel.CreateBounded<IMachineCommand>(new BoundedChannelOptions(100)
 {
 SingleReader = true,
 SingleWriter = false,
 FullMode = BoundedChannelFullMode.Wait
 });

 public ValueTask EnqueueAsync(
 IMachineCommand command,
 CancellationToken cancellationToken) =>
 _channel.Writer.WriteAsync(command, cancellationToken);

 public async Task RunAsync(CancellationToken cancellationToken)
 {
 await foreach (IMachineCommand command in
 _channel.Reader.ReadAllAsync(cancellationToken))
 {
 try
 {
 await command.ExecuteAsync(cancellationToken);
 }
 catch (OperationCanceledException)
 when (cancellationToken.IsCancellationRequested)
 {
 throw;
 }
 catch (Exception exception)
 {
 await failureHandler.HandleAsync(
 command,
 exception,
 cancellationToken);
 }
 }
 }

 public void Complete() => _channel.Writer.TryComplete();
}

有界队列使过载可见。FullMode = Wait 会对生产者施加背压，但这只适合不能静默丢弃的控制命令；高频遥测可以采用另一条管线和不同丢弃策略。队列容量不是越大越好，过大的命令积压会让用户看到“停止已点击”却迟迟不执行。

每条命令还应携带命令 ID、提交者、截止时间和权限上下文，并通过独立的完成源返回结果。入队成功只表示已被接受排队，不表示设备动作完成。

示例把单条命令异常交给 ICommandFailureHandler，由它记录失败、完成调用方结果并决定队列是否还能继续；若故障已经使设备状态不可知，处理器应让状态机进入 Faulted，也可以再次抛出异常终止命令泵。不能未经分类就吞掉异常并继续执行下一条硬件命令。

4. 停止类动作不能都排在队尾

暂停、取消、正常停止和急停的语义不同：

动作	目标	常见处理
暂停	在可恢复点暂时挂起	完成当前原子步骤，保存上下文
取消	放弃当前业务任务	协作式取消，执行必要清理
正常停止	让设备受控回到非运行态	阻止新任务，减速或完成安全序列
急停	尽快消除危险能量	独立安全回路或安全控制器执行

急停不应作为普通软件命令排在 100 个动作后面。软件可以观察急停、停止继续发命令并引导复位，但人身安全相关的紧急停止必须按设备风险评估和适用安全标准实现，不能依赖通用操作系统调度或托管队列。

正常停止也通常需要高优先级控制通道，或者通过取消当前执行上下文后进入受控停止流程。不要给普通队列随意加入“插队”能力，否则命令顺序重新变得不可推理。

5. 流程编排管理长事务

一次设备任务可能包含：夹紧工件、移动、开光源、采集、处理、保存和释放。它不是数据库事务，已经发生的物理动作无法统一回滚。流程编排器需要显式描述：

每个步骤的前置条件和完成条件；
步骤的超时、取消点和可重试性；
失败时进入安全状态的补偿动作；
可持久化检查点，以及重启后允许恢复的位置；
资源占用关系，避免两个流程争用同一设备。

补偿不等于撤销。例如“夹爪闭合”失败后的补偿可能是切断驱动并要求人工检查，而不是盲目发送“张开”。只有当前物理状态可确认、逆操作本身安全且幂等时，自动补偿才成立。

流程步骤最好是粗粒度业务动作，而不是把每次寄存器读写都做成节点。过细会淹没意图，过粗又无法设置检查点和诊断失败位置。

6. 状态发布要避免乱序

控制循环拥有可变状态，UI 和外部系统读取快照。可以为每次状态变更增加单调递增的 Revision，让订阅者丢弃迟到更新。时间戳有助于诊断，但不同线程、进程和机器上的墙上时钟不适合单独承担排序责任。

持久化事件日志可以帮助重建执行过程，但不要默认把所有设备状态都改造成事件溯源。高频遥测量大且带噪声，通常更适合时序存储；真正需要审计和恢复的命令、状态转换与 Recipe 快照才值得长期保留。

7. 验证控制模型

至少覆盖以下测试：

每个状态允许和拒绝的命令；
重复启动、重复停止和迟到事件；
命令排队时发生取消或故障；
队列满时生产者的行为；
流程每一步失败后的最终状态；
暂停、取消和恢复跨越检查点的行为；
状态通知乱序、重复和订阅者变慢。

测试重点是最终状态、已发生的物理副作用和保存的证据，而不只是某个 Mock 方法被调用几次。

总结

状态机负责守住不变量，命令队列负责建立唯一写顺序，流程编排负责跨设备长事务。三者组合后，UI、远程接口和后台任务都必须通过同一入口提交意图，设备控制权才不会被多个线程和模块瓜分。

下一篇将讨论 Recipe 和配置版本：哪些参数属于产品工艺，哪些属于设备常数与校准，以及如何保证一次运行始终绑定到可追溯的参数快照。

参考资料

设备软件架构与控制模型（三）：设备生命周期与连接管理

Sun, 12 Jul 2026 10:00:00 +0800

设备对象不是创建出来就能用。它可能尚未通电、驱动未加载、端口已打开但初始化失败，也可能刚刚断连，而上一次运动仍留在控制器中。若代码只用一个 bool IsConnected 描述这些情况，重复连接、退出卡死和“界面显示在线但命令全部失败”几乎不可避免。

本文建立一套通用的设备生命周期模型，重点不是枚举多少个状态，而是让启动、运行、停止和故障后的每一步都有唯一责任、明确超时和可验证的最终状态。

1. 连接、健康和就绪是三件事

“TCP 已连接”或“句柄不为空”只能证明通信资源曾经建立，不能证明设备可以执行任务。至少要区分：

连接性（Connectivity）：端口、会话或驱动句柄是否可用；
健康度（Health）：设备是否报告故障、心跳是否新鲜、关键传感器是否可信；
就绪度（Readiness）：完成当前业务操作所需的前置条件是否满足。

一台相机可以处于已连接但过温报警的状态；一根轴可以健康，却因为尚未回零而不能执行绝对定位。把三者压成一个绿色图标，会让 UI 和自动流程得到错误结论。

推荐由设备模型发布不可变快照：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


public enum DeviceLifecycleState
{
 Offline,
 Connecting,
 Initializing,
 Ready,
 Busy,
 Disconnecting,
 Faulted
}

public sealed record DeviceSnapshot(
 DeviceLifecycleState State,
 bool IsConnected,
 bool IsHealthy,
 bool IsHomed,
 string? ActiveFault,
 DateTimeOffset ObservedAt);

快照里的时间表示“这份观测何时产生”，调用方还要判断其新鲜度。通信中断后保留最后位置用于诊断是有价值的，但不能把旧位置继续当成当前事实。

2. 生命周期是一组受控转换

一条常见主路径是：

1
2
3
4


Offline → Connecting → Initializing → Ready → Busy
 ↑ │ │ │
 └──── Disconnecting ←─────┴───────────┴───────┘
 ↘ Faulted

实际系统可以增加 Degraded、Recovering 或 Maintenance，但不要为每个布尔组合造一个状态。状态机应回答三个问题：

当前允许哪些命令？
哪个事件能够触发下一次转换？
转换失败后，系统能诚实确认的状态是什么？

Faulted 不是所有异常的垃圾桶。参数校验失败时设备状态可能完全没变；读取一次遥测超时也未必意味着设备故障。只有当失败改变了设备可信度，或者无法确认物理状态时，才需要降级到故障或未知状态。

3. 初始化应当可分步、可清理

把所有初始化塞进构造函数会带来两个问题：构造无法异步等待，部分成功后的资源也难以释放。更好的做法是把初始化拆成显式阶段，并为每一步记录结果：

1
2
3
4
5
6
7


打开通信资源
 → 读取身份与固件版本
 → 校验能力和兼容性
 → 加载受控参数
 → 注册回调或启动采集
 → 首次状态同步
 → 标记 Ready

失败清理按已完成步骤的逆序执行，但“逆序补偿”并不保证物理世界回到原点。例如阀门已经打开后通信断开，上位机无法仅凭调用 CloseAsync 证明阀门已关闭。此时应进入未知或故障状态，并依赖下位机的失联策略和现场确认。

4. 用异步互斥保护生命周期转换

连接和断开不能同时执行，也不能让两个按钮各自启动一轮初始化。下面的简化实现使用 SemaphoreSlim 串行化生命周期转换：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71


public interface IDeviceTransport : IAsyncDisposable
{
 ValueTask OpenAsync(CancellationToken cancellationToken);
 ValueTask InitializeAsync(CancellationToken cancellationToken);
 ValueTask CloseAsync(CancellationToken cancellationToken);
}

public sealed class DeviceSession(IDeviceTransport transport) : IAsyncDisposable
{
 private readonly SemaphoreSlim _gate = new(1, 1);

 public DeviceLifecycleState State { get; private set; } =
 DeviceLifecycleState.Offline;

 public async ValueTask ConnectAsync(CancellationToken cancellationToken)
 {
 await _gate.WaitAsync(cancellationToken);
 try
 {
 if (State is DeviceLifecycleState.Ready)
 {
 return;
 }

 if (State is not (DeviceLifecycleState.Offline or
 DeviceLifecycleState.Faulted))
 {
 throw new InvalidOperationException(
 $"Cannot connect while state is {State}.");
 }

 State = DeviceLifecycleState.Connecting;
 try
 {
 await transport.OpenAsync(cancellationToken);
 State = DeviceLifecycleState.Initializing;
 await transport.InitializeAsync(cancellationToken);
 State = DeviceLifecycleState.Ready;
 }
 catch
 {
 State = DeviceLifecycleState.Faulted;
 await TryCloseAfterFailureAsync();
 throw;
 }
 }
 finally
 {
 _gate.Release();
 }
 }

 private async ValueTask TryCloseAfterFailureAsync()
 {
 using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(3));
 try
 {
 await transport.CloseAsync(timeout.Token);
 }
 catch
 {
 // 这里应记录原始清理异常，但不能覆盖最初的连接异常。
 }
 }

 public async ValueTask DisposeAsync()
 {
 await transport.DisposeAsync();
 _gate.Dispose();
 }
}

示例刻意没有把 Faulted 自动改回 Offline：清理调用完成不等于已经确认物理状态安全。生产代码还应实现受限时的 DisconnectAsync，阻止释放期间的新命令，并避免 DisposeAsync 与正在执行的方法竞态。

生命周期互斥锁不应覆盖数分钟的工艺流程。长任务应交给后续的命令队列和流程执行器；生命周期锁只保护建立、切换和销毁会话这些短而关键的转换。

5. 取消、超时和停止的含义不同

设备调用至少涉及三种时间边界：

调用方取消：用户或上层流程不再需要结果；
操作超时：在约定期限内没有达到完成条件；
应用停止：进程正在优雅退出，不再接受新工作。

CancellationToken 传递的是协作式取消请求，不会强制终止线程，更不会天然停止硬件。适配器收到取消后，需要根据操作契约发出停止、等待安全点，或者明确报告“等待已取消，但设备动作可能仍在继续”。

清理操作也不应继续使用已经取消的调用方令牌，否则 CloseAsync 可能在执行任何清理步骤之前就因取消而抛出异常；但使用 CancellationToken.None 又可能让退出永久卡住。常见做法是为清理创建独立、受限时的令牌，并把超时后的不确定状态记录下来。

6. 重连必须重新建立事实

重连不是简单再次调用 Open。旧会话失效后，至少要重新核对：

设备身份、序列号和固件是否仍是预期对象；
轴是否移动过、是否需要重新回零；
输出、阀门和光源的真实状态；
控制器内是否仍有未完成或排队的命令；
当前 Recipe、校准和上位机缓存是否仍匹配；
谁仍持有当前任务和物料的所有权。

因此自动重连通常只能恢复“通信”，不能自动恢复“生产”。是否继续任务应由恢复策略根据可证明的检查点决定。涉及材料损失或人身安全时，宁可要求人工确认，也不要从一个推测状态继续。

7. 进程启动与设备启动分开

应用进程成功启动，不等于所有设备都必须已经 Ready。可以让 Generic Host 先建立日志、配置和诊断能力，再由 DeviceSupervisor 并行或按依赖关系初始化设备。对非关键设备，可以进入降级模式；对关键设备，则阻止流程进入可运行状态。

同样，应用退出应先停止接收新命令，再取消流程、等待设备进入安全点、关闭会话，最后释放 Host。不要直接调用 Environment.Exit 跳过受控关闭；但也不能假设优雅停止必然发生，硬件安全仍需独立保证。

总结

设备生命周期不是一个连接布尔值，而是从资源建立、能力确认到安全关闭的一组受控转换。连接性、健康度和就绪度应分别建模；初始化要能处理部分失败；取消等待不能冒充物理停止；重连后必须重新建立事实。

下一篇将把执行入口收敛到状态机和有界命令队列，并区分暂停、取消、正常停止和急停，避免多个调用方争夺设备写控制权。

参考资料

设备软件架构与控制模型（二）：硬件抽象层与设备适配器

Sat, 11 Jul 2026 10:00:00 +0800

设备软件很少从零控制硬件。相机、运动控制卡、光源和传感器通常附带 C/C++ DLL、.NET 封装或通信手册。直接调用这些 API 可以很快点亮设备，却会把厂商枚举、句柄、错误码、线程限制和单位扩散到整个项目，最终让流程难以测试、硬件难以替换。

硬件抽象层（Hardware Abstraction Layer，HAL）的价值不是“给 SDK 再套一层接口”，而是建立一套由业务需要定义、语义稳定且可验证的设备能力模型。本文将用运动轴作为贯穿示例，说明能力接口、适配器和模拟器应该如何分工。半导体设备中运动控制与硬件抽象的领域实践见《半导体设备软件（四）：运动控制与硬件抽象》。

1. 抽象能力，不抽象厂商函数

假设厂商 SDK 提供以下函数：

1
2
3
4
5


OpenCard(cardNo)
SetProfile(axisNo, velocity, acceleration)
MoveAbs(axisNo, pulse)
GetMotionStatus(axisNo)
GetLastError()

机械地把每个函数改成 C# 方法，只是把调用位置搬了家。上层仍然要知道脉冲换算、状态位、到位条件和错误码，并不能替换实现。

能力接口应该从调用者真正需要的语义出发。例如流程需要“以指定速度移动到某个物理位置，并在到位或失败后结束”：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


public readonly record struct Millimeters(double Value);
public readonly record struct MillimetersPerSecond(double Value);

public enum AxisStopMode
{
 Decelerated,
 Immediate
}

public sealed record AxisSnapshot(
 Millimeters ActualPosition,
 bool IsMoving,
 bool IsServoOn,
 bool PositiveLimit,
 bool NegativeLimit,
 string? FaultCode);

public interface IAxis
{
 ValueTask<AxisSnapshot> ReadAsync(CancellationToken cancellationToken);

 ValueTask MoveAbsoluteAsync(
 Millimeters target,
 MillimetersPerSecond speed,
 CancellationToken cancellationToken);

 ValueTask StopAsync(
 AxisStopMode mode,
 CancellationToken cancellationToken);
}

这里没有暴露卡号、脉冲数或厂商状态字。强类型单位让位置和速度不容易被交换，也迫使适配器集中处理脉冲当量、零点和符号方向。接口是否使用 ValueTask 不是架构重点；若实现通常异步完成，使用 Task 同样合理，不应为了微小分配收益增加调用复杂度。

2. 把语义翻译集中在适配器

适配器负责把稳定能力映射到具体 SDK，它至少需要处理五件事：

生命周期：打开、初始化、关闭句柄；
数据映射：单位、坐标、枚举和位域；
完成语义：区分“命令已接受”和“物理动作已完成”；
错误映射：保留原始错误码，同时提供稳定的领域分类；
并发约束：遵守 SDK 对调用线程和重入的要求。

简化后的轮询等待可以写成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69


public sealed class VendorAxisAdapter(
 IVendorMotionApi api,
 int axisNumber,
 double pulsesPerMillimeter,
 TimeProvider timeProvider) : IAxis
{
 public async ValueTask MoveAbsoluteAsync(
 Millimeters target,
 MillimetersPerSecond speed,
 CancellationToken cancellationToken)
 {
 int targetPulse = checked((int)Math.Round(
 target.Value * pulsesPerMillimeter,
 MidpointRounding.AwayFromZero));

 // 速度同样按脉冲当量换算为 pulse/s，与目标位置保持同一单位域。
 api.StartAbsoluteMove(
 axisNumber,
 targetPulse,
 speed.Value * pulsesPerMillimeter);

 while (true)
 {
 cancellationToken.ThrowIfCancellationRequested();
 VendorAxisState state = api.ReadState(axisNumber);

 if (state.FaultCode is not null)
 {
 throw new DeviceFaultException(
 "AxisMotionFailed",
 state.FaultCode);
 }

 if (!state.IsMoving && state.InPosition)
 {
 return;
 }

 await Task.Delay(
 TimeSpan.FromMilliseconds(20),
 timeProvider,
 cancellationToken);
 }
 }

 public ValueTask<AxisSnapshot> ReadAsync(
 CancellationToken cancellationToken)
 {
 cancellationToken.ThrowIfCancellationRequested();
 VendorAxisState state = api.ReadState(axisNumber);

 return ValueTask.FromResult(new AxisSnapshot(
 new Millimeters(state.ActualPulse / pulsesPerMillimeter),
 state.IsMoving,
 state.IsServoOn,
 state.PositiveLimit,
 state.NegativeLimit,
 state.FaultCode));
 }

 public ValueTask StopAsync(
 AxisStopMode mode,
 CancellationToken cancellationToken)
 {
 cancellationToken.ThrowIfCancellationRequested();
 api.Stop(axisNumber, immediate: mode is AxisStopMode.Immediate);
 return ValueTask.CompletedTask;
 }
}

其中 IVendorMotionApi 和 VendorAxisState 是对原始 SDK 的窄封装：前者负责调用厂商函数，后者把一次读取所需的状态位和实际脉冲数打包返回。它们没有在示例中展开，因为具体签名必须以所用 SDK 版本为准。

这段代码只是说明职责位置，不代表所有轴都应以 20 ms 轮询。支持事件回调或硬件完成通知时，应按厂商文档选择机制；轮询周期也要结合控制器负载和业务响应要求测量。取消等待只表示调用方不再等待，适配器还必须按照设备策略决定是否发减速停止，不能假定取消 Task 会让物理轴自动停下。

3. 错误需要两层信息

只抛出 Exception("移动失败") 会丢失现场证据；让流程判断 -2017 又会把厂商实现泄漏出去。一个可维护的错误模型通常同时保留：

稳定分类：超时、通信中断、联锁不满足、设备报警、参数非法；
原始证据：厂商错误码、命令、控制器状态字和发生时间。

1
2
3
4
5
6
7
8


public sealed class DeviceFaultException(
 string faultKind,
 string vendorCode)
 : Exception($"Device operation failed: {faultKind}")
{
 public string FaultKind { get; } = faultKind;
 public string VendorCode { get; } = vendorCode;
}

预期内且高频出现的业务拒绝，例如“门未关闭，不能启动”，可以返回显式结果；真正无法继续的驱动故障更适合异常。关键不是统一用返回值还是异常，而是调用契约必须说明哪些结果可恢复、物理动作是否已经开始，以及失败后设备可能处于什么状态。

4. 资源所有权必须唯一

多数设备 SDK 背后持有非托管句柄、回调或驱动缓冲区。创建适配器的一方应该明确拥有并释放这些资源：

原生句柄优先封装为 SafeHandle，避免在普通业务类里手写终结器；
异步关闭需要等待时，实现 IAsyncDisposable；
不要让多个适配器分别关闭同一个全局 SDK；
回调注册和注销使用同一个委托实例，并在关闭前停止产生新回调；
关闭过程设计为幂等，允许在部分初始化失败后再次执行。

.NET 的垃圾回收器只管理托管内存，不会自动理解厂商句柄代表的硬件资源。Dispose 也不是“将来有空再清理”的提示，而是资源所有权协议的一部分。

5. 线程安全不能靠猜

厂商 SDK 是否线程安全，应以对应版本文档和实测为准。文档没有明确保证时，保守做法是让一个所有者串行化对设备的写操作，而不是在 UI、流程和监控线程中同时调用 SDK。

读状态也不一定可以任意并发：有的 SDK 使用进程级“最后错误码”，有的回调只能在初始化线程处理，还有的底层总线本来就是半双工。适配层应隐藏这些限制，并向上层提供一致的异步契约。若必须切换到专用线程，应把线程调度封装在适配器内部，而不是要求每个调用方记住 Invoke。

6. 模拟器要实现同一份契约

模拟器不是返回固定成功值的 Mock。它至少要保留真实接口的重要行为：

操作需要时间，状态会经历变化；
非法状态下拒绝命令；
支持取消、超时和故障注入；
单位、范围与软限位规则一致；
能构造断连、卡住和部分完成等失败场景。

由于流程只依赖 IAxis，组合根可以决定使用真实适配器还是模拟器：

1
2
3
4
5
6
7
8
9


// 需要 using Microsoft.Extensions.Configuration;（Worker 项目模板的隐式 using 已包含它）。
if (builder.Configuration.GetValue<bool>("Equipment:Simulation"))
{
 builder.Services.AddSingleton<IAxis, SimulatedAxis>();
}
else
{
 builder.Services.AddSingleton<IAxis, VendorAxisAdapter>();
}

不要在业务代码里到处判断 if (isSimulation)。真实与仿真实现的差异应留在组合根和适配层，否则两条逻辑路径会逐渐漂移。

7. 评审一份 HAL 的问题清单

在接口稳定之前，可以逐项检查：

方法描述的是业务能力，还是照搬厂商函数名？
单位、坐标系、精度和范围是否明确？
返回完成时，物理设备究竟到达了什么状态？
取消或超时后，动作仍可能继续吗？
原始错误证据是否保留，同时避免流程依赖厂商码？
谁拥有句柄、回调和关闭责任？
并发调用是否有文档依据，还是仅仅“目前没出过问题”？
同一套契约能否由模拟器实现并用于测试？

一个接口越短，不一定越好；一个接口越通用，也不一定越抽象。好的 HAL 会准确表达本设备需要保证的能力，并主动拒绝无法诚实实现的“万能接口”。

总结

硬件抽象层是语义边界：上层说物理能力，适配器处理厂商细节。单位换算、完成条件、错误映射、线程限制和资源所有权都应在这条边界上得到统一解释。这样做不仅为了将来换硬件，更为了让今天的流程能够被模拟、测试和诊断。

下一篇将继续讨论设备从离线到可运行的生命周期，解决初始化一半失败、重复连接、退出清理和重启后状态重建等问题。

参考资料

设备软件架构与控制模型（一）：上位机与下位机的职责边界

Fri, 10 Jul 2026 10:00:00 +0800

一套设备能在实验室里“跑起来”，不代表它已经具备可交付的软件架构。相机、运动轴、传感器和 PLC 接入之后，最容易出现的问题不是少一个按钮，而是职责散落：界面直接调用厂商 SDK，流程代码同时处理通信重连，控制器与上位机各自保存一份状态，安全动作甚至依赖 Windows 程序及时响应。

本文面向刚进入上位机或设备软件开发的工程师，先回答一个决定后续设计的问题：什么应该由上位机负责，什么必须留在下位机或独立安全链中？ 示例以 C#/.NET 10 为背景，但职责划分并不依赖某一种 UI 框架或控制器品牌。半导体场景下的领域化展开（状态机、Recipe、SECS/GEM、晶圆厂集成）见《半导体设备软件（一）：设备软件的整体架构》系列，本组只讲与行业无关的通用方法。

1. “上位机”和“下位机”不是按机器外壳划分

上位机通常运行在工业 PC 上，负责操作界面、流程编排、数据管理、诊断和对外集成；下位机可能是 PLC、运动控制器、嵌入式控制板或仪器固件，负责贴近硬件的采样和控制。但这只是常见形态，不是定义。

更可靠的划分方法是看四个约束：

约束	更适合放在哪里	原因
必须在确定的短周期内闭环	实时控制器或设备固件	桌面操作系统的调度延迟不具备硬实时保证
断网、进程崩溃后仍必须生效	下位机或独立安全回路	不能把安全依赖于上位机存活
经常变化且需要复杂业务规则	上位机	更适合版本管理、测试和快速迭代
需要大量存储、分析和人机交互	上位机	工业 PC 的算力、存储和 UI 能力更合适

因此，“电机移动到 125.0 mm”可以由上位机发起，但位置环通常在运动控制器内闭合；“检测到门打开后切断危险输出”也不应等待 WPF 事件处理程序执行。上位机可以展示联锁状态、阻止流程继续并记录证据，却不应成为唯一的安全屏障。

边界不是越靠下越好。把 Recipe 校验、批次追踪和复杂调度全部塞进 PLC，同样会让系统难以演进。目标是让每项职责位于能够满足其时序、安全和维护要求的最低复杂度层级。

2. 从五类职责看完整设备

可以先把系统按职责分成五层。它们是逻辑边界，不要求对应五个进程或五个项目：

1
2
3
4
5
6
7
8
9


操作与集成层 UI、权限、MES/上层系统接口
 ↓
流程与领域层 状态机、任务编排、Recipe、业务规则
 ↓
设备能力层 相机采集、轴运动、光源控制、传感器读取
 ↓
厂商适配与通信层 SDK、串口、TCP、现场总线、错误码映射
 ↓
控制器与安全层 实时闭环、硬联锁、安全 PLC、驱动器保护

最重要的依赖方向是：流程依赖“设备能力”，而不是依赖某个品牌的 DLL。厂商适配层实现能力接口，并把厂商类型、线程模型和错误码限制在边界内。这样更换相机或增加模拟器时，流程层不需要认识新的 SDK。

UI 也不是控制核心。按钮应提交一个带权限和前置条件的意图，由应用层决定能否执行；设备状态则通过只读快照或事件投影给 UI。若点击事件里同时出现 MessageBox、数据库事务和 VendorAxis.Move()，说明边界已经被穿透。

3. 命令、状态和事实要分开

设备软件里经常混淆三类信息：

命令（Command） 表达“希望系统做什么”，例如开始运行或移动轴；命令可能被拒绝、取消或失败。
状态（State） 表达系统当前允许什么，例如 Ready、Running、Faulted；状态是经过规则解释后的模型。
事实（Observation/Event） 表达实际发生了什么，例如限位输入变为有效、控制器返回故障码、图像采集完成。

命令成功返回也不一定代表物理动作已经完成。某些 SDK 的 Move 只表示命令已进入控制器队列，真正完成需要等待到位信号，并同时检查伺服报警、限位和超时。适配层必须把这种厂商语义翻译成统一契约，不能让每条业务流程自行猜测。

状态也不能由 UI 随意写入。较稳健的数据流是：

1
2
3
4
5


操作意图 → 命令处理器 → 设备能力接口 → 适配器/控制器
 ↓
 观测值与结果事件
 ↓
 状态投影 → UI

这条单向链路能避免“界面显示 Ready，但控制器仍在初始化”这样的双重事实源。

4. 进程边界与架构边界不是一回事

小型设备完全可以先采用模块化单体：一个进程中包含 UI、流程、设备抽象和适配器，通过明确的项目引用与接口维持边界。把每个模块拆成服务并不会自动获得可靠性，反而会引入网络故障、部署协调和分布式状态一致性问题。

只有当故障隔离、权限边界、独立升级或资源占用确有需要时，才值得引入进程边界。例如：

不稳定的 32 位厂商 SDK 无法加载进 64 位主进程，可以用独立进程承载；
图像处理需要独立 GPU 进程并允许单独重启；
控制服务必须在无人登录时作为 Windows Service 运行，而 UI 只是客户端；
多个客户端需要通过受控 API 访问同一台设备。

即使拆成多个进程，设备的写控制权也应有唯一所有者。两个进程同时向同一控制器下发命令，通常比单进程故障更难诊断。

5. 用 Generic Host 管理进程生命周期

.NET Generic Host 把依赖注入、配置、日志、后台服务和优雅停止组合在统一生命周期中。它既能承载 Worker Service，也能作为 WinForms/WPF 应用中的组合根。下面只展示骨架，具体设备接口将在下一篇展开：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton<IMachineController, MachineController>();
builder.Services.AddSingleton<IAxis, SimulatedAxis>();
builder.Services.AddHostedService<DeviceSupervisor>();

using IHost host = builder.Build();
await host.RunAsync();

对于桌面 UI，通常由应用启动代码调用 StartAsync，在退出流程中调用 StopAsync 并释放 Host，而不是同时调用会阻塞至关闭的 RunAsync。还要注意，优雅停止不是崩溃恢复机制：断电、进程被强制终止时，StopAsync 可能没有机会执行，所以安全状态必须由控制器、驱动器或独立回路兜底。

6. 用场景验证边界

架构评审不要只看方框图，可以逐个追问失败场景：

UI 无响应时，正在运行的轴由谁停止？
网线拔掉后，控制器继续执行还是进入安全状态？这个策略由谁定义？
上位机重启后，如何确认设备真实位置和当前物料，而不是加载一份过期缓存？
Recipe 更新到一半失败，下一次运行使用哪个版本？
两个客户端同时发送启动命令，谁拥有控制权？
厂商 SDK 卡死时，能否隔离、超时或重启，而不破坏物理安全？

如果答案是“UI 会处理”“正常不会发生”或“重启试试”，说明职责边界还没有真正落地。边界的价值正是在非正常路径上决定谁负责检测、谁负责处置、谁保存证据。

总结

上位机适合承担变化快、数据多、交互复杂的业务；下位机适合承担贴近硬件、时序确定的控制；独立安全链负责不能依赖通用软件存活的保护。逻辑分层不等于强行拆进程，但设备的事实源和写控制权必须清楚。

下一篇将沿着“流程只依赖设备能力”的原则，设计硬件抽象层和厂商适配器，并处理单位、错误语义、线程模型与资源所有权这些最容易泄漏的细节。