Newtonsoft Formatter¶

ServiceBus.Formatters.Newtonsoft provides formatter and serializer implementations based on Newtonsoft.Json.

Package¶

dotnet add package ServiceBus.Formatters.Newtonsoft

Main Components¶

classDiagram

    class IDataFormatter
    class IJsonSerializer

    class JsonDataFormatter
    class RwJsonDataFormatter

    class JsonNetSerializer

    class JsonSerializerSettings
    class JsonSerializer
    class Encoding

    IDataFormatter <|.. JsonDataFormatter
    IDataFormatter <|.. RwJsonDataFormatter

    IJsonSerializer <|.. JsonNetSerializer

    JsonDataFormatter --> JsonSerializerSettings
    JsonDataFormatter --> Encoding

    RwJsonDataFormatter --> JsonSerializer
    RwJsonDataFormatter --> Encoding

    JsonNetSerializer --> JsonSerializerSettings

Formatter Implementations¶

The package provides two formatter implementations.

JsonDataFormatter¶

JsonDataFormatter is the general-purpose formatter based on the higher-level Newtonsoft.Json APIs.

It uses:

JsonConvert.SerializeObject;
JsonConvert.DeserializeObject;
Encoding to convert JSON strings to and from byte[].

Example construction:

var settings = new JsonSerializerSettings();

IDataFormatter formatter =
    new JsonDataFormatter(
        settings,
        Encoding.UTF8);

Note

This example is intentionally shown to highlight the formatter dependencies. Use the constructor overloads exposed by the package version you are referencing.

RwJsonDataFormatter¶

RwJsonDataFormatter is the reader/writer formatter implementation.

It uses:

JsonSerializer;
StringWriter;
StringReader;
JsonTextWriter;
JsonTextReader;
Encoding.

Example construction:

var serializer =
    JsonSerializer.Create(
        new JsonSerializerSettings());

IDataFormatter formatter =
    new RwJsonDataFormatter(
        serializer,
        Encoding.UTF8);

Note

RwJsonDataFormatter should not be treated as a simple parameterless formatter. It depends on a configured Newtonsoft JsonSerializer and an Encoding.

JsonNetSerializer¶

The serializer implementation is:

JsonNetSerializer

It implements:

IJsonSerializer

and works with JSON strings.

Example construction:

var settings =
    new JsonSerializerSettings();

var serializer =
    new JsonNetSerializer(settings);

JsonDataFormatter Serialization Flow¶

JsonDataFormatter uses JsonConvert to create a JSON string, then uses Encoding to convert it to bytes.

graph LR
    Object["CLR object"]
    JsonConvert["JsonConvert"]
    Json["JSON string"]
    Encoder["Encoding"]
    Payload["byte[]"]

    Object --> JsonConvert
    JsonConvert --> Json
    Json --> Encoder
    Encoder --> Payload

Conceptually:

var json = JsonConvert.SerializeObject(data);

return Encoder.GetBytes(json);

JsonDataFormatter Deserialization Flow¶

graph LR
    Payload["byte[]"]
    Encoder["Encoding"]
    Json["JSON string"]
    JsonConvert["JsonConvert"]
    Object["CLR object"]

    Payload --> Encoder
    Encoder --> Json
    Json --> JsonConvert
    JsonConvert --> Object

Conceptually:

var json = Encoder.GetString(data);

return JsonConvert.DeserializeObject<TData>(json);

RwJsonDataFormatter Serialization Flow¶

RwJsonDataFormatter uses a reader/writer pipeline.

graph LR
    Object["CLR object"]
    Serializer["JsonSerializer"]
    Writer["JsonTextWriter"]
    StringWriter
    Json["JSON string"]
    Encoder["Encoding"]
    Payload["byte[]"]

    Object --> Serializer
    Serializer --> Writer
    Writer --> StringWriter
    StringWriter --> Json
    Json --> Encoder
    Encoder --> Payload

Conceptually:

using var writer = new StringWriter();

serializer.Serialize(writer, data);

return Encoder.GetBytes(writer.ToString());

RwJsonDataFormatter Deserialization Flow¶

graph LR
    Payload["byte[]"]
    Encoder["Encoding"]
    Json["JSON string"]
    StringReader
    Reader["JsonTextReader"]
    Serializer["JsonSerializer"]
    Object["CLR object"]

    Payload --> Encoder
    Encoder --> Json
    Json --> StringReader
    StringReader --> Reader
    Reader --> Serializer
    Serializer --> Object

Conceptually:

var json = Encoder.GetString(data);

using var reader = new StringReader(json);

return serializer.Deserialize<TData>(reader);

Why RwJsonDataFormatter Exists¶

RwJsonDataFormatter was introduced to reduce memory allocations during serialization and deserialization.

By using an explicit reader/writer pipeline, it can reduce allocation pressure compared to a formatter that relies only on the higher-level JsonConvert APIs.

The primary goal was to:

reduce temporary allocations;
reduce garbage collection pressure;
improve efficiency in high-throughput messaging scenarios.

The exact benefit depends on:

message size;
message volume;
serializer configuration;
application workload.

Choosing Between The Two Formatters¶

Formatter	Characteristics
`JsonDataFormatter`	Simpler implementation based on `JsonConvert`.
`RwJsonDataFormatter`	Reader/writer implementation designed to reduce allocations and GC pressure.

Both implementations are compatible with the same message contracts and use Newtonsoft.Json.

When To Use¶

Use the Newtonsoft formatter package when:

your application already uses Newtonsoft.Json;
custom converters are required;
advanced serialization behavior is needed;
legacy applications depend on Newtonsoft-specific features.

Considerations¶

For new applications, evaluate the Microsoft formatter first.

Choose the Newtonsoft formatter when compatibility or advanced serializer capabilities are more important than aligning with the default .NET JSON stack.