ApiFeatures.Mqtt.Apis 9.4.0

dotnet add package ApiFeatures.Mqtt.Apis --version 9.4.0
                    
NuGet\Install-Package ApiFeatures.Mqtt.Apis -Version 9.4.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ApiFeatures.Mqtt.Apis" Version="9.4.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="ApiFeatures.Mqtt.Apis" Version="9.4.0" />
                    
Directory.Packages.props
<PackageReference Include="ApiFeatures.Mqtt.Apis" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add ApiFeatures.Mqtt.Apis --version 9.4.0
                    
#r "nuget: ApiFeatures.Mqtt.Apis, 9.4.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package ApiFeatures.Mqtt.Apis@9.4.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=ApiFeatures.Mqtt.Apis&version=9.4.0
                    
Install as a Cake Addin
#tool nuget:?package=ApiFeatures.Mqtt.Apis&version=9.4.0
                    
Install as a Cake Tool

ApiFeatures.Mqtt.Apis

I. Overview

ApiFeatures.Mqtt.Apis is a .NET 9 library for managing MQTT connections and processing MQTT messages with MongoDB persistence. The library provides a complete API for creating, updating, and managing MQTT broker configurations with support for custom message parsers and processors.

Key Features

  • MQTT Broker Management: Configure and manage multiple MQTT broker connections
  • HiveMQ Cloud Support: Built-in support for HiveMQ Cloud MQTT brokers
  • Event-Driven Message Processing: Process incoming MQTT messages with custom parsers and processors
  • MongoDB Persistence: Store MQTT configurations in MongoDB
  • RESTful API Endpoints: Full CRUD operations for MQTT configuration management
  • Connection Management: Start/stop MQTT connections via API
  • Custom Message Processing: Extensible message parser and processor pattern
  • FluentValidation: Built-in validation for all API requests
  • Keyed Services: Uses .NET's keyed service pattern for flexible dependency injection
  • Hosted Services: Automatic MQTT connection lifecycle management

Use Cases

  • Connect to IoT device MQTT brokers
  • Process sensor data from MQTT topics
  • Integrate with cloud MQTT services (HiveMQ, AWS IoT, Azure IoT Hub)
  • Build real-time data pipelines from MQTT sources
  • Manage multiple MQTT connections from a single application

BREAKING (v9.3.0 (Apis) / v9.1.0 (Cores/Mongo/Postgres), sprint-10) — MQTT broker route restructuring, immediate cutover, no aliases. Every broker and broker-user route moved; the old paths return 404 as of this version. There is no deprecated-alias transition window — update all callers in the same deploy as this upgrade.

Area Old route New route
Brokers list GET api/mqtt/brokers GET api/mqtt-brokers (now paginated)
Single broker CRUD GET/POST/PUT/DELETE api/mqtt/broker/{id} GET/POST/PUT/DELETE api/mqtt-broker/{id:guid}
Broker start/stop POST/DELETE api/mqtt/broker/{id}/runtime POST/DELETE api/mqtt-broker/{id:guid}/connection
Broker-users list GET api/mqtt/broker/{brokerId}/users GET api/mqtt-broker/{mqttBrokerId:guid}/users (now paginated)
Broker-user create POST api/mqtt/broker/{brokerId}/user POST api/mqtt-broker/{mqttBrokerId:guid}/user
Broker-user update/delete PUT/DELETE api/mqtt/broker/{brokerId}/user/{userId} PUT/DELETE api/mqtt-broker/{mqttBrokerId:guid}/user/{userId:guid}
Live messages (SSE + purge) GET/DELETE api/mqtt/live-messages GET/DELETE api/mqtts/live-messages

Also breaking at the code level (consumers of ApiFeatures.Mqtt.Cores directly, not just HTTP callers):

  • IBrokerService and IBrokerUserService each gained a new paginated SearchAsync / SearchByBrokerIdAsync method (additive, not breaking on its own, but any existing third-party implementation of these interfaces must now implement the new member).

IBrokerUserService's GetByIdAsync/UpdateAsync/DeleteAsync signatures, BrokerUserByIdNotFoundException's constructor, and the OnBeforeBrokerUserCreateAsyncHandler/OnBeforeBrokerUserUpdateAsyncHandler/ OnBeforeBrokerUserDeleteAsyncHandler delegate shapes are unchanged from pre-sprint-10 — the broker-user route stayed nested under its broker, so these (brokerId, id)-based contracts were never broken. The only breaking change for the broker-user family is the route path rename above.

No deprecated aliases are provided for any of the above — this is an immediate, clean cutover.

II. Installation

Step 1: Add Package Reference

Add the ApiFeatures.Mqtt.Apis package to your project:

<ItemGroup>
  <PackageReference Include="ApiFeatures.Mqtt.Apis" Version="*" />
</ItemGroup>

Step 2: Register Services

In your Program.cs, configure and register the MQTT module:

