MQTTnet.Extensions.TopicTemplate 4.3.7.1207

.NET 5.0 This package targets .NET 5.0. The package is compatible with this framework or higher. .NET Core 3.1 This package targets .NET Core 3.1. The package is compatible with this framework or higher. .NET Standard 1.3 This package targets .NET Standard 1.3. The package is compatible with this framework or higher. .NET Framework 4.5.2 This package targets .NET Framework 4.5.2. The package is compatible with this framework or higher.
There is a newer prerelease version of this package available.
See the version list below for details. 
dotnet add package MQTTnet.Extensions.TopicTemplate --version 4.3.7.1207                

                    
                

            
NuGet\Install-Package MQTTnet.Extensions.TopicTemplate -Version 4.3.7.1207
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="MQTTnet.Extensions.TopicTemplate" Version="4.3.7.1207" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add MQTTnet.Extensions.TopicTemplate --version 4.3.7.1207                

                    
                

            
#r "nuget: MQTTnet.Extensions.TopicTemplate, 4.3.7.1207"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
// Install MQTTnet.Extensions.TopicTemplate as a Cake Addin
#addin nuget:?package=MQTTnet.Extensions.TopicTemplate&version=4.3.7.1207

// Install MQTTnet.Extensions.TopicTemplate as a Cake Tool
#tool nuget:?package=MQTTnet.Extensions.TopicTemplate&version=4.3.7.1207

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:

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 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

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp1.0 was computed.  netcoreapp1.1 was computed.  netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 is compatible. 
.NET Standard netstandard1.3 is compatible.  netstandard1.4 was computed.  netstandard1.5 was computed.  netstandard1.6 was computed.  netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net452 is compatible.  net46 was computed.  net461 is compatible.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 is compatible.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen30 was computed.  tizen40 was computed.  tizen60 was computed. 
Universal Windows Platform uap was computed.  uap10.0 was computed.  uap10.0.10240 is compatible. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
5.0.0.1214-RC 31 9/22/2024
4.3.7.1207 495 9/7/2024
4.3.6.1152 685 7/30/2024
4.3.5.1141 992 5/19/2024
4.3.4.1084 190 5/14/2024

For release notes please go to MQTTnet release notes (MQTTnet).