简介：NModbus4 通讯类库（Framework4.5版本）源码面向仍在使用 .NET Framework 4.5 的 C# 开发者，解决官方 NModbus 库升级后与旧项目、低版本框架不兼容的问题，让开发者无需迁移框架即可与 PLC、RTU、变频器等支持 Modbus 协议的设备通信。库覆盖 ASCII、RTU、TCP 三种通信模式，源码按 ModbusTCP、ModbusSerial、ModbusUDP 等功能模块拆分，并配有示例程序、单元测试用例、.csproj 项目配置文件及 README 说明文档，便于理解连接初始化、请求响应收发与寄存器读写流程。压缩包为 zip 格式，大小约 9.07MB，已有 4157 人学习下载。借助这份源码，读者可掌握功能码、寄存器类型与数据传输格式，结合异步编程、异常处理及设备模拟器调试，快速搭建稳定的 Modbus 通信模块，并对照测试用例排查超时、连接中断等常见问题。

1. 工控上位机通讯的"最后一公里"：为什么我最终选了 NModbus4

做 C# 上位机开发的同行大概都有过这种经历：项目里要接 PLC、仪表、变频器，通讯协议翻来覆去就是 Modbus RTU 和 Modbus TCP 两种，但每次都要重新造轮子。自己写串口收发、拼报文、算 CRC、处理粘包，代码写了一堆，现场一跑就出玄学问题——偶尔丢一帧、偶尔超时、偶尔读回来的寄存器值高低字节反了。更头疼的是，很多老项目还锁死在 .NET Framework 4.5 上，NuGet 上那些新潮的库要么只支持 .NET Standard，要么依赖一堆用不上的东西。

NModbus4 就是在这个场景下被我翻出来的。它是一个纯 C# 实现的 Modbus 通讯类库，Framework 4.5 版本能直接扔进老项目里编译，不挑环境、不引第三方依赖，RTU、TCP、ASCII 三种模式都覆盖。源码结构清晰，SerialPort 和 TcpClient 的封装都在明面上，出问题能直接断点进去看，不用对着黑匣子猜。适合谁？适合那些维护着 WinForm/WPF 工控上位机、需要快速对接 Modbus 设备、又不想被新框架绑架的开发者。下面我按"能跑起来 → 能改得动 → 能排得错"的顺序，把这份源码拆一遍。

2. 源码结构与核心类：先搞清楚谁在干活

拿到一份源码，我习惯先看目录树和 csproj，判断它能不能直接塞进现有解决方案。NModbus4 的 Framework 4.5 版本结构不复杂，核心就几个文件夹，但每个类的职责分得很清楚，搞明白之后改起来心里有底。

2.1 目录布局与关键文件

解压后大致是这么个结构（不同打包方式可能略有差异，以实际为准）：

NModbus4/ ├── NModbus4.csproj # 项目文件，TargetFrameworkVersion=v4.5 ├── Data/ # 数据存储区，从站寄存器模拟 │ ├── DataStore.cs │ └── DataStoreFactory.cs ├── Device/ # 主站/从站设备封装 │ ├── ModbusMaster.cs │ ├── ModbusSerialMaster.cs │ ├── ModbusTcpMaster.cs │ └── ModbusSlave.cs ├── IO/ # 流与适配器 │ ├── ModbusSerialTransport.cs │ ├── ModbusTcpTransport.cs │ └── ModbusAsciiTransport.cs ├── Message/ # 报文与功能码实现 │ ├── ReadHoldingRegistersRequest.cs │ ├── WriteSingleRegisterRequest.cs │ └── ... └── Utility/ # CRC、字节序等工具 ├── ModbusUtility.cs └── ...

几个必须认识的类：

ModbusMaster是抽象基类，定义了ReadHoldingRegisters、WriteSingleRegister、ReadInputs这些标准方法。真正干活的是它的两个子类，一个走串口，一个走网络。这种设计的好处是：上层业务代码可以面向ModbusMaster编程，底层换 RTU 还是 TCP 只改一行创建代码。

2.2 主站创建与连接：RTU 和 TCP 两条路

先看 RTU。串口主站的创建依赖SerialPort，参数必须和设备手册对齐，错一个就通讯不上：