Mongo persistence moved (sprint-9, Task 4): MongoMqttDatabaseContext, MongoMqttDatabaseOptions, MongoMqttDatabaseCollectionOptions, the BSON serializer, and the DB-tied MqttService / MqttConnectionService / BrokerService / BrokerUserService implementations now live in ApiFeatures.Mqtt.MongoDatabases (src/modules/mqtt/databases/ApiFeatures.Mqtt.MongoDatabases), not in this package. Apis never references MongoDatabases (forbidden dependency) — the host composes both: AddMqttsModule(...) (this package; only needs a provider-agnostic ApiFeatures.Modules.Cores.Interfaces.IModuleDatabaseOptions to gate WithEmbeddedBrokers) and IServiceCollection.WithMongoDatabase(mongoOptions) (MongoDatabases; registers the Mongo context + services). See that project's README for the Mongo connection/collection-name configuration shape.

using ApiFeatures.Mqtt.Apis.Extensions;
using ApiFeatures.Mqtt.Apis.Models;
using ApiFeatures.Mqtt.MongoDatabases.Extensions;
using ApiFeatures.Mqtt.MongoDatabases.Models.Options;
using IotVn.CoreFeatures.Services;

var builder = WebApplication.CreateBuilder(args);

// Configure MQTT options
var options = new AddMqttsFeatureOptions();

// Required (for the Mongo-backed endpoints): build the Mongo connection options
// (ApiFeatures.Mqtt.MongoDatabases — broken-out connection components, not a single connection
// string; see that project's README). This package itself needs no database configuration call —
// Mongo is composed separately, below, via IServiceCollection.WithMongoDatabase(...).
var mongoOptions = new MongoMqttDatabaseOptions
{
    Host = "localhost",
    Port = 27017,
    DatabaseName = "mqtt_db"
};

// Required: Configure JSON tool for message parsing
options.WithJsonTool<JsonTool>();
// Or with factory:
// options.WithJsonTool(sp => new JsonTool());

// Optional: Register custom message parser
options.WithMqttMessageParser<MyMqttMessageParser>();
// Or with factory:
// options.WithMqttMessageParser(sp => new MyMqttMessageParser(sp));

// Optional: Register custom message processor
options.WithMqttMessageProcessor<MyMqttMessageProcessor>();
// Or with factory:
// options.WithMqttMessageProcessor(sp => new MyMqttMessageProcessor(sp));

// Register the module
builder.Services.AddMqttsModule(options);

// Compose the Mongo persistence layer (ApiFeatures.Mqtt.MongoDatabases) — call order relative to
// AddMqttsModule does not matter (keyed services resolve lazily from the same container).
builder.Services.WithMongoDatabase(mongoOptions);

var app = builder.Build();

// Map endpoints (optional authorization)
app.AddMqttsEndpoints(new AddMqttsEndpointsOptions
{
    AuthorizationPolicyHandler = () => new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build()
});

app.Run();

Step 3: Implement Custom Message Parser (Optional)

Create a parser to transform raw MQTT messages:

using ApiFeatures.Mqtt.Apis.Interfaces;
using ApiFeatures.Mqtt.Apis.Models;

public class MyMqttMessageParser : IMqttMessageParser
{
    private readonly ILogger<MyMqttMessageParser> _logger;

    public MyMqttMessageParser(ILogger<MyMqttMessageParser> logger)
    {
        _logger = logger;
    }

    public async Task<MqttMessage?> ParseAsync(
        MqttMessage mqttMessage, 
        string rawMessage, 
        CancellationToken cancellationToken = default)
    {
        try
        {
            _logger.LogInformation("Parsing MQTT message from topic: {Topic}", mqttMessage.Event);
            
            // Parse the raw MQTT message
            var parsedData = JsonSerializer.Deserialize<MyDataType>(rawMessage);
            
            // Create strongly-typed message
            var typedMessage = new MqttMessage<MyDataType>(
                mqttMessage.MessageId, 
                mqttMessage.Event)
            {
                Data = new[] { parsedData },
                MacAddress = parsedData.DeviceId,
                Model = parsedData.Model,
                Version = parsedData.Version
            };
            
            return typedMessage;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to parse MQTT message");
            return null;
        }
    }
}

Step 4: Implement Message Processor (Optional)

Create a processor to handle parsed MQTT messages:

using ApiFeatures.Mqtt.Apis.Interfaces;
using ApiFeatures.Mqtt.Apis.Models;

public class MyMqttMessageProcessor : IMqttMessageProcessor
{
    private readonly ILogger<MyMqttMessageProcessor> _logger;
    private readonly IMyDataService _dataService;

    public MyMqttMessageProcessor(
        ILogger<MyMqttMessageProcessor> logger,
        IMyDataService dataService)
    {
        _logger = logger;
        _dataService = dataService;
    }

    public async Task<bool> CanExecuteAsync(
        MqttContext context,
        CancellationToken cancellationToken = default)
    {
        // Self-filter on the topic and/or the parsed message. Handlers run for every received
        // message, so context.Message may be null when no parser matched the payload.
        return context.Topic.StartsWith("sensors/");
    }

