简介一份面向C#初学者的TCP客户端通信示例资源围绕System.Net.Sockets命名空间下的TcpClient类演示从创建连接、发送数据到接收响应、关闭连接的完整流程。适合正在学习.NET网络编程、希望掌握同步与异步Socket通信基础的开发者参考。资源为zip压缩包共31个文件以9个cs源码文件为主体辅以配置、资源、可执行文件及相关工程文件整体体积约51KB。目前已有7158人学习下载属于轻量且针对性较强的入门示例。压缩包内含完整的WinForms客户端窗体程序涵盖Form1.cs逻辑实现、Program.cs入口调用及项目工程配置。通过阅读和调试该项目可以直观理解NetworkStream的Write/Read方法、缓冲区设置与UTF-8编码转换而异步BeginConnect、BeginRead的代码写法也便于拓展学习。1. C# TcpClient 发送与接收别把“能连上”当成“能通讯”上一回调试某个工控上位机现场反馈“数据收不全”我盯着日志看了半小时最后发现不是设备的问题而是客户端把两次业务报文当成一条消息解析了。TCP 是个流协议没有消息边界C# TcpClient 的 Read 一次只返回当前缓冲区里已有的数据多少完全不可预期。这套源码包就是一个完整的 C# TcpClient 发送与接收客户端 Demo从建立连接、维护发送队列到开独立线程收数据、做拆包解码再到期保活和断线重连一条链路全给你打通。适合正在写上位机、网关采集程序或者刚接触网络编程、想把 TcpClient 收发逻辑一次写对的人。2. 工程结构与技术选型一个能跑的 TcpClient Demo 由哪些文件组成2.1 从 .NET Framework 到 .NET 8不同环境下 TcpClient 的差异这份源码包以 .NET 8 WPF 为主工程。为什么不是 .NET Framework接手过老上位机的人应该深有体会很多工控主机还跑在 Framework 4.x 上但那套代码里最头疼的不是 TcpClient 本身而是异步模型和内存管理。.NET 8 对异步 IO 的支持更顺手Span 和 Memory 可以直接用在拆包逻辑里不用频繁 ToArray 拷贝。写协议解析的时候我最怕的就是每收一个包就产生一堆中间字节数组GC 压力会肉眼可见地涨。如果你要把代码放回老工程两个 API 差异需要同步改一个是 ConnectAsync 在 Framework 4.7.2 里没有 ValueTask 版本返回的是 Task方法名不用变另一个是 NetworkStream.ReadAsync 在 Framework 里只支持 byte[]不支持 Memory拆包时得手动管理缓冲区偏移。这份 Demo 里我刻意把协议解析这类纯算法逻辑独立成类不依赖 UI 层也不依赖高版本 API切回 Framework 时只要把异步读写的地方换成 byte[] 重载就能跑。工程切换目标框架时要注意WPF 在 .NET 8 下需要打开 SDK 风格的 csprojTargetFramework 写 net8.0-windows。老工程如果还是旧式 csproj 格式项目引用会报兼容性错误。常见做法是先新建一个 net8.0-windows 的 WPF 工程把源码包里的 .cs 文件拖进去而不是在旧工程上直接改版本号。同步接收和异步接收怎么选也是很多新手纠结的地方。我的习惯是业务简单、报文频率低用同步阻塞的 Read 包在线程里循环逻辑直白异常好定位报文频率高、需要和 UI 或业务系统联动就全链路 async。Demo 里我用的是异步但连接状态事件仍然通过 observer 接口同步回调避免异步上下文把调用链搞乱。2.2 项目目录结构与核心类职责以下是 Demo 的目录结构我用它说明每个类在整条链路里的位置。拿到源码包后你会看到这么一组文件TcpClientDemo/ ├── App.xaml / App.xaml.cs # WPF 入口 ├── MainWindow.xaml # 演示界面IP/端口/日志/发送区 ├── MainWindow.xaml.cs # 界面交互调 TcpClientService ├── Core/ │ ├── TcpClientService.cs # 客户端核心封装连接/发送/接收线程 │ ├── FrameDecoder.cs # 粘包半包解码器输出完整业务帧 │ ├── MessageParser.cs # 完整帧 - 业务对象的字段解析 │ ├── NetConfig.cs # IP、端口、心跳/超时/重连配置 │ └── IConnectionObserver.cs # 连接状态观察接口 ├── Protocol/ │ ├── PacketHeader.cs # 帧头长度定义与校验 │ └── MessageTypes.cs # 业务消息类型枚举 └── TestServer/ └── TcpServerSimulator.cs # 本地回环测试服务端用于验证各文件之间是单向依赖MainWindow 只依赖 Core 里的 TcpClientServiceTcpClientService 把收到的原始字节交给 FrameDecoderFrameDecoder 拆出完整帧后由 MessageParser 转成业务对象NetConfig 是一个纯配置类。下面把 TcpClientService 的连接、发送、接收三块分开讲FrameDecoder 单独放到第 4 章展开因为拆包这块值得单独说。2.3 通讯协议约定帧头 长度 正文的设计思路TCP 是字节流接收到的数据没有边界所以通讯双方必须先约定成帧格式。这份 Demo 里用的是一个最通用的长度前缀协议帧格式如下字段大小说明帧头2 字节固定 0xAA 0x55用于同步定位长度2 字节USHORT 小端表示正文长度不含帧头与长度字段自身正文N 字节业务数据最长 65535 字节外加一个可选的 1 字节校验位。帧头为什么不用 1 字节因为单个字节在报错重传、噪声干扰下容易误触发2 字节固定值把误判概率降了几个数量级。长度字段放在帧头后面解码器可以先读两个字节等缓冲区的字节数到达 length 再取出整帧这就是第 4 章要讲的解帧依据。正文内部再细分 MessageType Data 两部分MessageTypes 枚举里定义了 PING、PONG、DATA、ACK 四种类型。PING/PONG 是心跳报文正文可以为空DATA 里放业务数据ACK 用于某些需要确认的消息。设计上我把协议层拆成 Packet 和 Message 两级Packet 解决的是“拿一条完整的字节帧”Message 解决的是“这条帧是什么业务语义”两层各改各的互不影响。如果你要对接的第三方设备协议不是自己定的常见做法是先抓一份真实报文把帧头、长度、字节序画出来再去调 FrameDecoder 的分帧逻辑。这个动作我后面写进了自己的开发流程省掉了大量现场排查时间。3. 核心模块拆解连接管理、发送队列与接收线程的三段式设计3.1 连接管理TcpClient 与 NetworkStream 的建立和状态感知public async Taskbool ConnectAsync(CancellationToken ct) { try { _client new TcpClient(); _client.NoDelay true; // 禁用 Nagle实时场景优先低延迟 _client.ReceiveBufferSize 64 * 1024; // 接收缓冲别随意调大 _client.SendBufferSize 64 * 1024; using var timeoutCts CancellationTokenSource.CreateLinkedTokenSource(ct); timeoutCts.CancelAfter(_config.ConnectTimeoutMs); await _client.ConnectAsync( IPAddress.Parse(_config.RemoteIp), _config.RemotePort, timeoutCts.Token); _stream _client.GetStream(); _stream.ReadTimeout _config.ReadTimeoutMs; _stream.WriteTimeout _config.WriteTimeoutMs; IsConnected true; StartReceiveLoop(); _observer?.OnConnected(); return true; } catch (OperationCanceledException) { _observer?.OnConnectFailed(连接超时); return false; } catch (SocketException ex) { _observer?.OnConnectFailed($Socket错误: {ex.SocketErrorCode}); return false; } }这段代码是客户端链路的起点。NoDelay 要置为 trueTCP 默认启用 Nagle 算法会把小包攒到一起发对心跳和短报文来说延迟明显如果业务允许也可以试试默认值但工控场景里大多数都是关掉。BufferSize 设为 64KB 是常见值接收缓冲区太大反而会让解码器等更久才凑齐数据。ReadTimeout 和 WriteTimeout 是同步流才有的属性异步读写时超时靠 CancellationToken 控制这里两套方式都保留了。连接失败要区分“超时”和“被拒”。超时是 IP 可达但没握手成功被拒通常是端口没监听或防火墙拦了。生产环境里我会把 SocketErrorCode 记进日志排查时一眼能看出是哪一类。3.2 发送通道ConcurrentQueue 做发送队列避免多线程写同一个 NetworkStreamprivate readonly ConcurrentQueuebyte[] _sendQueue new(); private readonly SemaphoreSlim _sendSignal new(0); public void Send(byte[] data) { if (!IsConnected) return; // 简单校验重连场景在服务层处理 _sendQueue.Enqueue(data); _sendSignal.Release(); } private async Task SendLoopAsync(CancellationToken ct) { while (!ct.IsCancellationRequested) { await _sendSignal.WaitAsync(ct); if (!_sendQueue.TryDequeue(out byte[] data)) continue; try { await _stream.WriteAsync(data, ct); await _stream.FlushAsync(ct); } catch (Exception) { // 写失败说明链路已不可用交给断线重连逻辑统一处理 break; } } }为什么不用 locklock 语法本身没问题但发送逻辑里可能有异步写lock 不能跨 await硬套 lock 会让代码到处都是锁块。ConcurrentQueue 加 SemaphoreSlim 是 .NET 里比较顺手的组合入队和出队天然线程安全信号量只在有数据时唤醒发送线程。Send 方法可以被任意业务线程调用真正的 Write 永远只发生在 SendLoopAsync 这一个线程里从根上避免两个线程同时 Write 导致报文交叉。参数上要注意SemaphoreSlim 的 Release 次数必须和 Enqueue 次数一一对应否则要么线程空转要么信号耗尽卡住。这里的 Send 在 IsConnected 为 false 时直接 return信号量不会泄漏但如果你想在断线时也把数据暂存就要把 Enqueue 放到 return 判断之前同时保证 OnDisconnected 时清空队列并且把信号量里的残余计数吸干净。断线重连后发送线程卡死的案例多半就是信号量里还残留着旧数据的计数。3.3 接收线程持续读取与数据回调private async Task ReceiveLoopAsync(CancellationToken ct) { byte[] buffer new byte[4096]; while (!ct.IsCancellationRequested) { int readCount; try { readCount await _stream.ReadAsync(buffer, ct); } catch (Exception) { break; // 读异常视同断开 } if (readCount 0) // 对端正常关闭 { break; } FrameDecoder.Feed(buffer.AsSpan(0, readCount)); foreach (var frame in FrameDecoder.TryDecode()) { var message MessageParser.Parse(frame); _observer?.OnDataReceived(message); } } IsConnected false; _observer?.OnDisconnected(); }ReadAsync 返回 0 是 .NET 里判断对端关闭的标准方式它不抛异常但要是忘了处理接收线程会变成 0 字节忙转的 CPU 空转。4096 的缓冲区是初始值真实一帧可能超过这个大小所以解码器不能假设一次 Read 就是一条帧必须做累积缓存。Feed 负责把字节追加到内部缓冲TryDecode 返回所有已解出的帧这样无论包怎么粘、怎么拆一次 Read 都能产出 0 到多帧完整数据。这里我把 MessageParser 的解析放在接收线程里会出现一个问题如果业务处理逻辑耗时接收线程会被拖慢严重时缓冲区溢出。常见做法是 OnDataReceived 事件里做轻量处理复杂业务一律丢到独立任务队列。回调和 UI 的跨线程问题在第 5 章会专门展开。4. 拆包与粘包处理从底层字节流到完整业务报文4.1 为什么必须处理粘包、半包TCP 从底层看是字节流发送端两次 Send 的数据接收端不一定对应两次 Read。因为数据会被下层按 MTU 大小切片也会因为缓冲合并。曾经某个数据采集项目里设备每隔 50ms 发一条状态帧客户端经常遇到一个 Read 里包含 3 条完整帧或者一条帧被切成两半的情况。没有解码器的话MessageParser 去取长度字段就会取错位置。粘包是正常的物理现象不是程序 bug需要靠应用层协议主动解帧。UDP 是一包一收很多从 UDP 转过来的人天然带着“一次接收就是一条完整消息”的思维这个惯性在 TCP 里会踩大坑。TCP 只保证“我发的字节你能收到且顺序不变”不保证“一次收的量和一次发的量相等”。4.2 帧解码器 FrameDecoder缓存累积与长度前缀解帧public sealed class FrameDecoder { private readonly Listbyte _buffer new(); private const int HeaderLength 4; // 帧头2字节 长度2字节 public void Feed(ReadOnlySpanbyte data) { foreach (var b in data) _buffer.Add(b); // 追加到累积缓冲 } public Listbyte[] TryDecode() { var result new Listbyte[](); while (_buffer.Count HeaderLength) { if (_buffer[0] ! 0xAA || _buffer[1] ! 0x55) { // 没找到帧头丢弃第一个字节继续找 _buffer.RemoveAt(0); continue; } int bodyLength _buffer[2] | (_buffer[3] 8); int totalLength HeaderLength bodyLength; if (_buffer.Count totalLength) { break; // 数据还不够等下一次Feed } byte[] frame _buffer.GetRange(0, totalLength).ToArray(); _buffer.RemoveRange(0, totalLength); result.Add(frame); } return result; } }整个解码器的核心就是“找帧头、读长度、凑够再取”。找不到帧头时一次只移除一个字节极端情况下如果链路噪声很大性能会差一些但设备通讯场景里数据量也就几 KB 每秒完全够用。对端如果出现帧头错位这个机制会自动重新同步不会让整个后续报文全废。几个值得注意的点第一bodyLength 是大端还是小端取决于对端这份协议用的标准小端改字节序时注意 Reverse第二长度字段最好加上一个上限约束防止对端把 length 写成 65535 造成内存分配被撑爆第三GetRange 和 RemoveRange 是 O(n) 操作高频收发时可以换成环形缓冲但逻辑复杂度会上去等真到了压测瓶颈再优化也不迟。4.3 心跳与半开连接检测多久没数据判定为掉线private async Task HeartbeatLoopAsync(CancellationToken ct) { while (!ct.IsCancellationRequested) { await Task.Delay(_config.HeartbeatIntervalMs, ct); if (!IsConnected) continue; if (DateTime.UtcNow - _lastReceivedTime _config.HeartbeatTimeoutMs) { _observer?.OnHeartbeatTimeout(); CloseSocket(); // 强制关闭触发重连 break; } Send(PacketBuilder.BuildPing()); } }心跳要做的是“最终一致性”客户端定期发 PING服务端回 PONG客户端记录最近一次的 _lastReceivedTime。每次收到任何数据都更新这个时间戳比只认 PONG 更稳因为业务数据同样能证明链路还活着。HeartbeatTimeoutMs 要比 HeartbeatIntervalMs 大一般配 3 到 5 倍比如间隔 10 秒、超时 30 秒这样偶尔丢一个两个包也不会误判。半开连接的检测是心跳最大的价值。局域网里路由器重启、对端应用崩溃但不关闭 socketTCP 层面不会立刻通报。只靠 Send 前的 Connected 属性判断是无效的那只是“曾经连过”的状态不代表当下可用。心跳超时触发 CloseSocket然后由外部监听 OnDisconnected 事件做重连动作。重连间隔建议用指数退避避免对端没恢复时客户端高频发起连接把端口打爆。提示心跳超时阈值不要设成和心跳间隔一样大否则一次瞬时丢包就触发重连日志会被刷爆。5. 避坑与常见问题排查TcpClient 开发中的 5 个典型翻车现场这套 Demo 跑通之后真正花时间的是排查网络通讯里的各种玄学问题。下面五条是我在不同项目里踩过的坑每条按现象、原因、解决给顺序方便直接对号入座。5.1 坑一接收数据不完整最后一帧总是缺几个字节现象程序收发大多数时候正常但偶尔收到的最后一条报文“断尾”解析时业务字段缺少最后一段重试几次又好了。原因这是最典型的半包问题。发送端一次 Write 的数据在接收端可能分成两次 Read 到达。如果收到第一批数据就立刻按整帧解析长度字段指向的数据还没到齐。把 UDP 的“一次一包”思维带到 TCP 里是绝大多数此类问题的根源。解决所有解析必须在 FrameDecoder 完成Feed 之后循环 TryDecode。TryDecode 里数据不够时 break等下一次 Feed 继续拼接。一个可靠的验证方法是在 TestServer 里每帧主动打成三段、中间 Sleep 后分别发送客户端照样能还原出完整报文。如果每次拆包逻辑改动后都跑一遍这个用例半包问题基本不会流到现场。5.2 坑二多线程同时调用 Send 导致报文交叉现象多个业务线程并发发送时对端收到的内容里两条报文互相嵌在一起解析失败。原因NetworkStream.Write 是不保证原子性的流式写入线程 A 写一半线程 B 挤进来写底层 socket 缓冲里字节交替对端自然解不出帧。这是典型的 write 交叉。解决参考第 3.2 的发送队列入队线程不限只保留一个发送线程消费队列。如果你要保留同步 API一个 lock 包住 Write 也能凑合但异步场景千万别用 lock跨 await 会编译报错会让代码跳到锁外部反而制造新 bug。5.3 坑三断网后客户端毫不知情Connected 属性骗了所有人现象拔掉网线客户端界面还显示“已连接”再点发送按钮数据发不出去要等几十秒甚至两分钟才报错。原因TCP 断开检测依赖 ACK 超时和重传底层探测需要时间。TcpClient.Connected 只表示最近一次操作成功过不代表当前链路可用。这是所有初写 TcpClient 的人都会踩的坑。解决在发送和接收都设置超时控制之外关键是心跳。第 4.3 的 HeartbeatLoop 用 PING/PONG 探测超时未收到任何数据就强制关闭 socket立刻触发重连。生产环境里我还会把心跳超时原因打进日志区分为“对端无响应”和“本端网络断开”每次现场排查能省一半时间。5.4 坑四接收线程直接操作 UI 控件导致界面卡死或偶发闪退现象收到数据后直接在回调里写了 textBox.AppendText程序不定期卡死或者提示“调用线程无法访问此对象”。原因接收线程是后台线程WPF 的控件只能在 UI 线程操作跨线程操作要么抛异常要么引发死锁。控制台程序里没有这个问题但 WinForm 和 WPF 都躲不开。解决在 observer 回调里用 Dispatcher.BeginInvoke 切到 UI 线程优先级设为 Background避免频繁数据刷新阻塞界面。注意不要用 Invoke 的同步版本在接收线程里等 UI 响应接收线程被卡住会导致 read 超时。5.5 坑五Dispose 顺序反了导致程序退出时报 SocketException现象程序关闭时明明调了 client.Close()日志里还是报 SocketException提示连接被强制关闭偶发不影响功能但日志看起来很脏。原因直接对 TcpClient 调用 Close 时socket 上可能还有未读数据或未完成的异步操作底层会以 RST 方式断开而不是正常 FIN于是报出异常。解决关闭前先关 _stream再对 client.Client 调用 Shutdown(SocketShutdown.Both)最后再 Close整个流程包在 try/catch 里Shutdown 抛出的异常直接捕获忽略。这套“先关流、再 Shutdown、后 Close”的顺序我现在写进所有客户端封装基类里一次都没有再犯。6. 二次开发指引把 Demo 改造成可接入业务系统的 TcpClient 封装6.1 改造思路从事件回调到统一的消息入口Demo 里的数据回调是事件形式业务简单时直接订阅即可。但真正接入业务系统更稳的是让消息经过一个统一的消息分发器MessageParser 解析出的对象投递到一个 Channel由独立业务线程消费。这样做的直接好处是接收线程永远不会被业务逻辑堵住而且业务侧的消费速度可以通过 Channel 的容量直观监控。改造时把_observer?.OnDataReceived(message)换成_messageChannel.Writer.TryWrite(message)业务侧一个 while 循环读出来处理就行。6.2 验证方法用 TcpListener 搭一个回环测试服务端var listener new TcpListener(IPAddress.Loopback, 9000); listener.Start(); var client await listener.AcceptTcpClientAsync(); var stream client.GetStream(); // 模拟粘包把两条帧拼在一个 Write 里 stream.Write(frame1.Concat(frame2).ToArray()); // 模拟半包一条帧分两次写中间 Sleep 200ms stream.Write(frame3.Take(frame3.Length / 2).ToArray()); await Task.Delay(200); stream.Write(frame3.Skip(frame3.Length / 2).ToArray());回环测试是拿到源码包后最先要跑一遍的验证脚本。我自己每次改协议一定会跑四件事粘包、半包、心跳超时、断线重连。抓包工具能看链路层但验证应用层报文是否完整拿 TcpListener 做注入脚本是效率最高的方式不依赖任何外部设备。某个外设协议调试中我发现对方在帧头之前送了一个前导字节导致 FrameDecoder 一直丢数据。后来我开始坚持先把协议字段画出来再动解码器每次对接外部协议都会先抓一份原始报文、把帧格式和字节序写在代码注释里再写解析。把它变成习惯之后同类问题再没有在联调现场出现过。希望帮到你。本文还有配套的精品资源点击获取