nanoFramework.System.Net.WebSockets.Server 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 展示了如何使用 Websocket Server 和托管 WebApp 的 Web 服务器控制 Atom Lite ESP32 上的 RGB LED。

WebSockets 客户端示例

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

WebSockets 服务器和客户端示例

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

用法

这是一个.NET nanoFramework的WebSocket客户端和服务器库。WebSocket主要用于创建需要与服务器保持恒定连接的交互式Web应用。在物联网领域，一些协议（如SignalR）需要WebSocket连接。一些物联网服务器也支持或要求通过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使用字节数组发送二进制消息。您还可以调用Send，它接受一个字节数组和MessageType作为参数。

关闭连接

可以通过调用Close来关闭连接。调用此方法将发送一个关闭消息。您可以选择指定WebSocketCloseStatus和描述关闭原因以进行调试。每次关闭连接时都会触发Closed事件。

服务器

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

创建服务器

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

如果您希望托管一个与WebSocket服务器交互的Web应用，最好直接将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包含客户端的端点。

处理连接关闭

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

关闭客户端连接

您可以调用DisconnectClient来关闭特定的客户端连接。您需要提供要断开连接的客户端端点，并且您还需要提供适当的WebSocketCloseStatus。

接收消息

接收消息

当来自任何客户端的消息被接收时，将引发MessageReceived事件。有关如何处理消息，请参阅客户端部分的接收消息和消息帧。可以通过检查MessageFrame的Endpoint属性来识别发送消息的客户端。

发送消息

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

停止服务器

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

反馈和文档

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

致谢

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

许可

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

行为准则

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

.NET基金会

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