    public async Task ProcessAsync(
        MqttContext context,
        CancellationToken cancellationToken = default)
    {
        _logger.LogInformation(
            "Processing MQTT message from topic {Topic} on connection {Connection}",
            context.Topic,
            context.Connection.Name);

        // context.Message is the optional parsed convenience and may be null; null-check it.
        if (context.Message is MqttMessage<MyDataType> typedMessage)
        {
            // Process the message data
            foreach (var data in typedMessage.Data ?? Array.Empty<MyDataType>())
            {
                await _dataService.ProcessDataAsync(data, cancellationToken);
            }
        }
    }
}

Migration note (topic-aware handlers): CanExecuteAsync/ProcessAsync now receive a single MqttContext instead of a bare MqttMessage. Read the parsed message via context.Message (nullable — handlers run even when no parser matched), the topic via context.Topic, the raw payload via context.RawMessage, and the originating connection's non-sensitive metadata via context.Connection.Id / .Name / .Topics. Broker credentials are never exposed on the context. Handlers are dispatched error-isolated: a handler throwing is logged and the others still run.


III. Message Processors

A message processor is the module's primary extension point for reacting to incoming MQTT traffic. Implement IMqttMessageProcessor, register it with WithMqttMessageProcessor<T>(), and the module invokes it for every message received on any subscribed topic.

The IMqttMessageProcessor contract

// namespace ApiFeatures.Mqtt.Apis.Interfaces
public interface IMqttMessageProcessor
{
    Task<bool> CanExecuteAsync(MqttContext context, CancellationToken cancellationToken = default);

    Task ProcessAsync(MqttContext context, CancellationToken cancellationToken = default);
}
  • CanExecuteAsync — a cheap self-filter. Return true to opt this processor in for the current message (filter on context.Topic, the connection, or the parsed context.Message); return false to skip. Handlers run for every received message, so context.Message may be null when no parser matched the payload.
  • ProcessAsync — the actual work. Only called when CanExecuteAsync returned true.

The MqttContext handed to a processor

Both methods receive a single MqttContext (ApiFeatures.Mqtt.Apis.Models):

public class MqttContext
{
    public string Topic { get; }                  // topic the message was published to
    public string RawMessage { get; }             // raw UTF-8 payload exactly as received
    public MqttConnectionInfo Connection { get; } // non-sensitive connection info (no credentials)
    public MqttMessage? Message { get; }          // optional parsed convenience; null if unparsed
}

public class MqttConnectionInfo
{
    public Guid Id { get; }                       // the MqttEntity.Id created via POST api/mqtt
    public string Name { get; }
    public IReadOnlyList<string> Topics { get; }
}

Broker credentials (Options, username/password) are deliberately never exposed on the context.

How and when processors run

Processors are dispatched by MqttMessageService.ExecuteAsync(MqttEntity mqtt, string topic, string rawMessage, CancellationToken), which HiveMqService calls for each raw message off the broker:

  1. Whitespace guard — empty / whitespace-only payloads are skipped (nothing is dispatched).
  2. Best-effort parse — registered parsers run; the first non-null result becomes context.Message. Parsing does not gate dispatch: if nothing parses, context.Message is null and handlers still run.
  3. Context build — a MqttContext is built from the trusted entity, copying only the non-sensitive Id / Name / Topics into MqttConnectionInfo (credentials dropped).
  4. Dispatch — for every registered processor, CanExecuteAsync is awaited; if true, ProcessAsync is awaited. Dispatch is error-isolated: a handler that throws is logged and the remaining handlers still run, so one faulty processor never crashes the host or blocks the others.

Registering a processor

Register with the fluent AddMqttsFeatureOptions before AddMqttsModule(...):

var options = new AddMqttsFeatureOptions()
    .WithJsonTool<JsonTool>()
    .WithMqttMessageProcessor<MyProcessor>();   // generic form (type resolved from DI)

builder.Services.AddMqttsModule(options);

Both overloads exist (each registers the processor as Scoped, keyed ServiceKeys.Default):

// Generic: T : class, IMqttMessageProcessor — constructor dependencies resolved from DI
options.WithMqttMessageProcessor<MyProcessor>();

// Factory: build the instance yourself
options.WithMqttMessageProcessor(sp =>
    new MyProcessor(sp.GetRequiredService<ILogger<MyProcessor>>()));

Call it multiple times to register a pipeline — every processor whose CanExecuteAsync returns true is invoked (see Multiple Message Processors).

Example: a processor that logs the topic and raw message

A minimal processor that opts in for every message and logs the topic plus the raw payload. This mirrors the demo host's LoggingMqttMessageProcessor (src/apps/ApiFeatures.Applications.Mqtt/Services/), which the host wires up with .WithMqttMessageProcessor<LoggingMqttMessageProcessor>() in Program.cs:

using ApiFeatures.Mqtt.Apis.Interfaces;
using ApiFeatures.Mqtt.Apis.Models;
using Microsoft.Extensions.Logging;

public class LoggingMqttMessageProcessor : IMqttMessageProcessor
{
    private readonly ILogger<LoggingMqttMessageProcessor> _logger;

    public LoggingMqttMessageProcessor(ILogger<LoggingMqttMessageProcessor> logger)
    {
        _logger = logger;
    }

