Home

MqttControllerFramework — Wiki

Welcome to the documentation for MqttControllerFramework, a source-generated MQTT controller framework for .NET built on MQTTnet 5.

Pages

Topic	Description
Controllers and Routing	Defining controllers, topic templates, parameter binding, custom parsers, compile-time diagnostics
Middleware	Pipeline, MqttMessageContext, SessionItems, per-message state
Authentication	Username/password auth, lockout support
Authorization	Publish/subscribe authorization, roles, policies, [MqttAuthorize]
Connection Validation	Pre-auth hooks, IP/ClientId filtering, session-item seeding, auth bypass
Rate Limiting	Token-bucket rate limiting per route
TLS and Security	PKCS#12, PEM, hot-swap, client certificate allowlist
Retained Messages	Pluggable retain storage — file, database, Redis, or custom
Events	Client connected / disconnected / subscribed / unsubscribed
Server Actions	Publishing messages from the broker to topics
Broker Statistics	Message counters, byte throughput, per-topic summaries
Performance	Route matching internals, zero-reflection dispatch, JSON, scoped DI, tuning tips
Configuration Reference	All MqttSettings options

At a Glance

[MqttController]        ← marks the class as a controller
[MqttTopic("a/+/b")]    ← maps a method to a topic template
[FromMqttTopic(1)]      ← binds a parameter to the 1st '+' wildcard segment
[MqttAuthorize]         ← requires authorization for this handler
[MqttAllowAnonymous]    ← bypasses class-level [MqttAuthorize]
[TokenBucketRateLimit]  ← applies token-bucket rate limiting

The source generator reads these attributes at build time and emits:

• GeneratedMqttControllerRegistration — IMqttControllerRegistration passed to WithControllers<>()
• {Controller}Dispatcher — one per controller, handles deserialization and method dispatch
• GeneratedMqttRoutingService — DFA-based topic router with an LRU cache; no reflection at runtime

MQTT001 and MQTT002 diagnostics flag duplicate and ambiguous topic patterns at build time, before any code runs.