Utility class supporting dynamic topics using topic templates (#1932)

* Add MqttTopicTemplate

The topic template class is a way to deal with dynamic topics that
is less cumbersome and error-prone than String.Format or
other string fu one might use to handle dynamic topics.

Example:

  MyCity/{street}/{crossing}/lights

'street' and 'crossing' would be parameters.

The class and its extension methods are intended to support
dynamic subscription/publication, message-topic matching and
routing. The template syntax is modelled after the well-known
moustache syntax, which conincidentally is also published
as the 'AsyncAPI channel address expressions'.

* Add MQTTnet.Extensions.TopicTemplate to solution

* Apply code style from team shared resharper settings.
Add missing file headers.

* Update release notes

---------

Co-authored-by: christian <6939810+chkr1011@users.noreply.github.com>

Source/MQTTnet.Extensions.TopicTemplate/TopicTemplateExtensions.cs

@@ -0,0 +1,151 @@
+// 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.Protocol;
+
+namespace MQTTnet.Extensions.TopicTemplate
+{
+    public static class TopicTemplateExtensions
+    {
+        /// <summary>
+        ///     Modify this message builder to respond to a given message. The
+        ///     message's response topic and correlation data are included
+        ///     in the message builder.
+        /// </summary>
+        /// <param
+        ///     name="builder">
+        ///     a message builder
+        /// </param>
+        /// <param
+        ///     name="message">
+        ///     a message with a response topic
+        /// </param>
+        /// <returns>a message builder</returns>
+        /// <see
+        ///     cref="BuildResponse" />
+        public static MqttApplicationMessageBuilder AsResponseTo(this MqttApplicationMessageBuilder builder, MqttApplicationMessage message)
+        {
+            if (!string.IsNullOrEmpty(message.ResponseTopic))
+            {
+                throw new ArgumentException("message does not have a response topic");
+            }
+            
+            return builder.WithTopic(message.ResponseTopic).WithCorrelationData(message.CorrelationData);
+        }
+        
+        /// <summary>
+        ///     Set the filter topic according to the template, with
+        ///     remaining template parameters substituted by single-level
+        ///     wildcard.
+        /// </summary>
+        /// <param
+        ///     name="builder">
+        ///     a filter builder
+        /// </param>
+        /// <param
+        ///     name="topicTemplate">
+        ///     a topic template
+        /// </param>
+        /// <param
+        ///     name="subscribeTreeRoot">
+        ///     whether to subscribe to the whole topic tree
+        /// </param>
+        /// <returns>the modified topic filter</returns>
+        public static MqttTopicFilterBuilder BuildFilter(this MqttTopicTemplate topicTemplate, bool subscribeTreeRoot = false)
+        {
+            return new MqttTopicFilterBuilder().WithTopicTemplate(topicTemplate, subscribeTreeRoot);
+        }
+        
+        /// <summary>
+        ///     Return a message builder to respond to this message. The
+        ///     message's response topic and correlation data are included
+        ///     in the response message builder.
+        /// </summary>
+        /// <param
+        ///     name="message">
+        ///     a message with a response topic
+        /// </param>
+        /// <returns>a message builder</returns>
+        /// <see
+        ///     cref="AsResponseTo" />
+        public static MqttApplicationMessageBuilder BuildResponse(this MqttApplicationMessage message)
+        {
+            return new MqttApplicationMessageBuilder().AsResponseTo(message);
+        }
+        
+        /// <summary>
+        ///     Return whether the message matches the given topic template.
+        /// </summary>
+        /// <param
+        ///     name="message">
+        ///     a message
+        /// </param>
+        /// <param
+        ///     name="topicTemplate">
+        ///     a topic template
+        /// </param>
+        /// <param
+        ///     name="subtree">
+        ///     whether to include the topic subtree
+        /// </param>
+        /// <returns></returns>
+        public static bool MatchesTopicTemplate(this MqttApplicationMessage message, MqttTopicTemplate topicTemplate, bool subtree = false)
+        {
+            return topicTemplate.MatchesTopic(message.Topic, subtree);
+        }
+        
+        /// <summary>
+        ///     Set the filter topic according to the template, with
+        ///     template parameters substituted by a single-level
+        ///     wildcard.
+        /// </summary>
+        /// <param
+        ///     name="builder">
+        ///     a filter builder
+        /// </param>
+        /// <param
+        ///     name="topicTemplate">
+        ///     a topic template
+        /// </param>
+        /// <param
+        ///     name="subscribeTreeRoot">
+        ///     whether to subscribe to the whole topic tree
+        /// </param>
+        /// <returns>the modified topic filter</returns>
+        public static MqttTopicFilterBuilder WithTopicTemplate(this MqttTopicFilterBuilder builder, MqttTopicTemplate topicTemplate, bool subscribeTreeRoot = false)
+        {
+            return builder.WithTopic(subscribeTreeRoot ? topicTemplate.TopicTreeRootFilter : topicTemplate.TopicFilter);
+        }
+        
+        /// <summary>
+        ///     Set the publication topic according to the topic template. The template
+        ///     must not have remaining (unset) parameters or contain wildcards.
+        /// </summary>
+        /// <param
+        ///     name="builder">
+        ///     a message builder
+        /// </param>
+        /// <param
+        ///     name="topicTemplate">
+        ///     a parameterless topic template
+        /// </param>
+        /// <returns>the modified message builder</returns>
+        /// <exception
+        ///     cref="ArgumentException">
+        ///     if the topic template has parameters
+        /// </exception>
+        public static MqttApplicationMessageBuilder WithTopicTemplate(this MqttApplicationMessageBuilder builder, MqttTopicTemplate topicTemplate)
+        {
+            if (topicTemplate.Parameters.Any())
+            {
+                throw new ArgumentException("topic templates must be parameter-less when sending " + topicTemplate.Template);
+            }
+            
+            MqttTopicValidator.ThrowIfInvalid(topicTemplate.Template);
+            return builder.WithTopic(topicTemplate.Template);
+        }
+    }
+}