6.37WebSocketClient 客户端

创建于 2026 年 8 月 17 日约 3 分钟读完

框架内置了 WebSocketClient 类型，便于用户通过 ws 或 wss 协议与 WebSocket 服务器建立连接。要使用 WebSocket 功能，首先需要创建并初始化 WebSocketClient 的实例。以下详尽列出了 WebSocketClient 实例所具备的全部功能配置选项：

  • 创建 WebSocketClient 客户端

以下是创建 WebSocketClient 实例的三种方式，它们分别通过不同的构造函数重载实现，但实质上最终都调用了带有 WebSocketClientOptions 参数的构造函数来配置连接：

cs
// 直接使用 URL 字符串（支持 ws:// 和 wss://）using var webSocketClient = new WebSocketClient("wss://localhost:7044/ws");// 使用 Uri 对象using var webSocketClient = new WebSocketClient(new Uri("wss://localhost:7044/ws"));// 使用 WebSocketClientOptions 对象进行详细配置using var webSocketClient = new WebSocketClient(new WebSocketClientOptions("wss://localhost:7044/ws"));// 配置内部 ClientWebSocketOptions 实例using var webSocketClient = new WebSocketClient("wss://localhost:7044/ws", options => {});

WebSocketClientOptions 类型包含了多种配置属性，用于定制 ClientWebSocket 连接的详细设置。WebSocketClientOptions，包含以下属性：

  • 属性：
    • ServerUri：服务器地址（Uri 类型）。
    • ReconnectInterval：重连的间隔时间（毫秒），默认值为 2 秒。（TimeSpan 类型）。
    • MaxReconnectRetries：最大重连次数，默认 10 次。（int 类型）。
    • Timeout：超时时间（TimeSpan 类型）。
    • ReceiveBufferSize：接收服务器新消息缓冲区大小（以字节为单位的 int 类型）。
    • Configure：用户配置内部 ClientWebSocketOptions 实例（Action<ClientWebSocketOptions> 类型）。
  • WebSocketClient 客户端事件

WebSocketClient 客户端提供了多种事件，允许开发者在 WebSocket 通信的各个阶段插入自定义逻辑。以下示例展示了如何订阅这些事件：

cs
using var webSocketClient = new WebSocketClient("wss://localhost:7044/ws");    // 支持 ws:// 和 wss://// 开始连接时触发事件webSocketClient.Connecting += (s, e) => {};// 连接成功时触发事件webSocketClient.Connected += (s, e) => { };// 开始重新连接时触发事件webSocketClient.Reconnecting += (s, e) => { };// 重新连接成功时触发事件webSocketClient.Reconnected += (s, e) => { };// 开始关闭连接时触发事件webSocketClient.Closing += (s, e) => { };// 关闭连接成功时触发事件webSocketClient.Closed += (s, e) => { };// 开始接收消息时触发事件webSocketClient.ReceivingStarted += (s, e) => { };// 停止接收消息时触发事件webSocketClient.ReceivingStopped += (s, e) => { };// 接收文本消息事件，result 为 WebSocketTextReceiveResult 类型webSocketClient.TextReceived += (s, result) => { };// 接收二进制消息事件，result 为 WebSocketBinaryReceiveResult 类型webSocketClient.BinaryReceived += (s, result) => { };

WebSocketTextReceiveResult 类型派生自 WebSocketReceiveResult ，包含以下属性：

WebSocketBinaryReceiveResult 类型派生自 WebSocketReceiveResult ，包含以下属性：

WebSocketClient 客户端方法

WebSocketClient 类封装了与 WebSocket 服务器进行交互的关键操作，具体包括连接、发送消息和关闭连接三种方法。

cs
using var webSocketClient = new WebSocketClient("wss://localhost:7044/ws");    // 支持 ws:// 和 wss://// 连接服务器await webSocketClient.ConnectAsync(cancellationToken);// 向服务器发送消息await webSocketClient.SendAsync(message, endOfMessage, cancellationToken);  // 发送字符串消息await webSocketClient.SendAsync(byteArray, endOfMessage, cancellationToken);    // 发送二进制消息await webSocketClient.SendAsync(message, webSocketMessageType, endOfMessage, cancellationToken);    // 发送指定类型的消息（文本或二进制）// 等待消息（阻塞）await webSocketClient.WaitAsync(cancellationToken);// 关闭连接await webSocketClient.CloseAsync(cancellationToken);    // 无附加信息关闭await webSocketClient.CloseAsync(closeStatus, closeDescription, cancellationToken); // 提供关闭状态和描述信息关闭