Add feature validations (#1527)

* Add feature validation.

* Update ReleaseNotes.md

* Add validators or subscribe and unsubscribe.

* Add feature validation for disconnect.

* Fix build errors.

* Fix build errors
Co-authored-by: NHansM <HansM2013@gmx.de>

.github/workflows/ReleaseNotes.md

-*
\ No newline at end of file
+* [Client] MQTTv5 features are now checked and an exception is thrown if they are used when using protocol version 3.1.1 and lower. These checks can be disabled in client options. (BREAKING CHANGE!).

Source/MQTTnet.Extensions.Rpc/MqttRpcClient.cs

@@ -8,6 +8,7 @@ using System.Threading;
 using System.Threading.Tasks;
 using MQTTnet.Client;
 using MQTTnet.Exceptions;
+using MQTTnet.Formatter;
 using MQTTnet.Internal;
 using MQTTnet.Protocol;
 
@@ -17,9 +18,9 @@ namespace MQTTnet.Extensions.Rpc
     {
         readonly IMqttClient _mqttClient;
         readonly MqttRpcClientOptions _options;
-        
+
         readonly ConcurrentDictionary<string, AsyncTaskCompletionSource<byte[]>> _waitingCalls = new ConcurrentDictionary<string, AsyncTaskCompletionSource<byte[]>>();
-        
+
         public MqttRpcClient(IMqttClient mqttClient, MqttRpcClientOptions options)
         {
             _mqttClient = mqttClient ?? throw new ArgumentNullException(nameof(mqttClient));
@@ -83,11 +84,14 @@ namespace MQTTnet.Extensions.Rpc
                 throw new MqttProtocolViolationException("RPC response topic is empty.");
             }
 
-            var requestMessage = new MqttApplicationMessageBuilder().WithTopic(requestTopic)
-                .WithPayload(payload)
-                .WithQualityOfServiceLevel(qualityOfServiceLevel)
-                .WithResponseTopic(responseTopic)
-                .Build();
+            var requestMessageBuilder = new MqttApplicationMessageBuilder().WithTopic(requestTopic).WithPayload(payload).WithQualityOfServiceLevel(qualityOfServiceLevel);
+
+            if (_mqttClient.Options.ProtocolVersion == MqttProtocolVersion.V500)
+            {
+                requestMessageBuilder.WithResponseTopic(responseTopic);
+            }
+
+            var requestMessage = requestMessageBuilder.Build();
 
             try
             {

Source/MQTTnet.Tests/MqttApplicationMessageValidator_Tests.cs

+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using MQTTnet.Formatter;
+
+namespace MQTTnet.Tests
+{
+    [TestClass]
+    public sealed class MqttApplicationMessageValidator_Tests
+    {
+        [TestMethod]
+        [ExpectedException(typeof(NotSupportedException))]
+        public void Succeed_When_Using_TopicAlias_And_MQTT_311()
+        {
+            MqttApplicationMessageValidator.ThrowIfNotSupported(new MqttApplicationMessageBuilder().WithTopicAlias(1).Build(), MqttProtocolVersion.V311);
+        }
+
+        [TestMethod]
+        public void Succeed_When_Using_TopicAlias_And_MQTT_500()
+        {
+            MqttApplicationMessageValidator.ThrowIfNotSupported(new MqttApplicationMessageBuilder().WithTopicAlias(1).Build(), MqttProtocolVersion.V500);
+        }
+
+        [TestMethod]
+        public void Succeed_When_Using_UserProperties_And_MQTT_500()
+        {
+            MqttApplicationMessageValidator.ThrowIfNotSupported(
+                new MqttApplicationMessageBuilder().WithTopic("A").WithUserProperty("User", "Property").Build(),
+                MqttProtocolVersion.V500);
+        }
+
+        [TestMethod]
+        [ExpectedException(typeof(NotSupportedException))]
+        public void Succeed_When_Using_WillUserProperties_And_MQTT_311()
+        {
+            MqttApplicationMessageValidator.ThrowIfNotSupported(
+                new MqttApplicationMessageBuilder().WithTopic("B").WithUserProperty("User", "Property").Build(),
+                MqttProtocolVersion.V311);
+        }
+    }
+}
\ No newline at end of file

Source/MQTTnet.Tests/MqttClientOptionsValidator_Tests.cs

+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using MQTTnet.Client;
+using MQTTnet.Formatter;
+
+namespace MQTTnet.Tests
+{
+    [TestClass]
+    public sealed class MqttClientOptionsValidator_Tests
+    {
+        [TestMethod]
+        public void Succeed_When_Using_UserProperties_And_MQTT_500()
+        {
+            new MqttClientOptionsBuilder().WithProtocolVersion(MqttProtocolVersion.V500).WithUserProperty("User", "Property").WithTcpServer("FAKE").Build();
+        }
+
+        [TestMethod]
+        [ExpectedException(typeof(NotSupportedException))]
+        public void Succeed_When_Using_WillUserProperties_And_MQTT_311()
+        {
+            new MqttClientOptionsBuilder().WithProtocolVersion(MqttProtocolVersion.V311).WithWillUserProperty("User", "Property").WithTcpServer("FAKE").Build();
+        }
+
+        [TestMethod]
+        public void Succeed_When_Using_WillUserProperties_And_MQTT_500()
+        {
+            new MqttClientOptionsBuilder().WithProtocolVersion(MqttProtocolVersion.V500).WithWillUserProperty("User", "Property").WithTcpServer("FAKE").Build();
+        }
+
+        [TestMethod]
+        [ExpectedException(typeof(NotSupportedException))]
+        public void Throw_When_Using_UserProperties_And_MQTT_311()
+        {
+            new MqttClientOptionsBuilder().WithProtocolVersion(MqttProtocolVersion.V311).WithUserProperty("User", "Property").WithTcpServer("FAKE").Build();
+        }
+
+        [TestMethod]
+        [ExpectedException(typeof(NotSupportedException))]
+        public void Throw_When_Using_WithRequestResponseInformation_And_MQTT_311()
+        {
+            new MqttClientOptionsBuilder().WithProtocolVersion(MqttProtocolVersion.V311).WithRequestResponseInformation().WithTcpServer("FAKE").Build();
+        }
+
+        [TestMethod]
+        public void Throw_When_Using_WithRequestResponseInformation_And_MQTT_500()
+        {
+            new MqttClientOptionsBuilder().WithProtocolVersion(MqttProtocolVersion.V500).WithRequestResponseInformation().WithTcpServer("FAKE").Build();
+        }
+    }
+}
\ No newline at end of file

Source/MQTTnet.Tests/MqttTopicValidator_Tests.cs

@@ -9,33 +9,33 @@ using MQTTnet.Protocol;
 namespace MQTTnet.Tests
 {
     [TestClass]
-    public class MqttTopicValidator_Tests
+    public sealed class MqttTopicValidator_Tests
     {
         [TestMethod]
-        public void Valid_Topic()
+        [ExpectedException(typeof(MqttProtocolViolationException))]
+        public void Invalid_Topic_Empty()
         {
-            MqttTopicValidator.ThrowIfInvalid("/a/b/c");
+            MqttTopicValidator.ThrowIfInvalid(string.Empty);
         }
 
         [TestMethod]
         [ExpectedException(typeof(MqttProtocolViolationException))]
-        public void Invalid_Topic_Plus()
+        public void Invalid_Topic_Hash()
         {
-            MqttTopicValidator.ThrowIfInvalid("/a/+/c");
+            MqttTopicValidator.ThrowIfInvalid("/a/#/c");
         }
 
         [TestMethod]
         [ExpectedException(typeof(MqttProtocolViolationException))]
-        public void Invalid_Topic_Hash()
+        public void Invalid_Topic_Plus()
         {
-            MqttTopicValidator.ThrowIfInvalid("/a/#/c");
+            MqttTopicValidator.ThrowIfInvalid("/a/+/c");
         }
 
         [TestMethod]
-        [ExpectedException(typeof(MqttProtocolViolationException))]
-        public void Invalid_Topic_Empty()
+        public void Valid_Topic()
         {
-            MqttTopicValidator.ThrowIfInvalid(string.Empty);
+            MqttTopicValidator.ThrowIfInvalid("/a/b/c");
         }
     }
-}
+}
\ No newline at end of file

Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectOptions.cs

@@ -7,15 +7,15 @@ namespace MQTTnet.Client
     public sealed class MqttClientDisconnectOptions
     {
         /// <summary>
-        /// Gets or sets the reason code.
-        /// Hint: MQTT 5 feature only.
+        ///     Gets or sets the reason code.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public MqttClientDisconnectReason Reason { get; set; } = MqttClientDisconnectReason.NormalDisconnection;
 
         /// <summary>
-        /// Gets or sets the reason string.
-        /// Hint: MQTT 5 feature only.
+        ///     Gets or sets the reason string.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public string ReasonString { get; set; }
     }
-}
+}
\ No newline at end of file

