Welcome to PLCcom.Mqtt

PLCcom.Mqtt is a .NET MQTT toolkit for industrial applications that need a compact client API, an embeddable broker, TLS and certificate handling, diagnostics, and Java-aligned behavior across the PLCcom MQTT product line.

The C# fork follows the Java V02 design as closely as the .NET platform allows. Java getter and setter patterns are represented as .NET properties, asynchronous flows use tasks, and public or protected API surfaces are documented for generated reference help.

The library is split into three assemblies that can be used together or independently:

• PLCcom.Mqtt.Core contains shared result types, diagnostics, PKI helpers, certificate validation, and the internal MQTT wire implementation.

• PLCcom.Mqtt.Client contains the synchronous and asynchronous MQTT client API, fluent builders, request-response helpers, JSON payload helpers, reconnect behavior, last-will configuration, and subscription handles.

• PLCcom.Mqtt.Broker contains the embeddable MQTT broker, listener configuration, authorization hooks, enhanced authentication hooks, retained message storage, administrative snapshots, and host-side publishing/listening APIs.

The SDK targets .NET Framework 4.7.2, .NET Framework 4.8, .NET Standard 2.1, .NET 8, .NET 9, and .NET 10. The same source is used for all target frameworks unless a platform-specific capability requires guarded implementation.

The following table summarizes what each assembly contributes. In a typical NuGet installation, PLCcom.Mqtt.Core is pulled in automatically as a transitive dependency of the client or broker package and does not need to be referenced directly.

Pick the smallest set of packages that matches the role your application plays.

• A client-only application that connects to an existing broker needs only PLCcom.Mqtt.Client. Start from PlccomMqttClientFactory.CreateBuilder() and continue with the High-Level Client API.

• An application that hosts an embedded broker uses PLCcom.Mqtt.Broker. Start from PlccomMqttBrokerFactory.CreateBuilder() and continue with the High-Level Broker API. The host process can also publish and listen without a second network client, as described in the Broker Embedded API.

• An application that acts as both references both packages and combines a client instance with a broker instance in the same process.

The runtime implements the protocol scope of the PLCcom MQTT product line:

• MQTT 3.1.1 and MQTT 5 connect, publish, subscribe, unsubscribe, disconnect, ping, retain, and last-will flows.

• QoS 0 and QoS 1 application messaging, including packet identifiers, acknowledgement tracking, offline queue handling, and retained message replay.

• MQTT 5 metadata including payload format indicator, content type, response topic, correlation data, subscription identifiers, user properties, topic aliases, receive maximum, and maximum packet size limits.

• TCP, TLS over TCP, and WebSocket transports for client-side connections, with broker-side TCP and TLS listeners.

• Certificate validation via PKI store and custom validator delegate, including trust/reject directory handling for remote certificates.

• Selectable outgoing network interface on the client via WithLocalAddress for hosts with multiple network cards.

• A true asynchronous publish path with connection-fatal write deadlines, so a stalled broker connection cannot block the application indefinitely.

This help file combines the generated API reference with a set of conceptual topics. The conceptual topics describe how the pieces fit together; the API reference describes every public type and member.

• High-Level Client API — connect, publish, subscribe, request-response, reconnect, and MQTT 5 metadata from the client side.

• High-Level Broker API — starting the broker, configuring listeners, and controlling client access.

• Broker Embedded API — publishing and listening from the host application without a second network client.

• Builder Options — the complete option surface of the client and broker builders.

• Validators — access validators and enhanced authenticators for authorization decisions.

• Listeners and Events — callbacks and event hooks for connection lifecycle and message delivery.

• Interfaces — the public interfaces an application can implement or consume.

• Result Objects — result objects, reason codes, and error information returned by operations.

• PKI, TLS, and mTLS — TLS configuration, PKI stores, mutual TLS, and certificate validation models.

• Stores — retained-message and session storage, including custom store implementations.

• Diagnostics — diagnostic levels, listeners, and event codes.

• Best Practices — recommendations for production deployments.

In addition to this help file, the product ships four PDF guides: First Steps for project setup and the first running client and broker, and the appendices Security Guide, Client Guide, and Broker Guide for in-depth coverage of security, client usage, and broker usage. All four guides are available in English and German.

Create a client with the fluent builder, connect to a broker, publish messages, and subscribe with a handle that can later unsubscribe from the topic.

using PLCcom.Mqtt.Client;

using var client = PlccomMqttClientFactory.CreateBuilder()
    .WithLicense("<user name>", "<serial number>")
    .WithIdentifier("plccom-mqtt-client")
    .WithServer("127.0.0.1", 1883)
    .Build();

client.Connect();

client.CreatePublishBuilder("factory/line1/temperature", "23.7")
    .WithQualityOfService(PlccomMqttQualityOfService.AtLeastOnce)
    .Send();

IPlccomMqttSubscriptionHandle subscription = client.Subscribe(
    "factory/line1/#",
    PlccomMqttQualityOfService.AtLeastOnce,
    message => Console.WriteLine($"{message.TopicName}: {message.GetPayloadText()}"));

subscription.Unsubscribe();
client.Disconnect();

