IWebsocketClient 接口完全指南：gh_mirrors/webso/websocket-client 开发必备

IWebsocketClient 接口完全指南：gh_mirrors/webso/websocket-client 开发必备

【免费下载链接】websocket-client🔧 .NET/C# websocket client library项目地址: https://gitcode.com/gh_mirrors/webso/websocket-client

gh_mirrors/webso/websocket-client 是一个功能强大的 .NET/C# WebSocket 客户端库，而 IWebsocketClient 接口作为其核心组件，提供了简单易用且功能完善的 WebSocket 通信功能，包括内置的重连机制和错误处理，是开发 WebSocket 应用的必备工具。

一、IWebsocketClient 接口简介

IWebsocketClient 接口定义了 WebSocket 客户端的核心功能，位于 src/Websocket.Client/IWebsocketClient.cs 文件中。它继承自 IDisposable 接口，提供了发送消息、连接管理、事件订阅等一系列方法和属性，使开发者能够轻松实现 WebSocket 通信。

1.1 核心功能概览

IWebsocketClient 接口的主要功能包括：

• 发送文本和二进制消息
• 管理 WebSocket 连接（连接、断开、重连）
• 订阅接收消息、重连和断开事件
• 配置连接超时、重连策略等参数

二、消息发送方法详解

IWebsocketClient 提供了多种发送消息的方法，以满足不同的场景需求。

2.1 队列式发送方法

队列式发送方法将消息插入发送队列，实际发送在另一个线程中进行，避免了并发发送的问题：

• bool Send(string message)：发送文本消息
• bool Send(byte[] message)：发送二进制消息
• bool Send(ArraySegment<byte> message)：发送二进制消息
• bool Send(ReadOnlySequence<byte> message)：发送二进制消息

这些方法返回一个 bool 值，表示消息是否成功写入队列。

2.2 即时发送方法

即时发送方法不使用发送队列，直接发送消息，在 .NET Framework 平台上需注意并发发送的问题：

• Task SendInstant(string message)：即时发送文本消息
• Task SendInstant(byte[] message)：即时发送二进制消息

2.3 文本消息优化发送

对于已转换为字节数组的文本消息，可以使用以下方法避免双重序列化：

• bool SendAsText(byte[] message)
• bool SendAsText(ArraySegment<byte> message)
• bool SendAsText(ReadOnlySequence<byte> message)

三、连接管理与控制

IWebsocketClient 提供了完善的连接管理功能，包括连接、断开、重连等操作。

3.1 连接启动

• Task Start()：在后台线程开始监听 WebSocket 流，连接错误时不会抛出异常，而是通过DisconnectionHappened事件流和日志记录
• Task StartOrFail()：在后台线程开始监听 WebSocket 流，连接错误时抛出异常，采用快速失败策略

3.2 连接停止

• Task<bool> Stop(WebSocketCloseStatus status, string statusDescription)：使用自定义关闭代码停止/关闭 WebSocket 连接，方法不会抛出异常，仅记录日志并将客户端标记为已关闭，返回 true 表示成功启动关闭
• Task<bool> StopOrFail(WebSocketCloseStatus status, string statusDescription)：使用自定义关闭代码停止/关闭 WebSocket 连接，方法可能抛出异常，但无论如何客户端都会被标记为已关闭，返回 true 表示成功启动关闭

3.3 强制重连

• Task Reconnect()：强制重连，关闭当前 WebSocket 流并与服务器建立新连接，连接错误时不会抛出异常，而是无限期尝试重连
• Task ReconnectOrFail()：强制重连，关闭当前 WebSocket 流并与服务器建立新连接，连接错误时抛出异常，不进行其他重连尝试

四、事件订阅与数据接收

IWebsocketClient 提供了多个可观察流，用于订阅接收消息、重连和断开事件。

4.1 接收消息流

• IObservable<ResponseMessage> MessageReceived：接收消息流（原始格式）

通过订阅此流，开发者可以获取从服务器接收到的消息。

4.2 重连事件流

• IObservable<ReconnectionInfo> ReconnectionHappened：重连事件流（在新连接后触发）

订阅此流可以获取重连相关的信息。

