WebSocket4Net：强大的.NET WebSocket客户端库

2026-02-06 04:14:51作者：农烁颖Land

WebSocket4Net 是一个基于 SuperSocket 2.0 和现代 .NET 平台构建的高性能 WebSocket 客户端库。它提供了简单易用的 API，让开发者能够轻松地在 .NET 应用程序中创建和管理 WebSocket 连接。

什么是 WebSocket？

WebSocket 是一种在单个 TCP 连接上进行全双工通信的协议。与传统的 HTTP 请求-响应模式不同，WebSocket 允许服务器和客户端之间建立持久连接，实现真正的实时双向通信。

核心特性

现代化架构

WebSocket4Net 基于 SuperSocket 2.0 构建，完全支持 .NET Core 和现代 .NET 平台。该版本包含了与之前 WebSocket4Net 版本的破坏性变更，因此在升级时可能需要进行代码调整。

灵活的消息处理模式

库提供了两种主要的消息处理方式：

事件处理器模式：通过 PackageHandler 事件处理接收到的消息

using WebSocket4Net;

var websocket = new WebSocket("https://localhost/live");

websocket.PackageHandler += (sender, package) =>
{
    Console.WriteLine(package.Message);
}

await websocket.OpenAsync();
websocket.StartReceive();
await websocket.SendAsync("Hello");
await websocket.CloseAsync();

按需接收模式：通过 ReceiveAsync 方法主动获取消息

using WebSocket4Net;

var websocket = new WebSocket("https://localhost/live");

await websocket.OpenAsync();
await websocket.SendAsync("Hello");

while (true)
{
    var package = await websocket.ReceiveAsync();

    if (package == null)
        break;

    Console.WriteLine(package.Message);
}
await websocket.CloseAsync();

完整的 WebSocket 协议支持

支持 WebSocket 握手协议
自动 Ping/Pong 心跳机制
支持二进制和文本数据传输
完整的连接状态管理

主要功能

连接管理

WebSocket4Net 提供了完整的连接生命周期管理：

var websocket = new WebSocket(url);
await websocket.OpenAsync();  // 建立连接
websocket.StartReceive();    // 开始接收消息
await websocket.CloseAsync(); // 关闭连接

消息发送

支持多种数据格式的发送：

// 发送文本消息
await websocket.SendAsync("Hello World");

// 发送二进制数据
await websocket.SendAsync(byteArrayData);

// 发送序列数据
await websocket.SendAsync(ref sequenceData);

状态跟踪

库维护了详细的连接状态：

public WebSocketState State { get; private set; } = WebSocketState.None;

使用场景

WebSocket4Net 适用于各种需要实时通信的应用场景：

实时聊天应用：支持即时消息传递和群组聊天
股票交易系统：实时推送市场数据和交易信息
在线游戏：实现玩家间的实时互动和数据同步
物联网设备控制：远程监控和设备状态实时更新
实时数据分析：监控系统指标和业务数据变化
在线协作工具：支持多人实时编辑和协作

配置选项

自定义头部

可以添加自定义 HTTP 头部信息：

websocket.Headers["UserId"] = userId;
websocket.Headers["Authorization"] = token;

子协议支持

支持 WebSocket 子协议的配置：

websocket.AddSubProtocol("chat");
websocket.AddSubProtocol("file-transfer");

自动 Ping 功能

启用自动 Ping 来维持连接：

websocket.AutoPingEnabled = true;

测试覆盖

项目包含了全面的单元测试，确保功能的可靠性：

握手协议测试
消息回显测试
自定义头部测试
Ping/Pong 机制测试
重连机制测试
并发发送测试

项目结构

WebSocket4Net/
├── src/WebSocket4Net/          # 核心库源码
├── test/WebSocket4Net.Tests/    # 单元测试
├── assets/                         # 资源文件
└── 配置文件

快速开始

要开始使用 WebSocket4Net，可以通过以下步骤：

克隆项目：

git clone https://gitcode.com/gh_mirrors/we/WebSocket4Net

引用项目：将 WebSocket4Net 项目添加到您的解决方案中，或者通过 NuGet 包管理器安装。
基本使用：

using WebSocket4Net;

// 创建 WebSocket 实例
var websocket = new WebSocket("ws://localhost:8080/chat");

// 建立连接
if (await websocket.OpenAsync())
{
    // 发送消息
    await websocket.SendAsync("Hello from WebSocket4Net!");

    // 接收消息
    var response = await websocket.ReceiveAsync();
    Console.WriteLine(response.Message);
}