MqttControllerFramework 1.0.0

MqttControllerFramework

An ASP.NET Core–style source-generated MQTT controller framework for .NET, built on top of MQTTnet 5. Define topic handlers with attributes; the compile-time source generator handles routing, dispatch, and DI wiring — zero reflection at runtime.

Features

Installation

dotnet add package MqttControllerFramework

Or add directly to your project file:

<PackageReference Include="MqttControllerFramework" Version="1.0.0" />

Quick Start

1. Register the broker

// Program.cs
builder.Services
    .AddMqttServer(builder.Configuration.GetSection("MqttSettings"))
    .WithControllers<GeneratedMqttControllerRegistration>()
    .WithAuthentication<MyAuthProvider>();

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

2. Configure

// appsettings.json
{
  "MqttSettings": {
    "EnableNonSsl": true,
    "NonSslPort": 1883
  }
}

3. Write a controller

using MqttControllerFramework.Attributes;

[MqttController]
public class SensorsController
{
    [MqttTopic("sensors/+/temperature")]
    public async Task OnTemperature(
        [FromMqttTopic(1)] string deviceId,
        TemperaturePayload payload,
        CancellationToken ct)
    {
        Console.WriteLine($"Device {deviceId}: {payload.Value}°C");
    }
}

public record TemperaturePayload(double Value, string Unit);

4. Implement authentication

public class MyAuthProvider : IMqttAuthenticationProvider
{
    public ValueTask<MqttAuthenticationResult> AuthenticateAsync(
        string username, string password, CancellationToken ct)
    {
        var ok = username == "device" && password == "secret";
        return ValueTask.FromResult(
            ok ? MqttAuthenticationResult.Authenticated()
               : MqttAuthenticationResult.Failed("Invalid credentials"));
    }
}

The source generator produces GeneratedMqttControllerRegistration in the <YourAssembly>.Mqtt.Generated namespace at build time. Add a using for that namespace, or use a global using, to reference the class.

Full Builder API

builder.Services
    .AddMqttServer(configuration)            // registers the broker, reads MqttSettings section
    .WithControllers<TRegistration>()        // source-generated registration class
    .WithAuthentication<TProvider>()         // IMqttAuthenticationProvider (required)
    .WithAuthorization<TProvider>()          // IMqttAuthorizationProvider (optional)
    .WithConnectionValidator<TValidator>()   // IMqttConnectionValidator — pre-auth hook
    .WithNetworkTracker<TTracker>()          // replace built-in in-memory tracker
    .WithRetainStorage<TStorage>()           // IRetainStorage — custom retain message backend
    .UseMiddleware<TMiddleware>()            // IMqttMiddleware (ordered, chainable)
    .WithRateLimiting()                      // enable token-bucket rate limiting
    .OnClientConnected<THandler>()           // IMqttClientConnectedEvent
    .OnClientDisconnected<THandler>()        // IMqttClientDisconnectedEvent
    .OnClientSubscribedTopic<THandler>()     // IMqttClientSubscribedTopicEvent
    .OnClientUnsubscribedTopic<THandler>();  // IMqttClientUnsubscribedTopicEvent

Middleware Example (multi-tenancy)

SessionItems is populated once during connection validation and lives for the lifetime of the TCP connection — ideal for tenant, user, or role resolution:

// Connection validator — runs once per connection
public class ConnectionValidator : IMqttConnectionValidator
{
    public async ValueTask<MqttConnectionValidationResult> ValidateAsync(
        ValidatingConnectionEventArgs ctx, CancellationToken ct)
    {
        ctx.SessionItems["tenantId"] = await ResolveTenantAsync(ctx.UserName);
        return MqttConnectionValidationResult.Accept();
    }
}

// Middleware — runs for every message
public class TenantMiddleware(ITenantContext tenant) : IMqttMiddleware
{
    public Task InvokeAsync(MqttMessageContext ctx, MqttRequestDelegate next)
    {
        if (ctx.SessionItems["tenantId"] is string tid)
            tenant.SetTenant(tid);
        return next(ctx);
    }
}

Register both:

builder.Services
    .AddMqttServer(configuration)
    .WithControllers<GeneratedMqttControllerRegistration>()
    .WithConnectionValidator<ConnectionValidator>()
    .UseMiddleware<TenantMiddleware>()
    .WithAuthentication<MyAuthProvider>();

Rate Limiting

[MqttController]
public class TelemetryController
{
    // Allow burst of 10, refill 5 tokens every 1 second, consume 1 per message
    [MqttTopic("telemetry/+/data")]
    [TokenBucketRateLimit(capacity: 10, refillRate: 5, refillIntervalMs: 1000)]
    public Task OnData([FromMqttTopic(1)] string deviceId, SensorData payload) { ... }
}

Enable rate limiting in the builder:

.WithRateLimiting()

TLS

"MqttSettings": {
  "EnableSsl": true,
  "SslPort": 8883,
  "PkcsPath": "/etc/certs/broker.pfx",
  "PkcsPassword": "changeme"
}

PEM + separate key file:

"MqttSettings": {
  "EnableSsl": true,
  "SslPort": 8883,
  "PkcsPath": "/etc/certs/broker.crt",
  "PkcsKeyPath": "/etc/certs/broker.key"
}

Documentation

License

MIT © IoT Viet Solution