SyMqttBox public methods
The SyMqttBox class acts as the centralized orchestration engine of the framework. Almost every interaction with SyMqtt starts here. It manages the communication topology, coordinates connections, and routes messages safely.
Public methods naturally fall into three categories:
- configuring the communication topology,
- managing the MQTT connection,
- sending and receiving messages.
Configuration and topology management
Section titled “Configuration and topology management”These methods are used to provision your communication architecture. Note that mutating the topology (adding or removing channels and topics) is only allowed while the connection is closed.
| Method | Return Type | Description |
|---|---|---|
Initialize(SyMqttClientParameters params) | SyMqttBox | Configures the MQTTnet client connection with credentials, broker endpoints, TLS/SSL settings, and protocol versions (MQTT v5, v3.1.1, or v3.1.0). |
AddChannel(SyMqttChannel channel) | SyMqttBox | Adds a bidirectional communication channel to the internal topology box. |
RemoveChannel(string channelId) | SyMqttBox | Removes a registered channel from the infrastructure box by its unique ID. |
GetChannel(string channelId) | SyMqttChannel | Retrieves a registered channel instance from the box using its unique ID. |
AddTopic(SyMqttSenderTopicHolder senderTopic) | SyMqttBox | Registers a strongly-typed outbound topic destination into the infrastructure. |
AddTopic(SyMqttReceiverTopicHolder receiverTopic) | SyMqttBox | Registers a strongly-typed inbound topic listener into the infrastructure. |
RemoveTopic(string topicId) | SyMqttBox | Removes an inbound or outbound topic registration from the box by its unique ID. |
GetSenderTopic(string topicId) | SyMqttSenderTopicHolder | Retrieves a registered outbound topic instance from the box using its unique ID. |
GetReceiverTopic(string topicId) | SyMqttReceiverTopicHolder | Retrieves a registered inbound topic instance from the box using its unique ID. |
Lifecycle and connection control
Section titled “Lifecycle and connection control”These operations govern the connection state with the MQTT Broker.
| Method | Return Type | Description |
|---|---|---|
OpenConnectionAsync(CancellationToken ct = default) | Task<GenericResult<bool>> | Opens the network socket connection to the MQTT broker. Automatically triggers internal topic subscriptions upon success. |
CloseConnectionAsync() | Task<GenericResult<bool>> | Gracefully terminates the connection with the broker and safely signals the auto-reconnect logic to stand down. |
Core messaging operations
Section titled “Core messaging operations”These are the primary execution hooks used by your application logic to transmit data.
| Method | Return Type | Description |
|---|---|---|
FetchAsync(string channelId, SerialMessage msg, int timeoutMs, SyMqttSendMessageOptions opts, SyMqttDeliveryOptions delivery = null, CancellationToken ct = default) | Task<GenericResult<SerialMessage>> | Performs a synchronous Request-Response operation over a registered channel. Blocks asynchronously until the response payload arrives or the timeout expires. |
PublishSerialMessageAsync(string topicHolderId, SerialMessage msg, SyMqttSendMessageOptions opts, SyMqttDeliveryOptions delivery = null, CancellationToken ct = default) | Task<GenericResult<bool>> | Transmits a SerialMessage envelope to the outbound topic designated by the topic holder’s unique ID. |
PublishSerialMessageAsync(SyMqttSenderTopicHolder topicHolder, SerialMessage msg, SyMqttSendMessageOptions opts, SyMqttDeliveryOptions delivery = null, CancellationToken ct = default) | Task<GenericResult<bool>> | Sends a SerialMessage envelope directly via a reference to an outbound topic holder. |
PublishAsync(string topic, string payload, SyMqttDeliveryOptions delivery = null, CancellationToken ct = default) | Task<GenericResult<bool>> | Low-level direct publish method. Publishes raw string payloads straight to raw topic paths. (Advised to be used only when bypassing high-level framework features). |
ClearRetainedMessageAsync(string topic) | Task | Clears a server-side retained message by publishing an empty payload with the retain flag set to true on the specified topic path. Note: There is no need to use this in standard scenarios, since SyMqtt ignores retained messages by default. |
Implementation note: All public runtime operations (
FetchAsync,PublishSerialMessageAsync,PublishAsync) are fully thread-safe and use an internal snapshot mechanism to allow concurrent message processing without lock contention.