    // Opt in for every received message.
    public Task<bool> CanExecuteAsync(
        MqttContext context,
        CancellationToken cancellationToken = default)
    {
        return Task.FromResult(true);
    }

    // Log the topic, the originating connection, and the raw payload.
    public Task ProcessAsync(
        MqttContext context,
        CancellationToken cancellationToken = default)
    {
        _logger.LogInformation(
            "MQTT message on [{Connection}/{Topic}]: {RawMessage}",
            context.Connection.Name,
            context.Topic,
            context.RawMessage);

        return Task.CompletedTask;
    }
}

Register it:

options.WithMqttMessageProcessor<LoggingMqttMessageProcessor>();

The real demo LoggingMqttMessageProcessor self-filters to typed measurement messages (context.Message is MqttMessage<MeasurementMqttPayload>) and logs each metric; the snippet above is the simplest topic-and-payload variant. For a processor that captures every processed message and streams it to the browser, see WithLiveMessageStream.


IV. Configuration Options

AddMqttsFeatureOptions Methods

Composing the Mongo persistence layer (WithMongoDatabase(...)) [REQUIRED for WithEmbeddedBrokers and the Mongo-backed endpoints]

This package (AddMqttsModule/AddMqttsFeatureOptions) has no database configuration method — it depends only on the ApiFeatures.Mqtt.Cores contracts and registers no Mongo type. The database layer is a separate composition step the host performs directly on IServiceCollection, via ApiFeatures.Mqtt.MongoDatabases's WithMongoDatabase(mongoOptions) extension (see that project's README for MongoMqttDatabaseOptions, its broken-out connection components, and the per-collection name overrides). Call it alongside (order does not matter — all cross-layer registrations resolve lazily) builder.Services.AddMqttsModule(options).

Example:

using ApiFeatures.Mqtt.MongoDatabases.Extensions;
using ApiFeatures.Mqtt.MongoDatabases.Models.Options;

var mongoOptions = new MongoMqttDatabaseOptions
{
    Host = "localhost",
    Port = 27017,
    DatabaseName = "mqtt_db",
    Collections = new MongoMqttDatabaseCollectionOptions
    {
        Mqtts = "CustomMqttsCollection", // Default: "Mqtts"
        MqttConnections = "CustomConnectionsCollection", // Default: "MqttConnections"
        Brokers = "CustomBrokersCollection", // Default: "Brokers"
        BrokerUsers = "CustomBrokerUsersCollection" // Default: "BrokerUsers" (per-broker client credentials)
    }
};

builder.Services.AddMqttsModule(options);
builder.Services.WithMongoDatabase(mongoOptions);

WithJsonTool<T>() or WithJsonTool(Func<IServiceProvider, IJsonTool>) [REQUIRED]

Registers the JSON serialization tool for MQTT message parsing.

Generic version:

options.WithJsonTool<JsonTool>();

Factory version:

options.WithJsonTool(sp => new JsonTool());
// Or custom implementation:
options.WithJsonTool(sp => new CustomJsonTool());

Parameters:

  • T: Type that implements IJsonTool
  • factory: Factory function that returns an IJsonTool instance

Lifetime: Singleton (keyed with ServiceKeys.Default)


WithMqttMessageParser<T>() or WithMqttMessageParser(Func<IServiceProvider, IMqttMessageParser>) [OPTIONAL]

Registers custom MQTT message parsers for transforming raw messages.

Generic version:

options.WithMqttMessageParser<MyMqttMessageParser>();

Factory version:

options.WithMqttMessageParser(sp => new MyMqttMessageParser(
    sp.GetRequiredService<ILogger<MyMqttMessageParser>>()
));

Parser Interface:

public interface IMqttMessageParser
{
    Task<MqttMessage?> ParseAsync(
        MqttMessage mqttMessage, 
        string rawMessage, 
        CancellationToken cancellationToken = default);
}

When Used:

  • Called when a new MQTT message arrives from subscribed topics
  • Transforms raw string payload into strongly-typed MqttMessage objects

Parameters:

  • T: Type that implements IMqttMessageParser
  • factory: Factory function that returns an IMqttMessageParser instance

Lifetime: Singleton (keyed with ServiceKeys.Default)

Note: Multiple message parsers can be registered by calling this method multiple times.


WithMqttMessageProcessor<T>() or WithMqttMessageProcessor(Func<IServiceProvider, IMqttMessageProcessor>) [OPTIONAL]

Registers custom MQTT message processors for handling parsed messages.

Generic version:

options.WithMqttMessageProcessor<MyMqttMessageProcessor>();

Factory version:

options.WithMqttMessageProcessor(sp => new MyMqttMessageProcessor(
    sp.GetRequiredService<ILogger<MyMqttMessageProcessor>>(),
    sp.GetRequiredService<IMyDataService>()
));

Processor Interface:

public interface IMqttMessageProcessor
{
    Task<bool> CanExecuteAsync(MqttContext context, CancellationToken cancellationToken = default);
    Task ProcessAsync(MqttContext context, CancellationToken cancellationToken = default);
}