4.3 断开事件流

• IObservable<DisconnectionInfo> DisconnectionHappened：断开事件流（在连接丢失后触发）

通过订阅此流，开发者可以处理连接断开的情况。

五、配置参数设置

IWebsocketClient 提供了多个可配置的参数，用于调整客户端的行为。

5.1 连接超时设置

• TimeSpan ConnectTimeout：连接新客户端的最长等待时间，默认值为 5 秒

5.2 重连超时设置

• TimeSpan? ReconnectTimeout：如果没有消息从服务器传来，等待多久后重连，设为 null 可禁用此功能，默认值为 1 分钟
• TimeSpan? ErrorReconnectTimeout：如果上次重连失败，等待多久后重连，设为 null 可禁用此功能，默认值为 1 分钟
• TimeSpan? LostReconnectTimeout：如果连接因暂时性错误而丢失，等待多久后重连，设为 null 可禁用此功能，默认值为 null/禁用（立即重连）

5.3 功能开关

• bool IsReconnectionEnabled：启用或禁用重连功能，默认启用
• bool IsTextMessageConversionEnabled：启用或禁用文本消息从二进制到字符串的转换（通过 'MessageEncoding' 属性），默认启用
• bool IsStreamDisposedAutomatically：启用或禁用发送数据后自动释放 MemoryStream（仅适用于二进制响应），设为 false 允许直接访问流，但需自行处理释放，默认启用

5.4 其他配置

• string? Name：获取或设置当前 WebSocket 客户端实例的名称，用于日志记录（如果使用多个并行 WebSocket 客户端并希望区分它们）
• Encoding? MessageEncoding：文本消息的目标编码

六、状态属性与辅助方法

IWebsocketClient 提供了多个状态属性，用于获取客户端的当前状态。

6.1 运行状态

• bool IsStarted：返回 Start() 方法是否至少被调用过一次，如果未启动或已释放则返回 false
• bool IsRunning：返回客户端是否正在运行并已连接到服务器
• bool TextSenderRunning：返回文本消息发送器是否正在运行
• bool BinarySenderRunning：返回二进制消息发送器是否正在运行
• bool IsInsideLock：指示是否有任何线程已进入锁

6.2 辅助方法

• void StreamFakeMessage(ResponseMessage message)：流式传输/发布假消息（通过 'MessageReceived' 可观察对象），用于测试目的以模拟服务器消息
• new void Dispose()：终止 WebSocket 连接并清理所有资源

七、IWebsocketClient 接口的实现类

WebsocketClient 类是 IWebsocketClient 接口的实现，位于 src/Websocket.Client/WebsocketClient.cs 文件中。它实现了接口定义的所有方法和属性，提供了完整的 WebSocket 客户端功能。

开发者可以通过创建 WebsocketClient 实例来使用 IWebsocketClient 接口的功能，例如：

using IWebsocketClient client = new WebsocketClient(url);

八、使用示例

以下是一个简单的使用 IWebsocketClient 的示例，来自 test_integration/Websocket.Client.Sample/Program.cs：

using (IWebsocketClient client = new WebsocketClient(url, logger, factory)) { // 订阅接收消息事件 client.MessageReceived.Subscribe(msg => { Console.WriteLine($"Received message: {msg.Text}"); }); // 启动连接 await client.Start(); // 发送消息 client.Send("Hello, WebSocket!"); // 等待用户输入，保持连接 Console.ReadLine(); }

九、总结

IWebsocketClient 接口为 gh_mirrors/webso/websocket-client 项目提供了核心的 WebSocket 客户端功能，通过它，开发者可以轻松实现 WebSocket 通信，包括消息发送、连接管理、事件订阅等。掌握 IWebsocketClient 接口的使用，将有助于开发出稳定、高效的 WebSocket 应用。

无论是新手还是有经验的开发者，都可以通过本文档快速了解和使用 IWebsocketClient 接口，充分发挥 gh_mirrors/webso/websocket-client 项目的优势。

【免费下载链接】websocket-client🔧 .NET/C# websocket client library项目地址: https://gitcode.com/gh_mirrors/webso/websocket-client