> For the complete documentation index, see [llms.txt](https://pbouillon.gitbook.io/mqtttopicbuilder/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pbouillon.gitbook.io/mqtttopicbuilder/master.md).

# MqttTopicBuilder

## Overview

MqttTopicBuilder is a library that aims to provide a **robust context for MQTT topics handling** for developers.

Made with .NET Standard 2.0, chances are that [your application will be compatible](https://docs.microsoft.com/en-us/dotnet/standard/net-standard#net-implementation-support) (Minimum supported platforms: .NET Core 2.0+ and .NET Framework 4.6.1)

You can use it seamlessly in your application, both for your subscribers and publishers by using the builder's fluent API:

```csharp
var topic = new TopicBuilder(TopicConsumer.Subscriber)
    .AddTopic("Hello")
    .AddTopic("From")
    .AddTopics("Mqtt", "Topic", "Builder")
    .AddMultiLevelWildcard()
    .Build();

Console.WriteLine(topic);
// -> "Hello/From/Mqtt/Topic/Builder/#"
```

### Why ?

MQTT topics are raw strings by default. However, they do embed quite a lot of logic such as their level, wildcards or even their own structure. Moreover, they have to follow [some very strict rules](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901107), which can be a burden to developers to test, parse or maintain.

MqttTopicBuilder provides a bunch of tools in order to help developers to **manipulate strongly typed MQTT topics** objects instead of those strings.

This tools also handle all compliance checks with the MQTT specification regarding how the topic should be built: let us spend time on the tedious tasks so you can use more of yours to build awesome and robust applications !

## Installation

### NuGet package

In order to use this library, you should use [MqttTopicBuilder with NuGet](https://www.nuget.org/packages/MqttTopicBuilder/)

```aspnet
Install-Package MqttTopicBuilder
```

You can also use the dotnet cli

```aspnet
dotnet add package MqttTopicBuilder
```

### Local clone

To set up your own clone, simply clone the project from the main repository (or from your own fork)

```aspnet
git clone https://github.com/pBouillon/MqttTopicBuilder
```