Source/MQTTnet/Client/Disconnecting/MqttClientDisconnectOptionsValidator.cs

+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Linq;
+using MQTTnet.Formatter;
+
+namespace MQTTnet.Client
+{
+    public static class MqttClientDisconnectOptionsValidator
+    {
+        public static void ThrowIfNotSupported(MqttClientDisconnectOptions options, MqttProtocolVersion protocolVersion)
+        {
+            if (options == null)
+            {
+                throw new ArgumentNullException(nameof(options));
+            }
+
+            if (protocolVersion == MqttProtocolVersion.V500)
+            {
+                // Everything is supported.
+                return;
+            }
+
+            if (options.ReasonString?.Any() == true)
+            {
+                Throw(nameof(options.ReasonString));
+            }
+
+            if (options.Reason != MqttClientDisconnectReason.NormalDisconnection)
+            {
+                Throw(nameof(options.Reason));
+            }
+        }
+
+        static void Throw(string featureName)
+        {
+            throw new NotSupportedException($"Feature {featureName} requires MQTT version 5.0.0.");
+        }
+    }
+}
\ No newline at end of file

Source/MQTTnet/Client/MqttClient.cs

@@ -84,25 +84,15 @@ namespace MQTTnet.Client
             add => _inspectPacketEvent.AddHandler(value);
             remove => _inspectPacketEvent.RemoveHandler(value);
         }
