简介C# WebSocket 客户端与服务端 Demo 源代码是一套可直接运行的示例工程面向 .NET 开发者帮助理解基于 System.Net.WebSockets 的实时双向通信实现适合需要快速上手 WebSocket 或做即时通讯、消息推送、在线协作等场景的开发者。压缩包共 76 个文件核心代码以 cs 源码为主另有 aspx、config、js、css 等 Web 工程配套文件以及 dll、exe、pdb 等编译与调试产物整体约 333KB结构上区分 WebSocketClient 与 WebSocketService 服务端便于对照学习。已有 3509 人学习下载。示例完整展示了服务端通过 HttpListener 处理 Upgrade 请求、调用 AcceptWebSocketAsync 建立连接以及客户端使用 ClientWebSocket 完成 ConnectAsync、SendAsync、ReceiveAsync、CloseAsync 的完整流程同时包含异步收发、连接管理、多文件工程组织等关键知识点。通过学习可掌握 WebSocket 握手、文本/二进制消息处理与关闭连接的实现细节为实际项目封装可靠的双向通信模块打下基础也可作为教学演示或二次开发的参考起点。1. C# WebSocket 客户端及服务端一套能直接落地的双向通信Demo如果你正在做实时推送、在线聊天、远程控制或者 IoT 设备指令下发却不想被 SignalR 那套抽象绕来绕去这份 C# WebSocket 客户端及服务端 Demo 源代码值得你花一个下午拆开看。它不依赖第三方通信框架纯粹用 .NET 自带的 ClientWebSocket 与 HttpListener 实现了一整套握手、收发、心跳、断线重连流程跑起来就是一个能改能用的最小闭环。我当初拿它做设备指令通道的原型从下载到两个进程互通只花了不到二十分钟这份资源真正解决了「WebSocket 在 C# 里到底怎么裸写」的痛点。2. 技术选型与整体架构没有魔法只有原生 API 的完整拼装2.1 为什么不用 SignalR 而要裸写 WebSocket很多刚接触 C# 实时通信的开发者第一反应是上 SignalR毕竟它封装了传输、重连、协议协商甚至能自动降级到长轮询。但 SignalR 的问题恰恰在于封装太厚你想控制二进制帧的分包、想自己决定心跳间隔、想在服务端直接拿到原始握手请求头就得绕开它另起炉灶。这份 Demo 走的是另一条路——服务端用 HttpListener 监听 TCP 端口手动完成 HTTP Upgrade 握手再按 RFC 6455 规范解析和构造 WebSocket 帧客户端用 ClientWebSocket 发起连接ReceiveAsync 循环读取消息并触发事件回调。我建议你在决定用 SignalR 之前先拿这份 Demo 跑一遍裸协议。原因很实际当你需要对接的设备端是嵌入式硬件或者前端原生 WebSocket 对象时它们认的是标准 WebSocket 协议而不是 SignalR 的 JSON 封装。把这份源码吃透之后你再去读 SignalR 的源码会发现那些「看似高级」的功能其实都是在握手和帧解析这两件事上做文章。2.2 目录结构与工程职责整个 Demo 拆成了清晰的两个可执行工程外加一个共享消息类库这种结构拿来当脚手架非常合适。下面是实际解压后的目录结构WebSocketDemo/ ├── WebSocketServer/ # 服务端控制台程序 │ ├── Program.cs # 监听端口、启动服务、接受连接 │ ├── WebSocketServer.cs # 握手处理、帧解析、连接管理 │ └── app.config # 监听地址与端口配置 ├── WebSocketClient/ # 客户端 WinForms 程序 │ ├── Program.cs # 启动窗体 │ ├── MainForm.cs # 连接、发送、日志展示界面 │ ├── WebSocketClient.cs # 封装 ClientWebSocket 的收发与重连 │ └── app.config # 服务端地址配置 └── Common/ # 共享工程 └── MessageModels.cs # 文本消息、心跳包、二进制帧的消息模型服务端采用控制台工程是为了让你能在终端直接看到握手日志和收发帧的原始内容这对排查问题非常有用。客户端用 WinForms 是为了让演示效果直观——你可以在文本框里输入消息点发送下面的 ListBox 会实时显示收到的推送。两个工程引用同一个 Common 类库传递消息体时能保证序列化格式一致避免客户端和服务端各自定义模型导致字段对不上。2.3 消息模型与通信协议约定在 Common 工程里定义了一套极简的消息封装所有在服务端和客户端之间流转的数据都遵循这个约定。核心代码是把消息分成三个类型文本消息、心跳包和二进制数据块用一个 Type 字段区分用 Content 装文本内容用 Data 装二进制负载。public enum WebSocketMessageType { Text 1, // 普通文本消息 Heartbeat 2, // 心跳包 Binary 3 // 二进制数据 } public class WebSocketMessage { public WebSocketMessageType Type { get; set; } public string Content { get; set; } public byte[] Data { get; set; } public DateTime Timestamp { get; set; } public string ToJson() { return JsonConvert.SerializeObject(this); } public static WebSocketMessage FromJson(string json) { return JsonConvert.DeserializeObjectWebSocketMessage(json); } }这段代码定义了通信双方的「通用语言」。我在实际使用中给这个模型加过 FromUserId 和 ToUserId 字段用来做点对点转发也加过 MessageId 做消息去重——你二次开发时大概率也要动这个类。注意 Timestamp 字段我建议保留日志里排查乱序和延迟问题时它比什么都直观。如果你的项目传输的是大文件流把 Data 字段拆成分片序号数组会更合理但作为 Demo 这个模型已经足够覆盖大部分场景。3. 服务端核心模块拆解从监听端口到帧解析的完整链路3.1 HttpListener 监听与 HTTP Upgrade 握手服务端的第一步是监听指定端口并等待客户端发起握手请求。这里没有用 Kestrel 也没有用 OWIN直接创建 HttpListener 并绑定前缀代码很直观public void Start(string prefix) { _listener new HttpListener(); _listener.Prefixes.Add(prefix); // 例如 http://127.0.0.1:8080/ _listener.Start(); Console.WriteLine($WebSocket Server listening on {prefix}); while (_isRunning) { HttpListenerContext context _listener.GetContext(); if (context.Request.IsWebSocketRequest) { ProcessWebSocketRequest(context); } else { context.Response.StatusCode 400; context.Response.Close(); } } }这段代码有一个值得注意的参数设计prefix 必须写成http://ip:port/这种带结尾斜杠的格式否则 HttpListener 会直接抛异常。我就因为少写结尾斜杠折腾过十分钟后来养成了用$http://{ip}:{port}/拼接的习惯。IsWebSocketRequest属性是 HttpListener 帮我们做的判断它会检查请求头里的Upgrade: websocket和Connection: Upgrade这也是 WebSocket 握手区别于普通 HTTP 请求的核心特征。3.2 接受连接并包装 WebSocketContext握手通过之后就需要把 HttpListenerContext 转换成 WebSocketContext然后进入收发循环。这里有一段很关键的代码——我们用线程池处理每一个连接保证一个客户端的阻塞接收不会拖垮其他连接private async Task ProcessWebSocketRequest(HttpListenerContext context) { WebSocketContext webSocketContext await context.AcceptWebSocketAsync(null); WebSocket socket webSocketContext.WebSocket; // 把连接加入管理字典用于后续群发或定向推送 lock (_clientsLock) { _clients.Add(socket, new ClientInfo { ConnectedAt DateTime.Now }); } Console.WriteLine($[{DateTime.Now:HH:mm:ss}] 客户端已连接当前在线数: {_clients.Count}); await ReceiveLoop(socket); }这里把 socket 作为字典的 Key 是个巧妙的设计因为 WebSocket 对象在连接期间是唯一的用它做 Key 可以快速实现群发——遍历字典给每个 socket 调用 SendAsync 就行。AcceptWebSocketAsync方法只需要传入一个ArraySegmentbyte作为接收缓冲区传 null 表示使用默认缓冲区大小如果你的业务帧特别大可以手动指定一个更大的缓冲区。3.3 帧接收循环与分包重组真正的硬骨头在帧接收循环。WebSocket 协议规定数据可以是分片传输的也就是说一个大消息会被拆成多个 Frame 依次到达接收端必须根据 FIN 标志位判断消息是否结束。这份 Demo 的处理方式如下private async Task ReceiveLoop(WebSocket socket) { byte[] buffer new byte[1024 * 8]; while (socket.State WebSocketState.Open) { WebSocketReceiveResult result await socket.ReceiveAsync( new ArraySegmentbyte(buffer), CancellationToken.None); if (result.MessageType WebSocketMessageType.Close) { // 对端主动关闭 await socket.CloseAsync(WebSocketCloseStatus.NormalClosure, 客户端请求关闭, CancellationToken.None); RemoveClient(socket); break; } if (result.EndOfMessage) { // 单帧完整消息直接处理 string message Encoding.UTF8.GetString(buffer, 0, result.Count); Console.WriteLine($收到完整消息: {message}); await ProcessReceivedMessage(socket, message); } else { // 多帧消息这里标记一个处理策略实际项目需要拼接 Console.WriteLine(收到分片消息开始需要重组); } } }这段代码暴露了一个 Demo 级别的简化分片消息这里只打日志没有真正做拼接。我在实际改造中是用一个 StringBuilder 缓存分片内容等EndOfMessage为 true 时再统一处理。需要注意ReceiveAsync的ArraySegmentbyte必须使用同一个底层数组否则每次接收都会分配新的数组GC 压力会很大。还有一点容易踩坑result.Count是本次接收的字节数不一定等于 buffer 长度切字符串时不能用buffer直接转必须指定长度。3.4 消息分发与群发推送逻辑服务端收到消息后的处理逻辑我拆成了一个独立方法这样做是为了方便你加业务。Demo 默认的逻辑是把收到的文本原样回推给所有在线客户端形成一个简单的广播private async Task ProcessReceivedMessage(WebSocket sender, string rawMessage) { WebSocketMessage msg WebSocketMessage.FromJson(rawMessage); // 心跳包只更新在线状态不转发 if (msg.Type WebSocketMessageType.Heartbeat) { Console.WriteLine($收到心跳: {msg.Content}); return; } // 广播给所有在线客户端 byte[] payload Encoding.UTF8.GetBytes(msg.ToJson()); ArraySegmentbyte segment new ArraySegmentbyte(payload); lock (_clientsLock) { foreach (var client in _clients.Keys.ToList()) { if (client.State WebSocketState.Open) { client.SendAsync(segment, WebSocketMessageType.Text, true, CancellationToken.None); } } } Console.WriteLine($已广播消息给 {_clients.Count} 个客户端); }注意到我用了lock (_clientsLock)保护客户端字典原因很简单ReceiveLoop 在后台线程池里运行多个客户端同时断线时会在多个线程上修改字典不加锁会抛 ConcurrentModification 异常。这里SendAsync的第三个参数true表示这是最后一帧也就是完整消息不分片大多数业务消息用这个值就够了。如果你想做定向推送把foreach改成从字典里按某个标识取出对应 socket 即可。3.5 心跳检测与断线清理机制这份 Demo 里服务端对客户端的存活检测用了类似看门狗的思路——客户端每 30 秒发送一个心跳包服务端记录最后心跳时间超过 60 秒没收到就认为连接死了public void CheckHeartbeat() // 建议用 Timer 每隔 10 秒调用一次 { DateTime now DateTime.Now; ListWebSocket deadSockets new ListWebSocket(); lock (_clientsLock) { foreach (var pair in _clients) { if ((now - pair.Value.LastHeartbeat).TotalSeconds 60) { deadSockets.Add(pair.Key); } } foreach (var socket in deadSockets) { socket.Abort(); // 直接终止底层 TCP 连接 _clients.Remove(socket); Console.WriteLine(检测到心跳超时已强制清理死连接); } } }这里有个血泪经验清理死连接时不要调用CloseAsync因为对方可能已经断网Close 握手会一直等不到响应导致阻塞。用Abort()直接关底层 socket 是干净利落的方式。心跳超时阈值要根据你的网络环境调局域网内可以放短到 20 秒公网环境建议放到 90 秒以上否则手机切 Wi-Fi 的瞬间就会被踢下线。4. 客户端核心模块拆解连接、收发、断线重连的封装实践4.1 ClientWebSocket 的连接与状态管理客户端封装了 .NET 自带的 ClientWebSocket对外只暴露 Connect、Send、Close 三个方法并在内部维护一个线程安全的收发循环。连接部分代码如下public async Task ConnectAsync(string serverUri) { _socket new ClientWebSocket(); _socket.Options.RemoteCertificateValidationCallback (sender, certificate, chain, sslPolicyErrors) true; _socket.Options.KeepAliveInterval TimeSpan.FromSeconds(30); await _socket.ConnectAsync(new Uri(serverUri), CancellationToken.None); if (_socket.State WebSocketState.Open) { OnConnected?.Invoke(this, EventArgs.Empty); _ Task.Run(ReceiveLoop); // 启动独立接收线程 } }这里有两个参数值得说明。KeepAliveInterval是 ClientWebSocket 自带的 TCP KeepAlive 保活机制它只保证网络层连接不被交换机回收但不代表应用层正常——所以我们还需要在应用层发心跳包。RemoteCertificateValidationCallback这个我写死返回 true 只适用于本地测试的 wss 自签名证书生产环境必须删掉这行做正常证书校验否则就是给中间人攻击开门。4.2 接收循环与事件回调模式客户端把接收到的数据转换成事件触发给 UI 层解耦收发逻辑。核心代码如下private async Task ReceiveLoop() { byte[] buffer new byte[1024 * 4]; while (_socket.State WebSocketState.Open) { WebSocketReceiveResult result await _socket.ReceiveAsync( new ArraySegmentbyte(buffer), CancellationToken.None); if (result.MessageType WebSocketMessageType.Close) { OnDisconnected?.Invoke(this, EventArgs.Empty); break; } string message Encoding.UTF8.GetString(buffer, 0, result.Count); WebSocketMessage msg WebSocketMessage.FromJson(message); switch (msg.Type) { case WebSocketMessageType.Text: OnMessageReceived?.Invoke(this, new MessageEventArgs(msg.Content)); break; case WebSocketMessageType.Heartbeat: // 服务端回的心跳用于计算 RTT OnHeartbeatReceived?.Invoke(this, EventArgs.Empty); break; } } }事件模式的好处是 UI 线程可以直接订阅OnMessageReceived并更新控件因为事件是在接收线程触发的WinForms 控件更新时记得用Invoke跨线程调用。我在这个循环里吃过一次教训把result.Count当成 buffer 长度用结果消息尾部多出一堆空字符原因是上次接收的数据残留在数组里没被覆盖。那之后我统一用new ArraySegmentbyte(buffer, 0, result.Count)传给编码器问题再也没出现过。4.3 断线重连策略与退避算法客户端另一个核心设计是断线自动重连。Demo 里实现了一个简单的指数退避——第一次重连等 1 秒第二次等 2 秒最多等 30 秒private async Task ReconnectLoop() { int retryCount 0; while (!_isClosedByUser) { try { await ConnectAsync(_serverUri); retryCount 0; // 连接成功重置重试次数 } catch (Exception ex) { retryCount; int delaySeconds Math.Min(30, (int)Math.Pow(2, retryCount - 1)); Console.WriteLine($重连失败({retryCount}){delaySeconds}秒后重试: {ex.Message}); await Task.Delay(TimeSpan.FromSeconds(delaySeconds)); } } }重连逻辑必须在IsClosedByUser为 false 时才执行否则用户主动点断开后线程还会一直尝试连接。Math.Pow(2, retryCount - 1)生成的是 1、2、4、8、16 的序列配合Math.Min上限控制在 30 秒避免服务端长时间不可达时客户端做无意义的密集重连。如果你想让代码更稳健可以在这个循环里加入「连接成功后自动补发订阅消息」的逻辑因为服务端可能在断线期间重启丢失了客户端的状态。4.4 心跳包的发送与超时判定客户端心跳用定时器驱动每 30 秒向服务端发送一个心跳消息。这里的实现要点是心跳包也走同一个消息通道这样服务端可以通过心跳到达顺序判断链路是否存在中间代理的缓冲问题private void StartHeartbeatTimer() { _heartbeatTimer new Timer(async _ { if (_socket ! null _socket.State WebSocketState.Open) { WebSocketMessage heartbeat new WebSocketMessage { Type WebSocketMessageType.Heartbeat, Content $client-{DateTime.Now:yyyyMMddHHmmss}, Timestamp DateTime.Now }; byte[] payload Encoding.UTF8.GetBytes(heartbeat.ToJson()); await _socket.SendAsync( new ArraySegmentbyte(payload), WebSocketMessageType.Text, true, CancellationToken.None); } }, null, TimeSpan.FromSeconds(30), TimeSpan.FromSeconds(30)); }定时器回调是异步 void 模式注意里面的异常必须捕获否则定时器会静默死亡。我一般会在 SendAsync 外包一个 try-catchcatch 到异常就触发断线重连流程而不是让异常冒泡到定时器线程导致后续心跳全部失效。这里的client-{时间戳}格式是给服务端日志用的方便定位具体是哪个客户端失联。5. 常见避坑与排查记录那些会让你卡半天的实际问题5.1 现象服务端启动就报「拒绝访问」异常原因HttpListener 在 Windows 上需要 URL 预留权限。你用http://localhost:8080/启动可能没问题但换成http://192.168.1.100:8080/会触发 HTTP.sys 的权限校验。这是很多开发者第一次跑 WebSocket 服务端最常见的翻车点。解决打开管理员命令行执行netsh http add urlacl urlhttp://:8080/ userEveryone把该端口的所有前缀允许给所有用户。或者直接用管理员身份运行程序。我建议用前者因为你的程序可能被其他人用普通权限启动。5.2 现象客户端能连上但收不到任何消息原因八成是端口被防火墙拦了。客户端连接成功只说明 TCP 握手完成但如果服务端所在的 Windows 防火墙阻断了入站规则后续的数据帧会被丢弃。注意「连接成功」和「数据互通」是两码事。解决在服务端机器上执行netsh advfirewall firewall add rule nameWebSocketDemo dirin actionallow protocolTCP localport8080或者打开防火墙高级设置手动添加入站规则。测试时也可以临时关闭防火墙验证但记得开回来。5.3 现象客户端连接后 30 秒左右被强制断开原因你很可能没有实现心跳机制。TCP 长连接在公网链路上会被 NAT 网关或运营商回收空闲连接一般 30 秒到 2 分钟不等。如果客户端只连不发数据网关会认为链路已死。解决按照第 4.4 节实现心跳定时器发送频率要小于网关的超时阈值。我建议心跳间隔设为 30 秒这个值在大多数公网环境下都能保住连接活跃。如果你发现还是被断开把心跳间隔缩短到 15 秒再试。5.4 现象收到的中文消息变成乱码原因编码不一致。服务端用Encoding.UTF8.GetString解析如果客户端发送时用了Encoding.Default在中文 Windows 上是 GBK两边对不上就会乱码。这类问题特别隐蔽因为纯英文消息看不出问题。解决收发两端统一使用 UTF-8。特别注意Encoding.UTF8.GetBytes和GetString必须成对出现。这条看起来是常识但我见过太多项目因为这个细节在联调时浪费一天堪称典型的玄学问题——明明代码逻辑没问题就是显示不对。5.5 现象SendAsync 抛出「内部错误」导致崩溃原因向一个已经关闭的 WebSocket 发起发送。当服务端调用 Abort 清理死连接后客户端的 socket 状态可能还没有立刻变为 Closed此时如果恰好触发了定时器发送就会抛异常。这是并发场景下的竞态条件。解决发送前检查State WebSocketState.Open只是第一道防线真正的保险是把发送逻辑包在 try-catch 里catch 住异常后主动触发重连。也不要忘记在发送和 CheckHeartbeat 清理之间加锁避免同一个 socket 被并发访问。6. 二次开发与改造思路从 Demo 到生产可用小框架6.1 把广播改成按频道订阅的路由方案这份 Demo 的广播模型适合测试但真实业务通常是多个频道A 设备的指令不能发给 B 设备用户在聊天室 A 收不到聊天室 B 的消息。改造思路是维护一个ConcurrentDictionarystring, HashSetWebSocket键是频道名值是频道的 socket 集合。服务端收到消息时解析消息体里的频道标识字段找到对应的 socket 集合定向发送。private ConcurrentDictionarystring, HashSetWebSocket _channels new ConcurrentDictionarystring, HashSetWebSocket(); public void JoinChannel(string channelName, WebSocket socket) { _channels.AddOrUpdate(channelName, new HashSetWebSocket { socket }, (key, existingSet) { existingSet.Add(socket); return existingSet; }); } public async Task SendToChannel(string channelName, WebSocketMessage msg) { if (_channels.TryGetValue(channelName, out var sockets)) { byte[] payload Encoding.UTF8.GetBytes(msg.ToJson()); foreach (var socket in sockets) { if (socket.State WebSocketState.Open) { await socket.SendAsync(new ArraySegmentbyte(payload), WebSocketMessageType.Text, true, CancellationToken.None); } } } }这段代码把一个简单的广播改成了按频道路由的消息总线。注意AddOrUpdate的更新委托里要对HashSet做加锁处理因为同一频道的多个客户端可能在不同线程上同时加入HashSet不是线程安全的集合并发写会翻车。6.2 给服务端加消息持久化与历史回溯实时消息如果服务端重启就全丢了这在很多业务里不可接受。我的做法是在ProcessReceivedMessage里加一道旁路——消息广播之前先写入一个队列再异步批量写数据库或者本地文件。伪代码如下private ConcurrentQueueWebSocketMessage _persistQueue new ConcurrentQueueWebSocketMessage(); private void PersistToDisk() { while (true) { if (_persistQueue.TryDequeue(out var msg)) { File.AppendAllText(messages.log, ${msg.Timestamp:O}|{msg.Type}|{msg.Content}{Environment.NewLine}); } else { Thread.Sleep(100); } } }持久化和广播解耦后即使磁盘写入慢也不会阻塞实时消息的转发。消息格式用竖线分隔的纯文本是为了方便 grep 排查如果你有结构化查询需求直接改成 JSON Lines 格式一行一个对象更合适。6.3 用消息压缩优化带宽敏感场景如果你要传输的是大文本或者 JSON 数据可以在发送前用 GZip 压缩在接收端解压。压缩率通常能到 70% 以上对公网带宽紧张的场景是立竿见影的优化。发送端改造点private byte[] CompressPayload(string json) { using (MemoryStream ms new MemoryStream()) { using (GZipStream gzip new GZipStream(ms, CompressionLevel.Fastest)) { byte[] bytes Encoding.UTF8.GetBytes(json); gzip.Write(bytes, 0, bytes.Length); } return ms.ToArray(); } }对应的接收端在ReceiveLoop里判断消息帧的 opcode 是二进制而不是文本时走解压分支再反序列化。这里有个细节WebSocket 协议原生有压缩扩展 permessage-deflate但 .NET 的 ClientWebSocket 对它支持不完整所以我直接放弃了协议层压缩改用业务层压缩更可控。6.4 改造后的验证方法改完代码后不要只连自己测试我习惯跑一个三联验证第一起一个原版的服务端和一个改版后的客户端确认兼容性没有被破坏第二用浏览器控制台里new WebSocket(...)直接连服务端发送几条测试帧验证协议符合 RFC 6455——这个方法能确认你的服务端没有被 .NET 的特有实现绑死第三把所有项目里的心跳间隔改短到 5 秒跑 10 分钟看有没有误杀正常连接的日志之后再改回正常值。从那以后我每次接手这类通信项目都会强制走一遍这个验证流程把路由、持久化、压缩分开测而不是一把梭排查问题时能少走很多弯路。希望这份拆解能帮到你少踩几个我当年踩过的坑。本文还有配套的精品资源点击获取
