C# und .NET MQTT 3.1.1 und 5.0

C#-MQTT-Client für MQTT 3.1.1 und 5.0

Verbinde C#-Apps mit diesem .NET-MQTT-Client über TCP oder WebSocket mit jedem MQTT-Broker, von .NET Framework 2.0 bis .NET 10.

MQTT 3.1.1 und MQTT 5.0
QoS 0, 1 und 2
TLS über TCP oder WebSocket
Last Will, Retain, Keep-Alive

Verbinden, abonnieren und veröffentlichen in C# → · Preise ansehen →

C#-MQTT-Client
using esegece.sgcWebSockets;

var client = new TsgcWebSocketClient();
client.Host = "broker.example.com";
client.Port = 8883;
client.TLS = true;
client.Specifications.RFC6455 = false; // MQTT over TCP

var mqtt = new TsgcWSPClient_MQTT();
mqtt.Client = client;
mqtt.MQTTVersion = TwsMQTTVersion.mqtt5;

mqtt.OnMQTTConnect += (conn, session, code, reason, props) =>
    mqtt.Subscribe("sensors/#");
mqtt.OnMQTTPublish += (conn, topic, text, props) =>
    Console.WriteLine(topic + ": " + text);

client.Active = true;

Ein MQTT-Client, der auf dem sgcWebSockets-Client aufsetzt

Eine Transportkomponente, eine Protokollkomponente, Ereignisse für jedes MQTT-Paket.

Der C#-MQTT-Client in sgcWebSockets .NET ist TsgcWSPClient_MQTT im Namespace esegece.sgcWebSockets. Er öffnet selbst keine Sockets. Du weist seiner Eigenschaft Client einen TsgcWebSocketClient zu, und dieser Client transportiert die MQTT-Pakete entweder als einfachen TCP-Stream (Ports 1883 und 8883) oder in WebSocket-Frames für Broker, die einen MQTT-über-WebSocket-Endpunkt anbieten. Host, Port, TLS, Proxy und automatisches Wiederverbinden bleiben beim Transport, die MQTT-Sitzung, Topics und QoS liegen in der Protokollkomponente.

Jede Antwort des Brokers wird zu einem C#-Ereignis: OnMQTTConnect, OnMQTTPublish, OnMQTTSubscribe, OnMQTTPubAck, OnMQTTPubRec, OnMQTTPubComp, OnMQTTPing und OnMQTTDisconnect, dazu OnMQTTAuth für die erweiterte Authentifizierung von MQTT 5.0. Dasselbe Paket zielt auf .NET Framework 2.0 bis 4.8.1, .NET Core 1.0 bis 3.1, .NET 5 bis .NET 10 und .NET Standard 1.6 und 2.0, unter Windows, Linux und macOS.

MQTT 3.1.1 und 5.0

Wähle das Protokoll mit MQTTVersion: TwsMQTTVersion.mqtt311 oder TwsMQTTVersion.mqtt5.

TCP oder WebSocket

Specifications.RFC6455 = false am Transport sendet rohes MQTT über TCP; lass es aktiviert, um MQTT durch einen WebSocket-Pfad zu tunneln.

Drei QoS-Stufen

TmqttQoS.mtqsAtMostOnce, mtqsAtLeastOnce und mtqsExactlyOnce bei jedem Publish und Subscribe.

Sitzungssteuerung

Benutzername und Passwort in Authentication, Keep-Alive-Pings in HeartBeat, ein Last Will in LastWillTestament.

Verbinden, abonnieren und veröffentlichen in C#

Installiere das NuGet-Paket esegece.sgcWebSockets (oder esegece.sgcWebSockets.Community) und folge dann den vier Schritten.

using esegece.sgcWebSockets;

// transport: TCP with TLS on the standard secure MQTT port
var client = new TsgcWebSocketClient();
client.Host = "broker.example.com";
client.Port = 8883;
client.TLS = true;
client.TLSOptions.Version = TwsTLSVersions.tls1_2;
client.Specifications.RFC6455 = false;   // raw MQTT, no WebSocket handshake

// protocol: MQTT 3.1.1 with credentials and keep-alive
var mqtt = new TsgcWSPClient_MQTT();
mqtt.Client = client;
mqtt.MQTTVersion = TwsMQTTVersion.mqtt311;
mqtt.Authentication.Enabled = true;
mqtt.Authentication.UserName = "device-01";
mqtt.Authentication.Password = "secret";
mqtt.HeartBeat.Enabled = true;
mqtt.HeartBeat.Interval = 30;