-        
+
         public bool IsConnected => (MqttClientConnectionStatus)_connectionStatus == MqttClientConnectionStatus.Connected;
 
         public MqttClientOptions Options { get; private set; }
 
         public async Task<MqttClientConnectResult> ConnectAsync(MqttClientOptions options, CancellationToken cancellationToken = default)
         {
-            if (options == null)
-            {
-                throw new ArgumentNullException(nameof(options));
-            }
-
-            if (options.ChannelOptions == null)
-            {
-                throw new ArgumentException("ChannelOptions are not set.");
-            }
-
+            ThrowIfOptionsInvalid(options);
             ThrowIfConnected("It is not allowed to connect with a server after the connection is established.");
-
             ThrowIfDisposed();
 
             if (CompareExchangeConnectionStatus(MqttClientConnectionStatus.Connecting, MqttClientConnectionStatus.Disconnected) != MqttClientConnectionStatus.Disconnected)
@@ -197,7 +187,7 @@ namespace MQTTnet.Client
             {
                 return;
             }
-
+            
             try
             {
                 _disconnectReason = MqttClientDisconnectReason.NormalDisconnection;
@@ -205,6 +195,11 @@ namespace MQTTnet.Client
 
                 if (clientWasConnected)
                 {
+                    if (Options.ValidateFeatures)
+                    {
+                        MqttClientDisconnectOptionsValidator.ThrowIfNotSupported(options, _adapter.PacketFormatterAdapter.ProtocolVersion);
+                    }
+                    
                     var disconnectPacket = MqttPacketFactories.Disconnect.Create(options);
                     await SendAsync(disconnectPacket, cancellationToken).ConfigureAwait(false);
                 }
@@ -239,6 +234,11 @@ namespace MQTTnet.Client
             ThrowIfDisposed();
             ThrowIfNotConnected();
 
+            if (Options.ValidateFeatures)
+            {
+                MqttApplicationMessageValidator.ThrowIfNotSupported(applicationMessage, _adapter.PacketFormatterAdapter.ProtocolVersion);
+            }
+
             var publishPacket = MqttPacketFactories.Publish.Create(applicationMessage);
 
             switch (applicationMessage.QualityOfServiceLevel)
@@ -296,6 +296,11 @@ namespace MQTTnet.Client
                 MqttTopicValidator.ThrowIfInvalidSubscribe(topicFilter.Topic);
             }
 
+            if (Options.ValidateFeatures)
+            {
+                MqttClientSubscribeOptionsValidator.ThrowIfNotSupported(options, _adapter.PacketFormatterAdapter.ProtocolVersion);
+            }
+
             ThrowIfDisposed();
             ThrowIfNotConnected();
 
@@ -314,9 +319,19 @@ namespace MQTTnet.Client
                 throw new ArgumentNullException(nameof(options));
             }
 
