Skip to content

Upgrading guide

Jump to bottom
Christian edited this page Jun 8, 2024 · 30 revisions

From 4.x to 5.0.0:

Limited framework support

MQTTnet 5 only supports newer (and still supported) .NET versions starting with version 8.0. MQTTnet will start to drop support for frameworks as soon as support has officially ended by Microsoft.

Changing the strategy ensures that the limited resources of this project can be used to implement new features faster. It also allows us to make use of new features like Memory<> or Span<> etc. which allowes improving the memory usage and performance of this library.

Old versions

Version 5 of this library is leaving a lot of old code behind and opens the door for latest language features and performance optimizations. If the new version is not an option users can still use version 4. It will receive hotfixes but no new features.

More factories

The MqttFactory is now separeted into MqttClientFactory and MqttServerFactory.

Less exceptions when connecting

The client will no longer throw an exception if the server returned a proper CONNACK packet even if it indicates a failure (wrong password etc.). It will only throw exceptions when the server is not reachable on socket level etc.

Samples

Samples are now only available at the samples application in the repository. There will be no samples in the wiki anymore. This makes sure that the samples are always up to date and adopt latest API changes quickly.

New default values

The protocol version is set to 5.0.0 by default for client connections. Version 3.1.0 and 3.1.1 are still supported. This change makes sure that most users can make use of all features of the library because most of the MQTT brokers are already supporting version 5.0.0 of the MQTT protocol specification.

Excluded server

The MQTTnet server is no longer part of the core library. It has beed moved to a dedicated nuget package called MQTTnet.Server. This makes sure that users which only use the client do not need to deploy lots of files (dependencies) which are only required for the server.

WebSocket4Net extension

The extension is completely removed. It was not updated since 2018 and has known security issues. This library was added in the first place because it has support for some older/exotic encryption algorithms which are not supported in .NET.

ManagedClient extension is not available (yet)

The extension is not available. It is recommended to use the regular client and doing the reconnect stuff etc. via your own code. The current managed client in version 4 of MQTTnet lacks several features which require that the client will be built from scratch. It is not yet planned but may be happen in the future.

No obsolete stuff

All properties, methods and other things which are already marked as obsolete are now deleted.

From 3.x to 4.0.0:

  • A lot of namespaces have changed in the server component. Basically all classes are still there but have to be imported using new namespaces.
  • The entire library now uses async events instead of handles implemented by interfaces. So every interface implementation like application message received handler in the client must be ported to an async event handler. The former context information is still available as regular event argument classes. When an event is not async it should return Task.CompletedTask.
  • The server and client classes no longer support interface (IMqttClient etc.). The should be encapsulated in custom clients.
  • A lot of overloads and extension methods have been removed to keep the public API clean and small. Thus previously used extension methods etc. must be created again in user code.
  • Due to security reasons the default (unencrypted) endpoint is no longer enabled by default. It is still present and can be activated via existing APIs (call WithDefaultEndpoint()).
  • The Server and the Clients no longer share common interfaces like IApplicationMessagePublisher. They now have unique implementations offering the best API for each purpose. This is a preparation in order to move the server components into a dedicated nuget package.
  • Several APIs were removed from the builder to keep the API small and clean. If a used API is gone there should be another suitable overload.

Required Code Changes:

  • TopicFilter:

    MqttTopicFilterComparer.IsMatch(x, y)

    to

    MqttTopicFilterComparer.Compare(x, y) == MqttTopicFilterCompareResult.IsMatch)

  • ClientUnsubscribedTopicHandler:

    server.ClientUnsubscribedTopicHandler = new MqttServerClientUnsubscribedTopicHandlerDelegate(e => { ... });

    to

    server.ClientUnsubscribedTopicAsync += async e => { ... };

  • ApplicationMessageReceivedHandler:

    server.ApplicationMessageReceivedHandler = new MqttApplicationMessageReceivedHandlerDelegate(e => { ... });

    to

    server.InterceptingPublishAsync += async e => { ... };

  • General server startup:

    var options = new MqttServerOptionsBuilder();
var mqttFactory = new MqttFactory();
var server = mqttFactory.CreateMqttServer(_serverLogger);
await server.StartAsync(options.WithDefaultEndpointPort(port).Build());

    to

    var options = new MqttServerOptionsBuilder();
