MqttNetMosquittoSample

這是 .NET 10 Console App 範例，示範使用 MQTTnet 連接 Eclipse Mosquitto Broker，涵蓋基本發佈訂閱、Topic 設計、QoS、Retained Message 與 Last Will and Testament。

對應筆記：在 .NET 使用 MQTT：MQTTnet 與 Mosquitto 實作。

文件

• SPEC.md：demo 範圍、Solution / 專案檔規格、測試策略與 Demo 界線。
• LICENSE.md：MIT 授權條款。

技術重點

• Target Framework：.NET 10
• MQTT Client：MQTTnet
• Broker：Eclipse Mosquitto
• Broker 執行方式：Docker Compose
• 測試：NUnit 4、NSubstitute

專案結構

MqttNetMosquittoSample/
├── infra/mosquitto/
│   ├── compose.yaml
│   └── config/
├── src/MqttNetMosquittoSample/
│   ├── Mqtt/
│   ├── Models/
│   ├── Options/
│   ├── Scenarios/
│   └── Program.cs
├── tests/MqttNetMosquittoSample.Tests/
└── MqttNetMosquittoSample.slnx

筆記對照

筆記概念	專案實作
Mosquitto TCP listener	infra/mosquitto/config/mosquitto.conf 提供 1883 listener。
Mosquitto WebSocket listener	infra/mosquitto/config/mosquitto.conf 提供 9001 listener，僅作為設定展示。
帳號密碼連線	Compose 啟動時由 password.txt.example 產生本機 password.txt，並關閉匿名連線。
Topic 階層命名	MqttTopicBuilder 固定產生 demo/... 業務 Topic，並拒絕把萬用字元放入發佈 Topic。
QoS	CLI 支援 --qos 0、--qos 1、--qos 2。實際傳輸 QoS 由發佈端與訂閱端的較低值決定。
Retained Message	retained-publish 發佈 retained 裝置設定，retained-subscribe 可在新訂閱時收到最後狀態。
Last Will and Testament	last-will-client 註冊離線遺囑，last-will-listen 監看 demo/status/+。

啟動 Broker

cd .\infra\mosquitto
docker compose up -d
docker compose ps

若 1883 已被其他本機 Broker 或服務占用，Compose 會啟動失敗。可先停止既有服務，或調整 Compose 對外連接埠並同步設定 Mqtt:Port。

預設帳號密碼：

• 使用者名稱：demo-user
• 密碼：demo-password

Compose 會在第一次啟動時，從 config/password.txt.example 產生 config/password.txt。password.txt、data/ 與 log/ 已由 .gitignore 排除。

清除 Broker 狀態：

cd .\infra\mosquitto
docker compose down
Remove-Item -Force .\config\password.txt -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force .\data, .\log -ErrorAction SilentlyContinue

建置與測試

dotnet build .\MqttNetMosquittoSample.slnx
dotnet test .\MqttNetMosquittoSample.slnx

Smoke tests 只依賴本機 Mosquitto。若 Broker 未啟動或認證不符，MQTT smoke tests 會略過；Topic Builder 與 Payload Serializer 測試仍會執行。

執行範例

發佈一般訊息：

dotnet run --project .\src\MqttNetMosquittoSample -- publish --message "hello mqtt" --qos 1

訂閱一般訊息：

dotnet run --project .\src\MqttNetMosquittoSample -- subscribe --qos 1

模擬感測器發佈溫度資料：

dotnet run --project .\src\MqttNetMosquittoSample -- sensor --device-id device-001 --count 10 --interval-seconds 2 --qos 1

發佈 retained 裝置設定：

dotnet run --project .\src\MqttNetMosquittoSample -- retained-publish --device-id device-001 --qos 1

訂閱 retained 裝置設定：

dotnet run --project .\src\MqttNetMosquittoSample -- retained-subscribe --device-id device-001 --qos 1

監看 Last Will 狀態：

dotnet run --project .\src\MqttNetMosquittoSample -- last-will-listen --qos 1

建立帶有 Last Will 的 client：

dotnet run --project .\src\MqttNetMosquittoSample -- last-will-client --client-id demo-client --clean-disconnect false

--clean-disconnect false 會在 Ctrl+C 後直接釋放 client，讓 Broker 有機會發佈 Last Will 訊息。若改成 true，client 會正常送出 disconnect，Broker 不會發佈 Last Will。

設定

Console App 使用 Host.CreateApplicationBuilder() 讀取設定。預設連線到本機 Mosquitto：

設定	預設值
Mqtt:Host	localhost
Mqtt:Port	1883
Mqtt:Username	demo-user
Mqtt:Password	demo-password

PowerShell 環境變數範例：

$env:Mqtt__Host = "localhost"
$env:Mqtt__Port = "1883"
$env:Mqtt__Username = "demo-user"
$env:Mqtt__Password = "demo-password"

Demo 界線

• 不示範 TLS 憑證產生與正式環境憑證管理。
• 不示範 Broker Cluster、高可用架構或雲端 MQTT 服務。
• 不示範完整 IoT 裝置管理平台。
• 不示範 MQTT 5.0 所有屬性，只保留範例所需設定。
• 不提供 Web 前端，WebSocket listener 僅作為 Broker 設定範例。
• Last Will 的非預期斷線行為保留手動驗證，不列為必要自動化測試。

授權條款

本專案採用 MIT 授權條款。