+            foreach (var topicFilter in options.TopicFilters)
+            {
+                MqttTopicValidator.ThrowIfInvalidSubscribe(topicFilter);
+            }
+
             ThrowIfDisposed();
             ThrowIfNotConnected();
 
+            if (Options.ValidateFeatures)
+            {
+                MqttClientUnsubscribeOptionsValidator.ThrowIfNotSupported(options, _adapter.PacketFormatterAdapter.ProtocolVersion);
+            }
+
             var unsubscribePacket = MqttPacketFactories.Unsubscribe.Create(options);
             unsubscribePacket.PacketIdentifier = _packetIdentifierProvider.GetNextPacketIdentifier();
 
@@ -376,7 +391,7 @@ namespace MQTTnet.Client
                 var connAckPacket = await SendAndReceiveAsync<MqttConnAckPacket>(connectPacket, cancellationToken).ConfigureAwait(false);
 
                 var clientConnectResultFactory = new MqttClientConnectResultFactory();
-                result = clientConnectResultFactory.Create(connAckPacket, options.ProtocolVersion);
+                result = clientConnectResultFactory.Create(connAckPacket, _adapter.PacketFormatterAdapter.ProtocolVersion);
             }
             catch (Exception exception)
             {
@@ -705,6 +720,24 @@ namespace MQTTnet.Client
             }
         }
 