The MqttContext handed to handlers:

public class MqttContext
{
    public string Topic { get; }                 // topic the message was published to
    public string RawMessage { get; }            // raw payload exactly as received
    public MqttConnectionInfo Connection { get; }// non-sensitive connection info (no credentials)
    public MqttMessage? Message { get; }         // optional parsed convenience (nullable)
}

public class MqttConnectionInfo
{
    public Guid Id { get; }                      // the MqttEntity.Id created via POST api/mqtt
    public string Name { get; }
    public IReadOnlyList<string> Topics { get; }
}

When Used:

  • Called for every received (non-whitespace) message — parsing no longer gates delivery, so handlers also see messages no parser understood (context.Message is then null).
  • Checks CanExecuteAsync first (handlers self-filter on topic and/or the parsed message).
  • If true, calls ProcessAsync to handle the message.
  • Dispatch is error-isolated: if a handler throws, the error is logged and the remaining handlers still run; the host is not crashed.

Parameters:

  • T: Type that implements IMqttMessageProcessor
  • factory: Factory function that returns an IMqttMessageProcessor instance

Lifetime: Scoped (keyed with ServiceKeys.Default)

Note: Multiple message processors can be registered. All processors with CanExecuteAsync returning true will be invoked.


WithLiveMessageStream(Action<MqttLiveFeedOptions>? configure = null) [OPTIONAL]

Enables the live-message SSE feed: a dedicated capturing processor records every processed message (topic, originating configuration id/name, timestamp, raw payload, parsed result if any) into a bounded in-memory ring buffer and streams it to browser clients over GET /api/mqtt/live-messages (Server-Sent Events). The feature is off by default and purely additive — hosts that never call this method get no new services and no new route, so existing behaviour is unchanged.

The capturing processor runs inside the existing per-processor error isolation, so a capture failure is logged and never blocks or crashes the processing pipeline. Enqueue to the broadcast channel is non-blocking, so a slow or absent client never stalls message processing.

// Defaults (ring buffer of the 100 most-recent messages, replayed to new subscribers on connect):
options.WithLiveMessageStream();

// Or bind the buffer size from configuration:
var bufferSize = builder.Configuration.GetValue<int?>("Mqtt:LiveFeed:BufferSize") ?? 100;
options.WithLiveMessageStream(o => o.BufferSize = bufferSize);

Prerequisite: the host must register IDateTimeContext keyed ServiceKeys.Default (used to timestamp captured messages per the time-with-DI convention), e.g.:

builder.Services.AddKeyedScoped<IDateTimeContext, DateTimeContext>("ApiFeatures.Mqtt.Apis");

Configuration keys:

Key path Purpose Required Default Example
Mqtt:LiveFeed:BufferSize Max number of most-recent messages kept in the in-memory ring buffer and replayed to new SSE subscribers. Values below 1 are clamped to 1. No 100 200

appsettings.json example:

{
  "Mqtt": {
    "LiveFeed": {
      "BufferSize": 100
    }
  }
}

Lifetimes registered by this call: MqttLiveFeedOptions (singleton; its presence also gates the SSE route), the broadcast Channel<ProcessedMqttMessage> (singleton), IMqttLiveFeedPublisher (scoped), IMqttLiveFeedSessionManager (singleton), MqttLiveFeedBroadcastHostedService (hosted/singleton), and the capturing IMqttMessageProcessor (scoped, keyed ServiceKeys.Default).


WithEmbeddedBrokers(Action<BrokerHostingOptions>? configure = null) [OPTIONAL]

Enables the multi-broker runtime: registers the keyed-singleton IBrokerRuntimeManager, which hosts one real in-process MQTTnet server per stored broker definition (loopback, plain TCP, anonymous, in-memory), each on its own port, with per-broker start/stop and a visible running / stopped / failed(+reason) status. It also opens the broker runtime-control routes (POST/DELETE /api/mqtt/broker/{id}/runtime). The feature is off by default and purely additive — hosts that never call this method get no manager and no broker routes.

Prerequisite: the host must also compose the Mongo persistence layer via IServiceCollection.WithMongoDatabase(...) (ApiFeatures.Mqtt.MongoDatabases) — brokers are persisted in MongoDB; the manager reads their port/bind from the stored definitions. This package registers the broker runtime unconditionally on WithEmbeddedBrokers() (it no longer tracks DB state); if the host enables it without composing Mongo, the runtime's data dependencies (IBrokerService/ IBrokerUserService) fail to resolve at request time instead of at startup.

// Defaults (loopback bind, allowed-port range 1024-65535):
options.WithEmbeddedBrokers();

// Or bind the bind-address default from configuration and set a custom allowed-port set in code:
options.WithEmbeddedBrokers(o =>
{
    o.DefaultBindAddress = builder.Configuration["Mqtt:BrokerHosting:DefaultBindAddress"] ?? "127.0.0.1";
    o.Ports = new List<IBrokerPort> { new BrokerPortRange(5000, 5999) };
});

