C# 和 .NET MQTT 3.1.1 和 5.0

适用于 MQTT 3.1.1 和 5.0 的 C# MQTT 客户端

使用这个 .NET MQTT 客户端,可从 C# 应用程序通过 TCP 或 WebSocket 连接任意 MQTT 代理,支持从 .NET Framework 2.0 到 .NET 10。

MQTT 3.1.1 和 MQTT 5.0
QoS 0、1 和 2
基于 TCP 或 WebSocket 的 TLS
遗嘱消息、保留消息、保活

在 C# 中连接、订阅和发布 → · 查看价格 →

C# MQTT 客户端
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;

构建在 sgcWebSockets 客户端之上的 MQTT 客户端

一个传输组件,一个协议组件,每个 MQTT 数据包都有对应的事件。

sgcWebSockets .NET 中的 C# MQTT 客户端是 esegece.sgcWebSockets 命名空间中的 TsgcWSPClient_MQTT。它本身不打开套接字。你需要将一个 TsgcWebSocketClient 指定给它的 Client 属性,由该客户端以普通 TCP 流(端口 1883 和 8883)承载 MQTT 数据包,或在 WebSocket 帧内承载,适用于提供 MQTT over WebSocket 端点的代理。主机、端口、TLS、代理和自动重连保留在传输层,MQTT 会话、主题和 QoS 则位于协议组件上。

代理的每个回复都会变成一个 C# 事件:OnMQTTConnect、OnMQTTPublish、OnMQTTSubscribe、OnMQTTPubAck、OnMQTTPubRec、OnMQTTPubComp、OnMQTTPing 和 OnMQTTDisconnect,另有用于 MQTT 5.0 增强身份验证的 OnMQTTAuth。同一个包面向 .NET Framework 2.0 到 4.8.1、.NET Core 1.0 到 3.1、.NET 5 到 .NET 10,以及 .NET Standard 1.6 和 2.0,支持 Windows、Linux 和 macOS。

MQTT 3.1.1 和 5.0

使用 MQTTVersion 选择协议:TwsMQTTVersion.mqtt311 或 TwsMQTTVersion.mqtt5。

TCP 或 WebSocket

在传输层设置 Specifications.RFC6455 = false 会通过 TCP 发送原始 MQTT;保持开启则会通过 WebSocket 路径隧道传输 MQTT。

三个 QoS 级别

每次发布和订阅都可使用 TmqttQoS.mtqsAtMostOnce、mtqsAtLeastOnce 和 mtqsExactlyOnce。

会话控制

用户名和密码位于 Authentication,保活 ping 位于 HeartBeat,遗嘱消息位于 LastWillTestament。

在 C# 中连接、订阅和发布

安装 esegece.sgcWebSockets NuGet 包(或 esegece.sgcWebSockets.Community),然后按四个步骤操作。

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;

.NET 下载中的 WinForms 演示 MQTT Client 和 MQTT Console 将同样的调用接入窗体,带有代理列表、TLS 和代理设置,以及 QoS 和保留选项。

在 C# 中使用 MQTT QoS 0、1 和 2

将 TmqttQoS 值传递给 Publish、PublishAndWait 或 Subscribe。在 QoS 1 和 2 下,如果确认未能及时到达,客户端会重发消息。处理 OnMQTTPubAck 或 OnMQTTPubComp 以跟踪投递,或调用 PublishAndWait,当代理在超时时间(默认 10 秒)内没有响应时它会返回 false。

QoSC# 值投递确认事件
0TmqttQoS.mtqsAtMostOnce至多一次,尽力而为,无回复无
1TmqttQoS.mtqsAtLeastOnce至少一次,由代理确认OnMQTTPubAck
2TmqttQoS.mtqsExactlyOnce恰好一次,四步握手OnMQTTPubRec, OnMQTTPubComp

TLS、凭据、遗嘱消息和保活

端口 8883 上的 TLS

在传输层设置 TLS = true,并在 TLSOptions.Version 中选择协议,最高支持 TLS 1.3。对于要求客户端证书的代理,TLSOptions 还接受 CertFile、KeyFile、Password 和 RootCertFile,VerifyCertificate 用于检查服务器证书。

用户名和密码

Authentication.Enabled、Authentication.UserName 和 Authentication.Password 会被写入 CONNECT 数据包。

遗嘱消息

LastWillTestament 设置 Topic、Text、QoS 和 Retain,这样当设备未正常断开连接而掉线时,代理会发布一条“离线”消息。

保活

HeartBeat.Enabled 和 HeartBeat.Interval 发送 PINGREQ 数据包;OnMQTTPing 报告每次响应,Ping() 可按需发送一次。

客户端 ID 和清除会话

OnMQTTBeforeConnect 以引用方式传递 CleanSession 和 ClientIdentifier,因此你可以为每台设备选择持久会话和固定的客户端 ID。

代理和重连

传输层的 Proxy 设置和 WatchDog 自动重连同样适用于 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";
};

C# 中的 MQTT 5.0 功能

设置 MQTTVersion = TwsMQTTVersion.mqtt5 后,客户端就会使用 MQTT 5.0。此后每个确认事件都会携带代理的 ReasonCode 和 ReasonName 以及数据包属性,因此故障会附带原因,而不是连接直接中断。

