简介：一份面向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 风格的 csproj，TargetFramework 写 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 里的 TcpClientService；TcpClientService 把收到的原始字节交给 FrameDecoder，FrameDecoder 拆出完整帧后由 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 Task<bool> 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 要置为 true，TCP 默认启用 Nagle 算法，会把小包攒到一起发，对心跳和短报文来说延迟明显；如果业务允许也可以试试默认值，但工控场景里大多数都是关掉。BufferSize 设为 64KB 是常见值，接收缓冲区太大反而会让解码器等更久才凑齐数据。ReadTimeout 和 WriteTimeout 是同步流才有的属性，异步读写时超时靠 CancellationToken 控制，这里两套方式都保留了。
连接失败要区分“超时”和“被拒”。超时是 IP 可达但没握手成功，被拒通常是端口没监听或防火墙拦了。生产环境里我会把 SocketErrorCode 记进日志，排查时一眼能看出是哪一类。
3.2 发送通道：ConcurrentQueue 做发送队列，避免多线程写同一个 NetworkStream
private readonly ConcurrentQueue<byte[]> _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; } } }为什么不用 lock？lock 语法本身没问题，但发送逻辑里可能有异步写，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 List<byte> _buffer = new(); private const int HeaderLength = 4; // 帧头2字节 + 长度2字节 public void Feed(ReadOnlySpan<byte> data) { foreach (var b in data) _buffer.Add(b); // 追加到累积缓冲 } public List<byte[]> TryDecode() { var result = new List<byte[]>(); 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 秒，这样偶尔丢一个两个包也不会误判。
半开连接的检测是心跳最大的价值。局域网里路由器重启、对端应用崩溃但不关闭 socket，TCP 层面不会立刻通报。只靠 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 一直丢数据。后来我开始坚持先把协议字段画出来再动解码器，每次对接外部协议都会先抓一份原始报文、把帧格式和字节序写在代码注释里再写解析。把它变成习惯之后，同类问题再没有在联调现场出现过。希望帮到你。
本文还有配套的精品资源，点击获取
