简介面向工业自动化与上位机开发人员这份C# NModbus操作资源提供了基于NModbus4库的Modbus通信完整示例。内容覆盖Modbus RTU与Modbus TCP两种常见模式并针对协议差异、功能码使用做了相应实现可帮助读者快速掌握读写线圈、离散输入、保持寄存器等核心操作适合需要对接PLC、仪表等工业设备的C#开发者参考。资源包共195个文件压缩后仅5.84MB主要包括28个C#源码工程文件、22个DLL库及8个EXE可执行程序同时附带XML文档、Config配置、PDB调试符号等便于直接运行、二次开发与调试学习。已有2286人学习下载属于小巧实用的工业通信入门资料。通过示例工程与编译产物读者可以直观了解NModbus在C#中的调用方式、从站与主站工程结构以及RTU/TCP报文差异的实际处理逻辑。目录包含NModBus.Master、NModBus从站等工程适合作为工业通信开发的基础模板。1. C# NModbus 到底帮你省了什么从设备手册到代码的典型开场很多做上位机开发的工程师第一次碰 Modbus 都是同一个场景设备手册里甩给你一张寄存器表厂家示例用 C 写的而你手上只有 C#。自己拼报文要处理 CRC、功能码、异常码调试两天还可能因为字节序翻车。C# 侧的 NModbus 把整套 RTU/TCP 协议栈封装成了几个方法调用你只需要填从站地址、起始地址、数据长度剩下的帧组装和校验都在库里完成。这篇按做 Modbus 采集最常见的路径走先跑通最小读操作再接入 TCP、处理写操作和浮点转换最后是现场踩坑记录和一套可复用的轮询封装。适合刚接手采集项目的开发者也适合正在排查偶发超时的熟手。2. 先跑通 RTU 最小项目NModbus 读从站保持寄存器的完整代码串口 RTU 是工业现场成本最低的接入方式很多电表、温控器、PLC 都支持。这一章用最小代码把数据读出来同时把 NModbus 的库选型和几个核心参数讲清楚。你跟着敲完就能在自己的机器上看到真实设备数据。2.1 项目选型NModbus 原版与 NModbus4 维护分支的差别在 NuGet 上直接搜 NModbus会出现两个名字很像的包。早期 NModbus 版本更新慢对新的 .NET 框架兼容范围窄社区里被用得更多的维护分支是 NModbus4API 基本上一致命名空间也没有变。新项目直接选这个分支省去后面换包的麻烦。还需要补一个包System.IO.Ports。.NET Core 和 .NET 5 以上框架操作串口不再默认带上要用 NuGet 单独安装。新建项目后执行dotnet add package NModbus4 dotnet add package System.IO.Ports安装完核心代码只需要两个命名空间Modbus.Device放 Master 和 Slave 的对外类Modbus.IO放底层传输实现。日常使用主要在Modbus.Device下操作IModbusMaster接口不用关心Modbus.IO内部怎么搬运数据。2.2 最小读操作读回四个保持寄存器新建一个控制台项目写入下面代码。这段代码的目标是连上 COM3 口的从站设备读取从站地址 1、起始地址 0 起的 4 个保持寄存器。using System.IO.Ports; using Modbus.Device; // 1. 创建并打开串口 using var port new SerialPort(COM3, 9600, Parity.None, 8, StopBits.One); port.ReadTimeout 1000; port.WriteTimeout 1000; port.Open(); // 2. 通过工厂创建 RTU Master var factory new ModbusFactory(); IModbusMaster master factory.CreateRtuMaster(port); // 3. 从站参数地址 1起始寄存器 0读 4 个 byte slaveId 1; ushort startAddress 0; ushort count 4; // 4. 读保持寄存器内部自动完成报文组装和 CRC ushort[] values master.ReadHoldingRegisters(slaveId, startAddress, count); Console.WriteLine(string.Join(, , values));这段代码的逻辑分四层。前两步是资源准备SerialPort 负责物理链路CreateRtuMaster把串口包装成 Modbus 主站。第三步是业务参数slaveId 对应设备上的从站地址拨码或者配置项。第四步是核心调用ReadHoldingRegisters对应 Modbus 功能码 0x03返回的是ushort[]每个元素是 16 位无符号数直接反映了设备内部寄存器值。参数上注意ReadTimeout和WriteTimeout。很多设备响应慢默认的超时可能不够但也不要设得太大否则设备掉线时排查会变得很煎熬。我一般把读超时放到 1000 到 2000 毫秒轮询周期另算。2.3 三个必调参数从站地址、起始地址与串口参数第一次跑通之后你会发现几乎所有问题都出在三个地方。第一个是从站地址。设备如果没有正确握手主站发的请求会石沉大海结果就是读超时。先把设备手册翻出来确认拨码或软件配置的地址一般范围是 1 到 2470 是广播地址用于写操作时对全部从站下发正常采集不要用。第二个是起始地址。这里有个高频翻车点很多 PLC 手册写的是 40001、40002 这类地址而 Modbus 协议帧里用的是偏移量。40001 对应协议里的 040002 对应 1。直接把 40001 传进startAddress会从错误的位置开始读读回一堆看似正常但完全对不上的数据。第三个是串口参数组。波特率、数据位、校验位、停止位必须和设备端一致常见默认组合是 9600-8-N-1但现场经常遇到 19200 或偶校验的设备。参数不匹配时表现不是报错而是数据完全错乱或超时。可以用一个表格把常见组合放一起对照串口参数常见默认值说明波特率9600 / 19200与设备端一致查看手册或设备铭牌数据位8绝大多数设备固定 8校验位None / Even部分老设备用偶校验停止位1极少用 2先按默认尝试3. Modbus TCP 接入NModbus 连接管理与多从站轮询现在越来越多的设备支持以太网口尤其 PLC 和边缘网关。Modbus TCP 的 API 和 RTU 几乎一样物理链路变了但你在IModbusMaster上调用的方法没有变。这一章把 TCP 模式的最小代码、连接生命周期和多从站轮询模型讲透。3.1 TCP 与 RTU 的帧差异CRC 去哪了RTU 模式里每一帧都要在末尾追加 CRC 校验串口没有链路层的可靠机制全靠应用层保证。Modbus TCP 跑在 TCP 之上TCP 已经做了差错校验所以在帧结构里去掉了 CRC改成了 MBAP 报文头。MBAP 头包含事务 ID、协议 ID、长度和单元标识符每一条请求和响应用事务 ID 配对。这对使用者是好事。NModbus 内部帮你完成了这两件事RTU 模式下算 CRCTCP 模式下管理事务 ID 和响应匹配。你调用的方法和 RTU 一样传的从站地址在 TCP 帧里对应单元标识符。这也是我推荐用库而不是自己拼报文的原因自己做 MBAP 头的长度计算和 ID 配对非常容易出隐蔽 bug。3.2 最小 TCP DemoTcpClient 接入与释放顺序TCP 模式不需要 SerialPort改用TcpClient连接设备的 502 端口。代码结构如下using System.Net.Sockets; using Modbus.Device; using var tcpClient new TcpClient(); tcpClient.Connect(192.168.1.100, 502); tcpClient.ReceiveTimeout 2000; tcpClient.SendTimeout 2000; var factory new ModbusFactory(); IModbusMaster master factory.CreateTcpMaster(tcpClient); // 读从站 1 的输入寄存器功能码 0x04 ushort[] values master.ReadInputRegisters(1, 0, 8); Console.WriteLine(string.Join(, , values));CreateTcpMaster接收的是已经建立连接的TcpClient。注意这里的slaveId就是 MBAP 头里的单元标识符很多网关后面挂一批从站通过这个参数区分。ReadInputRegisters对应功能码 0x04读的是输入寄存器适合只读的测量值保持寄存器用ReadHoldingRegisters和上一章的用法一样。释放顺序值得单独说。NModbus 不同版本对TcpClient的拥有权处理不一样最稳妥的做法是统一接管释放先停掉所有正在进行的轮询再调用master.Dispose()最后关闭TcpClient。如果轮询线程还在跑你就先关了连接底层在读数据时可能抛IOException这个异常会掩盖真实问题干扰排查。提示TCP 超时和 RTU 超时是两套配置。TCP 用TcpClient.ReceiveTimeout和SendTimeout控制不要在串口参数里找 TCP 的超时设置。3.3 多从站轮询串行化请求与响应间隔一个 TCP 连接可以带多个从站轮询时在循环里切换slaveId就行。但有一个硬性约束同一个IModbusMaster实例不能并发发起请求必须串行。原因在于底层 transport 会复用同一个连接并发请求会把事务 ID 的配对打乱。常见的轮询骨架是这样var slaveIds new byte[] { 1, 2, 3 }; var cts new CancellationTokenSource(); while (!cts.IsCancellationRequested) { foreach (byte id in slaveIds) { try { ushort[] data master.ReadHoldingRegisters(id, 0, 10); // 按 id 存入对应的缓存对象 } catch (Exception ex) { // 记录日志标记该从站离线 } } await Task.Delay(100); // 给设备留出响应和处理时间 }轮询周期的设置要考虑现场设备的响应速度。你发一个请求设备处理完再回包通常需要几十毫秒如果设备逻辑比较慢100 毫秒的间隔都嫌短。轮询周期不要太激进我一般把间隔放在 100 到 500 毫秒之间具体在模拟从站上测一轮再定。设备数量多时每轮总耗时是所有从站响应时间之和这个值决定了你的采集上限。4. 写寄存器与浮点数NModbus 的写操作和字节序处理读数据只是第一步现场还需要下发控制指令和参数启停电机、设定温度、写入速度。NModbus 提供了一组写接口选择哪个接口取决于你写的是线圈还是寄存器以及是单点写还是批量写。4.1 写线圈与写寄存器不同控制场景的接口选择线圈对应布尔量适合启停和开关寄存器对应 16 位数值适合参数下发。最常见的三个写接口如下// 写单个线圈启动从站 1 的 0 号线圈 master.WriteSingleCoil(1, 0, true); // 写单个寄存器把转速 1600 写入从站 1 的 100 号寄存器 master.WriteSingleRegister(1, 100, 1600); // 批量写寄存器一次性下发三个参数 ushort[] data { 100, 200, 300 }; master.WriteMultipleRegisters(1, 200, data);WriteSingleCoil对应功能码 0x05WriteSingleRegister对应 0x06WriteMultipleRegisters对应 0x10。从帧格式看0x05 和 0x06 是单点写报文短执行快批量写适合初始化配置一次把一组参数下发减少交互次数。控制类操作尽量用单点写参数类操作用批量写。写操作之后要不要读回校验取决于设备类型。可控硅调功器和变频器这类设备写寄存器后通常需要读回确认。我会在写完重要参数后主动读一次和预期值比对不一致就记警告日志。虽然 Modbus 是请求响应式协议写失败会抛异常但设备固件可能写了寄存器但不生效读回校验能发现这类问题。4.2 32 位浮点写入大端帧与小端机器的转换设备手册里经常出现“温度是 32 位浮点占两个寄存器”。Modbus 协议规定多字节数据在帧内按大端传输也就是高字节在前。而 C# 跑在 x86 处理器的机器上BitConverter.GetBytes返回的是小端字节序。所以拿到 float 不能直接拆成两个寄存器发出去必须做一次字节序转换float temperature 23.6f; // BitConverter 按小端得到 4 字节 byte[] b BitConverter.GetBytes(temperature); Array.Reverse(b); // 反转为 Modbus 大端b[0] 是最高字节 // 按大端拆成两个 16 位寄存器 ushort[] registers new ushort[2]; registers[0] (ushort)((b[0] 8) | b[1]); registers[1] (ushort)((b[2] 8) | b[3]); master.WriteMultipleRegisters(1, 0, registers);Array.Reverse之后b 数组的顺序就是协议帧的字节顺序。然后每两个字节合成一个 ushort注意用移位而不是BitConverter.ToUInt16因为BitConverter.ToUInt16在小端机器上还会按小端解释字节容易再犯一次错。4.3 数据类型映射表寄存器组合与转换方式给寄存器赋值前先想清楚设备手册里的数据类型最常见的对应关系如下数据类型占用寄存器数转换方式特别说明16 位无符号1(ushort)value最基础16 位有符号1(short)value负温度值常见32 位无符号2(uint)high 16 | low注意组合顺序32 位有符号2先组合再BitConverter.ToInt32两端都要一致32 位浮点2字节序反转后按大端拆参考上一节代码字符串N逐字符写入寄存器通常每个寄存器存 2 个字符有符号数在读取时容易踩坑设备回 0xFFFF直接当 ushort 看是 65535但如果手册写的范围是 -32768 到 32767你就要先转成short再换算。这一行转换不写数据会在量程两端出现一堆离谱的跳变。5. NModbus 避坑指南从站不回包到数据错位的 5 个现场问题协议本身不复杂但现场问题总出在协议之外。这一章把我遇到过并且反复被同事问的五类问题按排查顺序列出来每条都是现象、原因、解决三步。你之后遇到同类问题直接照着这个顺序查能省很多时间。5.1 读超时异常从站不回包先查链路再查地址现象调用ReadHoldingRegisters抛出超时异常或者线程一直卡在调用上。读操作挂起不返回是串口和 TCP 模式下最常见的表现。原因可能性按频率排是从站地址不对、波特率或校验位不匹配、物理链路接触不良、设备忙不过来。先怀疑链路再怀疑配置因为链路问题会同时影响所有从站。解决第一步用串口调试工具看主站是不是发出了请求帧从站有没有回帧。如果发帧正常但不回把从站地址和串口参数逐项核对如果发帧都没看到检查接线和 COM 口有没有被其他程序占用。不要一上来就怀疑协议协议在这个库内部几乎不会错。5.2 数据全零或满量程跳变寄存器地址偏移现象请求不报错读回来要么全是 0要么是 65535 之类的满量程值偶尔还有点规律可循。原因这多半是把 PLC 地址直接当协议地址用。设备手册写“温度寄存器 40001”你以为传startAddress 40001实际协议里 40001 对应的偏移是 0你应该传 0。少算 1 个偏移在少数设备上影响不大但在数据区紧挨着控制区的设备上你会读到完全无关的寄存器。解决统一按“PLC 地址减去数据区起始号”换算。40961 就是偏移 040002 就是偏移 1。写一个地址换算函数把所有外部传入的地址先转成偏移再扔进 NModbus 调用避免散落在代码各处的 -1 操作。5.3 TCP 断线重连失败不要复用断开的 TcpClient现象设备断电重启或网线松动后程序循环重试但每次都在Connect或ReadInputRegisters上报异常重连永远不成功。原因断开的TcpClient内部状态可能已经损坏直接在原实例上重新Connect或继续用旧的IModbusMaster底层套接字的状态恢复不了。NModbus 的 TCP transport 持有对TcpClient的引用这个引用指向一个已断开的套接字。解决捕获到连接相关异常后把旧的master和tcpClient全部释放重新new一个TcpClient再建连接。不要试图复用一个已经死掉的客户端。这个过程用工厂方法封装最好重连失败时整个替换连接对象而不是打补丁。5.4 浮点数怎么换都不对CDAB 字节序现象按标准大端转换后数值不对经常是负号反转、指数乱跳的数字。比如读回来一个已经在合理范围外的温度值或者两个寄存器组合出来一个极其夸张的数据。原因标准 Modbus 大端顺序是 ABCD也就是高字在前低字在后但不少设备固件在双字处理时用的是 CDAB 顺序低 16 位字在前。看到浮点错乱先不要怀疑算法先确认设备手册写的字节序。我翻过不少设备的协议文档对双字的顺序基本都会有一句话定义。解决把字节序做成可配置的参数而不是写死在代码里。下面的代码支持 ABCD 和 CDAB 两种顺序按手册切换enum ByteOrder { ABCD, CDAB } static ushort[] FloatToRegisters(float value, ByteOrder order) { byte[] b BitConverter.GetBytes(value); Array.Reverse(b); // 转为大端b[0] 最高字节 ushort high (ushort)((b[0] 8) | b[1]); ushort low (ushort)((b[2] 8) | b[3]); return order ByteOrder.ABCD ? new[] { high, low } // 标准大端 : new[] { low, high }; // CDAB } static float RegistersToFloat(ushort[] regs, ByteOrder order) { byte[] b new byte[4]; if (order ByteOrder.ABCD) { b[0] (byte)(regs[0] 8); b[1] (byte)(regs[0]); b[2] (byte)(regs[1] 8); b[3] (byte)(regs[1]); } else { b[0] (byte)(regs[1] 8); b[1] (byte)(regs[1]); b[2] (byte)(regs[0] 8); b[3] (byte)(regs[0]); } Array.Reverse(b); // 大端转小端交给 BitConverter return BitConverter.ToSingle(b); }把转换函数集中放一个类里设备接入时在配置里注明字节序。这块属于那种一旦错了表现形式五花八门、查起来特别玄学的问题。别靠肉眼猜直接按手册配置。5.5 并发读写随机报错同一个 Master 必须串行现象程序里同时有两个调用点一个后台定时采集一个接口手动触发读取运行一段时间后随机抛IOException或读到错乱数据。原因NModbus 的IModbusMaster不是线程安全的。两个线程同时往同一个底层流写请求返回的响应会被另一个请求抢走事务 ID 匹配直接乱掉。问题只在特定时机出现所以特别难复现。解决给所有读写调用加锁或者把所有操作收敛到一个串行队列里。最简单的做法是把操作封装到一个带锁的方法里private readonly object _lock new object(); public ushort[] ReadSafe(byte slaveId, ushort start, ushort count) { lock (_lock) { return _master.ReadHoldingRegisters(slaveId, start, count); } }所有读和写都走ReadSafe保证同一时间只有一个请求在底层传输。注意锁要覆盖读和写因为读写共享同一个连接对象。如果用了异步接口改用SemaphoreSlim(1, 1)控制并发lock不方便用在 async 方法里。6. 从轮询变成订阅NModbus 边缘采集的封装与自测设备连接跑通以后剩下的问题就是怎么把采集做得稳定、不干扰业务代码。常见做法是把 NModbus 的读写和业务解耦后台一个循环负责采集写进缓存业务层只读缓存不直接碰设备。这样串口或 TCP 连接被锁住时UI 层不会被阻塞。public class Collector : IDisposable { private readonly IModbusMaster _master; private readonly ConcurrentDictionarybyte, ushort[] _cache new(); private CancellationTokenSource _cts new(); public async Task Start() { _cts new CancellationTokenSource(); var ct _cts.Token; await Task.Run(async () { while (!ct.IsCancellationRequested) { try { ushort[] data _master.ReadHoldingRegisters(1, 0, 10); _cache[1] data; await Task.Delay(200, ct); } catch (Exception) { _cache[1] null!; // 用空值标记离线 await Task.Delay(1000, ct); } } }, ct); } }缓存写入用ConcurrentDictionary后读线程之间不会互相阻塞。采集失败时把缓存置空比抛异常更安全业务侧读到空值就知道设备离线界面可以显示灰色状态。重试机制要加退避不要每次失败都以 200 毫秒的间隔无限打。用一个连续失败计数器失败次数越多间隔越长第一次失败等 1 秒第二次 2 秒最多退到 10 秒。一旦读成功就清零计数。这个策略能在设备掉线时保住 CPU 和串口资源恢复后又能及时重新接到数据。自测阶段最省事的办法是找一款从站模拟器把寄存器表配成手册上的值主站连上去读。验证地址换算和字节序是否和手册一致再改主站程序。如果你不想依赖外部工具NModbus 自己也提供从站端类可以在程序里起一个模拟从站做回环测试。这套采集循环和字节序封装的组合帮我少跑了好几次无谓的现场。希望帮到你。本文还有配套的精品资源点击获取