BREAKING CHANGE: the flat MinPort/MaxPort properties no longer exist. The allowed-port set is now expressed as BrokerHostingOptions.Ports — a collection of IBrokerPort (BrokerPortRange and/or BrokerPortCollection), set in code, not bound from appsettings. Leaving Ports untouched keeps a single default BrokerPortRange(1024, 65535). Setting Ports to an empty collection, or to a range with Min > Max or bounds outside 1-65535, throws InvalidOperationException at startup (inside WithEmbeddedBrokers, before the host finishes building) — fail-fast instead of a request-time surprise.

Configuration keys:

Key path Purpose Required Default Example
Mqtt:BrokerHosting:DefaultBindAddress Loopback address new brokers default to (never bound to all interfaces). No 127.0.0.1 127.0.0.1

appsettings.json example:

{
  "Mqtt": {
    "BrokerHosting": {
      "DefaultBindAddress": "127.0.0.1"
    }
  }
}

The host application wires Program.cs to read DefaultBindAddress and pass it into WithEmbeddedBrokers, and commits the example value into its own appsettings.json (done in the auto-run task). A custom allowed-port set is set in code via options.Ports — there is no JSON-bindable shape for it. The manager itself is a singleton (it owns long-lived MqttServer instances); BrokerHostingOptions registered by this call is the self-gate marker that gates the manager registration and the broker routes.

Lifetimes registered by this call: BrokerHostingOptions (singleton; marker that gates the broker surface) and IBrokerRuntimeManager → BrokerRuntimeManager (singleton, keyed ServiceKeys.Default).


V. API Endpoints

MQTT Configuration Management

GET /api/mqtts

Get all MQTT configurations.

Response:

[
  {
    "id": "018d1234-5678-7abc-def0-123456789abc",
    "name": "IoT Sensors HiveMQ",
    "description": "MQTT connection for IoT sensor data",
    "topics": [
      "sensors/temperature",
      "sensors/humidity"
    ],
    "options": {
      "type": "CloudHiveMq",
      "hostname": "abc123.s1.eu.hivemq.cloud",
      "port": 8883,
      "clientId": "iot-gateway-001",
      "username": "mqtt_user",
      "password": "***"
    },
    "createdTime": "2024-01-15T10:30:00Z",
    "updatedTime": "2024-01-20T14:45:00Z"
  }
]

GET /api/mqtt/{id}

Get a specific MQTT configuration by ID.

Path Parameters:

  • id (Guid, required): MQTT configuration ID

Response:

{
  "id": "018d1234-5678-7abc-def0-123456789abc",
  "name": "IoT Sensors HiveMQ",
  "description": "MQTT connection for IoT sensor data",
  "topics": [
    "sensors/temperature",
    "sensors/humidity"
  ],
  "options": {
    "type": "CloudHiveMq",
    "hostname": "abc123.s1.eu.hivemq.cloud",
    "port": 8883,
    "clientId": "iot-gateway-001",
    "username": "mqtt_user",
    "password": "***"
  },
  "createdTime": "2024-01-15T10:30:00Z"
}

POST /api/mqtt

Create a new MQTT configuration.

Request Body:

{
  "name": "IoT Sensors HiveMQ",
  "description": "MQTT connection for IoT sensor data",
  "topics": [
    "sensors/temperature",
    "sensors/humidity"
  ],
  "options": {
    "hostname": "abc123.s1.eu.hivemq.cloud",
    "port": 8883,
    "clientId": "iot-gateway-001",
    "username": "mqtt_user",
    "password": "secure_password_here"
  }
}

Response:

{
  "id": "018d1234-5678-7abc-def0-123456789abc",
  "name": "IoT Sensors HiveMQ",
  "description": "MQTT connection for IoT sensor data",
  "topics": [
    "sensors/temperature",
    "sensors/humidity"
  ],
  "options": {
    "type": "CloudHiveMq",
    "hostname": "abc123.s1.eu.hivemq.cloud",
    "port": 8883,
    "clientId": "iot-gateway-001",
    "username": "mqtt_user",
    "password": "***"
  },
  "createdTime": "2024-01-15T10:30:00Z"
}

PUT /api/mqtt/{id}

Update an existing MQTT configuration.

Path Parameters:

  • id (Guid, required): MQTT configuration ID

Request Body (all fields optional):

{
  "name": "Updated MQTT Name",
  "description": "Updated description",
  "topics": [
    "sensors/all"
  ],
  "hostname": "new-broker.hivemq.cloud",
  "port": 8883,
  "clientId": "new-client-id",
  "username": "new_user",
  "password": "new_password"
}

Response:

{
  "id": "018d1234-5678-7abc-def0-123456789abc",
  "name": "Updated MQTT Name",
  "description": "Updated description",
  "topics": [
    "sensors/all"
  ],
  "options": {
    "type": "CloudHiveMq",
    "hostname": "new-broker.hivemq.cloud",
    "port": 8883,
    "clientId": "new-client-id",
    "username": "new_user",
    "password": "***"
  },
  "createdTime": "2024-01-15T10:30:00Z",
  "updatedTime": "2024-01-20T15:00:00Z"
}

