nanoFramework.System.Net.WebSockets 1.1.102

欢迎来到 .NET nanoFramework System.Net.WebSockets 库代码仓库

此 API （尽可能接近）反映了官方 .NET System.Net.WebSockets API。异常主要来自 .NET nanoFramework 中缺乏 async 和泛型支持。

构建状态

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

示例

WebSockets 服务器示例

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

WebSockets 客户端示例

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

WebSockets 服务器和客户端示例

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

用法

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

客户端

连接到 WebSocket 服务器

要连接到 WebSocket 服务器，创建一个 ClientWebsocket。您可以在初始化时添加 ClientWebSocketOptions 来设置额外的 WebSocket 选项。这些选项可以用于设置特定的 SSL 选项、更改心跳间隔、服务器超时并设置最大发送和接收消息大小。您可以通过调用 Connect 并传入 WebSocket 服务器的 URI 来开始连接。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 来发送消息。您还可以调用接收字节数组和 MessageType 作为参数的 Send。

关闭连接

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

服务器

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

创建服务器

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

如果您想托管要与 WebSocket 服务器交互的 Web 应用程序，最好将 WebSocket 服务器直接集成到 .NET nanoFramework 的 HttpListner 或 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 的 HttpListner 或 WebServer 时，您可以通过调用 AddWebSocket 将 HttpListnerContext 传递到 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 服务器。

反馈和文档

有关文档、提供反馈、报告问题和了解如何贡献力量，请参阅 Home 仓库。

加入我们的 Discord 社区 此处。

致谢

此项目的贡献者名单可在 CONTRIBUTORS 中找到。

许可证

nanoFramework 类库是根据 MIT 许可证 许可的。

行为准则

本项目采用了贡献者守则中定义的行为规范，以明确我们社区中的预期行为。更多信息请参阅.NET Foundation行为规范。

.NET Foundation

本项目由.NET Foundation支持。