简介这是一套基于TCP的Modbus通信协议的C#实现源码包定位清晰服务于工业自动化领域需要与PLC等设备进行网络数据交换的开发人员也适合正在学习Modbus TCP组网与C#网络编程的读者。压缩包共46个文件整体仅148KB包含4个.cs源文件、4个.exe与4个.dll编译产物以及sln/csproj工程配置、xml注释、chm帮助和调试符号等目录结构简洁便于直接打开工程阅读或编译运行。代码围绕Modbus_TCP_class_demo展开覆盖TcpClient连接管理、请求报文构造、NetworkStream收发、响应解析、异常处理及async/await异步通信等关键环节并涉及输入寄存器、线圈状态等不同类型数据的解析要点还给出工业网络不稳定场景下的重试思路。资料已有1070人浏览学习通过源码调试可快速理解工业设备数据交换的完整链路适合入门与中级开发者作为实战参考。1. 用C#写Modbus TCP先搞清楚协议再动手做上位机和设备联调十次里有八次会遇到Modbus TCP。你拿着C#写控制界面设备那边是PLC、仪表或者网关两边要交换寄存器数据而Modbus TCP就是它们之间最省事的公共语言。这个标题的核心就是在C#里自己实现一套基于TCP的Modbus客户端不依赖收费控件自己把报文拼出来、发出去、解回来。很多朋友上来就搜“C# Modbus TCP源码”拿到手却不会改因为看不懂报文结构也不清楚地址是从0还是从1开始。其实协议本身非常薄核心就是一份固定格式的请求帧和响应帧。真正让你翻车的不是协议而是TCP连接细节粘包、半包、超时、断线重连以及从站设备返回异常时你怎么把错误码翻译成人话。这篇笔记按实际开发顺序来先把Modbus TCP报文拆明白再给出可直接复用的C#客户端源码然后说说调试工具怎么配合用最后把我踩过的坑集中列出来。适合已经在做上位机、想摆脱闭源库约束的C#开发者新手跟着走也能独立跑通一个最小实例。2. Modbus TCP报文结构从三次握手到功能码真正要背的没几行2.1 MBAP头7个字节里藏了事务和单元标识Modbus TCP和串口Modbus RTU最大的区别就是少了CRC校验多了MBAP头。MBAP头总共7字节依次是事务处理标识2字节、协议标识2字节、后续长度2字节、单元标识1字节。这个头决定了TCP层怎么把连续的字节流切成一条条完整报文。第一次写的时候我在想既然Modbus TCP跑在TCP上TCP已经保证数据不丢不乱序了为什么还要事务标识因为同一个TCP连接里可能同时发出多条请求响应不一定是按顺序回来的。事务标识就是用来匹配请求和响应的。你发出请求时把它设成0x0001响应帧里也会带回0x0001多线程轮询时靠它来分发结果不用锁也能避免串数据。协议标识固定为0x0000Modbus协议规定死。如果设备返回的不是0x0000那它很可能不是标准Modbus或者你的字节序搞反了。后续长度是从单元标识开始往后数剩余的字节数等于寄存器地址、寄存器数量、字节数加上数据区。你不需要手算在C#里用ushort直接拼接就行但要记住它是按大端序high byte在前放在报文里的。单元标识就是串口Modbus里的从站地址。总线型串口靠这个区分设备而Modbus TCP通常一个IP只对应一个设备所以很多人直接写0x01或0xFF。但要注意如果前面挂了一个Modbus TCP转串口网关网关后面接了多个RTU从站这时候单元标识就必须和后面从站地址一致。我在现场遇到过网关后面挂了3块电表把单元标识全写成1结果网关只返回第一块表的数这种错很容易被当成“设备坏了”折腾一下午。2.2 功能码与寄存器地址从0开始还是从1开始Modbus功能码是协议里最值得先背的几个读取保持寄存器用0x03读输入寄存器用0x04写单个保持寄存器用0x06写多个保持寄存器用0x10。寄存器地址怎么编号是这个协议最折磨人的地方没有之一。协议层寄存器地址永远是16位从0x0000到0xFFFF。但设备说明书上写的地址往往是从1开始的比如“保持寄存器40001对应地址0”“40002对应地址1”。也就是说设备厂商为了沿用早期数据表习惯把第一个寄存器叫40001映射到协议地址却是0x0000。你在C#里发请求时地址字段应该填寄存器索引值减1。反过来也有厂家文档直接写“寄存器地址2000”那这2000就是协议里的0x07D0你直接填进去就行。最稳的做法是问设备技术支持文档里的地址是按1还是按0他们心里有数。别信代码注释里“地址要加1”的贴吧说法。我的做法是在客户端方法接收“协议地址”调用方自己负责换算这样库这边永远不猜。功能码0x03的请求帧结构是这样的MBAP头7字节 功能码1字节 起始地址2字节 寄存器数量2字节。比如读地址0开始的两个寄存器完整报文是00 01 00 00 00 06 01 03 00 00 00 02。其中06是长度01是单元标识。响应帧则是MBAP头 功能码 字节数 寄存器数据。数据按大端序排列一个寄存器占两个字节你拿到byte[]后要自己BitConverter拼接并处理字节序。2.3 异常响应把错误码变成可读信息设备收到请求但执行不了不会不发数据而是回一个异常帧。异常帧的MBAP头一样功能码会把原功能码最高位置1比如读保持寄存器变成0x83后面跟一个异常码。实际调试中90%是地址越界、功能码不支持、非法数据值这几种。常见异常码对照表我建议直接放进代码里01表示非法功能02表示非法数据地址03表示非法数据值04表示从站设备故障。还有05接受、06忙但极少见。C#客户端解析时如果收到功能码高位为1的帧就抛一个ModbusException把异常码翻译成中文。这样和PLC对联时你看到“地址越界”就知道是寄存器地址算错了而不是瞎猜。网络抓包时还有个细节某些老设备对CRC错误不敏感但对超长报文会很暴躁。Modbus TCP最大PDU长度是253字节如果一次读的寄存器数量太多超过126个每个寄存器2字节部分从站会直接拒绝请求。我习惯把单次读取数量限制在120以内既安全又不会触发设备的PDU上限。这个参数在后面的源码里会直接暴露出来。3. 用C#封装Modbus TCP客户端忍得住不用第三方库源码自己写才放心3.1 连接管理用TcpClient还是原生SocketC#里做TCP连接我看到过两种极端一种直接用TcpClient满足一切另一种非要用Socket套一堆异步状态机。对一个Modbus客户端来说TcpClient完全够用它内部就是Socket的封装只是替你把流式读写、超时配置都简化了。你真正需要自己管理的是连接生命周期和断线重连而不是纠结底层API。我一般写一个ModbusTcpClient类构造函数接收IP、端口和超时时间。连接时用TcpClient.ConnectAsync端口固定502但如果现场被占用了也可能映射到其他端口所以端口写成参数。连接后把TcpClient.NoDelay设为true这是为了减少Nagle算法造成的延迟——Modbus报文很小Nagle会把多个小包攒在一起才发对实时轮询来说等于人为加了几十毫秒延迟。超时控制是TcpClient的坑。ConnectionTimeout和ReadTimeout设置的是同步方法但如果你用GetStream().ReadAsync()超时设置依然有效不过一旦超时网络流会进入不确定性状态。我的做法是任何读写操作如果抛IOException或SocketException直接关闭当前TcpClient置为未连接状态下次调用时自动重连。不要想着“是不是还能抢救一下”TCP断掉以后流对象几乎没法恢复与其在这上面花时间不如让重连逻辑更可靠。连接管理里还要处理“假连接”。设备重启或网线闪断后TCP连接在本地还处于Established状态但你发数据会发现对方没反应直到超时才报错。所以客户端里要维护一个最近通信时间戳每次收发都更新。轮询线程如果发现超过N秒没有成功通信主动断开重连。这个机制在PLC掉电重启后特别有用不然你的上位机会一直显示“已连接”数据却是死的。3.2 功能码实现读保持寄存器、写单个、写多个核心方法我封装成三个ReadHoldingRegisters、WriteSingleRegister、WriteMultipleRegisters。每个方法内部都走同一个流程构造请求帧、发送、等待响应、校验MBAP、解析数据。这样后续扩展新功能码时只需要加一个BuildRequest方法。读保持寄存器的代码我已经在多个项目里复用过按下面这样写就能跑通public async Taskushort[] ReadHoldingRegistersAsync(byte unitId, ushort startAddress, ushort count, CancellationToken ct default) { const byte functionCode 0x03; if (count 120) throw new ArgumentOutOfRangeException(nameof(count), 单次最多读120个寄存器); var request BuildRequest(unitId, functionCode, startAddress, count, null); var response await TransactAsync(request, ct).ConfigureAwait(false); // 校验功能码异常帧由TransactAsync抛出 int byteCount response[8]; // 响应帧里功能码后的第一个字节是数据字节数 if (byteCount ! count * 2) throw new ModbusException(返回的寄存器数量与请求不一致); var result new ushort[count]; for (int i 0; i count; i) { // 大端字节序高字节在前 result[i] (ushort)((response[9 i * 2] 8) | response[10 i * 2]); } return result; }BuildRequest负责拼MBAP头和功能码。事务标识用一个自增字段每发一条请求就加一溢出就归零。拼长度时注意MBAP头里的长度字段是从单元标识开始算的所以请求帧的长度恒等于单元标识1字节功能码1字节地址2字节数量2字节6。写多个寄存器时长度会变因为要带数据段。private byte[] BuildRequest(byte unitId, byte functionCode, ushort startAddress, ushort quantity, byte[] data) { using var ms new MemoryStream(); ushort transactionId unchecked((ushort)(_transactionId 0xFFFF)); ms.WriteByte((byte)(transactionId 8)); // 事务标识高字节 ms.WriteByte((byte)(transactionId 0xFF)); ms.WriteByte(0x00); // 协议标识高字节 ms.WriteByte(0x00); // 协议标识低字节 // 长度字段稍后写因为需要先计算后续字节数 int lengthIndex 4; ms.WriteByte(0x00); ms.WriteByte(0x00); ms.WriteByte(unitId); ms.WriteByte(functionCode); ms.WriteByte((byte)(startAddress 8)); ms.WriteByte((byte)(startAddress 0xFF)); ms.WriteByte((byte)(quantity 8)); ms.WriteByte((byte)(quantity 0xFF)); if (data ! null) { ms.Write(data, 0, data.Length); } // 回填长度字段后续所有字节数 int length (int)ms.Length - lengthIndex - 2; var buffer ms.ToArray(); buffer[lengthIndex] (byte)(length 8); buffer[lengthIndex 1] (byte)(length 0xFF); return buffer; }TransactAsync负责发请求、读响应、校验。关键点是一次请求必须读够一整条响应帧才能返回。Modbus TCP响应帧的最小长度是7字节MBAP头1字节功能码1字节异常码或2字节数据起始。你要先读6个字节拿到MBAP头从长度字段算出还差多少字节再继续读剩余部分。这就是处理TCP粘包半包的统一套路别指望NetworkStream.Read一次就能给你完整帧。3.3 发送与接收处理粘包半包的统一套路如果直接把请求写到流里就BeginRead你一定会被并发的响应和拆包搞得头皮发麻。Modbus TCP比RTU好的地方是有明确长度字段这让你可以用“先包头后包体”的方式收数据。读取响应的逻辑我放在TransactAsync里用ReadExactAsync这个辅助方法循环读直到填满指定长度的缓冲区。第一次读固定7字节的MBAP头然后从第4、5字节解出长度字段再据此读剩余字节。这里有个细节长度字段本身包含单元标识、功能码、数据和校验所以实际剩余字节数为 length - 1。加上MBAP头7字节总共收到 7 length 字节才是完整帧。校验响应时先看事务标识是否和请求一致再看协议标识是否为0最后看功能码高位。如果响应功能码是0x83这类就把后面的异常码提出来抛ModbusException。到这里你就有了一套不依赖任何库的Modbus TCP通信核心。private async Taskbyte[] TransactAsync(byte[] request, CancellationToken ct) { if (_tcpClient null || !_tcpClient.Connected) EnsureConnectedAsync(ct).Wait(ct); var stream _tcpClient.GetStream(); await stream.WriteAsync(request, 0, request.Length, ct).ConfigureAwait(false); await stream.FlushAsync(ct).ConfigureAwait(false); var header await ReadExactAsync(stream, 7, ct).ConfigureAwait(false); ushort length (ushort)((header[4] 8) | header[5]); var body await ReadExactAsync(stream, length - 1, ct).ConfigureAwait(false); var full header.Concat(body).ToArray(); // 事务标识匹配 ushort respTrans (ushort)((full[0] 8) | full[1]); ushort reqTrans (ushort)((request[0] 8) | request[1]); if (respTrans ! reqTrans) throw new ModbusException($事务标识不匹配: 请求{reqTrans}响应{respTrans}); // 协议标识 if (full[2] ! 0 || full[3] ! 0) throw new ModbusException(协议标识非0不是标准Modbus TCP); // 功能码异常 byte func full[7]; if ((func 0x80) ! 0) { byte errCode full[8]; throw new ModbusException($Modbus异常响应 功能码0x{func:X2} 错误码{errCode}: {GetErrorMessage(errCode)}); } return full; }这段代码里用到Wait(ct)的地方实际正式代码应该全部用async/await贯穿。我在这里写同步等待只是为了让你看清逻辑真项目里不要这么干后面会讲怎么用Task框架做真正异步。4. 用Modbus Poll和Wireshark验证你的C#客户端数据对不上先抓包再改代码4.1 用Modbus Poll当从站新建连接、设从站ID和地址写完客户端第一个想验证的对象不是PLC而是Windows上跑一个Modbus Poll。这软件既能当主站又能当从站。切到从站模式Modbus Slave更合适你开一个TCP端口502手动填一堆寄存器值然后让C#客户端去读。如果你的客户端能读出来再和Wireshark抓的包对比逻辑就通了一半。Wireshark抓本地回环包要先装Npcap并勾选“允许回环”。打开Wireshark选Adapter for loopback traffic capture过滤条件写tcp.port 502。然后启动Modbus从站问题是Windows上502端口经常被系统服务占用你可以把从站端口改成5020客户端IP填127.0.0.1端口5020。别在端口上耗时间。从站设置里你要留意两个复选框一个是“从功能码自动生成地址映射”另一个是“字节序”。我通常把从站地址设成1功能码0x03的保持寄存器区填几个已知值比如地址0填1234地址1填5678。这样C#客户端读出来如果正好是这两个数说明地址和字节序都对了。如果读出来是4660和35313那就是字节序反了——4660就是0x1234高字节后置的结果。4.2 抓包验证三次握手和每一帧报文用Wireshark抓到的包能直接对Modbus TCP做分层分析。你抓一次完整通信能看到TCP三次握手SYN、SYN-ACK、ACK然后是你的请求帧和设备的响应帧。Wireshark认出了Modbus TCP协议后会把MBAP头拆成Transation Id、Protocol Id、Length、Unit Id寄存器地址和数量也一并显示。这时候对比你的C#源码哪里拼错一目了然。注意看请求报文里的长度字段是不是6。我刚才说的BuildRequest里回填长度逻辑如果用MemoryStream在头部占位再回填很容易写成总长度而忘记要减2。我早期就是这样Wireshark报“Malformed Packets”一开始还以为是Wireshark问题后来才发现长度字段多算了2导致设备直接不响应。抓包能帮你把这类低级错误从“设备不回复”里区分出来。4.3 地址越界、非法功能、从站异常用从站把错误逼出来调试时故意制造异常是个好习惯。在Modbus从站里只配置少量寄存器然后客户端读一个大范围地址比如起始地址0读200个寄存器。请求发出后从站会回一个异常帧Wireshark里能看到功能码0x83、异常码0x02。你的C#客户端应该抛“非法数据地址”。如果客户端没抛异常而是卡死那多半是ParseException的代码没写好响应体只读了长度字段一半没读全就发解析。我用过一个取巧的验证方式让从站返回“非法功能”。找一个根本不存在的功能码发过去比如0x2B然后看异常帧结构。这样的好处是你能在代码里专门写一条单元测试喂进一个伪造的异常响应断言抛出的ModbusException的ErrorCode字段是不是2。不用真连设备也能测异常处理逻辑。5. 避坑C#实现Modbus TCP最容易翻车的5个问题5.1 字节序寄存器值读出来是个天文数字现象PLC里寄存器值明明是10C#读回来却是2560或者反过来。原因Modbus寄存器是大端序高字节在前低字节在后。C#的BitConverter在x86/x64架构上默认小端序你要是直接BitConverter.ToUInt16(byte[] index)拿到的地址是从低字节开始的结果就是对调了。解决手动按大端拼代码里写成 (byte[0] 8) | byte[1]。写多个寄存器时也一样要把ushort拆成高低字节顺序写入。我见过一些老库用System.Net.IPAddress.HostToNetworkOrder做转换也能用但不如直接位移直观也少一次转换开销。5.2 TCP粘包和半包读出来的报文错位现象连续快速读多个寄存器时隔几次读到一帧以错误事务标识开头的报文。原因NetworkStream不保证每次Read返回一条完整报文的字节。可能一次读了半条也可能一次读了好几条。如果直接按“读到多少算多少”来解析协议栈就崩了。解决用读超时和精确读取。我前面写的ReadExactAsync逼迫自己先读固定长度MQTT风格的头部然后按长度读包体。千万不要把一次Read循环到读到0就算完TCP不会给你0字节等待只会阻塞直到超时。所有Modbus TCP客户端都这么处理不是玄学。5.3 从站单元标识填错数据串了或根本没响应现象多台设备并联在一个IP的Modbus TCP网关后面读A设备返回B设备的数据。原因单元标识根本没有写在请求里或者全用了统一的1。Modbus TCP里的Unit ID在绕过网关、直连设备时看似可以忽略但只要网关是透明转发RTU的Unit ID就是决定性因素必须和背后从站的串口地址一致。解决规定客户端方法的unitId参数必填不允许默认1。从配置界面让用户填写即便现场只有一台设备也养成显式填号的习惯。写多个寄存器时尤其要小心写错Unit ID可能写到别的设备上比读错危险得多。5.4 并发请求和线程安全轮询任务打架现象用定时器同时轮询多组寄存器程序运行半小时后响应越来越慢偶尔报事务标识不匹配。原因多条请求复用同一个TcpClient和NetworkStream没有做串行化。TCP写入和读出的交错会导致响应帧错配——发了两条只收到一条下一轮的响应被本轮解析掉了。解决最简单的方案是封装一个SemaphoreSlim(1,1)让所有Modbus请求在同一个实例内部串行。这样虽然牺牲了并发吞吐但Modbus TCP本来就不是高并发协议单连接串行完全够用。如果你一定要并发就得为每个事务标识分配独立的TaskCompletionSource并让接收循环持续分发架构复杂度明显上升我的经验是普通上位机不值得。5.5 断线重连和死连接连接池不维护等于摆设现象PLC断电或网线松动后客户端显示“已连接”但读写全部超时。重连后第一次读写又失败要等多一轮。原因TCP连接断开后本地套接字不会立刻知道需要写入超时才会触发。而很多客户端只在连接建立时检查TcpClient.Connected这个属性在连接已经死亡但还没超时期间返回true导致你以为还能用。解决在客户端里放一个最后成功通信时间每次成功读写更新。轮询线程每回合检查这个时间和当前时间差超过设定阈值就执行Dispose重连。重连时不要立刻发数据先等地TCP握手完成再发第一条请求。我还在构造函数里加了ReconnectOnFailure选项默认关闭但实际现场都会打开。6. 进阶把客户端改成异步轮询服务并做协议健壮性验证到这一步你的ModbusTcpClient已经能单次读写寄存器了。但上位机最少要同时轮询几十个变量。如果按“建个Timer然后每100ms读一次”的写法第一个坑是当一次通信超时20秒Timer重入导致请求堆积内存爆掉。更稳的做法是把它包成后台轮询任务用Channel或观察者模式把数据推给UI。我常用的是System.Threading.Channels。定义一个Channel 后台一个专用任务循环每周期从通道里取任务串行执行读写结果发到UI。这样把Modbus轮询和界面刷新解耦界面再也不会因为等待网络而卡住。不要再写“异步空转Task.Delay”的裸循环玩坏了才后悔。关键代码其实就是把读写包进Channels里public async Task RunPollingAsync(CancellationToken ct) { var reader _channel.Reader; while (await reader.WaitToReadAsync(ct).ConfigureAwait(false)) { while (reader.TryRead(out var cmd)) { try { var result await ReadHoldingRegistersAsync(cmd.UnitId, cmd.StartAddress, cmd.Count, ct); _resultChannel.Writer.TryWrite(new RegisterReadResult(cmd.Tag, result)); } catch (Exception ex) { _errorHandler?.Invoke(cmd.Tag, ex); } } } }这个模式的优点是天然串行不会出现并发错帧缺点是单个从站响应慢会拖慢后续请求。所以调度参数要留两个轮询周期和单次读超时。如果一次通信耗时接近超时要主动把周期调大。做协议健壮性验证时不要只测“正常响应”。我给客户端加了个模拟TCPServer的单元测试用一个TcpListener在另一个线程监听收到请求后可以故意只回复半条报文、回复错误事务ID、回复协议标识非0、或回复异常码。这样能把TransactAsync里所有分支暴露出来尤其是超时路径。一测就发现原来ReadExactAsync在超时后没有把流关闭导致后续重连永远失败。后来我在ReadExactAsync的catch里强制Dispose把异常传给上层才算真正稳定。最后的常用习惯把Modbus报文日志做成开关默认关现场出问题打开后自动滚动保存到文件。不需要结构化日志一行一个请求、一行一个响应就够了出了事直接拉回来查比让用户截图快得多。我在现场排查“PLC偶发不响应”时就是靠这个日志配合Wireshark定位到是设备在特殊工艺段自动进异常状态不是客户端的问题。希望这些经验和代码对你有用。本文还有配套的精品资源点击获取