简介：面向C#物联网开发者的MQTT通信Demo测试案例，包含服务端Broker与客户端Client的完整实现，基于MQTTnet库演示连接配置、主题订阅、消息发布与接收处理，适合需要快速上手MQTT协议或搭建轻量级消息通信原型的开发者。压缩包内有约2000个文件，以xml配置、dll库、NuGet依赖包、cs源码等为主，另含p7s签名、pdb调试符号等，总大小约42.99MB，结构对应Visual Studio解决方案，便于直接打开调试验证。已有688人学习，案例覆盖服务端启动监听、客户端连接鉴权、QoS级别设置、订阅/发布交互等关键流程，并体现异常处理与事件驱动思路，可帮助理解MQTT在低带宽场景下的应用，为物联网、远程监控等实时数据交换项目提供可参考的C#实现模板。
1. 为什么是MQTT：一个C#开发者视角的选型记录
前阵子有朋友找我帮忙做停车场车牌识别相机的对接，海康、大华这类设备要把识别结果推给后端，最开始大家第一反应是走HTTP回调。但真到了现场就发现问题了——停车场网络环境复杂，相机在弱电井里，后端服务在机房，中间隔了好几层NAT。HTTP回调这种"后端主动拉取"的模式，要么需要公网IP，要么需要做端口映射，运维同学直接罢工。
后来换了思路，改用MQTT协议，让相机主动把识别结果发布到Broker上，后端服务订阅相关Topic就能实时收到消息。这套方案最直观的好处是网络穿透问题没了。相机只要能访问到Broker的IP和端口就能推送消息，服务端也不需要暴露任何端口。而且MQTT是发布/订阅模式，天然支持一对多，一台相机推送的消息可以同时被计费系统、大屏显示、云平台上报三个业务方订阅，互不干扰。
这也是我写这个MQTT C# demo的最初动机——把服务端和客户端整体跑通，验证C#生态里做MQTT通信是否成熟可靠。我当时在NuGet上搜了一圈，发现MQTTnet这个库已经做得相当完善，支持高版本MQTT协议，而且在GitHub上维护得很活跃。于是基于它搭了一套包含服务端和客户端的完整测试案例，项目本身不大，但麻雀虽小五脏俱全，从Broker的启动、客户端的连接、订阅发布，到QoS消息质量的控制，全链路都能跑通。
这篇文章就是把这个demo的搭建过程、关键代码、踩坑记录做一个完整的梳理。想快速上手MQTT的C#开发者、正在评估物联网方案的架构师，或者纯粹想搞明白发布/订阅和请求/响应到底区别在哪的同学，都可以参考。我会尽量把每一步的"为什么这么做"讲清楚，而不是只甩一堆代码。
2. 搭建前必须想清楚的几个关键决策
2.1 Broker选型：生产级还是内嵌式
MQTT通信里有几个角色你得先分清楚。客户端是发布消息或者订阅消息的一方，而Broker是消息中转站，所有消息都先到Broker，再由Broker转发给订阅者。C#这边写客户端很简单，关键是Broker怎么选。
生产环境里我推荐直接用EMQX或者Mosquitto这类独立的Broker服务。EMQX功能强，支持集群、规则引擎、仪表盘监控，生产环境基本首选。Mosquitto则轻量得多，适合嵌入式设备或资源受限的场景。如果把Broker跑在Docker里，一条命令就能搞定：docker run -d --name emqx -p 1883:1883 -p 18083:18083 emqx/emqx:5.0，其中1883是MQTT默认端口，18083是Web管理控制台。
但如果只是做demo测试，其实可以在C#程序里直接内嵌一个Broker——用MQTTnet库自带的MqttServer类就能实现。这样做的好处是我能在自己的机器上快速验证消息收发逻辑，不依赖外部服务，调试起来也方便。等验证通过，再切换到生产级Broker也不迟。所以这个demo我采用了"内嵌Broker + 两个客户端"的模式，一台机器上把服务端和客户端全跑起来。
2.2 客户端库为什么选MQTTnet
C#可以用的MQTT客户端库不止一个，我在选型时也调研过。老牌的M2Mqtt曾是首选，但它的维护节奏慢，对MQTT 5.0的支持也不到位。MQTTnet则是后起之秀，在GitHub上Star数高，代码更新频繁，API设计也更现代——基于async/await，写起来很顺手。
一个例子就能看出两者的差异。用M2Mqtt发送消息，你得手动处理连接事件，订阅确认要自己判断返回码，时间久了代码会变得很臃肿。而MQTTnet里，ConnectAsync、SubscribeAsync这些方法直接返回Task，配合ConfigureAwait(false)可以避免UI线程死锁，非常直观。另外一个加分项是MQTTnet的社区活跃度——你在Stack Overflow上搜MQTT C#相关的问题，十有八九的答案都是基于MQTTnet。
在NuGet里安装也简单，直接搜MQTTnet，安装最新的稳定版即可。需要注意一点，我在写这个demo时用的版本是4.x，它的命名空间已经从Mqttnet变成了MQTTnet，如果你在网上找到老教程，遇到编译报错先检查命名空间是不是带大写后缀的版本。
3. 服务端上线：先跑通一个能收消息的Broker
3.1 创建Broker服务
先看服务端的实现。说到底，MQTT的Broker核心职责就两件事：管理客户端连接、按主题转发消息。MQTTnet把它们封装成了MqttServer类，我们用几行代码就能搭起来。
var options = new MqttServerOptionsBuilder() .WithDefaultEndpoint() .WithDefaultEndpointPort(1883) .Build(); var mqttServer = new MqttServerFactory().CreateMqttServer(options); mqttServer.InterceptingPublishAsync += e => { Console.WriteLine($"收到消息: Topic={e.ApplicationMessage.Topic}, Payload={Encoding.UTF8.GetString(e.ApplicationMessage.PayloadSegment)}"); return Task.CompletedTask; }; await mqttServer.StartAsync();先别急着跑，逐行看下里面的逻辑。WithDefaultEndpoint()是允许默认的TCP接入点，WithDefaultEndpointPort(1883)指定监听端口。InterceptingPublishAsync这个事件是整个服务端的"灵魂"——每一帧经过Broker的消息都会触发它，你可以在里面做日志记录、统计流量，甚至做消息的过滤和改写。
启动服务端之后，还需要考虑客户端连接管理。默认配置下MQTTnet允许匿名连接，也就是任何客户端只要给个ClientId就能连上来。这在demo阶段没问题，但如果要在局域网里临时用，最好加一个连接验证器，只允许指定ClientId接入：
var options = new MqttServerOptionsBuilder() .WithDefaultEndpoint() .WithConnectionValidator(c => { if (c.ClientId != "demo_client") { c.ReasonCode = MqttConnectReasonCode.ClientIdentifierNotValid; return; } c.ReasonCode = MqttConnectReasonCode.Success; }) .Build();我当时在这里就踩了一个坑。最初我没有设置ConnectionValidator，客户端怎么连都报错说服务器不可用，但实际上问题出在我的ClientId用了中文——MQTT协议规范里ClientId只支持字母、数字和部分特殊字符，中文直接导致连接被拒绝。后来换成英文ClientId一切正常。
3.2 验证Broker是否在正常工作
服务端启动后，怎么确认它真的在干活？最简单的方法就是订阅$SYS/#——这是MQTT协议里Broker系统消息的保留Topic，用于查询Broker的运行状态。订阅这个Topic之后，如果Broker正常，你会周期性收到客户端数量、消息收发速率、内存占用等系统指标。可以说，$SYS/#就是MQTT世界里的"健康检查"入口。
如果你在生产环境使用了EMQX，直接在Web管理控制台的Topic页面就能看到实时流量。但内嵌Broker没有面板，所以我通常会在服务端程序里打个日志钩子，监控客户端连接和断开事件：
mqttServer.ClientConnectedAsync += e => { Console.WriteLine($"客户端已连接: {e.ClientId}"); return Task.CompletedTask; }; mqttServer.ClientDisconnectedAsync += e => { Console.WriteLine($"客户端已断开: {e.ClientId}"); return Task.CompletedTask; };一看到这两个事件能触发，基本就能确定Broker的网络层和协议栈是通的。
3.3 用户认证与权限必要吗
很多同学在搭demo时会忽略认证。我的建议是：demo阶段可以不做，但如果你准备把服务端部署在局域网甚至公网，用户认证是必须的。MQTT的用户认证机制和HTTP的Basic Auth很像，客户端在CONNECT报文里带上用户名和密码，Broker验证通过才允许连接。
MQTTnet里实现用户认证，主要还是在ConnectionValidator里做：
.WithConnectionValidator(c => { if (c.UserName != "admin" || c.Password != "123456") { c.ReasonCode = MqttConnectReasonCode.BadUserNameOrPassword; return; } c.ReasonCode = MqttConnectReasonCode.Success; })这里有个容易忽视的细节——如果你设置了用户名密码，客户端在连接时也必须对应地设置UserName和Password字段，否则连接会被Broker拒绝。我在测试时因为客户端忘记设置密码，排查了半天还以为是网络问题，最后看Broker日志才发现返回码是BadUserNameOrPassword。
4. 客户端收发：订阅、发布与QoS三层机制
4.1 连接参数里的门道
客户端的连接配置比大多数人想象的要讲究。如果你只想收发消息，最简单的连接代码确实只要三行，但实际生产环境里，连接参数的合理设置直接决定了程序的稳定性。
先看一段完整的连接代码：
var options = new MqttClientOptionsBuilder() .WithTcpServer("127.0.0.1", 1883) .WithClientId("device_001") .WithCleanSession(true) .WithKeepAlivePeriod(TimeSpan.FromSeconds(60)) .WithCredentials("admin", "123456") .Build(); var mqttClient = new MqttFactory().CreateMqttClient(); mqttClient.ConnectedAsync += async e => { Console.WriteLine("连接成功"); await Task.CompletedTask; }; mqttClient.DisconnectedAsync += async e => { Console.WriteLine($"连接断开: {e.Reason}"); await Task.CompletedTask; }; await mqttClient.ConnectAsync(options, CancellationToken.None);这里有两个参数需要重点解释。
第一个是WithCleanSession。它决定了Broker是否为客户端保留会话状态。设为true时，Broker在客户端断开后立即清除所有订阅关系和未消费的消息；设为false时，Broker会保留这些状态，客户端重连后能恢复订阅并收到离线期间的消息。对于需要确保不丢消息的场景，比如停车场出口抓拍结果，CleanSession应该设为false。
第二个是WithKeepAlivePeriod。这个参数决定了客户端和Broker之间的心跳间隔。客户端每隔这个时间发送一个PINGREQ报文，Broker如果在一段时间内没收到，就判定连接已断开。这个机制是MQTT协议能及时发现死连接的基础。默认值一般是60秒，如果你的网络环境差，可以适当缩短到30秒，但不能太短，否则心跳报文本身会变成网络负担。
4.2 订阅：不要忽略Topic和QoS的搭配
订阅操作看似简单，但Topic的匹配规则值得花点时间理解。MQTT的Topic是一个层级结构，用/分隔，比如parking/entrance/camera01。订阅时支持两种通配符：+匹配单个层级，#匹配多个层级。举个例子，订阅parking/+/camera01就能收到parking/entrance/camera01和parking/exit/camera01的消息，而parking/#能收到所有以parking开头的Topic消息。
我在demo里订阅了多个测试Topic：
var topicFilter = new MqttTopicFilterBuilder() .WithTopic("test/data") .WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtLeastOnce) .Build(); await mqttClient.SubscribeAsync(new[] { topicFilter }, CancellationToken.None);这里的WithQualityOfServiceLevel就是MQTT协议里的QoS设置，它有三级：
- QoS 0（AtMostOnce）：最多一次，消息可能丢失。适合传感器温度上报这类可以容忍丢包的数据。
- QoS 1（AtLeastOnce）：至少一次，消息必定送达，但可能重复。适合控制指令，重复执行一次通常无害。
- QoS 2（ExactlyOnce）：恰好一次，消息不丢不重，但开销最大。适合计费、扣费等不能出错的场景。
你可能会问，订阅端和发布端的QoS不一样时，实际消息的QoS等级如何决定？答案是取两者中较小的那个。比如发布端用QoS 2，订阅端用QoS 1，那最终消息按QoS 1投递。
我在一次项目对接中吃过大亏：设备端发布消息用QoS 0，但我以为订阅端设了QoS 1就能保证不丢，结果车场在高峰期丢了几条入场记录。后来排查Broker日志才发现，消息在入口就被丢弃了——发布端才是决定消息生死的第一环。
4.3 发布消息：从异步到确认
发布消息的代码看起来也不复杂：
var message = new MqttApplicationMessageBuilder() .WithTopic("test/data") .WithPayload("{\"device\":\"camera01\",\"plate\":\"京A12345\"}") .WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtLeastOnce) .WithRetainFlag(false) .Build(); await mqttClient.PublishAsync(message, CancellationToken.None);这里WithRetainFlag值得单独说。当保留标志设为true时，Broker会保存这条消息的最新副本，当有新的订阅者上线时，Broker会立刻把这条保留消息推给新订阅者。这个机制对设备状态上报非常有用——设备每次上报状态都带保留标志，新上线的客户端订阅Topic后，不用主动查询就能立即知道设备的当前状态。
不过也不要滥用保留消息。我在服务端demo里收到过很多"幽灵消息"——设备已经下线了，但它们最后一条保留消息还在Broker里，新订阅者一上来就收到这些过期状态。正确的做法是：设备下线前主动发送一条空的保留消息，把旧的保留消息清除掉。
5. 端到端联调：验证链路是否真的跑通
5.1 完整的收发测试流程
写完了服务端和客户端，接下来就是把它们串起来进行完整的联调。我建议遵循从简单到复杂的测试思路，每一步都验证清楚再往下走。
第一步，只启动服务端，然后在本地用MQTTX这个跨平台的MQTT测试工具连上去。MQTTX是一个图形化的MQTT客户端，可以像发微信一样收发Topic消息，特别适合在开发阶段排查问题。在MQTTX里新建连接，填入127.0.0.1:1883，点击连接按钮，观察服务端日志是否出现了"客户端已连接"的提示。如果没出现，问题大概率出在IP、端口或防火墙。
第二步，在MQTTX里订阅test/data，然后用C#客户端发布一条消息。如果MQTTX能收到，说明C#的发布链路是通的。反过来，在MQTTX里发布消息，用C#客户端的ApplicationMessageReceivedAsync事件接收。这个事件是客户端所有消息的入口，无论是订阅消息还是遗嘱消息，都会走这里。
第三步，两端都用C#实现，模拟真实的业务场景。我在demo里用一个模拟的传感器客户端，每隔3秒向sensor/temperature发布一次温度数据，然后一个控制台客户端订阅这个Topic，把数据实时打印出来。整个链路通了，再往上叠业务逻辑。
5.2 状态码排查手册
联调过程中最容易遇到的问题就是连接失败。MQTT的连接结果放在MqttClientConnectResult里，里面有ResultCode字段。我整理了几个常见状态码的排查思路：
Success：连接成功，无需处理。BadUserNameOrPassword：用户名密码不对，检查客户端配置和服务端验证逻辑。ClientIdentifierNotValid：ClientId不合法，检查是否包含中文或特殊字符。ServerUnavailable：服务端不可用，大概率是网络不通，或者Broker端口没监听。NotAuthorized：客户端没有权限，需要检查发布/订阅的ACL权限设置。
另外有一个非常经典的坑：Windows防火墙会把监听1883端口的程序拦下来。我第一次在公司电脑上做联调时，本地没问题，但同一局域网内的另一台机器死活连不上，捣鼓了半天才意识到是Windows防火墙把入站连接拦截了。在防火墙的入站规则里放行1883端口，问题立刻解决。
5.3 全链路测试后的验证思路
整个demo跑通后，我习惯额外做几个"刁难测试"来验证程序的健壮性。
第一个测试是杀掉Broker进程，看客户端会不会自动重连。如果客户端没有重连机制，程序会一直停留在断开状态，直到用户手动重启。MQTTnet提供EnableAutoReconnect选项，开启后客户端会在断线后自动尝试重连。我在demo里明确开启了这个选项，并设置了重连策略：
var options = new MqttClientOptionsBuilder() .WithTcpServer("127.0.0.1", 1883) .WithAutoReconnect() .Build();需要提醒的是，自动重连之后，如果你的CleanSession设的是true，那么之前订阅的Topic全部失效，需要重新订阅。所以生产环境的订阅操作最好放在ConnectedAsync事件里，这样不管是首次连接还是重连成功，订阅逻辑都会执行。
第二个测试是发大量消息，观察有没有消息积压或丢失。我在demo里用并发任务模拟1000条消息同时发布，然后通过服务端的消息计数对比，判断消息是否全部投递。
6. 从Demo到工程化：那些踩过的坑和必做的优化
6.1 掉线重连与服务可用性
demo跑通了，不代表能直接上生产。在工程化过程中，掉线重连是绕不开的一环。虽然EnableAutoReconnect能自动恢复连接，但还需要处理一个隐藏问题——客户端断线重连后，Broker上可能残留着旧连接的会话状态，如果你没有设置CleanSession = true，新旧会话会互相干扰。
一个稳妥的做法是，在重连成功后的ConnectedAsync里重新检查一下当前会话状态，然后主动重新订阅。另外，对于重要的业务消息，建议在客户端本地加一个持久化队列——断线期间产生的消息先存到本地，重连成功后统一补发。MQTTnet有一个扩展库MQTTnet.Extensions.ManagedClient就是专门解决这个问题的，它内置了消息队列和自动重连，建议有实际业务的同学直接用ManagedClient，而不是裸的MqttClient。
6.2 遗嘱消息：设备掉线时告诉别人
在物联网场景里，判断设备是否在线是件麻烦事——设备可能同时走了电源，也可能只是网络抖动断了几秒。MQTT提供了一个名为遗嘱消息（Last Will and Testament，LWT）的机制来解决这个问题。
遗嘱消息的原理是：客户端在连接时额外指定一个"遗嘱"，比如"设备已下线"。当客户端异常断开时（比如拔网线、断电），Broker会代替这个客户端把遗嘱消息发布到指定Topic。但如果客户端是正常断开（发送了DISCONNECT报文），Broker则不会发布遗嘱消息。
在MQTTnet里设置遗嘱消息很简单：
var willMessage = new MqttApplicationMessageBuilder() .WithTopic("device/status") .WithPayload("offline") .WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtLeastOnce) .Build(); var options = new MqttClientOptionsBuilder() .WithTcpServer("127.0.0.1", 1883) .WithWillPayload(willMessage.PayloadSegment) .WithWillTopic(willMessage.Topic) .WithWillRetain(true) .Build();设置之后，Broker侧订阅device/status的客户端就能实时感知设备上下线状态。我在demo里让服务端订阅了这个Topic，然后把设备状态打印出来，验证掉线检测是全自动的。
6.3 Topic命名设计与消息体规范
最后分享一个我个人的经验，也是demo之外最值得扩展的点——Topic的命名设计。很多第一次接触MQTT的同学，Topic写得随心所欲，比如test1、abc，结果业务一多就乱套了。
MQTT官方虽然没有强制Topic规范，但社区主流推荐使用"域/应用/设备/事件"的层级结构，比如：
parking/entrance/camera01/eventparking/exit/camera01/status
这样设计有几个好处。一是可读性强，看Topic能秒懂是哪台设备、什么事件。二是方便用通配符做权限控制——你可以在Broker上设置规则，只允许服务端订阅parking/#，只允许相机发布parking/+/+/event。
消息体方面，我建议统一用JSON，并且约定好版本号。第一次对接海康相机时，他们的老固件上报的JSON字段是plateNo，新固件改成了plate_number，前后端被这个问题折磨了很久。所以我的消息体规范里明确要求：字段命名统一小驼峰，时间字段必须带时区，数值类型固定精度。一旦定下规范，所有设备接入都按这个格式来，Broker端的数据清洗工作量能减少一大半。
这些看起来和demo关系不大，但恰恰是demo到实际落地之间最有价值的部分。我在实际项目中踩过一次设备的坑，就在遗嘱消息上——最初没考虑设备重启后主动发送保留的在线状态，导致服务端一直认为设备处于离线状态，直到设备下一次上报普通消息才恢复正常。所以在设计消息模型时，在线/离线的状态机既要考虑遗嘱，也要考虑设备启动后的主动上报。
整个demo跑通之后，我最大的体会是：MQTT本身并不复杂，真正决定项目质量的，是围绕连接、订阅、消息生命周期做出的每一个设计决策。C#生态里的MQTTnet已经把这些基础能力封装得足够好用，剩下的，就是结合业务把协议用对、用透。
本文还有配套的精品资源，点击获取