+        static void ThrowIfOptionsInvalid(MqttClientOptions options)
+        {
+            if (options == null)
+            {
+                throw new ArgumentNullException(nameof(options));
+            }
+
+            if (options.ChannelOptions == null)
+            {
+                throw new ArgumentException("ChannelOptions are not set.");
+            }
+
+            if (options.ValidateFeatures)
+            {
+                MqttClientOptionsValidator.ThrowIfNotSupported(options);
+            }
+        }
+
         void TryInitiateDisconnect()
         {
             lock (_disconnectLock)

Source/MQTTnet/Client/Options/MqttClientOptions.cs

@@ -14,13 +14,13 @@ namespace MQTTnet.Client
     {
         /// <summary>
         ///     Gets or sets the authentication data.
-        ///     Hint: MQTT 5 feature only.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public byte[] AuthenticationData { get; set; }
 
         /// <summary>
         ///     Gets or sets the authentication method.
-        ///     Hint: MQTT 5 feature only.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public string AuthenticationMethod { get; set; }
 
@@ -58,6 +58,10 @@ namespace MQTTnet.Client
         /// </summary>
         public TimeSpan KeepAlivePeriod { get; set; } = TimeSpan.FromSeconds(15);
 
+        /// <summary>
+        ///     Gets or sets the maximum packet size.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
+        /// </summary>
         public uint MaximumPacketSize { get; set; }
 
         public MqttProtocolVersion ProtocolVersion { get; set; } = MqttProtocolVersion.V311;
@@ -65,24 +69,26 @@ namespace MQTTnet.Client
         /// <summary>
         ///     Gets or sets the receive maximum.
         ///     This gives the maximum length of the receive messages.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public ushort ReceiveMaximum { get; set; }
 
         /// <summary>
         ///     Gets or sets the request problem information.
-        ///     Hint: MQTT 5 feature only.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public bool RequestProblemInformation { get; set; } = true;
 
         /// <summary>
         ///     Gets or sets the request response information.
-        ///     Hint: MQTT 5 feature only.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public bool RequestResponseInformation { get; set; }
 
         /// <summary>
         ///     Gets or sets the session expiry interval.
         ///     The time after a session expires when it's not actively used.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public uint SessionExpiryInterval { get; set; }
 
@@ -95,6 +101,7 @@ namespace MQTTnet.Client
         /// <summary>
         ///     Gets or sets the topic alias maximum.
         ///     This gives the maximum length of the topic alias.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public ushort TopicAliasMaximum { get; set; }
 
@@ -103,8 +110,10 @@ namespace MQTTnet.Client
         ///     client.
         ///     If successful, this means that loop detection will be more effective and that retained messages will be propagated
         ///     correctly.
-        ///     Not all brokers support this feature so it may be necessary to set it to false if your bridge does not connect
-        ///     properly.
+        ///     <remarks>
+        ///         Not all brokers support this feature so it may be necessary to set it to false if your bridge does not
+        ///         connect properly.
+        ///     </remarks>
         /// </summary>
         public bool TryPrivate { get; set; } = true;
 
@@ -115,28 +124,41 @@ namespace MQTTnet.Client
         ///     As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add
         ///     metadata to MQTT messages and pass information between publisher, broker, and subscriber.
         ///     The feature is very similar to the HTTP header concept.
-        ///     Hint: MQTT 5 feature only.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public List<MqttUserProperty> UserProperties { get; set; }
 
+        /// <summary>
+        ///     When this feature is enabled the client will check if used properties are supported in the selected protocol
+        ///     version.
+        ///     This feature can be validated if an application message is generated one time but sent via different protocol
+        ///     versions.
+        ///     Default values are applied if the validation is off and features are not supported.
+        /// </summary>
+        public bool ValidateFeatures { get; set; } = true;
+
         /// <summary>
         ///     Gets or sets the content type of the will message.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public string WillContentType { get; set; }
 
         /// <summary>
         ///     Gets or sets the correlation data of the will message.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public byte[] WillCorrelationData { get; set; }
 
         /// <summary>
         ///     Gets or sets the will delay interval.
         ///     This is the time between the client disconnect and the time the will message will be sent.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public uint WillDelayInterval { get; set; }
 
         /// <summary>
         ///     Gets or sets the message expiry interval of the will message.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public uint WillMessageExpiryInterval { get; set; }
 
@@ -147,8 +169,9 @@ namespace MQTTnet.Client
 
         /// <summary>
         ///     Gets or sets the payload format indicator of the will message.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
-        public MqttPayloadFormatIndicator WillPayloadFormatIndicator { get; set; }
+        public MqttPayloadFormatIndicator WillPayloadFormatIndicator { get; set; } = MqttPayloadFormatIndicator.Unspecified;
 
         /// <summary>
         ///     Gets or sets the QoS level of the will message.
@@ -157,6 +180,7 @@ namespace MQTTnet.Client
 
         /// <summary>
         ///     Gets or sets the response topic of the will message.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public string WillResponseTopic { get; set; }
 
@@ -172,6 +196,7 @@ namespace MQTTnet.Client
 
         /// <summary>
         ///     Gets or sets the user properties of the will message.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public List<MqttUserProperty> WillUserProperties { get; set; }
 

Source/MQTTnet/Client/Options/MqttClientOptionsBuilder.cs

@@ -74,6 +74,8 @@ namespace MQTTnet.Client
 
             _options.ChannelOptions = (IMqttClientChannelOptions)_tcpOptions ?? _webSocketOptions;
 
+            MqttClientOptionsValidator.ThrowIfNotSupported(_options);
+            
             return _options;
         }
 

Source/MQTTnet/Client/Options/MqttClientOptionsBuilderTlsParameters.cs

@@ -4,7 +4,6 @@
 
 using System;
 using System.Collections.Generic;
-using System.Net.Security;
 using System.Security.Authentication;
 using System.Security.Cryptography.X509Certificates;
 
@@ -13,7 +12,7 @@ namespace MQTTnet.Client
     public sealed class MqttClientOptionsBuilderTlsParameters
     {
         public bool UseTls { get; set; }
-        
+
         public Func<MqttClientCertificateValidationEventArgs, bool> CertificateValidationHandler { get; set; }
 
 #if NET48 || NETCOREAPP3_1 || NET5 || NET6
@@ -29,13 +28,13 @@ namespace MQTTnet.Client
 #endif
 
 #if NETCOREAPP3_1 || NET5_0_OR_GREATER
-        public List<SslApplicationProtocol> ApplicationProtocols { get;set; }
+        public List<System.Net.Security.SslApplicationProtocol> ApplicationProtocols { get; set; }
 #endif
 
-	    public bool AllowUntrustedCertificates { get; set; }
+        public bool AllowUntrustedCertificates { get; set; }
 
         public bool IgnoreCertificateChainErrors { get; set; }
 
         public bool IgnoreCertificateRevocationErrors { get; set; }
     }
-}
+}
\ No newline at end of file

Source/MQTTnet/Client/Options/MqttClientOptionsValidator.cs

