简介：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.DeserializeObject<WebSocketMessage>(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方法只需要传入一个ArraySegment<byte>作为接收缓冲区，传 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 ArraySegment<byte>(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的ArraySegment<byte>必须使用同一个底层数组，否则每次接收都会分配新的数组，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()); ArraySegment<byte> segment = new ArraySegment<byte>(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; List<WebSocket> deadSockets = new List<WebSocket>(); 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 ArraySegment<byte>(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 ArraySegment<byte>(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 ArraySegment<byte>(payload), WebSocketMessageType.Text, true, CancellationToken.None); } }, null, TimeSpan.FromSeconds(30), TimeSpan.FromSeconds(30)); }定时器回调是异步 void 模式，注意里面的异常必须捕获，否则定时器会静默死亡。我一般会在 SendAsync 外包一个 try-catch，catch 到异常就触发断线重连流程，而不是让异常冒泡到定时器线程导致后续心跳全部失效。这里的client-{时间戳}格式是给服务端日志用的，方便定位具体是哪个客户端失联。
5. 常见避坑与排查记录：那些会让你卡半天的实际问题
5.1 现象：服务端启动就报「拒绝访问」异常
原因：HttpListener 在 Windows 上需要 URL 预留权限。你用http://localhost:8080/启动可能没问题，但换成http://192.168.1.100:8080/会触发 HTTP.sys 的权限校验。这是很多开发者第一次跑 WebSocket 服务端最常见的翻车点。
解决：打开管理员命令行执行netsh http add urlacl url=http://+:8080/ user=Everyone，把该端口的所有前缀允许给所有用户。或者直接用管理员身份运行程序。我建议用前者，因为你的程序可能被其他人用普通权限启动。
5.2 现象：客户端能连上但收不到任何消息
原因：八成是端口被防火墙拦了。客户端连接成功只说明 TCP 握手完成，但如果服务端所在的 Windows 防火墙阻断了入站规则，后续的数据帧会被丢弃。注意「连接成功」和「数据互通」是两码事。
解决：在服务端机器上执行netsh advfirewall firewall add rule name="WebSocketDemo" dir=in action=allow protocol=TCP localport=8080，或者打开防火墙高级设置手动添加入站规则。测试时也可以临时关闭防火墙验证，但记得开回来。
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 的消息。改造思路是维护一个ConcurrentDictionary<string, HashSet<WebSocket>>，键是频道名，值是频道的 socket 集合。服务端收到消息时解析消息体里的频道标识字段，找到对应的 socket 集合定向发送。
private ConcurrentDictionary<string, HashSet<WebSocket>> _channels = new ConcurrentDictionary<string, HashSet<WebSocket>>(); public void JoinChannel(string channelName, WebSocket socket) { _channels.AddOrUpdate(channelName, new HashSet<WebSocket> { 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 ArraySegment<byte>(payload), WebSocketMessageType.Text, true, CancellationToken.None); } } } }这段代码把一个简单的广播改成了按频道路由的消息总线。注意AddOrUpdate的更新委托里要对HashSet做加锁处理，因为同一频道的多个客户端可能在不同线程上同时加入，HashSet不是线程安全的集合，并发写会翻车。
6.2 给服务端加消息持久化与历史回溯
实时消息如果服务端重启就全丢了，这在很多业务里不可接受。我的做法是在ProcessReceivedMessage里加一道旁路——消息广播之前先写入一个队列，再异步批量写数据库或者本地文件。伪代码如下：
private ConcurrentQueue<WebSocketMessage> _persistQueue = new ConcurrentQueue<WebSocketMessage>(); 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 分钟看有没有误杀正常连接的日志，之后再改回正常值。从那以后我每次接手这类通信项目，都会强制走一遍这个验证流程，把路由、持久化、压缩分开测而不是一把梭，排查问题时能少走很多弯路。希望这份拆解能帮到你少踩几个我当年踩过的坑。
本文还有配套的精品资源，点击获取