Note: Only send the fields you want to update. Null/missing fields won't be updated.


DELETE /api/mqtt/{id}

Delete an MQTT configuration.

Path Parameters:

  • id (Guid, required): MQTT configuration ID

Response: 204 No Content


POST /api/mqtt/{id}/connection

Start an MQTT connection (connect to the broker and subscribe to topics).

Path Parameters:

  • id (Guid, required): MQTT configuration ID

Response: 200 OK

Effects:

  • Connects to the MQTT broker specified in the configuration
  • Subscribes to all configured topics
  • Updates connection status to "Connected" in the database

DELETE /api/mqtt/{id}/connection

Stop an MQTT connection (disconnect from the broker).

Path Parameters:

  • id (Guid, required): MQTT configuration ID

Response: 200 OK

Effects:

  • Disconnects from the MQTT broker
  • Unsubscribes from all topics
  • Updates connection status to "Disconnected" in the database

Live Message Stream (Server-Sent Events)

GET /api/mqtt/live-messages

Stream processed MQTT messages to a browser as Server-Sent Events. Only mapped when the host enabled the feature via WithLiveMessageStream (see section IV). On connect the client first receives an event: connected frame, then the buffered recent-N messages, then each subsequent live message as an event: mqtt-message frame; : keep-alive comments are sent every 30 seconds.

Request: none (no body, no query — global feed).

Response: 200 OK, Content-Type: text/event-stream.

event: connected
data: {"message":"Connected to MQTT live message stream"}

event: mqtt-message
data: {"id":"018d...","configurationId":"018d...","configurationName":"IoT Sensors HiveMQ","topic":"sensors/temperature","receivedAtUtc":"2026-10-16T10:30:00Z","rawPayload":"{...}","parsed":true,"parsedMessage":{...}}

: keep-alive

On an unexpected failure an event: error frame is emitted and the connection closes. Surfaced messages carry no broker credentials (built from MqttContext, which excludes Options).


Broker Runtime Control

Only mapped when the host enabled the feature via WithEmbeddedBrokers (see section IV). Start/stop a stored broker's in-process listener; both are idempotent.

POST /api/mqtt/broker/{id}/runtime

Start the broker's listener. Resolves the stored broker definition, then starts it on its loopback port.

Response: 200 OK + BrokerRuntimeStatusResponseDto (running).

{ "brokerId": "018d...", "status": "Running", "isRunning": true, "failureReason": null, "endpoint": "127.0.0.1:1884" }

Errors: 404 Not Found (MQTT_BROKER__NOT_FOUND) when the broker id does not exist; 409 Conflict (MQTT_BROKER__START_FAILED) when the listener cannot bind (e.g. the port is in use). The manager records the broker's status as Failed so a subsequent read is truthful.

DELETE /api/mqtt/broker/{id}/runtime

Stop the broker's listener and release its port.

Response: 200 OK + BrokerRuntimeStatusResponseDto (stopped). Errors: 404 Not Found when the broker id does not exist.


VI. Advanced Configuration

Multiple Message Parsers

You can register multiple message parsers to handle different message formats:

options
    .WithMqttMessageParser<SensorDataParser>()
    .WithMqttMessageParser<DeviceStatusParser>()
    .WithMqttMessageParser<AlertMessageParser>();

The MQTT message service will try each parser in order until one successfully parses the message.

Multiple Message Processors

You can register multiple message processors for different processing pipelines:

options
    .WithMqttMessageProcessor<LoggingProcessor>()        // First: Log all messages
    .WithMqttMessageProcessor<ValidationProcessor>()     // Second: Validate data
    .WithMqttMessageProcessor<DataStorageProcessor>()    // Third: Store in database
    .WithMqttMessageProcessor<AlertingProcessor>();      // Fourth: Send alerts

All processors with CanExecuteAsync returning true will process each message.

Connection Lifecycle

The MQTT module includes hosted services that automatically manage connection lifecycles:

  • MqttHostedService: Manages the overall MQTT service lifecycle
  • MqttConnectionHostedService: Monitors and maintains active MQTT connections

VII. Configuration File Example

appsettings.json

{
  "Mqtt": {
    "MongoDatabase": {
      "Host": "localhost",
      "Port": 27017,
      "DatabaseName": "mqtt_db"
    }
  },
  "Logging": {
    "LogLevel": {
      "ApiFeatures.Mqtt.Apis": "Debug"
    }
  }
}

Host/Port/DatabaseName (plus optional Username/Password/AuthenticationDatabase/ ReplicaSet/UseTls/Collections) replace the former single ConnectionString key — see ApiFeatures.Mqtt.MongoDatabases's README for the full key list and client-settings notes. Note: AuthenticationDatabase now defaults to admin (DataMagic default), no longer to DatabaseName.

Program.cs with Configuration Binding

using ApiFeatures.Mqtt.MongoDatabases.Models.Options;

var mongoOptions = builder.Configuration
    .GetSection("Mqtt:MongoDatabase")
    .Get<MongoMqttDatabaseOptions>()!;