+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Linq;
+using MQTTnet.Formatter;
+using MQTTnet.Protocol;
+
+namespace MQTTnet.Client
+{
+    public static class MqttClientOptionsValidator
+    {
+        public static void ThrowIfNotSupported(MqttClientOptions options)
+        {
+            if (options == null)
+            {
+                throw new ArgumentNullException(nameof(options));
+            }
+
+            if (options.ProtocolVersion == MqttProtocolVersion.V500)
+            {
+                // Everything is supported.
+                return;
+            }
+            
+            if (options.WillContentType?.Any() == true)
+            {
+                Throw(nameof(options.WillContentType));
+            }
+
+            if (options.UserProperties?.Any() == true)
+            {
+                Throw(nameof(options.UserProperties));
+            }
+
+            if (options.RequestProblemInformation)
+            {
+                // Since this value is a boolean and true by default, validation would
+                // require a nullable boolean.
+                //Throw(nameof(options.RequestProblemInformation));
+            }
+
+            if (options.RequestResponseInformation)
+            {
+                Throw(nameof(options.RequestResponseInformation));
+            }
+
+            if (options.ReceiveMaximum > 0)
+            {
+                Throw(nameof(options.ReceiveMaximum));
+            }
+            
+            if (options.MaximumPacketSize > 0)
+            {
+                Throw(nameof(options.MaximumPacketSize));
+            }
+
+            // Authentication relevant properties.
+            
+            if (options.AuthenticationData?.Any() == true)
+            {
+                Throw(nameof(options.AuthenticationData));
+            }
+
+            if (options.AuthenticationMethod?.Any() == true)
+            {
+                Throw(nameof(options.AuthenticationMethod));
+            }
+
+            // Will relevant properties.
+            
+            if (options.WillPayloadFormatIndicator != MqttPayloadFormatIndicator.Unspecified)
+            {
+                Throw(nameof(options.WillPayloadFormatIndicator));
+            }
+
+            if (options.WillContentType?.Any() == true)
+            {
+                Throw(nameof(options.WillContentType));
+            }
+
+            if (options.WillCorrelationData?.Any() == true)
+            {
+                Throw(nameof(options.WillCorrelationData));
+            }
+            
+            if (options.WillResponseTopic?.Any() == true)
+            {
+                Throw(nameof(options.WillResponseTopic));
+            }
+            
+            if (options.WillDelayInterval > 0)
+            {
+                Throw(nameof(options.WillDelayInterval));
+            }
+            
+            if (options.WillMessageExpiryInterval > 0)
+            {
+                Throw(nameof(options.WillMessageExpiryInterval));
+            }
+            
+            if (options.WillUserProperties?.Any() == true)
+            {
+                Throw(nameof(options.WillUserProperties));
+            }
+        }
+
+        static void Throw(string featureName)
+        {
+            throw new NotSupportedException($"Feature {featureName} requires MQTT version 5.0.0.");
+        }
+    }
+}
\ No newline at end of file

Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptions.cs

@@ -10,27 +10,31 @@ namespace MQTTnet.Client
     public sealed class MqttClientSubscribeOptions
     {
         /// <summary>
-        /// Gets or sets a list of topic filters the client wants to subscribe to.
-        /// Topic filters can include regular topics or wild cards.
+        ///     Gets or sets the subscription identifier.
+        ///     The client can specify a subscription identifier when subscribing.
+        ///     The broker will establish and store the mapping relationship between this subscription and subscription identifier
+        ///     when successfully create or modify subscription.
+        ///     The broker will return the subscription identifier associated with this PUBLISH packet and the PUBLISH packet to
+        ///     the client when need to forward PUBLISH packets matching this subscription to this client.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
-        public List<MqttTopicFilter> TopicFilters { get; set; } = new List<MqttTopicFilter>();
+        public uint SubscriptionIdentifier { get; set; }
 
         /// <summary>
-        /// Gets or sets the subscription identifier.
-        /// The client can specify a subscription identifier when subscribing.
-        /// The broker will establish and store the mapping relationship between this subscription and subscription identifier when successfully create or modify subscription.
-        /// The broker will return the subscription identifier associated with this PUBLISH packet and the PUBLISH packet to the client when need to forward PUBLISH packets matching this subscription to this client.
-        /// Hint: MQTT 5 feature only.
+        ///     Gets or sets a list of topic filters the client wants to subscribe to.
+        ///     Topic filters can include regular topics or wild cards.
         /// </summary>
-        public uint SubscriptionIdentifier { get; set; }
+        public List<MqttTopicFilter> TopicFilters { get; set; } = new List<MqttTopicFilter>();
 
         /// <summary>
-        /// Gets or sets the user properties.
-        /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet.
-        /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber.
-        /// The feature is very similar to the HTTP header concept.
-        /// Hint: MQTT 5 feature only.
+        ///     Gets or sets the user properties.
+        ///     In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT
+        ///     packet.
+        ///     As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add
+        ///     metadata to MQTT messages and pass information between publisher, broker, and subscriber.
+        ///     The feature is very similar to the HTTP header concept.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public List<MqttUserProperty> UserProperties { get; set; }
     }