var mqttFactory = new MqttFactory();
var server = mqttFactory.CreateMqttServer(options.WithDefaultEndpointPort(port).Build(), _serverLogger);
await server.StartAsync();

From 3.0.13 to 3.0.14:

  • MQTTnet.Adapter.MqttChannelAdapter constructor has additional argument IMqttPacketInspector which is avalable as prroperty in MQTTnet.Client.Options.IMqttClientOptions.

From 3.0.11 to 3.0.12 or 3.0.13:

  • Rename namespace MQTTnet.AspNetCore to MQTTnet.AspNetCore.Extensions.

From 3.0.9 to 3.0.10 or 3.0.11:

  • Argument logger removed from IMqttChannelAdapter MQTTnet.Adapter.CreateClientAdapter(IMqttClientOptions options, IMqttNetLogger logger). Create a constructor in your AdapterFactory and pass there the logger.
  • Pass the root logger to MQTTnet.Adapter.MqttChannelAdapter. For other use cases where you previously created an CreateChildLogger create a CreateScopedLogger.

From 3.0.8 to 3.0.9:

  • Replace MQTTnet.Diagnostics.IMqttNetChildLoggerwith MQTTnet.Diagnostics.IMqttNetLogger.
  • Replace MQTTnet.AspNetCore.ApplicationBuilderExtensions.SelectSubProtocol(requestedSubProtocolValues) with MQTTnet.AspNetCore.MqttSubProtocolSelector.SelectSubProtocol(requestedSubProtocolValues).
  • Class MQTTnet.AspNetCore.ApplicationBuilderExtensions is deprecated and will be removed in a future version.

From 3.0.6 to 3.0.7 or 3.0.8:

  • Nothing special at the moment.

From 3.0.5 to 3.0.6:

From 3.0.3 to 3.0.5:

  • MqttConnectReturnCode is now deprecated, use MqttConnectReasonCode instead.
  • ConnectAsync has now a CancellationToken and can be used like this: await mqttClient.ConnectAsync(options, CancellationToken.None));

From 2.8.5 to 3.0.0:

General:

  • MqttProtocolVersion is now in the MQTTnet.Formatter namespace.
  • MqttFixedHeader, MqttPacketBodyReader, MqttPacketReader, MqttPacketWriter and MqttProtocolVersion are now in the MQTTnet.Formatter namespace.
  • IMqttPacketSerializer and MqttPacketSerializer do not exist anymore.

ManagedClient:

  • Updated async handlers:
private void Something()
{
    mqttClient.ApplicationMessageReceivedHandler = new MqttApplicationMessageReceivedHandlerDelegate(OnAppMessage);
    mqttClient.ConnectedHandler = new MqttClientConnectedHandlerDelegate(OnConnected);
    mqttClient.DisconnectedHandler = new MqttClientDisconnectedHandlerDelegate(OnDisconnected);
    mqttClient.ConnectingFailedHandler = new ConnectingFailedHandlerDelegate(OnConnectingFailed);
}

private async void OnAppMessage(MqttApplicationMessageReceivedEventArgs e)
{
}

private async void OnConnected(MqttClientConnectedEventArgs e)
{
}

private async void OnDisconnected(MqttClientDisconnectedEventArgs e)
{
}

private async void OnConnectingFailed(ManagedProcessFailedEventArgs e)
{
}

Client:

  • Updated async handlers:
private void Something()
{
    mqttClient.ApplicationMessageReceivedHandler = new MqttApplicationMessageReceivedHandlerDelegate(OnAppMessage);
    mqttClient.ConnectedHandler = new MqttClientConnectedHandlerDelegate(OnConnected);
    mqttClient.DisconnectedHandler = new MqttClientDisconnectedHandlerDelegate(OnDisconnected);
}

private async void OnAppMessage(MqttApplicationMessageReceivedEventArgs e)
{
}

private async void OnConnected(MqttClientConnectedEventArgs e)
{
}

private async void OnDisconnected(MqttClientDisconnectedEventArgs e)
{
}

From 2.7.5 to 3.x.x:

General:

Clone this wiki locally