API reference — SyMqttBox
The SyMqttBox class serves as the central hub and orchestrator of the entire framework. It implements ISyMqttBox and wraps the low-level MQTT client infrastructure, handling topology registration, prefix injections, connectivity states, logging links, and message dispatching.
Lifecycle and connection management
Section titled “Lifecycle and connection management”Initialization workflow
Section titled “Initialization workflow”Before opening a network connection to the broker, the engine state must be initialized using the Initialize method. Attempting to connect to the broker without prior initialization will trigger a SyMqttException.
You can call Initialize multiple times during the lifecycle of a SyMqttBox instance (for example, to swap parameters or connect to a different broker), provided that the client is not actively connected (IsConnectionOpen must be false). Re-initializing an idle instance will safely dispose of the previous client configuration and wire up the new parameters.
Thread-safe topology registration
Section titled “Thread-safe topology registration”Channels and standalone topic holders must be registered using AddChannel and AddTopic prior to invoking OpenConnectionAsync.
Core properties
Section titled “Core properties”| Property | Type | Access | Description |
|---|---|---|---|
TopicsPrefix | string | get; set; | Global namespace prefix appended to all physical broker topics upon connection. |
AutoReconnect | bool | get; set; | When true, automatically recovers topology subscriptions if the connection drops. |
Logger | ISyMqttLogger | get; set; | Reference to the internal thread-safe console tracking system. |
Public methods reference
Section titled “Public methods reference”1. Initialization and connection
Section titled “1. Initialization and connection”public ISyMqttBox Initialize(SyMqttClientParameters clientParameters);Initializes the internal client setup engine, loads custom TLS/SSL certificates if specified, and pre-configures connection state machines. Returns the current ISyMqttBox instance to allow fluent method chaining.
public async Task<GenericResult<bool>> OpenConnectionAsync(CancellationToken cancellationToken = default);Establishes the physical connection to the broker, applies the global TopicsPrefix, subscribes to all registered inbound paths, and spins up the background reading loops. Returns true if connected successfully.
2. Topology management
Section titled “2. Topology management”public ISyMqttBox AddChannel(SyMqttChannel channel);Registers a pre-configured bidirectional channel into the internal lookup directory. Throws a SyMqttException if invoked after the network connection was opened.
public ISyMqttBox AddTopic(SyMqttReceiverTopicHolder receiverTopic);public ISyMqttBox AddTopic(SyMqttSenderTopicHolder senderTopic);Registers a standalone inbound or outbound topic holder into the routing infrastructure.
3. Messaging operations
Section titled “3. Messaging operations”public Task<GenericResult<bool>> PublishSerialMessageAsync(string topicId, SerialMessage serialMessage, SyMqttSendMessageOptions messageOptions);Publishes an asynchronous, one-way message using a registered sender topic identifier. Returns a structured result wrapping execution success or error details.
public Task<GenericResult<SerialMessage>> FetchAsync(string channelId, SerialMessage serialMessage, SyMqttSendMessageOptions messageOptions, int timeoutMilliseconds);Executes a synchronous request-response transaction over the specified channel. This routine blocks the current task chain execution context until a valid response with a matching MessageId returns via the receiver leg or the timeout threshold expires.