-}
+}
\ No newline at end of file

Source/MQTTnet/Client/Subscribing/MqttClientSubscribeOptionsValidator.cs

+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Linq;
+using MQTTnet.Formatter;
+using MQTTnet.Protocol;
+
+namespace MQTTnet.Client
+{
+    public static class MqttClientSubscribeOptionsValidator
+    {
+        public static void ThrowIfNotSupported(MqttClientSubscribeOptions options, MqttProtocolVersion protocolVersion)
+        {
+            if (options == null)
+            {
+                throw new ArgumentNullException(nameof(options));
+            }
+            
+            if (protocolVersion == MqttProtocolVersion.V500)
+            {
+                // Everything is supported.
+                return;
+            }
+
+            if (options.UserProperties?.Any() == true)
+            {
+                Throw(nameof(options.UserProperties));
+            }
+            
+            if (options.SubscriptionIdentifier != 0)
+            {
+                Throw(nameof(options.SubscriptionIdentifier));
+            }
+            
+            if (options.TopicFilters?.Any(t => t.NoLocal) == true)
+            {
+                Throw("NoLocal");
+            }
+            
+            if (options.TopicFilters?.Any(t => t.RetainAsPublished) == true)
+            {
+                Throw("RetainAsPublished");
+            }
+            
+            if (options.TopicFilters?.Any(t => t.RetainHandling != MqttRetainHandling.SendAtSubscribe) == true)
+            {
+                Throw("RetainHandling");
+            }
+        }
+        
+        static void Throw(string featureName)
+        {
+            throw new NotSupportedException($"Feature {featureName} requires MQTT version 5.0.0.");
+        }
+    }
+}
\ No newline at end of file

Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptions.cs

@@ -10,18 +10,20 @@ namespace MQTTnet.Client
     public sealed class MqttClientUnsubscribeOptions
     {
         /// <summary>
-        /// Gets or sets a list of topic filters the client wants to unsubscribe from.
-        /// Topic filters can include regular topics or wild cards.
+        ///     Gets or sets a list of topic filters the client wants to unsubscribe from.
+        ///     Topic filters can include regular topics or wild cards.
         /// </summary>
         public List<string> TopicFilters { get; set; } = new List<string>();
 
         /// <summary>
-        /// Gets or sets the user properties.
-        /// In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT packet.
-        /// As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add metadata to MQTT messages and pass information between publisher, broker, and subscriber.
-        /// The feature is very similar to the HTTP header concept.
-        /// Hint: MQTT 5 feature only.
+        ///     Gets or sets the user properties.
+        ///     In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to almost every type of MQTT
+        ///     packet.
+        ///     As long as you don’t exceed the maximum message size, you can use an unlimited number of user properties to add
+        ///     metadata to MQTT messages and pass information between publisher, broker, and subscriber.
+        ///     The feature is very similar to the HTTP header concept.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
-        public List<MqttUserProperty> UserProperties { get; set; } = new List<MqttUserProperty>();
+        public List<MqttUserProperty> UserProperties { get; set; }
     }
-}
+}
\ No newline at end of file

Source/MQTTnet/Client/Unsubscribing/MqttClientUnsubscribeOptionsValidator.cs

+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Linq;
+using MQTTnet.Formatter;
+
+namespace MQTTnet.Client
+{
+    public static class MqttClientUnsubscribeOptionsValidator
+    {
+        public static void ThrowIfNotSupported(MqttClientUnsubscribeOptions options, MqttProtocolVersion protocolVersion)
+        {
+            if (options == null)
+            {
+                throw new ArgumentNullException(nameof(options));
+            }
+
+            if (protocolVersion == MqttProtocolVersion.V500)
+            {
+                // Everything is supported.
+                return;
+            }
+
+            if (options.UserProperties?.Any() == true)
+            {
+                Throw(nameof(options.UserProperties));
+            }
+        }
+
+        static void Throw(string featureName)
+        {
+            throw new NotSupportedException($"Feature {featureName} requires MQTT version 5.0.0.");
+        }
+    }
+}
\ No newline at end of file