using NModbus4; using NModbus4.Serial; using System.IO.Ports; // 创建串口对象，参数来自设备手册 SerialPort port = new SerialPort("COM3"); port.BaudRate = 9600; // 波特率，常见 9600/19200/38400 port.DataBits = 8; // 数据位，Modbus RTU 固定 8 port.Parity = Parity.None; // 校验位，None/Even/Odd 要和设备一致 port.StopBits = StopBits.One;// 停止位，通常 1，少数设备 2 port.ReadTimeout = 1000; // 读超时，毫秒 port.WriteTimeout = 1000; // 写超时，毫秒 // 用串口工厂创建 RTU 主站 IModbusSerialMaster master = ModbusSerialMaster.CreateRtu(port); // 从站地址 1，读 10 个保持寄存器，起始地址 0 ushort[] registers = master.ReadHoldingRegisters(1, 0, 10);

逻辑说明：ModbusSerialMaster.CreateRtu(port)内部把SerialPort包成ModbusSerialTransport，后续所有读写都走这个 transport。ReadHoldingRegisters的第一个参数是从站地址（Slave ID），第二个是起始寄存器地址，第三个是数量。注意这里的地址是"协议地址"，不是设备手册上那种 40001 格式的"PLC 地址"，两者差 1，后面避坑章节会细说。

再看 TCP。网口设备或者串口服务器转 Modbus TCP 的场景：

using NModbus4; using System.Net.Sockets; // 连接 Modbus TCP 设备，默认端口 502 TcpClient client = new TcpClient("192.168.1.100", 502); client.ReceiveTimeout = 1000; client.SendTimeout = 1000; // 创建 TCP 主站 IModbusMaster master = ModbusIpMaster.CreateIp(client); // 读从站 1 的 10 个保持寄存器 ushort[] registers = master.ReadHoldingRegisters(1, 0, 10);

逻辑说明：ModbusIpMaster.CreateIp(client)是 TCP 主站的工厂方法，内部用ModbusTcpTransport。TCP 模式下从站地址仍然要传，因为 Modbus TCP 报文头里保留了 Unit Identifier 字段，很多网关靠它区分后端串口设备。如果设备是纯 TCP 从站，这个值通常填 1 或 0xFF，具体看手册。

参数上最容易翻车的是超时。ReadTimeout设太短，现场干扰大时频繁超时；设太长，界面卡死。我一般先设 1000ms，现场调试时根据实际响应时间调整，但不要低于设备手册标称响应时间的 2 倍。

2.3 读写方法族与功能码对应关系

NModbus4 的方法名和 Modbus 功能码是对应的，记住这张表，看代码就不用翻文档：

实际项目里，读保持寄存器（0x03）和写多个寄存器（0x10）用得最多。写单个寄存器（0x06）适合改单个参数，比如设定值。线圈类操作多用于开关量控制。

有个细节值得注意：ReadHoldingRegisters返回的是ushort[]，但很多设备的一个参数占两个寄存器（32 位浮点或 32 位整型）。NModbus4 不帮你拼，需要自己按字节序组合。这是后面避坑章节的重点。

3. 从零跑通第一个读写：环境、编译与最小示例

光看结构不够，得让它真跑起来。这一章按"建项目 → 引源码 → 连设备 → 读写验证"的顺序走一遍，中间穿插我踩过的编译坑。

3.1 把源码引入现有工程：两种方式

方式一，直接引用项目。把 NModbus4 文件夹拷进解决方案目录，在 VS 里右键解决方案 → 添加 → 现有项目，选中NModbus4.csproj。然后在你的上位机项目里右键引用 → 添加引用 → 项目，勾选 NModbus4。这种方式的好处是能直接改源码、能断点调试。

方式二，编译成 DLL 再引用。打开 NModbus4 项目，确认目标框架是 .NET Framework 4.5，直接生成，在bin\Debug或bin\Release下拿到NModbus4.dll，然后在你项目里添加引用指向这个 DLL。适合不想让源码混进主工程的情况。

两种方式我都用过。调试阶段用方式一，能跟进 transport 层看收发报文；交付阶段用方式二，干净。

提示：如果你的主工程是 .NET Framework 4.5，而 NModbus4 项目文件里写的是更高版本，编译会报框架不兼容。打开 csproj 找到<TargetFrameworkVersion>节点，改成v4.5再试。

3.2 一个能直接抄的最小读写示例

下面这段代码是我常用的验证模板，RTU 和 TCP 都能套，先读后写，跑通说明链路没问题：

