MQTTnet
定义
MQTTnet 是一个用 C# 编写、运行于 .NET 平台的 MQTT 协议实现库，目标是让 .NET 程序能够接入以 MQTT 为通信基础的系统[3]。它的覆盖面并不限于客户端：库内既包含连接消息代理的客户端部分，也包含可作为消息代理运行的服务器部分，并且支持 MQTT 3.1.0、3.1.1 与 5.0 三个版本的报文规范[5]。库以 NuGet 包形式分发，安装后不引入额外的第三方依赖。
它与 MQTT 协议本身是两层不同的东西：协议规定报文格式与交互流程，MQTTnet 则把这种报文交互封装成可由 .NET 代码调用的接口，并提供统一 API 供不同协议版本共用[3]。
原理
MQTT 采用发布/订阅模型，客户端把带主题名的消息交给代理，代理再按订阅关系分发给其他客户端，发布方与接收方因此不必彼此知晓。主题字符串按层级组织，订阅时可使用单层通配符 + 与多层通配符 # 匹配一组主题；消息可靠性由 QoS 0、QoS 1、QoS 2 三档保证，分别对应至多一次、至少一次与仅一次投递[6]。
在库内部，报文编解码、连接状态维护与事件分发被拆成若干层次，客户端按需组合通信通道与协议版本，对外则以选项对象配置连接参数、证书与回调[3]。异步方法贯穿连接、订阅与发布等操作，返回值或事件回调中携带代理给出的应答结果[7]。
flowchart LR
A[发布方客户端] -->|PUBLISH 主题+QoS| B[MQTT 代理]
B -->|PUBLISH 转发| C[订阅方客户端]
B -.->|ACK / PUBACK| A
D[MQTTnet 服务器实现] --- B
从 4.0 版起，库内不再代为处理超时，连接、发布等方法改为接收取消令牌，调用方需自行设定超时策略；同时代理端的默认监听端口不再自动开启，需显式配置[8]。
发展历程
项目早期由开发者 Christian Kratky 创建并长期维护，代码托管于 GitHub，采用 MIT 许可证；版权声明覆盖 2016 年至 2019 年间[2][1]。2017 年 3 月起仓库持续更新，逐步形成客户端、服务器与若干扩展包并存的布局[9]。
2.x 与 3.x 时期，库以同步与异步混用的事件接口为主，并陆续加入对 MQTT 5.0 的支持；3.x 版本一度被大量项目采用，成为较稳定的分支[10][11]。约在 2022 年前后发布的 4.x 是一次较大的重构，接口由抽象类型改为事件模型，命名空间与类名亦有调整[8]。
4.0 版同时公布项目加入 .NET 基金会，此后仓库地址随之迁移到基金会组织名下[8][4]。5.x 版本的目标框架收缩至 .NET 6 及以上，客户端与服务器拆分为独立包，默认协议版本改为 MQTT 5.0，并移除了一批过时接口[12]。至 2024 年 9 月，NuGet 上的版本号已推进到 5.x 系列并持续更新[5]。
应用
由于同时具备客户端与服务端实现，MQTTnet 常被用于构建物联网数据采集与下发链路，例如设备状态上报、远程指令下发以及上位机与现场设备之间的数据交换[13]。在 .NET 环境中，开发者通过 NuGet 引入包，再按连接、订阅、发布三步组织代码，是这类应用最常见的起点[3]。
库的客户端部分可与微软的 Azure IoT Hub 对接，服务器部分则可用于自建轻量消息代理，把 MQTT 能力嵌入自有服务之中[3]。在工业软件领域，有商业组件把 MQTTnet 作为可插拔的底层通信包，用于 OPC UA 等场景下的消息传输[1]。此外，社区围绕它派生出托管客户端、RPC、主题模板等扩展包，用以补足自动重连、请求应答一类的功能[5]。
局限
MQTTnet 只覆盖 MQTT 协议本身，不含集群、规则引擎、持久化存储或运维管理界面，把它当作生产级消息平台使用时，这些能力需要另行搭建[3]。库的服务器实现虽提供保留消息与订阅校验等机制，但消息持久化等特性仅留下接口，需使用者自行实现。
版本间接口变动较频繁，从 3.x 升级到 4.x、再到 5.x 均伴随破坏性改动，旧代码往往需要逐处调整；5.x 还要求 .NET 6 及以上运行时，仍在 .NET Framework 上的项目无法直接迁移[7][12]。文档与示例的更新也常滞后于代码，官方 wiki 长期只对应 3.x 版本，阅读旧教程时容易遇到与当前版本不符的用法[8]。
在性能层面，项目文档给出的吞吐数据来自本机单进程、客户端与代理同机的测试条件，实际网络环境中的表现会因链路质量与配置而不同[3]。库本身只实现协议，QoS 语义的最终效果仍取决于所使用的代理与其他客户端是否遵循同一规范[6]。
参见
参考资料
- MQTT communication packages: Difference between revisions [引用日期2026-10-29]
- MQTTnet/LICENSE at master · chinason/MQTTnet · GitHub [引用日期2026-10-29]
- MQTTnet [引用日期2026-10-29]
- MQTTnet [引用日期2026-10-29]
- packages [引用日期2026-10-29]
- Mqtt | IEEE Technology Navigator [引用日期2026-10-29]
- github.com 上的网页 [引用日期2026-10-29]
- Release v4.0.0.167 · dotnet/MQTTnet - Skip to content [引用日期2026-10-29]
- MQTTnet | Ecosystem Directory | market.dev [引用日期2026-10-29]
- [ [引用日期2026-10-29]
- README [引用日期2026-10-29]
- github.com 上的网页 [引用日期2026-10-29]
- MQTTnet: 实战 MQTT 应用程序开发 [引用日期2026-10-29]