Skip to content

Releases: IoTSharp/CoAP.NET

Release list

v3.0.0

v3.0.0 Latest
Latest

Choose a tag to compare

View all tags
@maikebing maikebing released this 09 Jul 02:50
v3.0.0
098d647

CoAP.NET 3.0.0 发布说明

CoAP.NET 3.0.0 是 IoTSharp 维护 fork 的第一轮完整现代化发布。这个版本保留原 CoAP.NET 的 client、server、resource tree、Blockwise、Observe 和 CoAP/CoRE 语义，同时补齐 .NET 10、Generic Host、Resource/MVC 路由、AOT 友好 source generation、DTLS PSK、NuGet 发布和宿主迁移文档。

NuGet 包

本次发布包含三个包：

包 用途
IoTSharp.CoAP.NET 核心 CoAP client/server、resource tree、route adapter、Resource/MVC hosting、Blockwise、Observe、DTLS PSK。
IoTSharp.CoAP.NET.SourceGeneration Roslyn analyzer/source generator，用于生成 Resource/MVC endpoint factory，减少 Native AOT 宿主的反射发现依赖。
IoTSharp.CoAP.NET.AspNetCore ASP.NET Core IApplicationBuilder 扩展，使 ASP.NET Core 宿主可以调用 app.MapCoapResources()。

安装示例：

dotnet add package IoTSharp.CoAP.NET --version 3.0.0
dotnet add package IoTSharp.CoAP.NET.SourceGeneration --version 3.0.0
dotnet add package IoTSharp.CoAP.NET.AspNetCore --version 3.0.0

主要变化

.NET 10 与包发布

  • 主包升级到 net10.0，source generator 包面向 netstandard2.0，便于 analyzer 被宿主项目引用。
  • 三个 NuGet 包补齐 README.md、LICENSE、项目地址、仓库地址、NuGet 图标和包说明。
  • 新增 CoAP.NET 专属 logo，并打入 NuGet package icon。
  • IoTSharp.CoAP.NET.SourceGeneration 显式设置 C# language version，修复 CI 中 netstandard2.0 默认 C# 7.3 与 nullable 冲突的问题。

Host-managed Resource/MVC

  • 新增推荐宿主入口：AddCoapServer()、AddCoapResources() / AddCoapMvc()、MapCoapResources()。
  • CoAP server 生命周期由 Generic Host 管理，宿主应用不再需要手动 new CoapServer() 或传递裸 IServiceProvider。
  • 业务端点通过 [CoapResource]、[CoapRoute]、[CoapGet]、[CoapPost]、[CoapPut]、[CoapDelete]、[CoapObserve] 声明。
  • CoapResourceBase 提供 Context、Payload、RouteValues、Options 等请求上下文快捷访问。

常用启动形态：

builder.Services.AddCoapServer(options =>
{
    options.ListenAnyIP(5683);
});
builder.Services.AddCoapResources();

var app = builder.Build();
app.MapCoapResources();
app.Run();

Routing、绑定和结果模型

  • 新增 CoapRoutePattern、CoapEndpoint、CoapEndpointMetadataCollection、ICoapEndpointDataSource、ICoapEndpointMatcher 等 routing core 抽象。
  • CoapRouteContext.Payload 暴露 ReadOnlyMemory<byte>，route values 使用紧凑只读集合，降低小请求分配。
  • CoapRouteResult / ICoapResult 统一表达 status、text/binary/JSON payload、Content-Format、ETag、Max-Age、Location-Path、Location-Query 和 Observe。
  • action 参数支持 route value、query、request option、payload、CancellationToken、CoapRouteContext 和远端 endpoint 绑定。
  • Content-Format / Accept 根据 endpoint metadata 做协商，不支持的请求返回稳定 CoAP 错误。

JSON、AOT 和 source generation

  • 支持 source-generated System.Text.Json metadata 绑定 JSON payload。
  • IoTSharp.CoAP.NET.SourceGeneration 可根据 [CoapResource] 和 method route attribute 生成 endpoint factory。
  • Native AOT 宿主可使用 AddCoapJsonPayloadBinder(JsonSerializerContext) 和 options.AddEndpointFactory(...) 避免运行时反射发现。
  • 反射型 discovery 和 JSON binder 保留为非 AOT 或兼容场景的显式入口。

Discovery、Observe、Blockwise 和 DTLS

  • .well-known/core 由 endpoint metadata 生成 CoRE Link Format，支持 title、resource type、interface、content-format、Observe 可见性和隐藏端点。
  • Observe endpoint 可通过 [CoapObserve] 声明，并由 route-backed resource 接入 Observe registry。
  • C12 smoke 覆盖 route + Blockwise 大 payload、DTLS PSK 和 Observe。
  • 新增纯托管 DTLS PSK server/client channel，支持 coaps:// 可选启用。

安全和宿主扩展点

  • 新增 endpoint filter、authorization hook、request context hook 和请求级 Items。
  • [CoapAuthorize] / [CoapAllowAnonymous] 只表达 metadata；租户、身份、权限、审计仍由宿主实现。
  • 声明授权但未注册 authorization hook 时默认拒绝，避免误放行。
  • dispatcher 调用顺序为 context hook -> authorization hook -> endpoint filters -> action -> result executor。

路线完成情况

3.0.0 对应路线图 C0-C13 全部收口：

  • C0-C3：命名与兼容基线、route adapter、async handler、低分配 payload 与 option 访问。
  • C4-C6：routing core、hosted server/resource 注册、dispatcher pipeline。
  • C7-C10：attribute routing、model binding、resource discovery、filter 与安全扩展点。
  • C11-C12：Resource/MVC 示例、迁移文档、性能/AOT/发布检查清单。
  • C13：宿主应用迁移落地，宿主移除手写 route endpoint 注册，改用 AddCoapServer()、AddCoapResources() 和 app.MapCoapResources()。

兼容与迁移

保留能力：

  • 原 CoAP.NET Resource tree、Resource、IResource、ResourceAttributes、DiscoveryResource 等 CoAP/CoRE 协议概念继续保留。
  • CoAP.CoapClient、CoAP.Request、Observe、Blockwise、UDP endpoint 等原有入口继续可用。
  • 低层 CoapRouteEndpoint.Create(...) 仍可用于测试、兼容适配或极简 handler。

推荐迁移方向：

  • 新宿主代码优先使用 AddCoapServer()、AddCoapResources() 和 MapCoapResources()。
  • 业务路径放在 [CoapResource] / [CoapRoute] / method attributes 上。
  • 业务 DTO、授权、租户、审计、领域服务调用保留在宿主应用，不迁入 CoAP.NET。
  • AOT 敏感宿主使用 source-generated endpoint factory 和 source-generated JSON metadata。

更多迁移说明见 docs/resource-mvc-migration.md。

3.0 之后的路线

3.0 之后的工作重点不再是把宿主业务逻辑迁入 CoAP.NET，而是继续加强协议栈和框架边界：

  • 固化 public API 兼容性和 NuGet 发布节奏。
  • 继续补齐 source generator 能力，减少 AOT 宿主的 reflection fallback。
  • 增强 route matcher、discovery 和 Observe 的诊断可见性。
  • 增加更多 Resource/MVC 示例，覆盖安全 hook、插件程序集、DTLS 配置和复杂 payload 绑定。
  • 维护性能 benchmark，避免 route adapter 和 metadata discovery 引入不必要分配。
  • 保持 CoAP.NET 只拥有协议栈、resource/routing/discovery 框架；宿主业务模型、权限、租户、审计和数据库访问继续留在宿主应用。
Assets 2
Loading