using System; using System.IO.Ports; using NModbus4; using NModbus4.Serial; class Program { static void Main() { // 1. 配置串口，参数必须和设备手册一致 SerialPort port = new SerialPort("COM3") { BaudRate = 9600, DataBits = 8, Parity = Parity.None, StopBits = StopBits.One, ReadTimeout = 1000, WriteTimeout = 1000 }; // 2. 创建 RTU 主站 IModbusSerialMaster master = ModbusSerialMaster.CreateRtu(port); byte slaveId = 1; // 从站地址 ushort startAddr = 0; // 起始寄存器地址 ushort numRegs = 4; // 读取数量 try { // 3. 读保持寄存器 ushort[] values = master.ReadHoldingRegisters(slaveId, startAddr, numRegs); for (int i = 0; i < values.Length; i++) { Console.WriteLine($"寄存器[{startAddr + i}] = {values[i]}"); } // 4. 写单个寄存器，把地址 0 的值改成 100 master.WriteSingleRegister(slaveId, 0, 100); Console.WriteLine("写入完成"); // 5. 回读验证 ushort[] check = master.ReadHoldingRegisters(slaveId, 0, 1); Console.WriteLine($"回读地址0 = {check[0]}"); } catch (Exception ex) { // 超时、校验错、从站异常都会抛到这里 Console.WriteLine($"通讯异常: {ex.Message}"); } finally { // 6. 释放串口，否则下次打开会报占用 port.Close(); port.Dispose(); } } }

逻辑说明：整个流程是"配置 → 创建 → 读 → 写 → 回读 → 释放"。第 3 步读回来的ushort[]是原始寄存器值，如果设备是 32 位数据，这里只拿到一半。第 5 步回读很关键，写操作在 Modbus 里是"无响应确认"的（写单个寄存器有回显，写多个也有），但回读能确认设备真的接受了值，现场调试时这一步能省很多扯皮。

参数说明：slaveId必须和设备拨码或配置一致，错了会超时或收到异常码。startAddr是协议地址，设备手册上写 40001 的话，这里填 0。numRegs一次别读太多，有些设备限制单次最多读 125 个寄存器，超了会返回异常码 0x03。

3.3 用 DataStore 做无设备自测

手头没设备的时候，可以用 NModbus4 自带的DataStore和ModbusSlave搭一个从站模拟器，验证主站代码逻辑：

using NModbus4; using NModbus4.Data; using System.IO.Ports; // 创建数据区，模拟 100 个保持寄存器 DataStore store = new DataStore(); store.HoldingRegisters[0] = 1234; // 预置一个值 store.HoldingRegisters[1] = 5678; // 用同一个串口创建从站（实际测试可用虚拟串口对） SerialPort port = new SerialPort("COM4") { BaudRate = 9600, DataBits = 8, Parity = Parity.None, StopBits = StopBits.One }; ModbusSerialSlave slave = ModbusSerialSlave.CreateRtu(1, port); slave.DataStore = store; slave.Listen(); // 开始监听 // 此时主站从 COM3 发请求，从站从 COM4 响应

逻辑说明：DataStore内部维护了四类数据区——Coils、DiscreteInputs、HoldingRegisters、InputRegisters，和 Modbus 的四类数据一一对应。ModbusSerialSlave.CreateRtu(1, port)里的 1 是从站地址。Listen()是阻塞式的，实际项目里一般放到独立线程。

这个自测方式在没有硬件时特别有用，能验证主站的报文拼装、CRC 计算、超时处理是否正确。虚拟串口对可以用系统自带工具或第三方虚拟串口软件创建，这里不展开。

4. 避坑与排查：现场最容易翻车的五个点

这份源码本身质量不错，但 Modbus 这个协议在现场的坑，一半在协议本身，一半在设备厂商的"自由发挥"。下面五条是我这些年真金白银换来的，按"现象 → 原因 → 解决"写清楚。

4.1 读回来的值高低字节反了

现象：读一个 32 位浮点数，拼出来是乱码或者数量级完全不对。

原因：Modbus 寄存器是 16 位的，32 位数据要占两个寄存器。但设备厂商对"哪个寄存器是高字、字内字节怎么排"没有统一标准，常见的有 ABCD、CDAB、BADC、DCBA 四种组合。NModbus4 只负责把两个ushort给你，拼接逻辑要自己写。

解决：先确认设备手册里的字节序说明，然后用BitConverter配合手动交换：

// 假设寄存器 0 是低字，寄存器 1 是高字（CDAB 序） ushort low = registers[0]; ushort high = registers[1]; // 拼成 32 位整数 byte[] bytes = new byte[4]; bytes[0] = (byte)(low & 0xFF); bytes[1] = (byte)(low >> 8); bytes[2] = (byte)(high & 0xFF); bytes[3] = (byte)(high >> 8); float value = BitConverter.ToSingle(bytes, 0);

如果结果还是不对，把bytes的顺序整体反转再试。我一般会写一个ByteOrderHelper类，把四种序都实现，现场用哪个试哪个，试出来就固定下来。

4.2 地址偏移差 1，读到的全是隔壁寄存器

现象：按手册地址读，值不对，但读相邻地址就对了。

原因：设备手册常用 40001、30001 这种"PLC 地址"表示法，其中 4 代表保持寄存器，后面是序号，从 1 开始。而 Modbus 协议报文里的地址是从 0 开始的。所以手册 40001 对应协议地址 0，40002 对应 1，依此类推。

解决：写代码前先做一次地址换算，别直接把手册数字填进去。我习惯在代码里加注释：

// 手册地址 40001 -> 协议地址 0 // 手册地址 40100 -> 协议地址 99 ushort protocolAddr = (ushort)(manualAddr - 40001);

输入寄存器（30001 开头）同理，减 30001。线圈和离散输入类似，减 1 或减 10001，看手册用的是哪种表示法。

4.3 串口被占用，第二次打开就报错

现象：程序第一次跑正常，关掉再开就提示"访问被拒绝"或"端口已占用"。

原因：SerialPort没有正确释放，或者上一次的异常导致Close()没执行到。串口是独占资源，不释放别人就用不了。

解决：用try-finally或using包住，确保任何情况下都释放。另外，SerialPort的Close()在某些驱动上有延迟，如果立即重开可能还报占用，可以加一个短延时或重试：

try { // 通讯逻辑 } finally { if (port.IsOpen) { port.Close(); } port.Dispose(); // 部分驱动需要短暂等待才能重新打开 System.Threading.Thread.Sleep(100); }

4.4 超时设置不合理，界面卡死或频繁误报

现象：点一下"读取"，界面卡住好几秒；或者现场干扰大时频繁报超时。

原因：ReadTimeout设太长，同步调用会阻塞 UI 线程；设太短，设备正常响应时间波动就超时。

解决：两个层面。第一，超时值按设备手册标称响应时间的 2 到 3 倍设，一般 500ms 到 2000ms 之间。第二，通讯操作放到后台线程，别在 UI 线程里直接调ReadHoldingRegisters。WinForm 里可以用Task.Run或BackgroundWorker，WPF 里用async/await配合Task。

// WinForm 里避免卡 UI 的写法 private async void btnRead_Click(object sender, EventArgs e) { ushort[] result = await Task.Run(() => { return master.ReadHoldingRegisters(1, 0, 10); }); // 回到 UI 线程更新控件 txtResult.Text = string.Join(",", result); }

4.5 从站返回异常码，但异常信息看不懂

现象：抛异常，消息里带一个数字，比如"Exception of type 'NModbus4.Exceptions.SlaveException'"，不知道啥意思。

原因：Modbus 从站遇到非法请求会返回异常响应，功能码最高位置 1，后面跟一个异常码。NModbus4 把它包成SlaveException抛出。

解决：捕获SlaveException，读它的SlaveExceptionCode属性，对照标准异常码表：

try { master.ReadHoldingRegisters(1, 0, 10); } catch (SlaveException ex) { Console.WriteLine($"从站异常码: 0x{ex.SlaveExceptionCode:X2}"); // 根据异常码做针对性处理 }

现场遇到 0x02 最多，基本都是地址算错了或者设备不支持那么多寄存器。0x03 常见于写入值超范围，比如设备只接受 0 到 1000，你写了 5000。

5. 进阶技巧：封装一个能扛现场的通讯层

源码能跑通只是起点，真正上项目还得做一层封装，把重试、日志、字节序处理都收进去。这一章说几个我常用的技巧，都是被现场逼出来的。

5.1 带重试的读写封装

现场干扰、设备响应慢是常态，一次失败就报错给用户看体验很差。我一般包一层重试：

public ushort[] ReadWithRetry(IModbusMaster master, byte slaveId, ushort startAddr, ushort numRegs, int maxRetry = 3) { int attempt = 0; while (true) { try { return master.ReadHoldingRegisters(slaveId, startAddr, numRegs); } catch (Exception ex) when (attempt < maxRetry) { attempt++; // 记录日志，便于事后分析 Console.WriteLine($"第{attempt}次重试，原因: {ex.Message}"); System.Threading.Thread.Sleep(100); // 重试前短暂等待 } } }

逻辑说明：when (attempt < maxRetry)是 C# 6 的异常过滤器，只有重试次数没到才捕获，到了就往外抛。重试间隔 100ms 是经验值，太短设备还没缓过来，太长界面响应慢。重试次数别设太多，3 次足够，再多说明链路本身有问题，该查线查线。

5.2 字节序转换的通用工具

前面提过字节序的坑，我把它做成一个静态工具类，四种序都支持：

public static class ByteOrderHelper { // 把两个寄存器按指定字节序拼成 float public static float ToFloat(ushort reg1, ushort reg2, string order) { byte[] b1 = BitConverter.GetBytes(reg1); byte[] b2 = BitConverter.GetBytes(reg2); byte[] combined = new byte[4]; switch (order.ToUpper()) { case "ABCD": // 高字在前，字内高字节在前 combined[0] = b2[1]; combined[1] = b2[0]; combined[2] = b1[1]; combined[3] = b1[0]; break; case "CDAB": // 低字在前，字内高字节在前 combined[0] = b1[1]; combined[1] = b1[0]; combined[2] = b2[1]; combined[3] = b2[0]; break; case "BADC": // 高字在前，字内低字节在前 combined[0] = b2[0]; combined[1] = b2[1]; combined[2] = b1[0]; combined[3] = b1[1]; break; case "DCBA": // 低字在前，字内低字节在前 combined[0] = b1[0]; combined[1] = b1[1]; combined[2] = b2[0]; combined[3] = b2[1]; break; } return BitConverter.ToSingle(combined, 0); } }

参数说明：reg1和reg2是从ReadHoldingRegisters拿到的两个连续寄存器值，order是设备手册里标的字节序。现场调试时四种都试一遍，哪个对就固定用哪个。这个类还能扩展ToInt32、ToUInt32，思路一样。

5.3 通讯日志：出问题时的后悔药

现场出问题，最怕的是"当时没留日志"。我习惯在 transport 层加一个简单的日志钩子，把收发的原始字节记下来：

// 在创建主站后，包一层日志（示意，实际可继承 transport 或加事件） public static void LogFrame(string direction, byte[] frame) { string hex = BitConverter.ToString(frame).Replace("-", " "); Console.WriteLine($"[{DateTime.Now:HH:mm:ss.fff}] {direction}: {hex}"); }

Modbus RTU 的报文结构是"地址 + 功能码 + 数据 + CRC"，TCP 是"事务号 + 协议号 + 长度 + 单元号 + 功能码 + 数据"。把原始帧打出来，对着协议手册一比对，是请求发错了还是响应异常，一目了然。这个习惯帮我省过好几次和设备厂商扯皮的时间——有日志，谁的问题清清楚楚。

5.4 从站模拟器：没有硬件也能联调

项目前期硬件没到货是常事，用 NModbus4 的DataStore搭一个从站模拟器，主站代码可以先跑起来。除了前面提的串口从站，TCP 从站也能搭：

using NModbus4; using NModbus4.Data; using System.Net; using System.Net.Sockets; // 监听 502 端口 TcpListener listener = new TcpListener(IPAddress.Any, 502); listener.Start(); // 接受一个客户端连接 TcpClient client = listener.AcceptTcpClient(); // 创建 TCP 从站，单元号 1 ModbusTcpSlave slave = ModbusTcpSlave.CreateTcp(1, client); slave.DataStore = new DataStore(); slave.Listen();

逻辑说明：ModbusTcpSlave.CreateTcp(1, client)里的 1 是单元号，对应主站请求里的 Unit Identifier。Listen()同样是阻塞的，实际用的时候放到独立线程。DataStore里的寄存器可以预先填值，模拟真实设备的数据。

这个模拟器还有个用处：做自动化测试。主站代码写完后，用模拟器跑一遍读写流程，确认逻辑没问题，再上真设备，能省不少现场调试时间。

从那以后我每次接新设备，都强制走一遍"模拟器验证 → 真机单点读写 → 批量读写 → 异常注入"的流程，再急也不跳过。希望这些经验帮到你，少走点弯路。

本文还有配套的精品资源，点击获取