Source/MQTTnet/MqttApplicationMessageValidator.cs

+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Linq;
+using MQTTnet.Formatter;
+using MQTTnet.Protocol;
+
+namespace MQTTnet
+{
+    public static class MqttApplicationMessageValidator
+    {
+        public static void ThrowIfNotSupported(MqttApplicationMessage applicationMessage, MqttProtocolVersion protocolVersion)
+        {
+            if (applicationMessage == null)
+            {
+                throw new ArgumentNullException(nameof(applicationMessage));
+            }
+
+            if (protocolVersion == MqttProtocolVersion.V500)
+            {
+                // Everything is supported.
+                return;
+            }
+
+            if (applicationMessage.ContentType?.Any() == true)
+            {
+                Throw(nameof(applicationMessage.ContentType));
+            }
+            
+            if (applicationMessage.UserProperties?.Any() == true)
+            {
+                Throw(nameof(applicationMessage.UserProperties));
+            }
+            
+            if (applicationMessage.CorrelationData?.Any() == true)
+            {
+                Throw(nameof(applicationMessage.CorrelationData));
+            }
+            
+            if (applicationMessage.ResponseTopic?.Any() == true)
+            {
+                Throw(nameof(applicationMessage.ResponseTopic));
+            }
+            
+            if (applicationMessage.SubscriptionIdentifiers?.Any() == true)
+            {
+                Throw(nameof(applicationMessage.SubscriptionIdentifiers));
+            }
+            
+            if (applicationMessage.TopicAlias > 0)
+            {
+                Throw(nameof(applicationMessage.TopicAlias));
+            }
+            
+            if (applicationMessage.PayloadFormatIndicator != MqttPayloadFormatIndicator.Unspecified)
+            {
+                Throw(nameof(applicationMessage.PayloadFormatIndicator));
+            }
+        }
+        
+        static void Throw(string featureName)
+        {
+            throw new NotSupportedException($"Feature {featureName} requires MQTT version 5.0.0.");
+        }
+    }
+}
\ No newline at end of file

Source/MQTTnet/Packets/MqttTopicFilter.cs

@@ -10,8 +10,8 @@ namespace MQTTnet.Packets
     {
         /// <summary>
         ///     Gets or sets a value indicating whether the sender will not receive its own published application messages.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
-        /// Hint: MQTT 5 feature only.
         public bool NoLocal { get; set; }
 
         /// <summary>
@@ -27,15 +27,15 @@ namespace MQTTnet.Packets
 
         /// <summary>
         ///     Gets or sets a value indicating whether messages are retained as published or not.
-        ///     Hint: MQTT 5 feature only.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
         public bool RetainAsPublished { get; set; }
 
         /// <summary>
         ///     Gets or sets the retain handling.
-        ///     Hint: MQTT 5 feature only.
+        ///     <remarks>MQTT 5.0.0+ feature.</remarks>
         /// </summary>
-        public MqttRetainHandling RetainHandling { get; set; }
+        public MqttRetainHandling RetainHandling { get; set; } = MqttRetainHandling.SendAtSubscribe;
 
         /// <summary>
         ///     Gets or sets the MQTT topic.

Source/MQTTnet/Protocol/MqttTopicValidator.cs

@@ -11,7 +11,10 @@ namespace MQTTnet.Protocol
     {
         public static void ThrowIfInvalid(MqttApplicationMessage applicationMessage)
         {
-            if (applicationMessage == null) throw new ArgumentNullException(nameof(applicationMessage));
+            if (applicationMessage == null)
+            {
+                throw new ArgumentNullException(nameof(applicationMessage));
+            }
 
             if (applicationMessage.TopicAlias == 0)
             {
@@ -26,7 +29,7 @@ namespace MQTTnet.Protocol
                 throw new MqttProtocolViolationException("Topic should not be empty.");
             }
 
-            foreach(var @char in topic)
+            foreach (var @char in topic)
             {
                 if (@char == '+')
                 {
@@ -54,4 +57,4 @@ namespace MQTTnet.Protocol
             }
         }
     }
-}
+}
\ No newline at end of file