<commit_before># Serialization plugins for SlimMessageBus <!-- omit in toc -->

Please read the [Introduction](intro.md) before reading this provider documentation.

- [Configuration](#configuration)
- [Json](#json)
- [Avro](#avro)
- [GoogleProtobuf](#googleprotobuf)
- [Hybrid](#hybrid)

## Configuration

Part of message bus configuration is choosing the serialization plugin:

```cs
// Use JSON for message serialization
IMessageSerializer serializer = new JsonMessageSerializer();

// MessageBusBuilder mbb;
mbb.    
   .WithSerializer(serializer)
```

> One serializer instance will be used across all the concurently running tasks of producing and consuming messages in a given bus instance. The serializers are designed, so that they are Thread-safe.

## Json

Nuget package: [SlimMessageBus.Host.Serialization.Json](https://www.nuget.org/packages/SlimMessageBus.Host.Serialization.Json)

The Json plugin brings in JSON serialization using the [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json) library.

To use it install the nuget package `SlimMessageBus.Host.Serialization.Json` and then configure the bus:

```cs
var jsonSerializer = new JsonMessageSerializer();
mbb.WithSerializer(jsonSerializer);
```

This will apply the `Newtonsoft.Json` default serialization settings and will use `UTF8` encoding for converting `string` to `byte[]`.

In order to customize how messages are formatted use the alternative constructor:

```cs
var jsonSerializerSettings = new Newtonsoft.Json.JsonSerializerSettings
   {
      TypeNameHandling = Newtonsoft.Json.TypeNameHandling.Objects
   };

var jsonSerializer = new JsonMessageSerializer(jsonSerializerSettings, Encoding.UTF8)
```

## Native Json

Nuget package: [SlimMessageBus.Host.Serialization.NativeJson](https://www.nuget.org/packages/SlimMessageBus.Host.Serialization.NativeJson)

The Json plugin brings in JSON serialization using the [System.Text.Json](https://www.nuget.org/packages/System.Text.Json) library.

To use it install the nuget package `SlimMessageBus.Host.Serialization.NativeJson` and then configure the bus similar to Json above.

## Avro

Nuget package: [SlimMessageBus.Host.Serialization.Avro](https://www.nuget.org/packages/SlimMessageBus.Host.Serialization.Avro)

The Avro plugin brings in the [Apache Avro](https://avro.apache.org/) binary serialization using the [Apache.Avro](https://www.nuget.org/packages/Apache.Avro/) library.

To use it install the nuget package `SlimMessageBus.Host.Serialization.Avro` and then configure the bus:

```cs
var avroSerializer = new AvroMessageSerializer();
mbb.WithSerializer(avroSerializer);
```

The Apache.Avro library requires each of your serialized messages to implement the interface `Avro.Specific.ISpecificRecord`. That interface requires to provide the `Avro.Schema` object as well as is responsible for serializing and deserializing the message.

The typical approach for working with Avro is to create the contract first using the [Avro IDL contract](https://avro.apache.org/docs/current/idl.html) and then generating the respective C# classes that represent messages. The sample [Sample.Serialization.MessagesAvro](../src/Samples/Sample.Serialization.MessagesAvro) shows how to generate C# classes having the IDL contract. Consult the sample for more details. 

There are ways to customize the `AvroMessageSerializer` by providing strategies for message creation and Avro schema lookup (for reader and writer):<commit_msg>Improve docs<commit_after># Serialization plugins for SlimMessageBus <!-- omit in toc -->

Please read the [Introduction](intro.md) before reading this provider documentation.

- [Configuration](#configuration)
- [Json (Newtonsoft.Json)](#json-newtonsoftjson)
- [Json (System.Text.Json)](#json-systemtextjson)
- [Avro](#avro)
- [GoogleProtobuf](#googleprotobuf)
- [Hybrid](#hybrid)

## Configuration

Part of message bus configuration is choosing the serialization plugin:

```cs
// Use JSON for message serialization
IMessageSerializer serializer = new JsonMessageSerializer();

// MessageBusBuilder mbb;
mbb.    
   .WithSerializer(serializer)
```

> One serializer instance will be used across all the concurently running tasks of producing and consuming messages in a given bus instance. The serializers are designed, so that they are Thread-safe.

## Json (Newtonsoft.Json)

Nuget package: [SlimMessageBus.Host.Serialization.Json](https://www.nuget.org/packages/SlimMessageBus.Host.Serialization.Json)

The Json plugin brings in JSON serialization using the [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json) library.

To use it install the nuget package `SlimMessageBus.Host.Serialization.Json` and then configure the bus:

```cs
var jsonSerializer = new JsonMessageSerializer();
mbb.WithSerializer(jsonSerializer);
```

This will apply the `Newtonsoft.Json` default serialization settings and will use `UTF8` encoding for converting `string` to `byte[]`.

In order to customize how messages are formatted use the alternative constructor:

```cs
var jsonSerializerSettings = new Newtonsoft.Json.JsonSerializerSettings
   {
      TypeNameHandling = Newtonsoft.Json.TypeNameHandling.Objects
   };

var jsonSerializer = new JsonMessageSerializer(jsonSerializerSettings, Encoding.UTF8)
```

## Json (System.Text.Json)

Nuget package: [SlimMessageBus.Host.Serialization.NativeJson](https://www.nuget.org/packages/SlimMessageBus.Host.Serialization.NativeJson)

The Json plugin brings in JSON serialization using the [System.Text.Json](https://www.nuget.org/packages/System.Text.Json) library.

To use it install the nuget package `SlimMessageBus.Host.Serialization.NativeJson` and then configure the bus similar to Json above.

## Avro

Nuget package: [SlimMessageBus.Host.Serialization.Avro](https://www.nuget.org/packages/SlimMessageBus.Host.Serialization.Avro)

The Avro plugin brings in the [Apache Avro](https://avro.apache.org/) binary serialization using the [Apache.Avro](https://www.nuget.org/packages/Apache.Avro/) library.

To use it install the nuget package `SlimMessageBus.Host.Serialization.Avro` and then configure the bus:

```cs
var avroSerializer = new AvroMessageSerializer();
mbb.WithSerializer(avroSerializer);
```

The Apache.Avro library requires each of your serialized messages to implement the interface `Avro.Specific.ISpecificRecord`. That interface requires to provide the `Avro.Schema` object as well as is responsible for serializing and deserializing the message.

The typical approach for working with Avro is to create the contract first using the [Avro IDL contract](https://avro.apache.org/docs/current/idl.html) and then generating the respective C# classes that represent messages. The sample [Sample.Serialization.MessagesAvro](../src/Samples/Sample.Serialization.MessagesAvro) shows how to generate C# classes having the IDL contract. Consult the sample for more details. 

There are ways to customize the `AvroMessageSerializer` by providing strategies for message creation and Avro schema lookup (for reader and writer):
{'fraction_non_alphanumeric': 0.0925610448608745, 'fraction_numerical': 0.0005678591709256105, 'mean_word_length': 5.487108655616943, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 7, 'https://': 16, 'lorem ipsum': 0, 'www.': 12, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7421846', 'n_tokens_mistral': 1923, 'n_tokens_neox': 1877, 'n_words': 654}