mqtt.OnMQTTConnect += (conn, session, reasonCode, reasonName, props) =>
    Console.WriteLine("#mqtt connected: " + reasonName);
mqtt.OnMQTTDisconnect += (conn, reasonCode, reasonName, props) =>
    Console.WriteLine("#mqtt disconnected: " + reasonName);

client.Active = true;
// subscribe once the broker has accepted the session
mqtt.OnMQTTConnect += (conn, session, reasonCode, reasonName, props) =>
{
    mqtt.Subscribe("sensors/+/temperature");
    mqtt.Subscribe("alerts/#", TmqttQoS.mtqsExactlyOnce, null);
};

mqtt.OnMQTTSubscribe += (conn, packetId, codes, props) =>
    Console.WriteLine("#subscribed, packet " + packetId);

// every message on a subscribed topic arrives here
mqtt.OnMQTTPublish += (conn, topic, text, props) =>
    Console.WriteLine(topic + " = " + text);

// stop receiving a topic
mqtt.UnSubscribe("alerts/#");
// QoS 0: fire and forget
mqtt.Publish("sensors/room1/temperature", "21.5");

// QoS 1 with the retain flag, so late subscribers get the last value
mqtt.Publish("devices/device-01/status", "online", TmqttQoS.mtqsAtLeastOnce, true);

// QoS 2: wait up to 10 seconds for the broker to confirm
bool ok = mqtt.PublishAndWait("orders/new", "{\"id\": 42}", TmqttQoS.mtqsExactlyOnce, 10000);

// binary payloads
mqtt.Publish("images/cam1", File.ReadAllBytes("frame.jpg"));

// acknowledgements
mqtt.OnMQTTPubAck  += (conn, packetId, reasonCode, reasonName, props) =>
    Console.WriteLine("#puback " + packetId);
mqtt.OnMQTTPubComp += (conn, packetId, reasonCode, reasonName, props) =>
    Console.WriteLine("#pubcomp " + packetId);
using esegece.sgcWebSockets;

// the same MQTT client, tunnelled through a secure WebSocket (wss://)
var client = new TsgcWebSocketClient();
client.Host = "broker.example.com";
client.Port = 443;
client.TLS = true;
client.Options.Parameters = "/mqtt";   // the broker's WebSocket path
client.WatchDog.Enabled = true;          // reconnect after network drops

var mqtt = new TsgcWSPClient_MQTT();
mqtt.Client = client;
mqtt.OnMQTTPublish += (conn, topic, text, props) => Console.WriteLine(topic + ": " + text);

client.Active = true;

Die WinForms-Demos MQTT Client und MQTT Console im .NET-Download verdrahten dieselben Aufrufe mit einem Formular, mit Broker-Liste, TLS- und Proxy-Einstellungen sowie QoS- und Retain-Optionen.

MQTT QoS 0, 1 und 2 aus C#

Übergib einen TmqttQoS-Wert an Publish, PublishAndWait oder Subscribe. Bei QoS 1 und 2 sendet der Client eine Nachricht erneut, wenn die Bestätigung nicht rechtzeitig eintrifft. Behandle OnMQTTPubAck oder OnMQTTPubComp, um die Zustellung zu verfolgen, oder rufe PublishAndWait auf, das false zurückgibt, wenn der Broker innerhalb des Timeouts (standardmäßig 10 Sekunden) nicht antwortet.

QoSC#-WertZustellungBestätigungsereignis
0TmqttQoS.mtqsAtMostOnceHöchstens einmal, nach bestem Bemühen, keine Antwortkeines
1TmqttQoS.mtqsAtLeastOnceMindestens einmal, vom Broker bestätigtOnMQTTPubAck
2TmqttQoS.mtqsExactlyOnceGenau einmal, Handshake in vier SchrittenOnMQTTPubRec, OnMQTTPubComp

TLS, Zugangsdaten, Last Will und Keep-Alive

TLS auf Port 8883

Setze TLS = true am Transport und wähle das Protokoll in TLSOptions.Version, bis TLS 1.3. Für Broker, die Clientzertifikate verlangen, nimmt TLSOptions außerdem CertFile, KeyFile, Password und RootCertFile entgegen, und VerifyCertificate prüft das Serverzertifikat.

