IDataFormatter¶

IDataFormatter is the main formatter contract used by ServiceBus.Core.

It represents the component responsible for converting application messages into broker payloads.

Contract Model¶

IDataFormatter extends:

IDataEncoder
IDataDecoder

and exposes:

Encoding Encoder { get; }

This means that formatters are responsible for binary payload conversion, not only JSON serialization.

Purpose¶

IDataFormatter separates message formatting from transport behavior.

graph LR
    Object["CLR object"]
    Formatter["IDataFormatter"]
    Payload["byte[] payload"]

    Object --> Formatter
    Formatter --> Payload

Serialization Flow¶

The conceptual serialization flow is:

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

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

Deserialization Flow¶

The conceptual deserialization flow is:

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

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

IDataFormatter vs IJsonSerializer¶

IDataFormatter and IJsonSerializer are related, but they are not the same abstraction.

Contract	Responsibility
`IDataFormatter`	Converts CLR objects to `byte[]` broker payloads and back.
`IJsonSerializer`	Converts CLR objects to JSON strings and back.

Broker clients use IDataFormatter.

IJsonSerializer is used by formatter implementations when string-based JSON serialization is needed.

Formatter Implementations¶

Package	Formatter	Main dependencies
`ServiceBus.Formatters.Ms`	`MsJsonDataFormatter`	`JsonSerializerOptions`
`ServiceBus.Formatters.Newtonsoft`	`JsonDataFormatter`	`JsonSerializerSettings`, `Encoding`
`ServiceBus.Formatters.Newtonsoft`	`RwJsonDataFormatter`	`JsonSerializer`, `Encoding`

Note

Formatter implementations may require constructor dependencies. Do not assume that every formatter can be created with a parameterless constructor.

Serializer Implementations¶

Package	Serializer	Main dependencies
`ServiceBus.Formatters.Ms`	`MsJsonSerializer`	`JsonSerializerOptions`
`ServiceBus.Formatters.Newtonsoft`	`JsonNetSerializer`	`JsonSerializerSettings`

Relationship Diagram¶

classDiagram

    class IDataFormatter
    class IJsonSerializer

    class MsJsonDataFormatter
    class JsonDataFormatter
    class RwJsonDataFormatter

    class MsJsonSerializer
    class JsonNetSerializer

    class JsonSerializerOptions
    class JsonSerializerSettings
    class JsonSerializer
    class Encoding

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

    IJsonSerializer <|.. MsJsonSerializer
    IJsonSerializer <|.. JsonNetSerializer

    MsJsonDataFormatter --> JsonSerializerOptions

    JsonDataFormatter --> JsonSerializerSettings
    JsonDataFormatter --> Encoding

    RwJsonDataFormatter --> JsonSerializer
    RwJsonDataFormatter --> Encoding

    MsJsonSerializer --> JsonSerializerOptions
    JsonNetSerializer --> JsonSerializerSettings

Used By Publishers¶

Before publishing a message, the publisher uses IDataFormatter to create the payload sent to RabbitMQ.

await publisher.SendAsync(
    new OrderCreated
    {
        OrderId = Guid.NewGuid(),
        CreatedAtUtc = DateTime.UtcNow
    });

Used By Subscribers¶

Before invoking the handler, the subscriber uses IDataFormatter to decode the broker payload.

subscriber.Received.Add(
    async (sender, args) =>
    {
        var message = args.Message.Data;

        Console.WriteLine(message.OrderId);

        await Task.CompletedTask;
    });

Custom Implementations¶

Applications can provide custom implementations of:

IDataFormatter
IJsonSerializer

when custom serialization behavior is required.