For events and theirs description see the MQTTClientBuilder’s documentation.


  • ConnectionOptions Options: Connection related options.
  • ClientStates State: Current state of the client. State changed events are emitted through the OnStateChanged event.
  • NegotiatedOptions NegotiatedOptions: Options negotiated with the broker.
  • Session Session: Session instance to persist QoS data.
  • LoggingContext Context: Context of the MQTTClient and all child instances (like its transport, etc.) that can produce log outputs.


  • void BeginPacketBuffer()

    With the use of BeginPacketBuffer and EndPacketBuffer sent messages can be buffered and sent in less network packets. It supports nested Begin-EndPacketBuffer calls.

  • void EndPacketBuffer()

    Call this after a BeginPacketBuffer.

  • BeginConnect(ConnectPacketBuilderDelegate connectPacketBuilderCallback, CancellationToken token = default)

    Starts the connection process to the broker. It’s a non-blocking method. ConnectPacketBuilderCallback is a function that will be called after a successfully transport connection to negotiate protocol details.

// Connect without any customization.
client.BeginConnect((client, builder) => builder);
  • Task ConnectAsync(ConnectPacketBuilderDelegate connectPacketBuilder, CancellationToken token = default)

    Task-based, awaitable connect implementation. It has the same behavior as BeginConnect.

    await client.ConnectAsync(ConnectPacketBuilderCallback);
catch (Exception ex)

ConnectPacketBuilder ConnectPacketBuilderCallback(MQTTClient client, ConnectPacketBuilder builder) => builder;

  • ConnectPacketBuilder CreateConnectPacketBuilder()

    Creates and returns with a ConnectPacketBuilder instance. Normally it isn’t used as the ConnectPacketBuilder callback passed to the BeginConnect/ConnectAsync calls already receiving a builder.

private ConnectPacketBuilder ConnectPacketBuilderCallback(MQTTClient client, ConnectPacketBuilder builder)
    return client.CreateConnectPacketBuilder()
	               .WithUserNameAndPassword("<user>", "<passwd>");
  • SubscribePacketBuilder CreateSubscriptionBuilder(string topicFilter)

    Creates and returns with a SubscribePacketBuilder. A SubscribePacketBuilder can be used to subscribe to a single topic.

  • BulkSubscribePacketBuilder CreateBulkSubscriptionBuilder()

    Creates and return with a BulkSubscribePacketBuilder instance. A BulkSubscribePacketBuilder can be used to subscribe to multiple topics with less overhead than using multiple SubscribePacketBuilders.

        .WithTopic(new SubscribeTopicBuilder("$SYS/#").WithMessageCallback(OnSysMessages))
        .WithTopic(new SubscribeTopicBuilder("/test/msgs").WithMessageCallback(OnTestMessages))
  • UnsubscribePacketBuilder CreateUnsubscribePacketBuilder(string topicFilter)

    Creates and returns with an UnsubscribePacketBuilder instance. An UnsubscribePacketBuilder can be used to unsubscribe from a single topic.

  • BulkUnsubscribePacketBuilder CreateBulkUnsubscribePacketBuilder()

    Creates and returns with a BulkUnsubscribePacketBuilder instance. A BulkUnsubscribePacketBuilder can be used to unsubscribe from multiple topics with less overhead than using multiple UnsubscribePacketBuilders.

         .WithTopicFilter(new UnsubscribeTopicFilterBuilder("topic 1"))
         .WithTopicFilter(new UnsubscribeTopicFilterBuilder("topic 2"))
  • void AddTopicAlias(string topicName)

Frequnetly sent and/or long topic names can add significant overhead to all application messages. To reduce this overhead a topic alias can be added and the plugin can switch consecutive application messages’ topic for a short id to send. The maximum number of topic alias supported by the server can be found through NegotiatedOptions.ServerOptions.TopicAliasMaximum.

private static string[] LongTopicNames = new string[] {
    "Long Topic Name 1",
    "Long Topic Name 2",
    "Long Topic Name 3",
    // ...
    "Long Topic Name N"

void OnConnected(MQTTClient client)
    var maxTopicAliases = Math.Min(LongTopicNames.Length, client.NegotiatedOptions.ServerOptions.TopicAliasMaximum);
    for (int i = 0; i < maxTopicAliases; i++)
  • ApplicationMessagePacketBuilder CreateApplicationMessageBuilder(string topicName)

    Creates and returns with an ApplicationMessagePacketBuilder instance. An ApplicationMessagePacketBuilder can be used to publish messages to a topic.

        .WithPayload("Hello MQTT World!")
  • AuthenticationPacketBuilder CreateAuthenticationPacketBuilder()

    Creates and returns with an AuthenticationPacketBuilder instance. An AuthenticationPacketBuilder can be used to send additional authentication data when the broker requests it. For more details and usage of the builder read the topic about Extended Authentication.

  • DisconnectPacketBuilder CreateDisconnectPacketBuilder()

Creates and returns with a DisconnectPacketBuilder instance. A DisconnectPacketBuilder can be used to initiate a graceful disconnection from the broker.