Benutzername und Passwort

Authentication.Enabled, Authentication.UserName und Authentication.Password kommen in das CONNECT-Paket.

Last Will

LastWillTestament setzt Topic, Text, QoS und Retain, sodass der Broker eine Offline-Nachricht veröffentlicht, wenn ein Gerät ohne sauberes Trennen wegbricht.

Keep-Alive

HeartBeat.Enabled und HeartBeat.Interval senden PINGREQ-Pakete; OnMQTTPing meldet jede Antwort, und Ping() sendet bei Bedarf eines.

Client-ID und Clean Session

OnMQTTBeforeConnect übergibt CleanSession und ClientIdentifier per Referenz, sodass du eine persistente Sitzung und eine feste Client-ID pro Gerät wählst.

Proxy und Wiederverbinden

Die Proxy-Einstellungen des Transports und das automatische Wiederverbinden per WatchDog gelten unverändert auch für MQTT.

mqtt.LastWillTestament.Enabled = true;
mqtt.LastWillTestament.Topic = "devices/device-01/status";
mqtt.LastWillTestament.Text = "offline";
mqtt.LastWillTestament.QoS = TmqttQoS.mtqsAtLeastOnce;
mqtt.LastWillTestament.Retain = true;

mqtt.OnMQTTBeforeConnect += (TsgcWSConnection conn, ref bool cleanSession, ref string clientId) =>
{
    cleanSession = false;
    clientId = "device-01";
};

MQTT-5.0-Funktionen in C#

Setze MQTTVersion = TwsMQTTVersion.mqtt5, und der Client spricht MQTT 5.0. Jedes Bestätigungsereignis trägt dann den ReasonCode und ReasonName des Brokers zusammen mit den Paketeigenschaften, sodass Fehler mit einem Grund eintreffen statt mit einer abgebrochenen Verbindung.

Verbindungseigenschaften

ConnectProperties setzt SessionExpiryInterval, ReceiveMaximum, MaximumPacketSize, TopicAliasMaximum, UserProperties und Anfrage-Flags für Antwort- und Probleminformationen.

Publish-Eigenschaften

Pro Nachricht ContentType, ResponseTopic, CorrelationData, MessageExpiryInterval, TopicAlias, PayloadFormat und Benutzereigenschaften für Anfrage-Antwort-Muster.

Erweiterte Authentifizierung

Auth() sendet AUTH-Pakete mit einer AuthenticationMethod und AuthenticationData, auch zur erneuten Authentifizierung, und OnMQTTAuth empfängt die Challenge des Brokers.

Will- und Disconnect-Eigenschaften

Ein Will-Verzögerungsintervall und Nachrichtenablauf beim Last Will, dazu ein Reason Code, ein Reason String und ein Sitzungsablauf bei Disconnect.

mqtt.MQTTVersion = TwsMQTTVersion.mqtt5;
mqtt.ConnectProperties.Enabled = true;
mqtt.ConnectProperties.SessionExpiryInterval = 3600;   // keep the session one hour
mqtt.ConnectProperties.ReceiveMaximum = 100;

mqtt.OnMQTTConnect += (conn, session, reasonCode, reasonName, props) =>
    Console.WriteLine("CONNACK " + reasonCode + " " + reasonName);

Jeder Standard-MQTT-Broker, dazu AWS IoT und Azure IoT

Weil der Client den Spezifikationen MQTT 3.1.1 und 5.0 folgt, verbindet er sich mit selbst gehosteten und verwalteten Brokern gleichermaßen: über Port 1883 für reines TCP, 8883 für TLS oder über den WebSocket-Pfad des Brokers, wenn nur HTTPS-Ports offen sind. Für die Cloud-IoT-Plattformen liefert sgcWebSockets .NET außerdem einen AWS-IoT-Client für AWS IoT Core und einen Azure-IoT-Client für Azure IoT Hub, beide MQTT-basiert, aufgeführt in der .NET-Funktionsmatrix.

Dieselbe Bibliothek bietet dir außerdem AMQP 0.9.1 und 1.0, STOMP, Kafka und den C#-WebSocket-Client und -Server, sodass eine einzige Abhängigkeit jedes Messaging-Protokoll in der Anwendung abdeckt.