连接属性

ConnectProperties 设置 SessionExpiryInterval、ReceiveMaximum、MaximumPacketSize、TopicAliasMaximum、UserProperties,以及用于响应和问题信息的请求标志。

发布属性

每条消息可带 ContentType、ResponseTopic、CorrelationData、MessageExpiryInterval、TopicAlias、PayloadFormat 和用户属性,用于请求与响应模式。

增强身份验证

Auth() 使用 AuthenticationMethod 和 AuthenticationData 发送 AUTH 数据包,包括重新身份验证,OnMQTTAuth 接收代理的质询。

遗嘱和断开连接属性

遗嘱消息上的遗嘱延迟间隔和消息过期时间,以及 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);

任意标准 MQTT 代理,以及 AWS IoT 和 Azure IoT

由于客户端遵循 MQTT 3.1.1 和 5.0 规范,它可连接自托管和托管的代理:纯 TCP 使用端口 1883,TLS 使用 8883,当只开放 HTTPS 端口时则使用代理的 WebSocket 路径。对于云 IoT 平台,sgcWebSockets .NET 还附带适用于 AWS IoT Core 的 AWS IoT 客户端和适用于 Azure IoT Hub 的 Azure IoT 客户端,两者都基于 MQTT,详见 .NET 功能对比表。

同一个库还提供 AMQP 0.9.1 和 1.0、STOMP、Kafka 以及 C# WebSocket 客户端和服务器,因此一个依赖项即可涵盖应用程序中的每种消息协议。

免费开始,所有协议统一价格

MQTT 客户端包含在每个 .NET 版本中。Community 对小型团队(收入低于 100 万欧元,最多 5 名开发者)的商业和非商业用途免费,功能完整,带有启动提示。Professional 去除启动提示,每位开发者 €149 起,含 1 年更新;Enterprise 增加了用于重新构建程序集的源代码。Team 和 Site 许可证见价格页面(.NET 标签页)。

C# MQTT 常见问题

使用代理的 Host 和 Port 创建 TsgcWebSocketClient,对于普通 TCP 代理设置 Specifications.RFC6455 = false,创建 TsgcWSPClient_MQTT 并将该客户端指定给它的 Client 属性。设置 client.Active = true 会打开连接,代理接受会话时会触发 OnMQTTConnect。

支持。将 MQTTVersion 设为 TwsMQTTVersion.mqtt5 即为 MQTT 5.0,设为 TwsMQTTVersion.mqtt311 即为 MQTT 3.1.1。MQTT 5.0 在每个确认上增加了原因码,并增加了连接和发布属性、用户属性和增强身份验证。

调用 Publish(topic, text, TmqttQoS.mtqsAtLeastOnce) 或 TmqttQoS.mtqsExactlyOnce,也可以选择带上保留标志。当代码必须知道代理已处理消息时,请使用 PublishAndWait:如果在超时时间内没有收到响应,它会返回 false。

可以。在 TsgcWebSocketClient 上设置 Port = 8883 和 TLS = true,在 TLSOptions.Version 中选择版本(最高 TLS 1.3),如果代理要求客户端证书,则添加 TLSOptions.CertFile 和 KeyFile。

可以,这是传输层的默认设置。保持 Specifications.RFC6455 开启,将 Options.Parameters 设为代理的 WebSocket 路径(例如 /mqtt),并在端口 443 上使用 TLS = true 以支持 wss://。这样 MQTT 就能通过只允许 HTTPS 的防火墙。

.NET Framework 2.0 到 4.8.1、.NET Core 1.0 到 3.1、.NET 5 到 .NET 10,以及 .NET Standard 1.6 和 2.0,支持 Windows、Linux 和 macOS。请从 nuget.org 安装 esegece.sgcWebSockets 或免费的 esegece.sgcWebSockets.Community 包。

有。Community 版本包含 MQTT 客户端,对小型团队(收入低于 100 万欧元,最多 5 名开发者)的商业和非商业用途免费,带有启动提示。规模更大的组织可购买 Professional(每位开发者 €149 起)或 Enterprise。

更多 sgcWebSockets .NET 内容

C# WebSocket 库

承载 MQTT 流量的 WebSocket 客户端和服务器,支持 TLS、压缩和自动重连。

.NET 功能对比表

各 .NET 版本中的每个组件和协议,包括 MQTT、AMQP、STOMP、AWS IoT 和 Azure IoT。

下载

Community 版本、NuGet 包和已编译的 .NET 演示,其中包括 MQTT Client 和 MQTT Console。

也适用于 Delphi 和 C++Builder

同样的 MQTT 客户端也适用于 Delphi 和 C++Builder,类和事件相同,同为 TsgcWSPClient_MQTT。

超值之选:All-AccesseSeGeCe 全部产品,含高级支持,每年 €1,059 起。
查看 All-Access 价格

今天就从 C# 发布你的第一条 MQTT 消息

下载试用版,或从 NuGet 安装 esegece.sgcWebSockets.Community。Professional 每位开发者 €149 起。