Hyz.MqttClient 1.0.0

Hyz.MqttClient

基于 Roslyn 源码生成器的 MQTT 客户端库，编译时自动生成订阅代码，零运行时反射。

安装

dotnet add package Hyz.MqttClient

快速开始

1. 注册服务

using Hyz.MqttClient.Extensions;

builder.Services.AddHyzMqttClientConfig(options =>
{
    options.Server = "localhost";
    options.Port = 1883;
    options.ClientId = "MyMqttClient";
});
builder.Services.AddHyzMqttClient();
builder.Services.AddHyzMqttServices();

2. 定义消息处理器

using Hyz.MqttClient.Core.Attributes;

public class MqttHandlers
{
    // 处理字符串消息
    [MqttSubscribe("topic/string")]
    public async Task HandleStringMessage(string payload)
    {
        Console.WriteLine($"收到: {payload}");
    }

    // 处理强类型消息（自动反序列化）
    [MqttSubscribe("topic/json", MessageType = typeof(MyMessage))]
    public async Task HandleJsonMessage(MyMessage message)
    {
        Console.WriteLine($"收到: {message.Content}");
    }
}

public class MyMessage
{
    public string Content { get; set; }
}

3. 连接并订阅

var mqttClient = sp.GetRequiredService<IMqttClientHelper>();
await mqttClient.ConnectFromConfigAsync();
await sp.StartAllHyzMqttSubscriptions();

// 发布消息
await mqttClient.PublishAsync("topic/string", "Hello MQTT!");

核心特性

特性详解

MqttSubscribeAttribute

[MqttSubscribe(
    topic: "device/+/data",      // 必填：订阅主题
    qos: MqttQoS.AtLeastOnce,    // QoS 等级，默认 AtMostOnce
    connectionName: "server1",   // 连接名称，默认使用默认连接
    messageType: typeof(MyMessage),  // 消息类型，用于自动反序列化
    enableAutoDeserialization: true  // 是否启用自动反序列化
)]
public async Task HandleMessage(MyMessage message) { }

方法参数类型：

QoS 等级

public enum MqttQoS
{
    AtMostOnce = 0,   // 最多一次
    AtLeastOnce = 1,  // 至少一次
    ExactlyOnce = 2   // 恰好一次
}

完整示例

基本发布/订阅

using Hyz.MqttClient.Core.Attributes;
using Hyz.MqttClient.Extensions;
using MQTTnet.Protocol;

var builder = WebApplication.CreateBuilder(args);

// 注册
builder.Services.AddHyzMqttClientConfig(options =>
{
    options.Server = "localhost";
    options.Port = 1883;
});
builder.Services.AddHyzMqttClient();
builder.Services.AddHyzMqttServices();

var app = builder.Build();

// 连接并订阅
var mqttClient = app.Services.GetRequiredService<IMqttClientHelper>();
await mqttClient.ConnectFromConfigAsync();
await app.Services.StartAllHyzMqttSubscriptions();

// 发布
await mqttClient.PublishAsync("topic/test", "Hello!", MqttQualityOfServiceLevel.AtMostOnce);

app.Run();

// 处理器
public class MyHandler
{
    [MqttSubscribe("topic/test")]
    public async Task Handle(string payload)
    {
        Console.WriteLine(payload);
    }
}

强类型消息

public class SensorData
{
    public string DeviceId { get; set; }
    public double Temperature { get; set; }
}

public class SensorHandler
{
    [MqttSubscribe("sensor/+/data", MessageType = typeof(SensorData))]
    public async Task Handle(SensorData data)
    {
        Console.WriteLine($"设备 {data.DeviceId}: {data.Temperature}°C");
    }
}

// 发布时需要传递 JSON 字符串
var json = JsonSerializer.Serialize(new SensorData { DeviceId = "001", Temperature = 25.5 });
await mqttClient.PublishAsync("sensor/001/data", json);

多连接

// 注册多个连接
builder.Services.AddHyzMqttClientConfig("server1", options =>
{
    options.Server = "mqtt1.example.com";
});
builder.Services.AddHyzMqttClientConfig("server2", options =>
{
    options.Server = "mqtt2.example.com";
});
builder.Services.AddHyzMqttClient();

// 处理器指定连接
public class MultiHandler
{
    [MqttSubscribe("topic/a", ConnectionName = "server1")]
    public async Task HandleA(string payload) { }

    [MqttSubscribe("topic/b", ConnectionName = "server2")]
    public async Task HandleB(string payload) { }
}

// 发布到指定连接
mqttClient.Use("server1").PublishAsync("topic/a", "message");

WebSocket 连接

builder.Services.AddHyzMqttClientConfig(options =>
{
    options.WebSocketUrl = "wss://mqtt.example.com/mqtt";
});

MQTT 5.0 用户属性

var properties = new List<MqttUserProperty>
{
    new("correlation-id", Guid.NewGuid().ToString())
};

await mqttClient.PublishAsync(
    "topic/data",
    jsonPayload,
    MqttQualityOfServiceLevel.AtLeastOnce,
    retain: false,
    properties);

MqttConfig 配置

IMqttClientHelper 主要方法

属性： IsConnected、IsReconnecting、ClientId

事件： MessageReceived、ConnectionStateChanged

依赖项

许可证

MIT