From 4e5661e7533e8fa0cd00d1c2bfc6df71802356a3 Mon Sep 17 00:00:00 2001
From: Simon Thum <sthum@meddv.de>
Date: Fri, 14 Jun 2024 20:59:37 +0200
Subject: [PATCH] Topic templates: add README

---
 .../MQTTnet.Extensions.TopicTemplate.csproj   | 10 ++-
 .../README.md                                 | 79 +++++++++++++++++++
 2 files changed, 86 insertions(+), 3 deletions(-)
 create mode 100644 Source/MQTTnet.Extensions.TopicTemplate/README.md

diff --git a/Source/MQTTnet.Extensions.TopicTemplate/MQTTnet.Extensions.TopicTemplate.csproj b/Source/MQTTnet.Extensions.TopicTemplate/MQTTnet.Extensions.TopicTemplate.csproj
index d1c50d7d0..14d653c04 100644
--- a/Source/MQTTnet.Extensions.TopicTemplate/MQTTnet.Extensions.TopicTemplate.csproj
+++ b/Source/MQTTnet.Extensions.TopicTemplate/MQTTnet.Extensions.TopicTemplate.csproj
@@ -11,10 +11,10 @@
         <Company>The contributors of MQTTnet</Company>
         <Product>MQTTnet</Product>
         <Description>
-           This is an extension library which provides mqtt topic templating logic to support dispatch,
-           routing and similar functionality based on the well known moustache syntax, aka
-           AsyncAPI dynamic channel address.
+           Provides mqtt topic templating logic to support dispatch,
+           routing and similar functionality based on the well known moustache syntax (AsyncAPI compatible).
         </Description>
+		<PackageReadmeFile>README.md</PackageReadmeFile>
         <Authors>The contributors of MQTTnet</Authors>
         <PackageId>MQTTnet.Extensions.TopicTemplate</PackageId>
         <SignAssembly>false</SignAssembly>
@@ -51,6 +51,10 @@
     </PropertyGroup>
 
     <ItemGroup>
+        <None Include="README.md">
+            <Pack>True</Pack>
+            <PackagePath>\</PackagePath>
+        </None>
         <None Include="..\..\Images\nuget.png">
             <Pack>True</Pack>
             <PackagePath>\</PackagePath>
diff --git a/Source/MQTTnet.Extensions.TopicTemplate/README.md b/Source/MQTTnet.Extensions.TopicTemplate/README.md
new file mode 100644
index 000000000..35935b3be
--- /dev/null
+++ b/Source/MQTTnet.Extensions.TopicTemplate/README.md
@@ -0,0 +1,79 @@
+# MQTTNet.Extensions.TopicTemplate
+
+Provides mqtt topic templating logic to support dispatch, routing and
+similar functionality based on the well known moustache syntax, aka
+AsyncAPI dynamic channel address.
+
+Generating and parsing MQTT topics and topic filters is often done in
+an ad-hoc fashion, leading to error-prone code and subtly introduced
+showstoppers like forgetting to strip a slash from a parameter.  To
+remedy, this extension aids you write safe, maintainable logic
+for topic generation, routing and dispatch.
+
+
+## How it works
+
+The package lets you write MQTTNet code like:
+```csharp
+var template = new MqttTopicTemplate("App/v1/{sender}/message");
+
+var filter = new MqttTopicFilterBuilder()
+    .WithTopicTemplate(template) // (1)
+    .WithAtLeastOnceQoS()
+    .WithNoLocal()
+    .Build();
+
+// filter.Topic == "App/v1/+/message"
+
+var myTopic = template
+    .WithParameter("sender", "me, myself & i"); // (2)
+
+var message = new MqttApplicationMessageBuilder()
+    .WithTopicTemplate(  // (3)
+        myTopic)
+    .WithPayload("Hello!")
+    .Build();
+
+// message.Topic == "App/v1/me, myself & i/message"
+
+Assert.IsTrue(message.MatchesTopicTemplate(template)); // (4)
+```
+
+At (1), the parameter "sender" was automatically replaced by a plus sign
+(single level wildcard) because the caller is creating a topic filter.
+
+Using the same template (they are immutable), you can send
+a message. At (2), we replace the parameter with a known value.
+If that value contained a level separator or topic filter only
+characters, we'd get an ArgumentException. If we forgot to replace
+the parameter "sender" (e.g. when placing template not myTopic),
+we would be prevented from sending at (3).
+
+On the receiving side, a message can be matched to a template
+using code like at (4).
+
+These daily tasks become much safer and easier to code than 
+string.Format() and Split() allow for. More elaborate computation is supported
+too. You could extract the sender using the template or route
+messages based on topic content.
+
+## Features
+
+- Safe handling of topic parameters in moustache syntax
+- Simplifies topic generation and parsing logic
+- Match topics and extract the values of their parameters
+- Translate between topic templates to ease dynamic routing
+- Derive a canonical topic filter from a bunch of templates
+- Integrates with MQTTNet message, subscription and filter builders
+- Extension method friendly (sealed class with one public ctor)
+
+## Additional documentation
+
+- Some of the [unit tests](https://github.com/dotnet/MQTTnet/blob/master/Source/MQTTnet.Tests/Extensions/MqttTopicTemplate_Tests.cs) are instructive
+- Some examples feature the extension, e.g. TopicGenerator, Client_Subscribe_Samples
+
+## Feedback
+
+Report any issues with the main project on https://github.com/dotnet/MQTTnet/issues
+
+