builder.Services.AddMqttsModule(options);
builder.Services.WithMongoDatabase(mongoOptions);

VIII. Dependencies

Required Packages

  • MongoDB.Driver (3.5.1+)
  • MQTTnet (4.3.7+)
  • FluentValidation (12.1.1+)
  • Newtonsoft.Json (13.0.4+)
  • IotVn.CoreFeatures (9.1.0+)
  • ApiFeatures.Modules.Cores (9.0.1+)
  • BusinessFeatures.Cores (latest)

Framework

  • .NET 9.0

IX. Features

Automatic Connection Management

  • Auto-start on demand: Start MQTT connections via API endpoints
  • Auto-reconnect: Automatic reconnection on connection loss
  • Graceful shutdown: Proper cleanup when stopping connections

Thread-Safe Operations

  • All MQTT operations are thread-safe
  • Concurrent message processing is handled safely

GUID Serialization

  • Uses GuidRepresentation.CSharpLegacy for MongoDB compatibility
  • Automatically configures GUID serialization on database context initialization

Validation

All API endpoints use FluentValidation:

  • MQTT configuration validation
  • Unique MQTT configuration names
  • Required fields validation
  • Connection parameter validation

Security

  • Passwords are masked in API responses (displayed as ***)
  • Secure TLS connections to MQTT brokers
  • Username/password authentication support

X. Error Handling

Common Exceptions

Exception When Thrown
MqttByIdNotFoundException MQTT configuration with specified ID not found
ValidationException Request validation failed
MqttConnectionException Failed to connect to MQTT broker

XI. Service Keys

The module uses keyed services for dependency injection. MongoMqttDatabaseContext, IMqttService, IMqttConnectionService, IBrokerService, and IBrokerUserService are registered by ApiFeatures.Mqtt.MongoDatabases's WithMongoDatabase(...) (not by AddMqttsModule — see that project's README), but listed here too since this package's endpoints resolve them:

Service Key Lifetime Registered by
IValidator<*> ServiceKeys.Default Scoped AddMqttsModule
IJsonTool ServiceKeys.Default Singleton AddMqttsModule (via WithJsonTool)
IBrokerUserPasswordHasher ServiceKeys.Default Singleton AddMqttsModule
MongoMqttDatabaseContext ServiceKeys.Default Scoped WithMongoDatabase (MongoDatabases)
IMqttService ServiceKeys.Default Scoped WithMongoDatabase (MongoDatabases)
IMqttConnectionService ServiceKeys.Default Scoped WithMongoDatabase (MongoDatabases)
IBrokerService ServiceKeys.Default Scoped WithMongoDatabase (MongoDatabases)
IBrokerUserService ServiceKeys.Default Scoped WithMongoDatabase (MongoDatabases)
IHiveMqService ServiceKeys.Default Singleton AddMqttsModule
IMqttMessageParser ServiceKeys.Default Singleton AddMqttsModule
IMqttMessageProcessor ServiceKeys.Default Scoped

ServiceKeys Values:

  • ServiceKeys.Default = "ApiFeatures.Mqtt.Apis"

XII. Message Flow

Incoming MQTT Message Processing

  1. Message Received: MQTT client receives message from subscribed topic
  2. Message Parsing: Each registered parser attempts to parse the raw message
  3. Message Processing: All processors with CanExecuteAsync returning true process the message
  4. Error Handling: Errors are logged but don't stop other processors
MQTT Broker 
    ↓
HiveMqService (receives raw message)
    ↓
MqttMessageService
    ↓
┌─────────────────────────┐
│ Message Parsers         │
│ (try in order)          │
│  - SensorDataParser     │
│  - DeviceStatusParser   │
│  - AlertMessageParser   │
└─────────────────────────┘
    ↓
┌─────────────────────────┐
│ Message Processors      │
│ (all with CanExecute)   │
│  - LoggingProcessor     │
│  - ValidationProcessor  │
│  - DataStorageProcessor │
│  - AlertingProcessor    │
└─────────────────────────┘

XIII. Best Practices

1. Parser Design

  • Keep parsers focused on a single message format
  • Return null if the parser can't handle the message
  • Log parsing errors for debugging
  • Use strongly-typed MqttMessage<T> for parsed messages

2. Processor Design

  • Implement CanExecuteAsync to filter messages efficiently
  • Keep processors independent and stateless when possible
  • Handle exceptions gracefully
  • Log processing activities for monitoring

3. Connection Management

  • Use descriptive names for MQTT configurations
  • Document topic patterns in descriptions
  • Test connections before deploying
  • Monitor connection status regularly

4. Security

  • Store MQTT credentials securely (use secrets management)
  • Use TLS/SSL connections to brokers (port 8883)
  • Rotate credentials periodically
  • Limit topic subscriptions to necessary topics only

XIV. License

[Your License Here]


XV. Contributing

[Your Contributing Guidelines Here]

Product Compatible and additional computed target framework versions.
.NET net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
9.4.0 95 11/3/2026
9.3.0 152 10/30/2026
9.2.0 204 10/23/2026
9.0.1 180 5/7/2026