nanoFramework.WebServer 1.2.56

欢迎使用 .NET nanoFramework WebServer 代码库

构建状态

组件	构建状态	NuGet 包
nanoFramework.WebServer
nanoFramework.WebServer.FileSystem

.NET nanoFramework WebServer

此库由 Laurent Ellerbach 编写，他慷慨地将其提供给 .NET nanoFramework 项目。

这是一个简单的 nanoFramework WebServer。功能包括

• 处理多线程请求
• 使用 nanoFramework.WebServer.FileSystem NuGet 从任何存储空间中提供服务。需要一个支持存储（具有 System.IO.FileSystem 功能）的目标设备。
• 处理 URL 中的参数
• 可行同时运行多个 WebServer
• 支持 GET/PUT 和其他任何命令
• 支持任何类型的头部
• 支持 POST 中的内容
• 反射以方便使用控制器和路由概念
• 辅助函数以直接返回错误代码，方便 REST API 使用
• 支持 HTTPS
• URL 解码/编码

限制

• 不支持请求或响应流中的任何 zip 文件

用法

您只需要为查询指定端口和超时时间，并添加一个当请求到来时进行事件处理的操作。用这种方法，每次接收到请求时都会触发一个事件。

using (WebServer server = new WebServer(80, HttpProtocol.Http)
{
    // Add a handler for commands that are received by the server.
    server.CommandReceived += ServerCommandReceived;

    // Start the server.
    server.Start();

    Thread.Sleep(Timeout.Infinite);
}

您还可以传递一个控制器，您可以在其中对路由和方法使用装饰。

using (WebServer server = new WebServer(80, HttpProtocol.Http, new Type[] { typeof(ControllerPerson), typeof(ControllerTest) }))
{
    // Start the server.
    server.Start();

    Thread.Sleep(Timeout.Infinite);
}

在这种情况下，您正在传递两个具有公开方法的类，这些方法将在找到路由时被调用。

使用前面的例子，一个非常简单直接测试控制器看起来是这样的

public class ControllerTest
{
    [Route("test"), Route("Test2"), Route("tEst42"), Route("TEST")]
    [CaseSensitive]
    [Method("GET")]
    public void RoutePostTest(WebServerEventArgs e)
    {
        string route = $"The route asked is {e.Context.Request.RawUrl.TrimStart('/').Split('/')[0]}";
        e.Context.Response.ContentType = "text/plain";
        WebServer.OutPutStream(e.Context.Response, route);
    }

    [Route("test/any")]
    public void RouteAnyTest(WebServerEventArgs e)
    {
        WebServer.OutputHttpCode(e.Context.Response, HttpStatusCode.OK);
    }
}

在这个例子中，当请求的URL是 test 或 Test2 或 tEst42 或 TEST 时，将调用 RoutePostTest，URL可以带参数，且方法是GET。请注意，Test 不会调用该函数，也不会调用 test/。

RouteAnyTest 在URL是 test/any 且不区分方法时会被调用。

更高级的例子是通过简单的REST API获取人员列表并添加人员。请查看示例。

[!Important]

默认情况下，路由不区分大小写，并且属性必须全部小写。如果您想使用区分大小写的路由，如前面的例子所示，请使用属性 CaseSensitive。同样，您必须按照您想要的方式响应路由来编写路由。

一个简单的GPIO控制器REST API

您将在简单的 GPIO控制器示例 REST API中找到。控制器不区分大小写，工作方式如下

• 打开2号引脚作为输出：http://你的链接/open/2/output
• 打开4号引脚作为输入：http://你的链接/open/4/input
• 将2号引脚写入高电平：http://你的链接/write/2/high
  • 您可以使用high或1，它们具有相同的效果，并将引脚放置在高电平位置
  • 您可以使用low或0，它们具有相同的效果，并将引脚放置在低电平位置
• 读取4号引脚：http://你的链接/read/4，您将得到纯文本形式的 high 或 low，取决于状态

控制器上的身份验证

控制器支持身份验证。目前控制器上只有三种身份验证类型已实施

• 基本身份验证：遵循HTTP标准的经典用户和密码。用法：
  • [Authentication("Basic")] 将使用Web服务器的默认凭证
  • [Authentication("Basic:myuser mypassword")] 将使用myuser作为用户名，使用mypassword作为密码。注意：用户名不能包含空格。
• 在标题中添加ApiKey：在标题中添加带有关键API的ApiKey。用法：
  • [Authentication("ApiKey")] 将使用Web服务器的默认凭证
  • [Authentication("ApiKey:akey")] 将使用akey作为ApiKey。
• 无：无需身份验证。用法：
  • [Authentication("None")] 将使用Web服务器的默认凭证

Authentication属性适用于公开类和公开方法。

至于控制器中的其余部分，您可以为它们添加属性来定义或覆盖它们。以下示例显示了可以做什么

[Authentication("Basic")]
class ControllerAuth
{
    [Route("authbasic")]
    public void Basic(WebServerEventArgs e)
    {
        WebServer.OutputHttpCode(e.Context.Response, HttpStatusCode.OK);
    }

    [Route("authbasicspecial")]
    [Authentication("Basic:user2 password")]
    public void Special(WebServerEventArgs e)
    {
        WebServer.OutputHttpCode(e.Context.Response, HttpStatusCode.OK);
    }

    [Authentication("ApiKey:superKey1234")]
    [Route("authapi")]
    public void Key(WebServerEventArgs e)
    {
        WebServer.OutputHttpCode(e.Context.Response, HttpStatusCode.OK);
    }

    [Route("authnone")]
    [Authentication("None")]
    public void None(WebServerEventArgs e)
    {
        WebServer.OutputHttpCode(e.Context.Response, HttpStatusCode.OK);
    }

    [Authentication("ApiKey")]
    [Route("authdefaultapi")]
    public void DefaultApi(WebServerEventArgs e)
    {
        WebServer.OutputHttpCode(e.Context.Response, HttpStatusCode.OK);
    }
}

并且您可以向服务器传递默认凭证

using (WebServer server = new WebServer(80, HttpProtocol.Http, new Type[] { typeof(ControllerPerson), typeof(ControllerTest), typeof(ControllerAuth) }))
{
    // To test authentication with various scenarios
    server.ApiKey = "ATopSecretAPIKey1234";
    server.Credential = new NetworkCredential("topuser", "topPassword");

    // Start the server.
    server.Start();

    Thread.Sleep(Timeout.Infinite);
}

使用前面的示例发生以下情况：

• 默认情况下，所有控制器，即使未指定任何内容，也将使用控件凭证。在我们的案例中，使用默认用户（topuser）和密码（topPassword）的基本身份验证将被使用。
  • 当通过浏览器调用http://你的链接/authbasic时，将提示您输入用户名和密码，使用默认的用户topuser和密码topPassword以获取访问权限
  • 当调用http://你的链接/authnone时，因为没有身份验证被覆盖为无，所以不会提示您。
  • 当调用 http://yoururl/authbasicspecial 时，用户和密码与默认的 user2 和密码不同，这里正确的用户密码对是 user2 和 password
• 如果您在控制器中定义了特定的用户和密码，例如 [Authentication("Basic:myuser mypassword")]，那么所有控制器都将使用 myuser 和 mypassword 作为默认密码
• 当调用 http://yoururl/authapi 时，您必须传递名为 ApiKey（区分大小写）的头部，其值应为 superKey1234 以获得授权，这将覆盖默认的 Basic 认证
• 当调用 http://yoururl/authdefaultapi 时，将使用默认密钥 ATopSecretAPIKey1234，因此您需要在请求头部中传递它

总的来说，这是一个展示如何使用认证的示例，它被定义为允许灵活性

通过事件管理传入的查询

基本用法如下

private static void ServerCommandReceived(object source, WebServerEventArgs e)
{
    var url = e.Context.Request.RawUrl;
    Debug.WriteLine($"Command received: {url}, Method: {e.Context.Request.HttpMethod}");

    if (url.ToLower() == "/sayhello")
    {
        // This is simple raw text returned
        WebServer.OutPutStream(e.Context.Response, "It's working, url is empty, this is just raw text, /sayhello is just returning a raw text");
    }
    else
    {
        WebServer.OutputHttpCode(e.Context.Response, HttpStatusCode.NotFound);
    }
}

您可以进行更复杂的场景，例如 返回一个完整的 HTML 页面

WebServer.OutPutStream(e.Context.Response, "<html><head>" +
    "<title>Hi from nanoFramework Server</title></head><body>You want me to say hello in a real HTML page!<br/><a href='/useinternal'>Generate an internal text.txt file</a><br />" +
    "<a href='/Text.txt'>Download the Text.txt file</a><br>" +
    "Try this url with parameters: <a href='/param.htm?param1=42&second=24&NAme=Ellerbach'>/param.htm?param1=42&second=24&NAme=Ellerbach</a></body></html>");

并且可以从 URL 获取参数，例如从之前的 param.html 页面中的链接示例

if (url.ToLower().IndexOf("/param.htm") == 0)
{
    // Test with parameters
    var parameters = WebServer.decryptParam(url);
    string toOutput = "<html><head>" +
        "<title>Hi from nanoFramework Server</title></head><body>Here are the parameters of this URL: <br />";
    foreach (var par in parameters)
    {
        toOutput += $"Parameter name: {par.Name}, Value: {par.Value}<br />";
    }
    toOutput += "</body></html>";
    WebServer.OutPutStream(e.Context.Response, toOutput);
}

并且服务静态文件

// E = USB storage
// D = SD Card
// I = Internal storage
// Adjust this based on your configuration
const string DirectoryPath = "I:\\";
string[] _listFiles;

// Gets the list of all files in a specific directory
// See the MountExample for more details if you need to mount an SD card and adjust here
// https://github.com/nanoframework/Samples/blob/main/samples/System.IO.FileSystem/MountExample/Program.cs
_listFiles = Directory.GetFiles(DirectoryPath);
// Remove the root directory
for (int i = 0; i < _listFiles.Length; i++)
{
    _listFiles[i] = _listFiles[i].Substring(DirectoryPath.Length);
}

var fileName = url.Substring(1);
// Note that the file name is case sensitive
// Very simple example serving a static file on an SD card                   
foreach (var file in _listFiles)
{
    if (file == fileName)
    {
        WebServer.SendFileOverHTTP(e.Context.Response, DirectoryPath + file);
        return;
    }
}

WebServer.OutputHttpCode(e.Context.Response, HttpStatusCode.NotFound);

[!Important]

服务文件需要 nanoFramework.WebServer.FileSystem nuget AND 设备支持存储，因此需要 System.IO.FileSystem。

此外，也支持 REST API，这里有一个全面的示例

if (url.ToLower().IndexOf("/api/") == 0)
{
    string ret = $"Your request type is: {e.Context.Request.HttpMethod}\r\n";
    ret += $"The request URL is: {e.Context.Request.RawUrl}\r\n";
    var parameters = WebServer.DecodeParam(e.Context.Request.RawUrl);
    if (parameters != null)
    {
        ret += "List of url parameters:\r\n";
        foreach (var param in parameters)
        {
            ret += $"  Parameter name: {param.Name}, value: {param.Value}\r\n";
        }
    }

    if (e.Context.Request.Headers != null)
    {
        ret += $"Number of headers: {e.Context.Request.Headers.Count}\r\n";
    }
    else
    {
        ret += "There is no header in this request\r\n";
    }

    foreach (var head in e.Context.Request.Headers?.AllKeys)
    {
        ret += $"  Header name: {head}, Values:";
        var vals = e.Context.Request.Headers.GetValues(head);
        foreach (var val in vals)
        {
            ret += $"{val} ";
        }

        ret += "\r\n";
    }

    if (e.Context.Request.ContentLength64 > 0)
    {

        ret += $"Size of content: {e.Context.Request.ContentLength64}\r\n";
        byte[] buff = new byte[e.Context.Request.ContentLength64];
        e.Context.Request.InputStream.Read(buff, 0, buff.Length);
        ret += $"Hex string representation:\r\n";
        for (int i = 0; i < buff.Length; i++)
        {
            ret += buff[i].ToString("X") + " ";
        }

    }

    WebServer.OutPutStream(e.Context.Response, ret);
}

这个 API 示例很简单，但如您所知，您可以选择做什么。

当您获得 URL 时，您可以检查是否调用了特定的控制器。您还有参数和内容有效载荷！

以下是一个调用示例的结果

还有更多！查看完整的示例了解有关此 WebServer 的更多信息！

使用 HTTPS

您需要生成证书和密钥

X509Certificate _myWebServerCertificate509 = new X509Certificate2(_myWebServerCrt, _myWebServerPrivateKey, "1234");

// X509 RSA key PEM format 2048 bytes
        // generate with openssl:
        // > openssl req -newkey rsa:2048 -nodes -keyout selfcert.key -x509 -days 365 -out selfcert.crt
        // and paste selfcert.crt content below:
        private const string _myWebServerCrt =
@"-----BEGIN CERTIFICATE-----
MORETEXT
-----END CERTIFICATE-----";

        // this one is generated with the command below. We need a password.
        // > openssl rsa -des3 -in selfcert.key -out selfcertenc.key
        // the one below was encoded with '1234' as the password.
        private const string _myWebServerPrivateKey =
@"-----BEGIN RSA PRIVATE KEY-----
MORETEXTANDENCRYPTED
-----END RSA PRIVATE KEY-----";

using (WebServer server = new WebServer(443, HttpProtocol.Https)
{
    // Add a handler for commands that are received by the server.
    server.CommandReceived += ServerCommandReceived;
    server.HttpsCert = _myWebServerCertificate509;

    server.SslProtocols = System.Net.Security.SslProtocols.Tls | System.Net.Security.SslProtocols.Tls11 | System.Net.Security.SslProtocols.Tls12;
    // Start the server.
    server.Start();

    Thread.Sleep(Timeout.Infinite);
}

[!重要] 由于上述证书不是由证书颁发机构签发的，因此它不会被认可为有效证书。如果您想通过浏览器访问 nanoFramework 设备，例如，您必须将 CRT 文件添加为可信对象。在 Windows 上，您只需双击 CRT 文件，然后单击“安装证书...”。

当然，您可以使用前面定义的路径。两种方法都有效，即使路由或具有控制器概念的路径。

WebServer 状态

可以通过订阅事件来获取 WebServer 的状态。这可以很有用，例如重新启动服务器，设置重试机制或类似机制。

server.WebServerStatusChanged += WebServerStatusChanged;

private static void WebServerStatusChanged(object obj, WebServerStatusEventArgs e)
{
    // Do whatever you need like restarting the server
    Debug.WriteLine($"The web server is now {(e.Status == WebServerStatus.Running ? "running" : "stopped" )}");
}

端到端测试

在 WebServerE2ETests 中有一个名为 nanoFramework WebServer E2E Tests.postman_collection.json 的 Postman 测试集合，它应该在真实世界场景中测试 WebServer。使用方法简单

• 将 json 文件导入 Postman
• 将 WebServerE2ETests 部署到您的设备上 - 复制 IP 地址
• 将 base_url 变量设置为与您的设备 IP 地址匹配
• 选择要测试的请求或运行整个集合并检查测试结果。

反馈和文档

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

加入我们的 Discord 社区 这里。

鸣谢

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

许可

nanoFramework WebServer 库 licensed under the MIT license。

行为准则

此项目已采用贡献者公约中定义的行为准则，以阐明我们在社区中期望的行为。有关更多信息，请参阅 .NET Foundation Code of Conduct。

.NET Foundation

此项目由 .NET Foundation 支持。