MQTTnet 개요

MQTTnet은 .NET 환경에서 MQTT 프로토콜을 구현한 고성능 라이브러리입니다. MQTT v3.1.0, v3.1.1, v5.0.0을 모두 지원하며, 클라이언트와 브로커(서버) 기능을 모두 제공합니다. IoT 환경에서 센서, 액추에이터, 스마트 기기 간의 경량 통신에 적합합니다.

패키지 설치

NuGet을 통해 프로젝트에 추가합니다:

dotnet add package MQTTnet --version 4.3.6.1152

클라이언트 연결 구현

MQTT 브로커에 접속하는 기본 클라이언트 코드는 다음과 같습니다:

using MQTTnet;
using MQTTnet.Client;

var mqttFactory = new MqttFactory();
var mqttClient = mqttFactory.CreateMqttClient();

var connectionSettings = new MqttClientOptionsBuilder()
    .WithTcpServer("broker.hivemq.com", 1883)
    .WithClientId("device_" + Guid.NewGuid().ToString("N")[..8])
    .WithCleanSession(true)
    .WithKeepAlivePeriod(TimeSpan.FromSeconds(30))
    .Build();

await mqttClient.ConnectAsync(connectionSettings);

메시지 발행(Publish)

특정 토픽으로 데이터를 전송하는 예시:

var payloadData = Encoding.UTF8.GetBytes("{\"temp\":24.5,\"humidity\":60}");

var outboundMessage = new MqttApplicationMessageBuilder()
    .WithTopic("sensors/livingroom/climate")
    .WithPayload(payloadData)
    .WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtLeastOnce)
    .WithRetainFlag(false)
    .Build();

await mqttClient.PublishAsync(outboundMessage);

메시지 구독(Subscribe) 및 수신

토픽을 구독하고 들어오는 메시지를 비동기로 처리합니다:

var topicFilter = new MqttTopicFilterBuilder()
    .WithTopic("sensors/+/climate")
    .WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtMostOnce)
    .Build();

await mqttClient.SubscribeAsync(topicFilter);

mqttClient.ApplicationMessageReceivedAsync += async msgEvent =>
{
    var received = msgEvent.ApplicationMessage;
    var topic = received.Topic;
    var body = Encoding.UTF8.GetString(received.Payload);
    
    Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] {topic}: {body}");
    await Task.CompletedTask;
};

관리형 클라이언트(Managed Client)

자동 재연결과 오프라인 메시지 큐잉이 필요한 경우 MQTTnet.Extensions.ManagedClient를 사용합니다:

using MQTTnet.Extensions.ManagedClient;

var managedOptions = new ManagedMqttClientOptionsBuilder()
    .WithAutoReconnectDelay(TimeSpan.FromSeconds(5))
    .WithClientOptions(new MqttClientOptionsBuilder()
        .WithTcpServer("broker.hivemq.com")
        .Build())
    .Build();

var managedClient = new MqttFactory().CreateManagedMqttClient();
await managedClient.StartAsync(managedOptions);

// 자동 큐잉되는 발행
await managedClient.EnqueueAsync("status/heartbeat", "online");

ASP.NET Core 통합

MQTTnet.AspNetCore 패키지로 미들웨어 형태로 브로커를 호스팅할 수 있습니다:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHostedMqttServer(options =>
    options.WithDefaultEndpoint().WithDefaultEndpointPort(1883));

builder.Services.AddMqttConnectionHandler();
builder.Services.AddConnections();

var app = builder.Build();
app.UseMqttEndpoint();
app.Run();

활용 시 고려사항

• 토픽 계층 설계: building/floor/room/device/metric 형태의 계층적 구조로 관리성 확보
• QoS 레벨 선택: 실시간성이 중요한 센서 데이터는 AtMostOnce(0), 중요한 제어 명령은 ExactlyOnce(2) 활용
• TLS 적용: 민감 데이터 전송 시 WithTls() 옵션으로 암호화 채널 구성
• Will 메시지: WithWillMessage()로 비정상 연결 해제 시 타 장치에 알림 전파

관련 확장 프로젝트