nanoFramework.System.Net.WebSockets.Client 1.1.102

欢迎使用 .NET nanoFramework System.Net.WebSockets 库仓库

此 API 尽可能地反映官方 .NET System.Net.WebSockets。异常主要源自 .NET nanoFramework 中缺乏 async 和泛型支持。

构建状态

组件	构建状态	NuGet 包
System.Net.WebSockets
System.Net.WebSockets.Client
System.Net.WebSockets.Server

示例

WebSockets 服务器示例

Server.RgbSample 展示了如何使用 WebSockets 服务器与托管 WebApp 的 Web 服务器一起控制 Atom Lite ESP32 上的 rgb led。

WebSockets 客户端示例

Client.Sample 展示了如何使用 WebSockets 客户端。

WebSockets 服务器和客户端示例

ServerClient.Sample 展示了如何配置和启动 WebSocket 服务器和 (ssl) 客户端。

使用方法

这是一个 .NET nanoFramework 的 WebSocket 客户端和服务器库。WebSocket 主要用于创建需要与网络服务器保持持续连接的交互式 Web 应用程序。在物联网领域中，一些协议需要 WebSocket 连接，例如 SignalR。一些 IoT 服务器也支持或需要通过 WebSocket 运行的协议，例如 MQTT。

客户端

连接到 WebSocket 服务器

要连接到 WebSocket 服务器，创建一个 ClientWebsocket。在初始化时，您可以通过添加 ClientWebSocketOptions 来设置额外的 WebSocket 选项。这些选项可以用于设置特定的 SSL 选项、改变保持活跃间隔、服务器超时，并设置最大发送和接收消息大小。您可以通过调用包含 WebSocket 服务器 uri 的 Connect 来启动连接。WebSocket 的位置始终以 ws:// 或 wss:// 开头。您可以使用可选的 ClientWebSocketHeaders 来设置特定的头。

注意：ClientWebSocketOptions.MaxFragmentSize 设置了传出消息的最大包大小。当发送超过最大包大小的消息时，该消息将被自动分成更小的消息。

using System;
using System.Threading;
using System.Net.WebSockets;
using System.Net.WebSockets.WebSocketFrame;
using System.Text;

namespace NFWebsocketTestClient
{
    public class Program
    {
        public static void Main()
        {
            //setup WebSocketClient
            ClientWebSocket websocketClient = new ClientWebSocket(new ClientWebSocketOptions()
            {
                //Change the heart beat to a 30 second interval
                KeepAliveInterval = TimeSpan.FromSeconds(30)
            });

            //Handler for receiving websocket messages
            websocketClient.MessageReceived += WebsocketClient_MessageReceived;
            //Setup custom header
            var headers = new ClientWebSocketHeaders();
            headers["userId"] = "nano";

            //Connect the client to the websocket server with custom headers
            websocketClient.Connect("wss://websocket.nanoFramework.net", headers);

            //Send a message very 5 seconds
            while(websocketClient.State == System.Net.WebSockets.WebSocketFrame.WebSocketState.Open)
            {
                websocketClient.SendString("Hello nanoFramework Websocket!");
                Thread.Sleep(5000);
            }
        }

        private static void WebsocketClient_MessageReceived(object sender, MessageReceivedEventArgs e)
        {
            var client = (ClientWebSocket)sender;

            //If message is of type Text, echo message back to client
            if(e.Frame.MessageType == WebSocketMessageType.Text)
            {
                string message = Encoding.UTF8.GetString(e.Frame.Buffer, 0, e.Frame.MessageLength);
                client.SendString(message);
            }
        }
    }
}

连接状态

可以通过检查 ClientWebSocket 的 State 来监视连接状态。连接建立后，状态设置为 Open。仅当状态为 Open 时，客户端才能发送消息。

接收消息

可以通过为 MessageReceived 设置事件处理器来接收消息。每当接收到消息时，都会调用此处理器。《MesageReceivedArguments》包含一个带有包含消息的缓存的《MessageReceivedFrame》。

消息帧

WebSocket 的 MessageReceivedFrame 支持两种消息类型：Text 和 Binary。《MessageType》属性表示接收到的消息类型。《EndPoint》包含消息发送者的 IPEndPoint。《Buffer》包含实际发送的信息。

