Hands-on MQTT for .NET developers — a comfortable high-level Client and an embeddable Broker.
MQTT looks simple — connect, publish, subscribe — but real projects get concrete fast: which QoS should this message use, does a late subscriber see the last value, what happens when a device drops off the network, how do I attach a content type or a correlation id, and how do I secure the transport with TLS or a client certificate?
This repository is a practical learning path that answers those questions with small, readable, runnable programs. Each workshop is a self-contained console project: it prints a framed explanation, runs a real MQTT flow against a broker, checks the result and tells you exactly what to expect. When you outgrow the console examples, two full reference applications (a WPF Client tool and a WPF Broker tool) let you click through the same features by hand.
Everything here uses the high-level PLCcom MQTT API only — the comfortable Client and Broker surface, not the wire protocol.
This is not a feature wish-list: every capability below is backed by a small, runnable workshop in this repository — the Client and Broker workshop maps further down point to the exact one.
Protocol & Messaging
- MQTT 3.1.1 and 5.0 over
mqtt://,mqtts://,ws://andwss:// - QoS 0 / 1 / 2 and topic wildcards (
+,#) - Retained messages including retained deletion
- Last Will — fired on an ungraceful drop, suppressed by a clean disconnect
- All MQTT 5 message properties: content type, payload format, user properties, message expiry, response topic, correlation data and topic alias
- MQTT 5 subscription options: subscription identifiers, no local, retain as published, retain handling
- Request / response as one high-level call, and JSON mapping (publish a .NET object, read it back as the same type)
Client
- Persistent sessions with offline queueing and session expiry
- Automatic reconnect with lifecycle callbacks (connected / disconnected / reconnect failed)
- Async API (
async/await,Task) alongside the blocking API - Shared subscriptions to load-balance a topic across workers
- TLS / mTLS / WSS with trusted and client certificates, hostname verification and an optional custom remote-certificate validator
- MQTT 5 enhanced authentication (application-owned challenge/response)
- Structured diagnostics with level filtering — and every call returns a checkable OperationResult/Quality
Broker
- Runs standalone or embedded inside your .NET application
- Multiple listeners side by side: TCP, WebSocket, TLS and secure WebSocket — with per-port server certificates
- In-process publish and listen — exchange data with connected clients without a network client
- Access control (application-owned validator for CONNECT / PUBLISH / SUBSCRIBE) and enhanced authentication
- PKI store for certificate management (own, trusted and issuer certificates)
- Custom state stores — keep retained messages and sessions in your own durable storage
- Admin snapshots and statistics, plus structured diagnostics
| Area | What it teaches | Typical use |
|---|---|---|
| Client Workshops | Connect, QoS, retained messages, Last Will, all MQTT 5 properties and subscription options, request/response, JSON, sessions, reconnect, async/await, shared subscriptions, TLS/mTLS/WSS, diagnostics and enhanced authentication. | Learn the client side step by step, from a first connection to a secured, resilient application. |
| Broker Workshops | Standalone and embedded brokers, multiple listeners, TLS/WSS with per-port certificates, in-process publish/listen, retained state, access control, authentication, custom stores, admin & diagnostics. | Host your own MQTT broker inside a .NET product, edge gateway or test environment. |
| Reference Applications | Two complete WPF applications — a Client tool and a Broker tool — with DE/EN UI and integrated help. | Manual testing, demos and troubleshooting against real devices, Mosquitto or each other. |
PLCcom.Mqtt.Examples.sln solution with every example project
Workshops/
Client/ 13 client workshops (grouped 1x..4x)
CSharp/ C# version
GettingStarted/ Mqtt5/ Resilience/ Security/
VisualBasic/ Visual Basic version (1:1 to C#)
GettingStarted/ Mqtt5/ Resilience/ Security/
Broker/ 10 broker workshops (grouped 1x..4x)
CSharp/ C# version
Basics/ Embedded/ Security/ Service/
VisualBasic/ Visual Basic version (1:1 to C#)
Basics/ Embedded/ Security/ Service/
Reference_Applications/
Client/ full WPF client tool
Broker/ full WPF broker tool
assets/ overview graphic
README.md this file
Every workshop is available in both C# and Visual Basic — the two versions are line-for-line equivalent, so pick the language you work in. The reference applications (WPF tools) are provided in C# only.
The root PLCcom.Mqtt.Examples.sln opens every example in Visual Studio at once. Every workshop is also a self-contained console project: open any single .csproj (C#) or .vbproj (Visual Basic) on its own and everything it needs — including the PLCcom MQTT NuGet package version — is written right there.
Each workshop class is numbered _1x, _2x, _3x, _4x. The tens digit is the topic group (shown by the folder and namespace), the ones digit is the order inside the group — so the folder tree already reads like the learning path.
Client — start here if you connect to a broker:
| Step | Workshop | Why |
|---|---|---|
| 1 | GettingStarted/_11_FirstConnection |
The smallest complete rhythm: connect, subscribe, publish, receive, close. |
| 2 | GettingStarted/_12_PublishSubscribeAndQos |
Choose QoS 0/1/2 deliberately and use topic wildcards. |
| 3 | GettingStarted/_13_RetainedMessagesAndLastWill |
Remember state and announce unexpected disconnects. |
| 4 | Mqtt5/_21..._24 |
MQTT 5 properties, subscription options, request/response and JSON. |
| 5 | Resilience/_31..._33 |
Sessions, reconnect, async/await API and shared subscriptions. |
| 6 | Security/_41..._43 |
TLS/mTLS/WSS, structured diagnostics and MQTT 5 enhanced authentication. |
Broker — start here if you host a broker:
| Step | Workshop | Why |
|---|---|---|
| 1 | Basics/_11_FirstBroker |
Start the smallest standalone broker and read its bound port. |
| 2 | Basics/_12..._14 |
Multiple listeners, secure listeners, and all four transports with per-port certificates. |
| 3 | Embedded/_21..._22 |
Own the broker lifecycle in .NET; publish and listen in-process. |
| 4 | Security/_31..._32 |
Access control, authentication and PKI. |
| 5 | Service/_41..._42 |
Durable custom stores, admin snapshots and diagnostics. |
The two sides are independent, so you can mix and match — a PLCcom client against a PLCcom broker, a PLCcom client against Mosquitto, or a client tool against the broker tool. A convenient pairing to see the whole picture:
- Start Broker Workshop
Basics/_11_FirstBroker(or a local Mosquitto onmqtt://localhost:1883). - Run Client Workshop
GettingStarted/_11_FirstConnectionand point it at that broker. - For TLS, pair Broker
Basics/_13_SecureListenerswith ClientSecurity/_41_SecureConnection.
Every client workshop reads its broker address from a visible BrokerEndpoint constant and can be overridden without editing the file:
$env:PLCCOM_MQTT_WORKSHOP_ENDPOINT = "mqtt://localhost:1883"The examples use the PLCcom MQTT .NET packages:
<PackageReference Include="PLCcom.Mqtt.Core" Version="2.x.x" />
<PackageReference Include="PLCcom.Mqtt.Client" Version="2.x.x" />
<PackageReference Include="PLCcom.Mqtt.Broker" Version="2.x.x" />Each project is self-contained. Open any workshop's own .csproj and the SDK version is written right there, at the package reference — there is no hidden central file that controls it. To target another PLCcom MQTT release, change the Version in the project you build.
- .NET SDK 10 or newer (
dotnet --version) - A valid PLCcom MQTT license user name and serial number (see the note in each workshop)
- A running MQTT broker for the client workshops (a broker workshop, the broker tool, or Mosquitto)
- Windows for the WPF reference applications (the workshops themselves are cross-platform)
git clone https://github.com/Indi-An/PLCcom-mqtt-example-dotnet.git
cd PLCcom-mqtt-example-dotnetEvery workshop shows exactly where the credentials go — a visible block near the top of each class, shipped blank:
private const string LicenseUser = "";
private const string LicenseSerial = "";You can start without a license. Those two empty strings are what turns on evaluation mode: the library then runs for 15 minutes during a debug session with the full functional scope — enough to bring up a connection and exchange messages. So you can try the workshops out before you register. (Removing the WithLicense(...) call altogether is a different thing and does not work — evaluation mode has to be asked for.)
For uninterrupted work you need a PLCcom MQTT license (a user name and a serial number). Two ways to get one:
- Free trial — generate a 14-day trial license on the PLCcom MQTT download page.
- Purchase — buy a full license on the PLCcom MQTT buy page.
Fill both values in from your license (trial or purchased). A client-only license is enough for the client workshops; broker workshops need a broker (or broker+client) license. Both values can also come from configuration or an environment variable — license data does not belong in source code you publish.
Open PLCcom.Mqtt.Examples.sln in Visual Studio, or build everything from the command line:
dotnet build PLCcom.Mqtt.Examples.slnSet a workshop as startup project in Visual Studio and press F5, or use the command line. Start a broker first, then a client, each in its own terminal:
# Terminal 1 - broker (C#)
dotnet run --project "Workshops/Broker/CSharp/Basics/_11_FirstBroker"
# Terminal 2 - client (point it at the broker or a local Mosquitto)
dotnet run --project "Workshops/Client/CSharp/GettingStarted/_11_FirstConnection"
# The Visual Basic version of any workshop is the same path with VisualBasic instead of CSharp:
dotnet run --project "Workshops/Client/VisualBasic/GettingStarted/_11_FirstConnection"Run a reference application the same way:
dotnet run --project "Reference_Applications/Client/PLCcom MQTT Client.csproj"
dotnet run --project "Reference_Applications/Broker/PLCcom MQTT Broker.csproj"| # | Workshop | Short description |
|---|---|---|
| 11 | First Connection | Connect, protocol selection, Topic Name vs Topic Filter, one QoS 1 round trip. |
| 12 | Publish, Subscribe & QoS | QoS 0/1/2 explained and topic wildcards on one subscription. |
| 13 | Retained Messages & Last Will | Set, read and delete retained state; fire and suppress a Last Will. |
| 21 | MQTT 5 Message Properties | Content Type, Payload Format, User Properties, Message Expiry, Topic Alias. |
| 22 | MQTT 5 Subscription Options | Subscription Identifier, No Local, Retain As Published, Retain Handling. |
| 23 | Request / Response | Response Topic and Correlation Data with a visible responder client. |
| 24 | JSON Mapping | Publish a .NET object as JSON and read it back as the same type. |
| 31 | Sessions, Reconnect & Lifecycle | Persistent session, offline queue, automatic reconnect, lifecycle handlers. |
| 32 | Async API | The same MQTT flow using awaited Tasks instead of blocking calls. |
| 33 | Shared Subscriptions | Load-balance a job stream across two workers. |
| 41 | Secure Connection | TLS, WSS and mutual TLS with client-side PKI options. |
| 42 | Diagnostics & Error Handling | Diagnostic listener, level filtering, Quality checks and error handling. |
| 43 | Enhanced Authentication | Client-side MQTT 5 enhanced authentication: method + token and AUTH challenges (pairs with Broker 32). |
| # | Workshop | Short description |
|---|---|---|
| 11 | First Broker | The smallest standalone broker; start it, read the port, stop it cleanly. |
| 12 | Listeners & Bind Addresses | Several TCP ports plus a WebSocket listener on one broker. |
| 13 | Secure Listeners | Plain TCP + TLS (mqtts) + secure WebSocket (wss) with an auto-created certificate. |
| 14 | All Listener Types | All four transports on one broker, with a per-port certificate. |
| 21 | Embedded Broker in a .NET App | Own the lifecycle; publish and listen in-process, with metadata, batch and JSON. |
| 22 | Retained Messages & Sessions | Retained replay and deletion; session/queue behavior explained. |
| 31 | Access Control | An access validator for CONNECT/PUBLISH/SUBSCRIBE with deny-by-default. |
| 32 | Authentication & PKI | Username/password, MQTT 5 enhanced authentication and where PKI/mTLS fit. |
| 41 | Custom Stores | Move retained/session state into your own durable storage. |
| 42 | Admin & Diagnostics | Read-only admin snapshots, safe counter reset and structured diagnostics. |
The security workshops use TLS to protect the transport. The broker owns a server certificate; the client trusts it through its PKI options, and optionally presents a client certificate to authenticate itself (mutual TLS). Broker certificates can be created on demand in a local PKI folder, and every TLS/WSS listener carries its own certificate — so one broker can present different identities on different ports.
The generated PKI/TLS folders are ignored by Git on purpose: they are local runtime material, not source code. Some workshops relax hostname or certificate checks to keep the flow readable — that is convenient for learning, not a production security policy.
The two WPF tools are complete, clickable versions of the same features:
- Client Tool — connect to any broker, publish/subscribe, try QoS 2, retained messages, MQTT 5 request/response, subscription identifiers, TLS and diagnostics.
- Broker Tool — start a configurable broker with TCP/WS/TLS/WSS listeners, publish and listen in-process, review statistics and diagnostics, and try access validation.
Both ship with a German/English interface and integrated help.
The complete PLCcom MQTT documentation lives at docs.plccom.net. More information about PLCcom for MQTT: www.indi-an.com.
Examples License — all example sources in this repository are released under the MIT License. You may use, modify and distribute them according to the license terms.
PLCcom Library License — the PLCcom MQTT library itself is proprietary software and is not part of the MIT license. To use the SDK in your own applications you need a valid PLCcom MQTT license and must accept the applicable EULA. More information: www.indi-an.com.
These examples are written for learning, integration tests and manual validation. Do not use them unchanged in production, safety-critical or industrial environments. Review topics, QoS, retained state, timeouts, TLS settings, certificate trust and authorization logic before connecting to real equipment. Use at your own risk.
All product names, company names and trademarks referenced in this repository are trademarks or registered trademarks of their respective owners. Their use is solely for identification and interoperability documentation.