For background use, choose PlccomMqttAsyncClient or the asynchronous methods on the standard client. Reconnect callbacks, connected callbacks, disconnected callbacks, enhanced authentication, and request-response helpers are available through the same Java-aligned builder style.

The broker can be embedded into a service or test harness. It can accept client connections and can also be used by the host application to publish or listen for application messages without creating a second network client.

using PLCcom.Mqtt.Broker;

using var broker = PlccomMqttBrokerFactory.CreateBuilder()
    .WithLicense("<user name>", "<serial number>")
    .WithTcpPort(1883)
    .AllowAnonymous()
    .Build();

broker.Start();

using MqttBrokerListenerHandle listener = broker.Listen(
    "factory/+/temperature",
    PlccomMqttBrokerQualityOfService.AtLeastOnce,
    message => Console.WriteLine($"Broker received {message.TopicName}: {message.GetPayloadText()}"));

broker.CreatePublishBuilder("factory/line1/temperature", "24.1")
    .WithQualityOfService(PlccomMqttBrokerQualityOfService.AtLeastOnce)
    .WithRetain()
    .Send();

broker.Stop();

Authorization can be customized with IPlccomMqttBrokerAccessValidator. Enhanced authentication can be implemented with IPlccomMqttBrokerEnhancedAuthenticator. Retained messages and session state can use the default in-memory store or a custom IPlccomMqttBrokerStore.

Clients and brokers own network resources and must be released when they are no longer needed.

• PlccomMqttClient, PlccomMqttBroker, and the broker listener handle (MqttBrokerListenerHandle) implement IDisposable. Wrap them in a using block, or call Dispose() from a finally block, so that resources are released even when an error occurs.

• PlccomMqttAsyncClient implements IAsyncDisposable and is released with DisposeAsync() or an await using block.

• Message callbacks and lifecycle callbacks are invoked from SDK threads, for example the MQTT reader thread. Keep callback code short and offload database, file, network, or UI work to your own task or thread; a slow callback holds up message processing.

• The SDK catches exceptions thrown from your callbacks so that a single callback error does not damage MQTT processing, and reports them as diagnostic events. Do not rely on callbacks to propagate exceptions to the caller.

PLCcom.Mqtt supports two certificate validation models. The first model uses a PKI store with trusted and rejected certificate directories. The second model uses a validator callback when the application wants to make the trust decision itself.

• Accepted certificate inputs include X509Certificate2 instances and file based certificates loaded by the application before assigning them to TLS options.

• Private key material can be provided through platform-supported certificate containers such as PFX/P12 files when the application needs client certificate authentication.

• Remote certificates can be accepted, rejected, or persisted to the rejected store for later review, depending on the configured validation result.

• For development systems, a custom validator may temporarily accept self-signed certificates. Production systems should use an explicit trust store and should reject unexpected issuer, subject, EKU, hostname, or chain errors.

The broker TLS configuration controls whether client certificates are ignored, allowed, or required. The client TLS configuration controls server certificate validation and optional client certificate presentation. The full trust-on-first-use workflow — an unknown remote certificate lands in the rejected store, is reviewed, and is moved to the trusted store — is described in PKI, TLS, and mTLS.

Most public operations return PLCcom result objects or throw PLCcom-specific exceptions when the operation cannot continue. Result objects preserve the topic, packet identifier, QoS status, reason code, reason string, user properties, and transport or protocol error where available.

Diagnostic listeners can be attached to observe connection lifecycle events, protocol decisions, rejected packets, authorization decisions, retained-message operations, and broker statistics. This is especially useful for service installations where console output is not available.

PlccomMqttDiagnosticLevel controls which diagnostic events are delivered to the listeners; every event at or above the configured level is delivered. The default level is Info. Debug delivers all SDK diagnostics for troubleshooting, Warning, Error, and Fatal progressively reduce the output, and Off suppresses SDK diagnostics completely. Broker access-validator CONNECT denials are emitted as Warning events with code BROKER_ACCESS_CONNECT_DENIED; the event includes client id, user name, denial reason, MQTT reason code, and remote address, but never password data.

The SDK is continuously verified against its own broker and against Eclipse Mosquitto, covering MQTT 3.1.1 publish/subscribe, MQTT 5 metadata, retained message replay, TLS connections, stress iterations, and reconnect cycles. Client and broker can therefore be combined freely with third-party MQTT peers that follow the MQTT 3.1.1 or MQTT 5 specification.

The SDK ships with guided client and broker workshops in C# and Visual Basic, covering connect, publish, subscribe, request-response, TLS, and broker embedding scenarios. In addition, two WPF sample applications (client tool and broker tool) expose practical client and broker operations for manual testing and demonstrations.

Client and broker instances are created with PLCcom license information (user name and serial number) supplied through the builder.

If you pass two empty strings for user name and serial number, the library runs for 15 minutes with the full functional scope during a debug session — enough to bring up a connection and read values. That way you can try the library out before you register. Evaluation mode applies to the client and the broker alike. For uninterrupted work, generate yourself a free trial license (14 days) at the PLCcom MQTT download page.

License data does not belong in source code. Use configuration files, environment variables or a secret manager to load it at runtime.

Other Resources