注意：为了能够接收分段的消息，用户需要实现自己的逻辑。通过检查 IsFragmented，您可以看到是否正在处理分段消息。《Fragmentation》属性表示您是否正在处理消息的起始、中间或结束部分。

发送消息

可以通过调用 SendString（用于发送文本消息）或 SendBytes（用于使用字节数组发送二进制消息）来发送消息。您还可以调用 Send，该函数接受字节数组和 MessageType 作为参数。

关闭连接

可以通过调用 Close 关闭连接。调用此方法将在行上发送一个关闭消息。您可以选择指定 WebSocketCloseStatus 和关闭原因的描述，以便进行调试。无论何时关闭连接，《Closed》事件都会触发。

服务器

WebSocketServer 是 .NET nanoFramework 的 WebSocket 主机，可以处理多个 WebSocket 连接。服务器可以独立运行或集成到 nanoFramework 的 HttpListener 或 WebServer 中。服务器与客户端实现共享一个常见的 WebSocket 基础。

创建服务器

要启动一个新的服务器，使用可选的 WebSocketServerOptions 创建一个 WebsocketServer。默认情况下，这将启动本地托管服务器，端口为 80。通过设置 Prefix 和 Port 选项，您可以指定服务器将在哪个端口和前缀下监听。默认前缀为 /。建议设置 MaxClients 以确保服务器不会耗尽资源。

如果您想要托管一个与websocket服务器交互的webapp，最好直接将websocket服务器与.NET nanoFramework HttpListener 或 WebServer 集成。为此，请将选项 IsStandAlone 设置为 false。

要启动websocket服务器，只需调用 Start。

WebSocketServer wsServer = new WebSocketServer(new WebSocketServerOptions() { 
                MaxClients = 10,
                IsStandAlone = false
            });

wsServer.MessageReceived += WsServer_MessageReceived;
wsServer.Start();

处理客户端连接

当websocket服务器为自托管时，客户端连接将自动处理并添加到websocket服务器客户端池中。您可以使用 ClientsCount 检查已连接客户端的数量。调用 ListClients 将返回所有已连接客户端的Ip端点数组。

当使用 .NET nanoFramework HttpListener 或 WebServer 时，您可以通过调用 AddWebSocket 将 HttpListenerContext 传递给websocket服务器来升级websocket请求。如果连接成功建立，AddWebSocket 将返回 true。

//webserver receive message event handler
private static void WebServer_CommandReceived(object obj, WebServerEventArgs e)
{
    //check the path of the request
    if(e.Context.Request.RawUrl == "/ws")
    {
        //check if this is a websocket request or a page request 
        if(e.Context.Request.Headers["Upgrade"] == "websocket")
        {
            //Upgrade to a websocket
            _wsServer.AddWebSocket(e.Context);
        }
    }
}

处理新连接

当客户端连接时，将调用 WebsocketOpened 事件。WebserverEventArgs 包含客户端的端点。

处理连接关闭

当客户端连接关闭时，将再次调用 WebsocketClosed 事件，其中在 webserverEventArgs 中包含端点。

关闭客户端连接

您可以通过调用 DisconnectClient 来关闭一个特定的客户端连接。您需要通过提供一个客户端端点来指定要断开的客户端。您还需要指定合适的 WebSocketCloseStatus。

接收消息

当接收到任何客户端的消息时，将会引发 MessageReceived。请参阅客户端部分的接收消息 和 消息帧 了解如何处理消息。可以检查 MessageFrame 的 Endpoint 属性来识别发送消息的客户端。

发送消息

可以通过调用 SendString 来发送文本消息，或者调用 SendData 来使用字节数组发送二进制消息。您需要指定要发送消息的确切客户端 EndPoint。如果您想要向所有客户端发送消息，可以使用 Broadcast 并提供一个字节数组或字符串。

停止服务器

您可以通过调用 Stop 来停止websocket服务器。

反馈和文档

有关文档、提供反馈、问题以及了解如何贡献，请参阅主仓库。

加入我们的Discord社区这里。

鸣谢

此项目的贡献者列表可以在贡献者中找到。

许可证

nanoFramework 类库采用MIT许可。

行为守则

本项目已采用贡献者公约中定义的行为守则，以阐明社区中应有的行为。有关更多信息，请参阅 .NET 基金会行为守则。

.NET 基金会

本项目由 .NET 基金会 支持。