简介面向物联网开发初学者与.NET技术人员的MQTT通信实践资源聚焦在.NET Core 3.0环境下借助MQTTnet库打通客户端与服务器Broker的完整链路解决发布/订阅模式落地、QoS等级选择与消息收发处理等常见入门问题。压缩包共77个文件、约1.15MB以cs源码、csproj项目文件、sln解决方案为主辅以dll、exe等编译产物及json、cache等中间缓存文件可直接还原Visual Studio工程结构。资源内含Client与Server两套示例源码对连接、发布、订阅及消息接收处理等关键步骤均有注释便于对照理解协议工作机制并动手调试。目前已有2568人学习下载适合希望快速上手MQTT物联网协议通信的开发者参考实践。1. 从一份 .NET Core 3.0 的 MQTT 双端 Demo 说起它到底能帮你省掉哪几天物联网项目里最磨人的环节往往不是业务逻辑而是设备和服务端之间那条“消息通道”能不能稳定跑通。我见过不少团队在 MQTT 上卡住Broker 选型纠结、客户端连上就掉线、QoS 设了 2 结果消息重复、Topic 层级设计混乱导致订阅收不到。这份基于 .NET Core 3.0 的 MQTT 通信 Demo把 Client 和 Server 两端都做成了可运行工程用的正是 MQTTnet 这个 .NET 生态里最常用的 MQTT 库。它解决的不是“教你什么是发布订阅”而是给你一套能直接跑起来、能改参数、能对照排查的双端骨架。适合谁正在做设备接入网关、上位机通信、工业数据采集或者单纯想用 C# 快速验证 MQTT 链路的从业者。下面我按“先跑通、再拆参数、最后避坑”的顺序把这份资源拆开讲。2. 双端工程怎么落地从 Broker 启动到第一条消息回环2.1 先认清 Server 端在 Demo 里的角色很多人拿到“Client 和 Server 完整 demo”会误以为 Server 是业务服务端其实在 MQTT 语境里Server 通常指 Broker消息代理。这份 Demo 的 Server 端基于 MQTTnet 的 Server 实现负责监听端口、管理会话、转发消息。它和 EMQX、Mosquitto 这类独立 Broker 的定位一致只是用 .NET 代码内嵌方便你在同一个解决方案里调试。选它而不是外挂 Broker 的理由很实际不用额外装服务、端口和证书配置全在代码里、断点能直接打进消息分发逻辑。代价是生产环境要自己补持久化、集群和鉴权这点后面避坑章会展开。启动 Server 的核心代码大致如下我按 Demo 的结构还原了关键片段// Server 端构建并启动 MQTT Broker var optionsBuilder new MqttServerOptionsBuilder() .WithDefaultEndpoint() // 使用默认监听配置 .WithDefaultEndpointPort(1883) // MQTT 明文端口 .WithConnectionBacklog(100); // 连接排队上限 var mqttServer new MqttFactory().CreateMqttServer(optionsBuilder.Build()); // 客户端连接时触发可用于做接入鉴权 mqttServer.ClientConnectedHandler new MqttServerClientConnectedHandlerDelegate(e { Console.WriteLine($客户端接入: {e.ClientId}); }); await mqttServer.StartAsync(); Console.WriteLine(Broker 已启动监听 1883);这段代码的逻辑很直白MqttServerOptionsBuilder负责拼装监听参数WithDefaultEndpointPort决定端口WithConnectionBacklog控制同时排队等待握手的连接数。ClientConnectedHandler是接入钩子Demo 里只打印 ClientId实际项目里可以在这里查白名单、校验用户名密码。注意StartAsync之后进程要保活控制台程序别让主线程直接退出否则 Broker 跟着进程一起没了——这是新手第一个翻车点。2.2 Client 端连接、订阅、发布的最小闭环Client 端是这份 Demo 更值得抄的部分因为它把连接、订阅、发布、断线重连的骨架都摆出来了。MQTTnet 的客户端 API 在 3.x 版本里是MqttFactory().CreateMqttClient()连接用ConnectAsync订阅用SubscribeAsync发布用PublishAsync。下面是我整理的可直接对照的片段// Client 端连接 Broker 并完成订阅 发布 var factory new MqttFactory(); var client factory.CreateMqttClient(); var options new MqttClientOptionsBuilder() .WithTcpServer(127.0.0.1, 1883) // Broker 地址与端口 .WithClientId(demo-client-01) // 客户端唯一标识 .WithCleanSession(true) // 是否清除会话 .WithKeepAlivePeriod(TimeSpan.FromSeconds(30)) .Build(); // 收到消息的回调 client.ApplicationMessageReceivedHandler new MqttApplicationMessageReceivedHandlerDelegate(e { var payload Encoding.UTF8.GetString(e.ApplicationMessage.Payload); Console.WriteLine($收到 [{e.ApplicationMessage.Topic}]: {payload}); }); await client.ConnectAsync(options); // 订阅通配符 指定 QoS await client.SubscribeAsync(new MqttTopicFilterBuilder() .WithTopic(device//status) // 匹配单层 .WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtLeastOnce) .Build()); // 发布一条消息 await client.PublishAsync(new MqttApplicationMessageBuilder() .WithTopic(device/001/status) .WithPayload({\online\:true}) .WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtLeastOnce) .Build());逻辑说明分三层看。连接层WithClientId必须全局唯一两个客户端用同一个 ID 会互相踢下线这是 MQTT 协议行为不是库的 bug。WithCleanSession(true)表示不保留会话断线后订阅关系丢失要做离线消息就得设 false 并配合 Broker 的会话保留。订阅层device//status里的是单层通配能匹配device/001/status但匹配不到device/001/raw/status多层要用#。QoS 层AtLeastOnce对应 QoS 1保证至少送达但可能重复业务侧要自己做幂等。参数怎么改端口跟 Server 端一致KeepAlive 默认 60 秒网络差的环境调到 30 秒能更快发现断线但别低于 10 秒否则心跳包太密。2.3 用命令行验证链路是否真的通了光看控制台打印不够我习惯用独立客户端交叉验证排除“自己发自己收”的假象。装好 Mosquitto 客户端工具后开两个终端# 终端 A订阅所有设备状态 mosquitto_sub -h 127.0.0.1 -p 1883 -t device//status -q 1 -v # 终端 B模拟设备发布 mosquitto_pub -h 127.0.0.1 -p 1883 -t device/002/status -m {online:true} -q 1如果终端 A 能收到终端 B 的消息说明 Broker 转发正常如果 Demo 的 Client 收不到而 mosquitto_sub 能收到问题就在 Demo 的订阅过滤器或 QoS 上。这一步能快速把故障域从“整条链路”缩到“某一个客户端”。-q 1要和订阅端 QoS 对齐发布 QoS 低于订阅 QoS 时实际生效的是两者较小值这个细节后面避坑章还会提。3. MQTTnet 的关键参数QoS、会话与 Topic 设计怎么定3.1 QoS 三档的真实代价与选型QoS 是 MQTT 里最容易被“默认设 2 保平安”的参数但三档的代价差别很大。QoS 0 是发完即忘网络一抖就丢适合高频传感器数据这种丢一帧无所谓的场景。QoS 1 是至少一次Broker 要回 PUBACK发送端没收到会重发代价是可能重复适合状态上报、指令下发这类不能丢但能容忍重复的消息。QoS 2 是恰好一次靠四次握手保证不重不漏代价是往返次数翻倍、Broker 要维护更多状态吞吐明显下降。我的经验是设备遥测用 0 或 1控制指令用 1 加业务幂等只有计费、审计这类绝对不能重复的场景才上 2。Demo 里订阅和发布都用了AtLeastOnce是个稳妥的起点但你要按消息类型拆开别整条链路一个 QoS 走到底。3.2 CleanSession 与离线消息的取舍WithCleanSession这个布尔值决定了断线后 Broker 认不认你。设 true每次连接都是全新会话订阅关系不保留离线期间的消息全丢设 falseBroker 会记住你的订阅QoS 1/2 的消息在你离线时排队重连后补发。听起来 false 更好但它有代价Broker 要为每个持久会话占内存ClientId 固定的设备多了会撑爆 Broker而且补发的消息可能已经过期业务侧要带时间戳判断。常见做法是移动端或临时调试用 true固定设备用 false 并给会话设过期时间。Demo 默认 true 是为了好调试你改成 false 后记得用同一个 ClientId 重连才能收到离线消息换个 ID 就前功尽弃。3.3 Topic 层级设计别让通配符变成性能黑洞Topic 是 MQTT 的路由键设计好坏直接影响 Broker 的匹配开销。推荐按“业务域/设备类型/设备ID/数据类别”分层比如factory/plc/001/telemetry。通配符和#用起来方便但订阅#等于让 Broker 把每条消息都往你这里匹配一遍客户端一多就是灾难。我一般要求订阅端尽量精确到设备 ID只在聚合看板这种确实需要全量的地方用并且避免#出现在层级中间。另外 Topic 大小写敏感、不能用空格设备 ID 里别塞斜杠否则层级会被意外切开。这些规则写进团队约定比事后排查订阅收不到要省事得多。4. 避坑与排查五条血泪经验4.1 连上就掉线日志只报“连接被关闭”现象Client 刚连上几秒就断开重连循环。原因多半是 ClientId 冲突——两个进程用了同一个 IDBroker 按协议把旧连接踢掉。解决给每个实例生成带 GUID 后缀的 ClientId或者用设备序列号保证唯一。排查时先看 Broker 端的连接日志有没有“同一 ClientId 重复接入”的记录。4.2 订阅成功但收不到消息现象SubscribeAsync返回成功发布端也发了回调就是不触发。原因通常是 Topic 过滤器写错层级比如订阅device//status却发布到device/001/raw/status只匹配一层。解决用 mosquitto_sub 用同样的过滤器订阅一遍能收到就是代码问题收不到就是 Topic 不匹配。另外检查 QoS发布 QoS 0 而订阅 QoS 1 时消息仍会送达但某些 Broker 配置下低 QoS 消息可能被丢弃策略影响。4.3 消息重复消费导致业务重复执行现象QoS 1 下同一条指令被执行两次。原因QoS 1 的语义就是“至少一次”网络抖动触发重发是正常行为不是 bug。解决业务侧做幂等消息体里带唯一消息 ID 或业务流水号消费端去重。别指望把 QoS 调到 2 就万事大吉QoS 2 的握手开销在弱网下反而更容易超时。4.4 Broker 内存持续上涨现象跑一段时间后 Server 进程内存只增不减。原因CleanSession 设 false 的客户端越积越多Broker 为每个持久会话缓存离线消息没人清理。解决给会话设过期时间定期清理僵尸 ClientId或者对离线消息设上限超出丢弃最旧的。Demo 里没有这块逻辑上生产必须补。4.5 端口通了但握手失败现象telnet 端口能通客户端连接报协议错误。原因端口上跑的不是 MQTT 服务或者 TLS 端口用了明文连接。解决确认 Server 端WithDefaultEndpointPort和 Client 端WithTcpServer端口一致如果 Broker 开了 TLSClient 要用WithTls()并配证书别拿 1883 的配置去连 8883。5. 进阶验证把 Demo 改成可压测、可观测的骨架跑通单条消息只是起点真正要判断这份 Demo 能不能进项目得看它在多客户端和异常网络下的表现。我的做法是写一个轻量压测脚本用同一套 MQTTnet API 起 N 个客户端每个订阅自己的 Topic 再互发消息观察 Broker 的 CPU 和消息延迟。关键是把连接建立和消息发布分开计时连接耗时反映握手开销发布到接收的往返时间反映转发延迟。参数上客户端数从 50 起步每轮翻倍直到出现连接超时或消息丢失那个拐点就是当前配置的容量上限。验证订阅是否真的生效别只看回调打印加一个计数器发布 M 条统计回调触发次数QoS 1 下允许略大于 M重复但小于 M 就是丢了。再配合 Broker 端的连接数、会话数指标能区分是客户端没订上还是 Broker 没转发。这套方法我一般会固化成脚本每次改 QoS 或会话配置都跑一遍比拍脑袋调参靠谱。还有一个容易被忽略的点Demo 用的是 .NET Core 3.0这个运行时版本较老新项目建议升到受支持的 LTS 版本再落地MQTTnet 的 API 在大版本间有变动升级时注意MqttFactory和 Handler 的写法差异。从那以后我每次拿这类双端 Demo 做原型都强制先跑一遍多客户端压测和断线重连确认会话和 QoS 行为符合预期再往业务里接省下的返工时间远比压测本身多。希望帮到你。本文还有配套的精品资源点击获取
