简介：本资源是一套基于WinForm平台的MQTT通信完整示例工程，面向C#初学者及物联网应用开发人员，解决MQTT协议在桌面端服务端与客户端双向通信、消息持久化存储等核心实践问题。压缩包共67个文件，含10个关键DLL（如MQTTnet核心库）、8个C#源码文件（涵盖服务端Program.cs、客户端Form1.cs等核心逻辑）、4个可执行EXE（便于直接运行验证）、2个SLN/CSProj项目文件（支持VS快速加载），以及JSON配置、日志缓存和编译产物等辅助文件，整体仅494KB，轻量易上手。已有2133人学习下载，资源结构清晰，包含独立的服务端与客户端双项目，支持消息订阅、实时显示及自动保存至本地文件，附带完整VS解决方案与调试配置，开箱即用，适合快速理解MQTTnet在WinForm中的集成方式、消息流转机制与落地存储方案。
1. Winform + MQTTnet 实战：一个能跑通、能存日志、能改配置的轻量级 MQTT 通信样板
你有没有试过在 Winform 项目里接入 MQTT，结果卡在“连上了但收不到消息”“订阅了但回调不触发”“消息来了却不知道怎么落盘”这三座大山？这不是玄学——是缺一个真正从 .NET Framework 4.7.2 起手、用 MQTTnet 3.1.15（非最新版！）实测跑通的完整链路。这个压缩包里没有花哨的 Web 管理界面，也没有 Docker 编排，就两个干净的 Winform 工程：MQTTServerDemo（模拟服务端，实际是 MQTT Broker 的简易封装）和MQTTClientDemo（带 UI 的客户端），所有通信走标准 MQTT v3.1.1 协议，关键动作——连接、订阅、发布、断线重连、消息序列化、文件追加写入——全部可调试、可打断点、可改路径。它适合正在做工业设备监控、IoT 数据采集、或学校课程设计的 .NET 开发者：不需要部署 Mosquitto，不依赖云平台，双击 exe 就能看订阅流，关掉再打开还能续上日志文件。我拿它给某高校实验室搭传感器数据中转站，三天内把温湿度节点数据稳定存进logs/2024-06-12.log，中间没丢一条。
2. 项目结构与技术栈：为什么选 MQTTnet 而不是官方库？Winform 下的取舍逻辑
这个项目不是“为了用 MQTT 而用 MQTT”，而是为了解决 Winform 场景下几个具体痛点：UI 线程不能被阻塞、消息要持久化到本地磁盘、Broker 需要嵌入式运行（避免额外安装服务）、协议必须兼容老旧 PLC 设备。所以技术选型非常务实：MQTTnet 是目前 .NET 生态中唯一同时满足“纯 C# 实现”“支持 .NET Framework 4.5+”“提供 Server 和 Client 双 API”“文档直白、源码易读”的库。它不依赖 libuv 或 native 依赖，打包后单个 exe 就能跑；而微软官方的 Azure IoT SDK 过重，Paho.NET 已停止维护，且都不提供内嵌 Broker。
2.1 目录结构：两个工程，五类核心文件
解压后你会看到两个 Visual Studio 2019 解决方案文件夹：
MQTTServerDemo/ ├── Program.cs // 入口：初始化 Broker 并启动 Winform 主窗体 ├── MainForm.cs // 主窗体：显示在线客户端数、当前主题列表、手动发布按钮 ├── BrokerService.cs // 核心：封装 MQTTnet.Server，处理连接/断开/订阅/取消订阅事件 ├── MessageLogger.cs // 关键：所有收到的 PUBLISH 消息都经由此类写入文件（带时间戳、QoS、主题） └── app.config // 配置端口（默认 1883）、日志路径、最大连接数 MQTTClientDemo/ ├── Program.cs // 入口：启动客户端主窗体 ├── MainForm.cs // 主窗体：连接配置区、订阅主题输入框、消息发送区、接收消息滚动日志框 ├── MqttClientWrapper.cs // 核心：封装 MQTTnet.Client，含自动重连、心跳保活、异常捕获 ├── MessageSerializer.cs // 序列化：默认 UTF-8 字符串，可扩展为 JSON 或 Protobuf（代码留了钩子） └── app.config // 配置 Broker 地址、端口、Client ID、Clean Session、默认订阅主题提示：两个工程都引用了
MQTTnet.dll（v3.1.15），不要用 NuGet 升级到 4.x —— 4.x 移除了MqttServerOptionsBuilder的WithDefaultEndpointPort方法，会导致BrokerService.cs编译失败。这是血泪经验：某开发者升级后折腾两天才发现版本不兼容。
2.2 为什么 Broker 是“模拟”的？真正的嵌入式服务长什么样
标题说“服务端”，但 Winform 里不可能真跑一个完整 Mosquitto。这里的BrokerService.cs实际是 MQTTnet 提供的MqttFactory.CreateServer()创建的内存内 Broker，它：
- 启动时绑定
IPAddress.Any:1883，接受 TCP 连接； - 为每个客户端分配唯一
ClientId，维护 Session（含遗嘱消息、Clean Session 控制）； - 支持 QoS 0/1（QoS 2 因 Winform 场景极少用，已注释掉）；
- 不实现持久化存储：客户端离线期间的消息会丢失（符合 MQTT 规范），但所有成功投递到客户端的消息，都会被
MessageLogger.cs捕获并落盘。
关键代码在BrokerService.cs的构造函数里：
public BrokerService() { var options = new MqttServerOptionsBuilder() .WithDefaultEndpointPort(1883) // 绑定端口 .WithConnectionBacklog(100) // 连接队列长度 .WithMaxPendingMessagesPerClient(1000) // 每客户端最大待发消息数 .WithMaxInflightMessages(100) // QoS1/2 最大飞行窗口 .Build(); _server = new MqttFactory().CreateMqttServer(options); // 注册事件：只要消息被成功分发给某个客户端，就记录 _server.ApplicationMessageReceived += OnApplicationMessageReceived; }OnApplicationMessageReceived事件处理器直接调用MessageLogger.Log()，这才是“消息保存到文件”的真实入口——不是 Broker 自己存，而是由业务层监听并落盘。这种解耦让日志格式、路径、编码完全可控。
2.3 客户端重连机制：不是简单 try-catch，而是状态机驱动
MqttClientWrapper.cs里的重连不是“断了就ConnectAsync()”，而是基于MqttClientConnectedEventArgs和MqttClientDisconnectedEventArgs构建的状态机：
- 初始状态：
Disconnected - 收到
Connected事件 → 切换为Connected，自动重新订阅上次主题； - 收到
Disconnected事件 → 切换为Reconnecting，启动指数退避（首次 1s，失败后 2s、4s、8s…上限 60s）； - 重连成功 → 清空重连计数器，恢复
Connected； - 连续 5 次重连失败 → 触发
ConnectionFailed事件，UI 显示红色告警。
这个逻辑藏在StartAutoReconnectTimer()方法里，参数全可配：
private void StartAutoReconnectTimer() { if (_reconnectTimer == null) { _reconnectTimer = new Timer { Interval = _reconnectDelayMs }; // 初始 1000ms _reconnectTimer.Elapsed += async (s, e) => { _reconnectTimer.Stop(); await TryConnectAsync(); // 尝试重连 if (!_isConnected && ++_reconnectCount < 5) { _reconnectDelayMs = Math.Min(_reconnectDelayMs * 2, 60000); // 指数退避 _reconnectTimer.Interval = _reconnectDelayMs; _reconnectTimer.Start(); } }; } _reconnectTimer.Start(); }_reconnectDelayMs和_reconnectCount都是私有字段，你可以在app.config里加<add key="ReconnectBaseDelayMs" value="2000"/>来调整起始延迟——这是为现场网络抖动预留的后悔药。
3. 核心模块拆解：MessageLogger 如何保证消息不丢、不乱、可追溯？
消息落地不是简单File.AppendAllText()。MessageLogger.cs是整个项目最稳的模块，它解决三个硬需求：原子写入（避免多线程冲突）、按天分文件（防止单文件过大）、带完整元数据（方便后续解析）。它不依赖数据库，纯文件系统操作，但做了足够多的防护。
3.1 日志路径与文件名生成：动态、可配置、防冲突
日志根目录来自app.config：
<configuration> <appSettings> <add key="LogRootPath" value="logs\" /> </appSettings> </configuration>MessageLogger在构造时解析该路径，并确保目录存在：
public MessageLogger(string logRootPath = "logs\\") { _logRootPath = Path.IsPathRooted(logRootPath) ? logRootPath : Path.Combine(AppDomain.CurrentDomain.BaseDirectory, logRootPath); Directory.CreateDirectory(_logRootPath); // 自动创建 logs\ 目录 }每日日志文件名格式为yyyy-MM-dd.log，由GetCurrentLogFileName()生成：
private string GetCurrentLogFileName() { var today = DateTime.Today.ToString("yyyy-MM-dd"); return Path.Combine(_logRootPath, $"{today}.log"); }注意：这里用
DateTime.Today而不是DateTime.Now.Date，避免跨午夜时出现文件名突变。曾有开发者用Now.ToString("yyyy-MM-dd")导致 23:59 写入2024-06-12.log，00:01 却新建2024-06-13.log，造成日志断层。
3.2 原子写入实现：用 FileStream + Lock 避免多客户端并发写崩
当多个客户端同时发消息（比如 10 个传感器节点），OnApplicationMessageReceived会被并发调用。如果直接File.AppendAllText()，可能因文件句柄竞争导致内容错乱。MessageLogger采用FileStream手动控制：
public void Log(MqttApplicationMessage message, string clientId, string ipAddress) { var logEntry = BuildLogEntry(message, clientId, ipAddress); var fileName = GetCurrentLogFileName(); // 使用 FileMode.Append + FileAccess.Write + FileShare.Read 确保只追加 using (var fs = new FileStream(fileName, FileMode.Append, FileAccess.Write, FileShare.Read, 4096, FileOptions.SequentialScan)) using (var sw = new StreamWriter(fs, Encoding.UTF8)) { sw.WriteLine(logEntry); // 单行写入，原子性由 FileStream 保证 sw.Flush(); // 强制刷盘，避免缓存丢失 } }FileOptions.SequentialScan告诉 Windows 这是顺序写，提升 IO 效率；4096缓冲区大小是经验值，在机械硬盘和 SATA SSD 上表现均衡。sw.Flush()是关键——没有它，进程崩溃时最后几条日志可能永远不落盘。
3.3 日志内容格式：一行一消息，JSON 化元数据，人类可读机器可 parse
每条日志是严格的一行文本，包含时间戳、客户端标识、IP、主题、QoS、Payload（Base64 编码）和消息 ID：
2024-06-12 14:23:05.123 | CLIENT: sensor-001 | IP: 192.168.1.105:54321 | TOPIC: home/livingroom/temp | QOS: 1 | PAYLOAD: VGhpcyBpcyBhIHRlc3Q= | MSG_ID: 42BuildLogEntry()方法组装此字符串：
private string BuildLogEntry(MqttApplicationMessage message, string clientId, string ipAddress) { var payloadStr = Encoding.UTF8.GetString(message.Payload); var payloadBase64 = Convert.ToBase64String(message.Payload); // 防止乱码，保留原始字节 return $"{DateTime.Now:yyyy-MM-dd HH:mm:ss.fff} | " + $"CLIENT: {clientId} | " + $"IP: {ipAddress} | " + $"TOPIC: {message.Topic} | " + $"QOS: {message.QualityOfServiceLevel} | " + $"PAYLOAD: {payloadBase64} | " + $"MSG_ID: {message.PacketIdentifier}"; }提示：
message.PacketIdentifier是 MQTT 协议层的 ID，QoS1/2 消息才有，QoS0 为 0。这个 ID 能帮你追踪“这条消息是否被对方 ACK”，是调试 QoS 行为的黄金字段。
4. 运行与调试：从零开始跑通的六步法，附常见翻车现场
别急着双击 exe。Winform + MQTT 的坑，80% 出在环境和配置。按下面六步走，99% 的人能 10 分钟内看到“Received: Hello World”出现在客户端日志框里。
4.1 第一步：确认 .NET Framework 版本与运行时
两个工程目标框架均为.NET Framework 4.7.2。检查你的开发机：
- Win10/11 默认自带 4.8，向下兼容 4.7.2，无需额外安装；
- Win7 SP1 需手动安装 .NET Framework 4.7.2 Runtime ；
- 严禁在 .NET Core / .NET 5+ 环境下运行——MQTTnet 3.1.15 不支持。
验证方法：命令行执行
reg query "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full" /v Release返回值 ≥ 461808 即表示 4.7.2+ 已就绪。
4.2 第二步：修改 Broker 端口避免冲突
MQTTServerDemo/app.config中：
<add key="BrokerPort" value="1883" />如果你本机已运行 IIS Express（占 1883）、Docker（占 1883）、或杀毒软件（如某国产卫士会劫持 1883），请改成1884或2883，并同步改MQTTClientDemo/app.config的BrokerPort。改完务必重启服务端程序。
4.3 第三步：关闭防火墙临时规则（仅调试期）
Windows 防火墙默认阻止入站 1883。临时放行（管理员权限 PowerShell）：
New-NetFirewallRule -DisplayName "Allow MQTT Server" -Direction Inbound -Protocol TCP -LocalPort 1883 -Action Allow注意：生产环境必须用证书加密 + 用户认证，此处仅为快速验证。
4.4 第四步：启动顺序与 UI 操作流
- 先双击
MQTTServerDemo.exe→ 主窗体显示 “Broker running on 0.0.0.0:1883”； - 再双击
MQTTClientDemo.exe→ 客户端窗体弹出； - 在客户端“Broker Address”填
localhost，“Port”填1883，“Client ID”填任意不重复字符串（如winform-client-01）； - 点击 “Connect” → 状态栏变绿，服务器窗体“Connected Clients”计数 +1；
- 在客户端“Subscribe Topic”填
test/#，点 “Subscribe”； - 在服务器窗体“Publish Topic”填
test/msg，“Message”填Hello World，点 “Publish” → 客户端日志框立刻出现接收记录。
4.5 常见问题排查：五条血泪踩坑记录
现象 1：客户端显示 Connected，但服务器“Connected Clients”始终为 0
原因：MQTTServerDemo的BrokerService.cs中WithDefaultEndpointPort(1883)绑定的是0.0.0.0，但客户端连的是localhost（即127.0.0.1），某些网络策略下回环地址不通。
解决：在服务器MainForm.cs启动 Broker 前，显式指定IPAddress.Loopback：
var endpoint = new IPEndPoint(IPAddress.Loopback, 1883); _server.StartAsync(new MqttServerTcpEndpointOptions { Endpoint = endpoint });现象 2：消息能发、能收，但日志文件为空
原因：MessageLogger.cs的Log()方法被调用，但FileStream构造时路径错误（如logs\目录无写入权限，或路径含非法字符）。
解决：在Log()开头加日志：
File.AppendAllText("debug.log", $"Try write to: {fileName}\r\n");查看debug.log确认路径是否正确；若权限不足，右键logs文件夹 → 属性 → 安全 → 编辑 → 添加Users组并勾选“写入”。
现象 3：订阅sensor/+后收不到sensor/001的消息
原因：MQTT 主题通配符+是单层匹配，sensor/+匹配sensor/001，但不匹配sensor/001/data；而#是多层。客户端代码中SubscribeAsync()传入的是字符串数组，需确保未被意外截断。
解决：在MqttClientWrapper.cs的SubscribeAsync()调用处打日志：
Debug.WriteLine($"Subscribing to: [{string.Join(",", topics)}]");确认传入的是["sensor/+"]而非["sensor/"]。
现象 4：客户端断网重连后，之前订阅的主题失效
原因：Clean Session = true（默认），重连后 Broker 清空 Session，需手动重新订阅。代码中OnConnected事件处理器未触发重订阅。
解决：检查MqttClientWrapper.cs的OnConnected事件注册：
_client.Connected += (s, e) => { ReSubscribeTopics(); }; // 必须有这一行现象 5：中文消息显示为乱码（如Hello 你好变成Hello）
原因：MqttApplicationMessage的Payload是byte[]，客户端MessageSerializer.cs默认用Encoding.UTF8，但若发送方用GBK编码，就会乱码。
解决：统一强制 UTF-8。在MessageSerializer.cs的Serialize()和Deserialize()方法中，明确指定编码：
public static byte[] Serialize(string text) => Encoding.UTF8.GetBytes(text); public static string Deserialize(byte[] bytes) => Encoding.UTF8.GetString(bytes);5. 二次开发指南：如何接入真实设备、替换序列化、添加认证？
这个项目不是终点，而是你 IoT 系统的起点。我把它用在三个真实场景：某工厂的振动传感器数据采集、某实验室的 CO2 浓度监控、某智能农业大棚的光照控制。每次改造，我都遵循同一套验证流程——先改一小块，再用 Wireshark 抓包看 MQTT 协议层是否合规，最后用另一台电脑上的 MQTT Explorer 订阅验证。下面是你最可能遇到的三个改造方向。
5.1 接入真实硬件：从模拟发布到串口/Modbus 数据桥接
MQTTServerDemo当前是手动点击发布，但真实场景是串口读取传感器数据。你需要替换MainForm.cs中的btnPublish_Click事件：
// 原代码：手动发布 private void btnPublish_Click(object sender, EventArgs e) { _brokerService.Publish(txtTopic.Text, txtMessage.Text); } // 改造后：从串口读数据并发布 private SerialPort _serialPort; private void InitSerialPort() { _serialPort = new SerialPort("COM3", 9600, Parity.None, 8, StopBits.One); _serialPort.DataReceived += (s, e) => { var data = _serialPort.ReadExisting(); // 假设传感器返回 JSON：{"temp":25.3,"hum":45.1} if (data.Contains('{') && data.Contains('}')) { _brokerService.Publish("sensor/env", data); // 直接发原始字符串 } }; _serialPort.Open(); }关键点：
DataReceived是后台线程回调，_brokerService.Publish()必须是线程安全的。原项目BrokerService.cs的Publish()方法已用lock (_publishLock)保护，可直接调用。
5.2 替换序列化：从字符串到 Protobuf，减小带宽占用
传感器数据量大时，JSON 文本太重。MessageSerializer.cs是你的切入点。先安装Google.ProtobufNuGet 包（v3.21.12，兼容 .NET Framework），然后定义.proto文件：
syntax = "proto3"; package sensor; message EnvData { double temp = 1; double hum = 2; int32 timestamp = 3; }生成 C# 类后，改造MessageSerializer.cs：
public static byte[] Serialize(EnvData data) { return data.ToByteArray(); // Protobuf 自带序列化 } public static EnvData Deserialize(byte[] bytes) { return EnvData.Parser.ParseFrom(bytes); }再改MqttClientWrapper.cs的PublishAsync()：
var payload = MessageSerializer.Serialize(new EnvData { temp = 25.3, hum = 45.1, timestamp = (int)DateTime.UtcNow.Subtract(new DateTime(1970,1,1)).TotalSeconds }); await _client.PublishAsync(new MqttApplicationMessageBuilder() .WithTopic("sensor/env-bin") .WithPayload(payload) .WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtMostOnce) .Build());提示：
.bin后缀是约定，告诉下游消费者这是二进制数据。Wireshark 的 MQTT 插件能自动识别 Protobuf，比 Base64 更直观。
5.3 添加用户名密码认证：拒绝裸奔，最小成本加固
MQTTnet Server 支持WithCredentials()，只需两步：
在
MQTTServerDemo/BrokerService.cs的MqttServerOptionsBuilder中添加：.WithDefaultEndpointPort(1883) .WithCredentials() // 启用认证在
OnClientConnecting事件中校验：_server.ClientConnecting += async (s, e) => { // 从配置文件或数据库读取合法凭据 var validUsers = new Dictionary<string, string> { { "admin", "p@ssw0rd" }, { "sensor", "readonly123" } }; if (!validUsers.TryGetValue(e.Username, out var pwd) || pwd != e.Password) { e.ReasonCode = MqttConnectReasonCode.BadUserNameOrPassword; e.CloseConnection = true; } };
客户端连接时，MqttClientOptionsBuilder必须设置：
.WithCredentials("admin", "p@ssw0rd")注意：密码明文存
app.config仅用于演示。生产环境应使用 Windows DPAPI 加密配置节，或从环境变量读取。
从那以后我每次给新项目接入 MQTT，都强制走一遍这三步：先用本项目验证 Broker/Client 连通性，再用 Wireshark 抓包确认 QoS 和遗嘱行为，最后用 MQTT Explorer 订阅所有主题看数据流是否符合预期。这套组合拳让我避开 90% 的协议级翻车。希望帮到你。
本文还有配套的精品资源，点击获取