Kostenlos starten, ein Preis für jedes Protokoll

Der MQTT-Client steckt in jeder .NET-Edition. Community ist für die kommerzielle und nichtkommerzielle Nutzung durch kleine Teams kostenlos (unter 1 Mio. EUR Umsatz, bis zu 5 Entwickler), mit vollem Funktionsumfang und einem Starthinweis. Professional entfernt den Hinweis und beginnt bei €149 pro Entwickler mit 1 Jahr Updates; Enterprise ergänzt den Quellcode zum Neubau der Assemblies. Team- und Site-Lizenzen findest du auf der Preisseite (Tab .NET).

Fragen zu C# und MQTT

Erstelle einen TsgcWebSocketClient mit Host und Port des Brokers, setze Specifications.RFC6455 = false für einen einfachen TCP-Broker, erstelle ein TsgcWSPClient_MQTT und weise den Client seiner Eigenschaft Client zu. Mit client.Active = true wird die Verbindung geöffnet, und OnMQTTConnect wird ausgelöst, wenn der Broker die Sitzung akzeptiert.

Ja. Setze MQTTVersion auf TwsMQTTVersion.mqtt5 für MQTT 5.0 oder auf TwsMQTTVersion.mqtt311 für MQTT 3.1.1. MQTT 5.0 ergänzt Reason Codes bei jeder Bestätigung, Verbindungs- und Publish-Eigenschaften, Benutzereigenschaften und erweiterte Authentifizierung.

Rufe Publish(topic, text, TmqttQoS.mtqsAtLeastOnce) oder TmqttQoS.mtqsExactlyOnce auf, optional mit einem Retain-Flag. Verwende PublishAndWait, wenn der Code wissen muss, dass der Broker die Nachricht verarbeitet hat: Es gibt false zurück, wenn innerhalb des Timeouts keine Antwort eintrifft.

Ja. Setze Port = 8883 und TLS = true am TsgcWebSocketClient, wähle die Version in TLSOptions.Version (bis TLS 1.3) und füge TLSOptions.CertFile und KeyFile hinzu, falls der Broker ein Clientzertifikat verlangt.

Ja, das ist die Standardeinstellung des Transports. Lass Specifications.RFC6455 aktiviert, setze Options.Parameters auf den WebSocket-Pfad des Brokers (zum Beispiel /mqtt) und verwende TLS = true auf Port 443 für wss://. So kommt MQTT durch Firewalls, die nur HTTPS erlauben.

.NET Framework 2.0 bis 4.8.1, .NET Core 1.0 bis 3.1, .NET 5 bis .NET 10 und .NET Standard 1.6 und 2.0, unter Windows, Linux und macOS. Installiere esegece.sgcWebSockets oder das kostenlose Paket esegece.sgcWebSockets.Community von nuget.org.

Ja. Die Community-Edition enthält den MQTT-Client und ist für die kommerzielle und nichtkommerzielle Nutzung durch kleine Teams kostenlos (unter 1 Mio. EUR Umsatz, bis zu 5 Entwickler), mit einem Starthinweis. Größere Organisationen kaufen Professional, ab €149 pro Entwickler, oder Enterprise.

Mehr zu sgcWebSockets .NET

C#-WebSocket-Bibliothek

Der WebSocket-Client und -Server, die den MQTT-Verkehr transportieren, mit TLS, Kompression und automatischem Wiederverbinden.

.NET-Funktionsmatrix

Jede Komponente und jedes Protokoll in den .NET-Editionen, darunter MQTT, AMQP, STOMP, AWS IoT und Azure IoT.

Download

Community-Edition, NuGet-Pakete und die kompilierten .NET-Demos, darunter MQTT Client und MQTT Console.

Auch für Delphi und C++Builder

Derselbe MQTT-Client gibt es für Delphi und C++Builder, mit derselben Klasse TsgcWSPClient_MQTT und denselben Ereignissen.

Bestes Preis-Leistungs-Verhältnis: All-AccessAlle eSeGeCe-Produkte, inklusive Premium-Support, ab €1,059 pro Jahr.
All-Access-Preise ansehen

Veröffentliche noch heute deine erste MQTT-Nachricht aus C#

Lade die Testversion herunter oder installiere esegece.sgcWebSockets.Community über NuGet. Professional ab €149 pro Entwickler.