简介这是一份面向物联网初学者与测试人员的 C# MQTT 测试工具源码基于 WinForm 与 M2MQTT 库构建用于快速验证 MQTT 连接、主题订阅、取消订阅及消息接收等核心流程。项目以 Visual Studio 解决方案形式组织包含窗体界面、业务逻辑与事件处理代码并附带 M2MQTT 依赖包便于直接编译运行与二次修改。压缩包共 49 个文件以 cs 源码、dll 动态库、pdb 调试符号、config 配置及 resx 资源文件为主整体约 1.38MB结构紧凑、依赖清晰。目前已有 719 人学习下载。读者可借此理解发布/订阅模式下的 Broker 连接参数设置、主题监听与消息回调机制并在此基础上扩展发布消息、调整 QoS 级别等功能适合作为 MQTT 协议入门与 C# 桌面端通信开发的实践参考。1. 一个 WinForm 上位机连不上 MQTT 的下午某天下午A同学拿着一个 C# WinForm 写的设备调试工具来找我说现场那台工控机连不上 MQTT Broker日志里只有一句“连接超时”没有任何其他信息。这个工具本身不复杂一个窗体几个按钮用来订阅设备主题、发控制指令、看实时上报数据。但问题在于它把 MQTT 的连接逻辑写在了按钮点击事件里没有重连、没有心跳监控、没有报文日志出问题只能靠猜。这就是“c# mqtt测试软件winform”这个标题背后最真实的诉求不是要做一个多牛的客户端而是要有一个能跑在 Windows 上、能连 Broker、能收发主题、能看日志、能复现现场问题的调试工具。它面向的是做物联网设备、工控采集、边缘网关的开发者日常需要快速验证设备端 MQTT 行为而不是每次都去翻服务端日志。我后来给 A同学的建议是别在业务窗体里直接调 MQTT 库先把连接层抽出来用 MQTTnet 做客户端WinForm 只负责展示和触发。这样调试工具本身才可维护也才敢在现场反复用。下面这篇就把这套东西从选型、搭建、参数、避坑到进阶完整讲一遍。2. 选 MQTTnet 还是自己写 SocketWinForm 调试工具的库选型2.1 为什么 WinForm 场景下 MQTTnet 是默认答案在 .NET 生态里做 MQTT 客户端常见选项有三个MQTTnet、Paho MQTT 的 .NET 封装、以及自己基于 TCP 写一套。自己写 Socket 这件事除非你是为了研究协议本身否则在调试工具场景里完全不划算。MQTT 3.1.1 和 5.0 的报文类型有十几种QoS 1/2 的握手流程、会话保持、遗嘱消息、主题别名每一项都有细节。调试工具的核心价值是“快速验证设备行为”不是“重新实现协议”。Paho 的 .NET 版本在跨平台上有历史包袱API 风格偏 Java 移植感在 WinForm 里做异步 UI 更新时容易写出回调地狱。MQTTnet 是纯 .NET 实现支持 .NET Framework 4.6.2 以上和 .NET 6/7/8API 是 async/await 风格和 WinForm 的 Invoke 配合起来很直接。更重要的是它同时支持 MQTT 3.1.1 和 5.0调试工具经常需要切换协议版本去复现设备端问题这一点很关键。我一般会这样选如果目标设备只跑 MQTT 3.1.1用 MQTTnet 的 3.1.1 模式如果设备支持 5.0优先用 5.0因为 5.0 有 ReasonCode 和 UserProperties调试时能看到更多失败原因。WinForm 本身不限制库的选择但 MQTTnet 的MqttFactory和IMqttClient接口设计让窗体代码可以只依赖接口方便以后换实现。2.2 用 NuGet 把 MQTTnet 装进 WinForm 项目的最小步骤新建一个 Windows Forms App (.NET Framework 或 .NET 6) 项目后不要急着拖控件。先通过 NuGet 安装 MQTTnet。命令行方式如下# 在项目目录下执行安装 MQTTnet 最新稳定版 dotnet add package MQTTnet # 如果项目是 .NET Framework用 Package Manager Console # Install-Package MQTTnet安装完成后在窗体代码里引入命名空间using MQTTnet; using MQTTnet.Client; using MQTTnet.Protocol;这里要注意MQTTnet 4.x 和 3.x 的 API 有差异。4.x 里MqttClientOptionsBuilder的WithTcpServer仍然可用但WithCleanSession在 5.0 模式下要换成WithCleanStart。我一般会在项目里锁定一个版本避免不同机器上还原出不同行为。调试工具最怕“在我这能跑在你那报错”版本锁定是第一步。2.3 连接层抽离别把 MQTT 逻辑写进按钮事件这是血泪经验。很多 WinForm 调试工具一开始就是button1_Click里直接await client.ConnectAsync(options)然后button2_Click里SubscribeAsync。一旦连接断开按钮状态就乱了重连逻辑也没地方放。我的做法是建一个MqttService类把客户端实例、连接状态、订阅列表、消息事件都封装进去。窗体只订阅这个 Service 的事件通过Invoke更新 UI。这样即使窗体关闭再打开Service 可以做成单例或者由主窗体持有连接不会因为窗体重建而丢失。public class MqttService { private IMqttClient _client; public event Actionstring, string MessageReceived; // topic, payload public event Actionbool ConnectionChanged; public async Task ConnectAsync(string host, int port, string clientId) { var factory new MqttFactory(); _client factory.CreateMqttClient(); var options new MqttClientOptionsBuilder() .WithTcpServer(host, port) .WithClientId(clientId) .WithCleanSession(true) // 3.1.1 下用 CleanSession .WithKeepAlivePeriod(TimeSpan.FromSeconds(30)) .Build(); _client.ApplicationMessageReceivedAsync e { var topic e.ApplicationMessage.Topic; var payload System.Text.Encoding.UTF8.GetString(e.ApplicationMessage.Payload); MessageReceived?.Invoke(topic, payload); return Task.CompletedTask; }; _client.DisconnectedAsync e { ConnectionChanged?.Invoke(false); return Task.CompletedTask; }; await _client.ConnectAsync(options); ConnectionChanged?.Invoke(true); } }这段代码的关键点WithKeepAlivePeriod设成 30 秒是因为很多现场网络设备会在一分钟无流量时断链WithCleanSession(true)在调试工具里通常够用避免 Broker 端残留会话导致订阅重复。MessageReceived事件把 payload 转成 UTF-8 字符串如果设备发的是二进制这里要改成按字节展示后面避坑章节会讲。3. 在 WinForm 里跑通连接、订阅、发布的最小闭环3.1 窗体布局与控件命名让调试工具自己会说话一个能用的 MQTT 调试工具界面上至少要有Broker 地址、端口、ClientId、用户名、密码、连接/断开按钮、订阅主题输入框、订阅按钮、发布主题输入框、发布内容输入框、发布按钮、日志文本框、连接状态标签。控件命名不要用button1、textBox1用btnConnect、txtBroker、txtLog这种后面写事件处理时不容易搞混。日志文本框用RichTextBox设ReadOnly trueScrollBars Vertical。每次追加日志时用AppendText并滚动到底部。不要用TextBox追加长日志会卡。连接状态标签用Label绿色显示“已连接”红色显示“已断开”灰色显示“连接中”。3.2 连接与断开的异步处理别让 UI 线程卡死WinForm 的按钮点击事件是同步的但 MQTT 连接是异步的。如果直接.Wait()或.ResultUI 会假死。正确做法是async void事件处理器内部await。private async void btnConnect_Click(object sender, EventArgs e) { btnConnect.Enabled false; lblStatus.Text 连接中...; lblStatus.ForeColor Color.Gray; try { await _mqttService.ConnectAsync( txtBroker.Text.Trim(), int.Parse(txtPort.Text.Trim()), txtClientId.Text.Trim() ); lblStatus.Text 已连接; lblStatus.ForeColor Color.Green; AppendLog(连接成功); } catch (Exception ex) { lblStatus.Text 已断开; lblStatus.ForeColor Color.Red; AppendLog($连接失败: {ex.Message}); } finally { btnConnect.Enabled true; } }int.Parse这里没有做异常保护实际写的时候要用int.TryParse否则端口输入非数字会直接抛异常。AppendLog方法内部要判断InvokeRequired因为 MQTT 的消息事件是在后台线程触发的。private void AppendLog(string msg) { if (txtLog.InvokeRequired) { txtLog.Invoke(new Actionstring(AppendLog), msg); return; } txtLog.AppendText($[{DateTime.Now:HH:mm:ss.fff}] {msg}\r\n); txtLog.ScrollToCaret(); }时间戳精确到毫秒是因为调试 QoS 1 重发和心跳间隔时秒级精度不够用。3.3 订阅与发布QoS 和 Retain 怎么设才不坑自己订阅时SubscribeAsync要传主题和 QoS。调试工具里我一般默认 QoS 1因为 QoS 0 丢消息不报错QoS 2 握手太重现场设备很少用。Retain 标志在订阅时不用设发布时才有意义。private async void btnSubscribe_Click(object sender, EventArgs e) { var topic txtSubTopic.Text.Trim(); if (string.IsNullOrEmpty(topic)) return; var subOptions new MqttClientSubscribeOptionsBuilder() .WithTopicFilter(f f.WithTopic(topic).WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtLeastOnce)) .Build(); await _mqttService.SubscribeAsync(subOptions); AppendLog($已订阅: {topic} (QoS 1)); }发布时MqttApplicationMessageBuilder要设WithRetainFlag。如果调试的是设备状态主题Retain 设 true 可以让新订阅者立刻收到最后一条状态如果调试的是控制指令Retain 必须 false否则 Broker 会一直保留这条指令设备重连后会再次执行这是典型的翻车场景。private async void btnPublish_Click(object sender, EventArgs e) { var topic txtPubTopic.Text.Trim(); var payload txtPubPayload.Text; var message new MqttApplicationMessageBuilder() .WithTopic(topic) .WithPayload(payload) .WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtLeastOnce) .WithRetainFlag(false) // 控制指令绝不保留 .Build(); await _mqttService.PublishAsync(message); AppendLog($已发布: {topic} - {payload}); }QoS 1 下PublishAsync返回并不代表 Broker 已确认只代表客户端已发出。如果要确认需要看PUBACKMQTTnet 内部会处理重发但调试工具里最好在日志里体现“已发出”而不是“已送达”。4. 调试现场最容易翻车的 5 个 MQTT 细节4.1 现象连接成功但收不到任何消息原因通常有三个订阅主题写错、Broker 权限限制、QoS 不匹配。主题写错最常见的是通配符用错#必须单独一层sensor/#能匹配sensor/1/temp但sensor#不合法。Broker 权限方面很多现场 Broker 配置了 ACL只允许特定 ClientId 订阅特定主题调试工具用的 ClientId 如果不在白名单连接成功但订阅会被静默拒绝。解决在SubscribeAsync后检查返回的MqttClientSubscribeResult里面每个 TopicFilter 都有ResultCode。如果非成功日志里要打出来。另外用mosquitto_sub命令行工具在同一个 Broker 上验证主题是否有消息排除设备端问题。4.2 现象发布成功但设备没反应原因可能是 Retain 标志设错、主题层级不对、payload 格式不对。Retain 设 true 时如果设备订阅时用了cleanSessionfalseBroker 会把保留消息推给设备但设备可能只处理实时消息忽略保留消息。payload 格式方面设备端可能要求 JSON 且字段名大小写敏感调试工具发的是纯文本设备解析失败但不报错。解决在调试工具里加一个“十六进制显示”选项把 payload 按字节展示。同时用mosquitto_sub -t # -v在 Broker 侧抓全量消息确认消息确实到了 Broker。如果 Broker 有消息但设备没反应问题在设备端解析逻辑。4.3 现象连接几分钟后自动断开原因通常是 KeepAlive 设置过大或过小。KeepAlive 设成 60 秒但网络中间有 NAT 超时是 30 秒连接就会被静默丢弃。设成 5 秒又会产生大量 PINGREQ增加 Broker 负担。现场经验是局域网内设 30 秒跨公网设 15 到 20 秒并且客户端要处理DisconnectedAsync做自动重连。解决在MqttService里加一个重连计时器断开后延迟 5 秒重连重连成功后再重新订阅之前的主题。注意重连时 ClientId 不要变否则 Broker 会认为是新客户端会话状态丢失。4.4 现象中文 payload 显示乱码原因设备端发的是 GBK 编码调试工具按 UTF-8 解码。或者设备端发的是 UTF-8但调试工具用了Encoding.Default在中文 Windows 上是 GBK。解决在MessageReceived事件里不要硬编码 UTF-8。加一个下拉框让用户选编码UTF-8、GBK、ASCII。默认 UTF-8如果乱码就切 GBK。代码里用Encoding.GetEncoding(GBK)注意 .NET Core 需要注册CodePagesEncodingProvider。4.5 现象UI 卡顿日志越多越卡原因每次收到消息都直接AppendTextRichTextBox 在消息量大时重绘开销很大。另外如果消息事件在后台线程直接操作控件虽然Invoke能解决跨线程问题但频繁Invoke会阻塞后台线程。解决用生产者-消费者队列。消息到达时先入ConcurrentQueueUI 用Timer每 200 毫秒批量取出并追加到日志。这样既不会丢消息也不会让 UI 卡死。日志文本框设一个最大行数比如 5000 行超过就删最旧的避免内存无限增长。5. 让调试工具从“能用”到“敢在现场用”的进阶技巧5.1 用 MQTT 5.0 的 UserProperties 做链路追踪MQTT 5.0 允许在消息里带 UserProperties调试工具可以在发布时自动加一个traceId设备端如果也支持 5.0回传时带上同一个traceId就能在日志里把请求和响应串起来。这在调试多设备并发场景时特别有用。var message new MqttApplicationMessageBuilder() .WithTopic(topic) .WithPayload(payload) .WithUserProperty(traceId, Guid.NewGuid().ToString(N)) .WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtLeastOnce) .Build();接收端在ApplicationMessageReceivedAsync里读e.ApplicationMessage.UserProperties把 traceId 打到日志里。这样一条控制指令发出去哪个设备回了什么一目了然。5.2 把连接参数存成配置文件别每次手输现场调试经常要切换多个 Broker手输地址端口效率低还容易错。用System.Text.Json把连接配置存成connections.json窗体启动时加载到下拉框选择后自动填充。配置文件放在程序目录下不要放系统目录避免权限问题。public class BrokerProfile { public string Name { get; set; } public string Host { get; set; } public int Port { get; set; } public string ClientId { get; set; } public string Username { get; set; } public string Password { get; set; } }密码字段不要明文存用ProtectedData做当前用户加密。调试工具虽然不要求高安全但现场机器可能多人共用明文密码是隐患。5.3 用“模拟设备”模式反向验证调试工具不仅能当客户端还能当服务端。MQTTnet 支持MqttServer可以在本地起一个 Broker让调试工具模拟设备发布消息然后用另一个客户端订阅验证主题和 payload 是否符合预期。这个模式在设备还没到位时特别有用。我一般会在工具里加一个“本地 Broker”按钮点击后在localhost:1883起一个内存 Broker日志里显示“本地 Broker 已启动”。然后可以用同一个工具连上去自己发自己收快速验证 UI 逻辑和消息格式。注意本地 Broker 不要设认证否则自己连自己还要输密码反而麻烦。5.4 日志导出与现场取证现场调试最怕“当时看到了回来复现不了”。日志文本框旁边加一个“导出日志”按钮把RichTextBox内容存成.log文件文件名带时间戳。导出时把连接参数、订阅列表、消息收发记录都带上但密码字段要脱敏。我自己的习惯是每次现场调试结束先导出日志再关工具。日志文件按日期建文件夹后面写报告或者跟设备端对质时直接翻日志比回忆靠谱得多。这个习惯帮我省过很多次“后悔药”。希望帮到你。本文还有配套的精品资源点击获取