-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Upgrading guide
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.
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.
The MqttFactory is now separeted into MqttClientFactory and MqttServerFactory.
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 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.
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.
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.
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.
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.
All properties, methods and other things which are already marked as obsolete are now deleted.
- 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();
-
MQTTnet.Adapter.MqttChannelAdapter
constructor has additional argumentIMqttPacketInspector
which is avalable as prroperty inMQTTnet.Client.Options.IMqttClientOptions
.
- Rename namespace
MQTTnet.AspNetCore
toMQTTnet.AspNetCore.Extensions
.
- Argument
logger
removed fromIMqttChannelAdapter 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 anCreateChildLogger
create aCreateScopedLogger
.
- Replace
MQTTnet.Diagnostics.IMqttNetChildLogger
withMQTTnet.Diagnostics.IMqttNetLogger
. - Replace
MQTTnet.AspNetCore.ApplicationBuilderExtensions.SelectSubProtocol(requestedSubProtocolValues)
withMQTTnet.AspNetCore.MqttSubProtocolSelector.SelectSubProtocol(requestedSubProtocolValues)
. - Class
MQTTnet.AspNetCore.ApplicationBuilderExtensions
is deprecated and will be removed in a future version.
- Nothing special at the moment.
- There is a new
Dictionary<object, object>
calledSessionItems
. It allows to store custom data in the session and is available in all interceptors. For more examples, check https://github.com/chkr1011/MQTTnet/wiki/Server#storing-data-in-the-session.
-
MqttConnectReturnCode
is now deprecated, useMqttConnectReasonCode
instead. -
ConnectAsync
has now a CancellationToken and can be used like this:await mqttClient.ConnectAsync(options, CancellationToken.None));
-
MqttProtocolVersion
is now in theMQTTnet.Formatter
namespace. -
MqttFixedHeader
,MqttPacketBodyReader
,MqttPacketReader
,MqttPacketWriter
andMqttProtocolVersion
are now in theMQTTnet.Formatter
namespace. -
IMqttPacketSerializer
andMqttPacketSerializer
do not exist anymore.
- 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)
{
}
- 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)
{
}
- Checkout the issue under https://github.com/chkr1011/MQTTnet/issues/781 or open new issues if you are unsure.