ApiFeatures.Mqtt.Apis
9.3.0
See the version list below for details.
dotnet add package ApiFeatures.Mqtt.Apis --version 9.3.0
NuGet\Install-Package ApiFeatures.Mqtt.Apis -Version 9.3.0
<PackageReference Include="ApiFeatures.Mqtt.Apis" Version="9.3.0" />
<PackageVersion Include="ApiFeatures.Mqtt.Apis" Version="9.3.0" />
<PackageReference Include="ApiFeatures.Mqtt.Apis" />
paket add ApiFeatures.Mqtt.Apis --version 9.3.0
#r "nuget: ApiFeatures.Mqtt.Apis, 9.3.0"
#:package ApiFeatures.Mqtt.Apis@9.3.0
#addin nuget:?package=ApiFeatures.Mqtt.Apis&version=9.3.0
#tool nuget:?package=ApiFeatures.Mqtt.Apis&version=9.3.0
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/brokersGET 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}/runtimePOST/DELETE api/mqtt-broker/{id:guid}/connectionBroker-users list GET api/mqtt/broker/{brokerId}/usersGET api/mqtt-broker/{mqttBrokerId:guid}/users(now paginated)Broker-user create POST api/mqtt/broker/{brokerId}/userPOST api/mqtt-broker/{mqttBrokerId:guid}/userBroker-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-messagesGET/DELETE api/mqtts/live-messagesAlso breaking at the code level (consumers of
ApiFeatures.Mqtt.Coresdirectly, not just HTTP callers):
IBrokerServiceandIBrokerUserServiceeach gained a new paginatedSearchAsync/SearchByBrokerIdAsyncmethod (additive, not breaking on its own, but any existing third-party implementation of these interfaces must now implement the new member).
IBrokerUserService'sGetByIdAsync/UpdateAsync/DeleteAsyncsignatures,BrokerUserByIdNotFoundException's constructor, and theOnBeforeBrokerUserCreateAsyncHandler/OnBeforeBrokerUserUpdateAsyncHandler/OnBeforeBrokerUserDeleteAsyncHandlerdelegate 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-tiedMqttService/MqttConnectionService/BrokerService/BrokerUserServiceimplementations now live inApiFeatures.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-agnosticApiFeatures.Modules.Cores.Interfaces.IModuleDatabaseOptionsto gateWithEmbeddedBrokers) andIServiceCollection.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/ProcessAsyncnow receive a singleMqttContextinstead of a bareMqttMessage. Read the parsed message viacontext.Message(nullable — handlers run even when no parser matched), the topic viacontext.Topic, the raw payload viacontext.RawMessage, and the originating connection's non-sensitive metadata viacontext.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. Returntrueto opt this processor in for the current message (filter oncontext.Topic, the connection, or the parsedcontext.Message); returnfalseto skip. Handlers run for every received message, socontext.Messagemay benullwhen no parser matched the payload.ProcessAsync— the actual work. Only called whenCanExecuteAsyncreturnedtrue.
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:
- Whitespace guard — empty / whitespace-only payloads are skipped (nothing is dispatched).
- Best-effort parse — registered parsers run; the first non-null result becomes
context.Message. Parsing does not gate dispatch: if nothing parses,context.Messageisnulland handlers still run. - Context build — a
MqttContextis built from the trusted entity, copying only the non-sensitiveId/Name/TopicsintoMqttConnectionInfo(credentials dropped). - Dispatch — for every registered processor,
CanExecuteAsyncis awaited; iftrue,ProcessAsyncis 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
LoggingMqttMessageProcessorself-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, seeWithLiveMessageStream.
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 implementsIJsonToolfactory: Factory function that returns anIJsonToolinstance
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
MqttMessageobjects
Parameters:
T: Type that implementsIMqttMessageParserfactory: Factory function that returns anIMqttMessageParserinstance
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.Messageis thennull). - Checks
CanExecuteAsyncfirst (handlers self-filter on topic and/or the parsed message). - If true, calls
ProcessAsyncto 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 implementsIMqttMessageProcessorfactory: Factory function that returns anIMqttMessageProcessorinstance
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/MaxPortproperties no longer exist. The allowed-port set is now expressed asBrokerHostingOptions.Ports— a collection ofIBrokerPort(BrokerPortRangeand/orBrokerPortCollection), set in code, not bound fromappsettings. LeavingPortsuntouched keeps a single defaultBrokerPortRange(1024, 65535). SettingPortsto an empty collection, or to a range withMin > Maxor bounds outside1-65535, throwsInvalidOperationExceptionat startup (insideWithEmbeddedBrokers, 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.csto readDefaultBindAddressand pass it intoWithEmbeddedBrokers, and commits the example value into its ownappsettings.json(done in the auto-run task). A custom allowed-port set is set in code viaoptions.Ports— there is no JSON-bindable shape for it. The manager itself is a singleton (it owns long-livedMqttServerinstances);BrokerHostingOptionsregistered 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 optionalUsername/Password/AuthenticationDatabase/ReplicaSet/UseTls/Collections) replace the former singleConnectionStringkey — seeApiFeatures.Mqtt.MongoDatabases's README for the full key list and connection-equivalence notes.
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.CSharpLegacyfor 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
- Message Received: MQTT client receives message from subscribed topic
- Message Parsing: Each registered parser attempts to parse the raw message
- Message Processing: All processors with
CanExecuteAsyncreturning true process the message - 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
nullif the parser can't handle the message - Log parsing errors for debugging
- Use strongly-typed
MqttMessage<T>for parsed messages
2. Processor Design
- Implement
CanExecuteAsyncto 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 | Versions 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. |
-
net9.0
- ApiFeatures.Modules.Cores (>= 9.0.2)
- ApiFeatures.Mqtt.Cores (>= 9.1.0)
- BusinessFeatures.Cores (>= 9.0.1)
- DataMagic.Abstractions (>= 1.0.2)
- FluentValidation (>= 12.1.1)
- IotVn.CoreFeatures (>= 9.1.0)
- Microsoft.AspNetCore.Http.Abstractions (>= 2.3.13)
- Microsoft.AspNetCore.OpenApi (>= 9.0.11)
- Microsoft.Extensions.Hosting.Abstractions (>= 9.0.11)
- MongoDB.Driver (>= 3.5.2)
- MQTTnet (>= 5.0.1.1416)
- MQTTnet.Server (>= 5.0.1.1416)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.