Message Serialization

MassTransit uses types for messages. Serializers are used convert those types into their respective format (such as JSON, XML, BSON, etc.), which is sent to the message broker. A corresponding deserializer is then used to convert the serialized format back into a type.

By default, MassTransit uses System.Text.Json to serialize and deserialize messages using JSON.

Supported Serializers

MassTransit include support for several commonly used serialization packages.

System.Text.Json

System.Text.Json is the default message serializer/deserializer.

Customize the Serializer Support

services.AddMassTransit(cfg =>
{
    cfg.Using[Broker](broker => 
    {
        broker.ConfigureJsonSerializerOptions(options =>
        {
            // customize the JsonSerializerOptions here
            return options;
        });
    })
    
})

Newtonsoft

The MassTransit.Newtonsoft package adds the serialization formats listed below.

In MassTransit versions before v8, Newtonsoft was the default message serializer/deserializer.

MessagePack

The MassTransit.MessagePack package adds the serialization formats listed below.

Message Types

MassTransit stores the supported .NET types for a message as an array of URNs, which include the namespace and name of the message type. All interfaces and superclasses of the message type are included. The namespace and name are formatted as shown below.

urn:message:Namespace:TypeName

A few examples of valid message types:

urn:message:MyProject.Messages:UpdateAccount
urn:message:MyProject.Messages.Events:AccountUpdated
urn:message:MyProject:ChangeAccount
urn:message:MyProject.AccountService:MyService+AccountUpdatedEvent

The last one is a nested class, as indicated by the '+' symbol.

MessageUrn Attribute

MessageUrn is an optional attribute that may be specified on a message type to provide a custom Urn that will be used when the message is published or consumed. The generated Urn will be prefixed with urn:messages: by default, however a full Urn may be provided by specifying useDefaultPrefix: false in the attribute declaration.

[MessageUrn("publish-command")]
public record PublishCommand
{
    // Will generate a urn of: urn:messages:publish-command
}

[MessageUrn("scheme:publish-command", useDefaultPrefix: false)]
public record PublishCommand
{
    // Will generate a urn of: scheme:publish-command
}

Message Envelope

To interoperate with other languages and platforms, message structure is important. MassTransit encapsulates messages in an envelope before they are serialized. An example JSON message envelope is shown below.

{
    "messageId": "181c0000-6393-3630-36a4-08daf4e7c6da",
    "requestId": "ef375b18-69ee-4a9e-b5ec-44ee1177a27e",
    "correlationId": null,
    "conversationId": null,
    "initiatorId": null,
    "sourceAddress": "rabbitmq://localhost/source",
    "destinationAddress": "rabbitmq://localhost/destination",
    "responseAddress": "rabbitmq://localhost/response",
    "faultAddress": "rabbitmq://localhost/fault",
    "messageType": [
        "urn:message:Company.Project:SubmitOrder"
    ],
    "message": {
        "orderId": "181c0000-6393-3630-36a4-08daf4e7c6da",
        "timestamp": "2023-01-12T21:55:53.714Z"
    },
    "expirationTime": null,
    "sentTime": "2023-01-12T21:55:53.715882Z",
    "headers": {
        "Application-Header": "SomeValue"
    },
    "host": {
        "machineName": "MyComputer",
        "processName": "dotnet",
        "processId": 427,
        "assembly": "TestProject",
        "assemblyVersion": "2.11.1.93",
        "frameworkVersion": "6.0.7",
        "massTransitVersion": "8.0.10.0",
        "operatingSystemVersion": "Unix 12.6.2"
    }
}

Set indicates whether the property is automatically set by MassTransit when producing messages. Yes, Requests only, or Situational.

Raw JSON

Consuming messages from other systems where messages may not be produced by MassTransit, raw JSON is commonly used.

When using a serializer that doesn't wrap the message in an envelope (application/json), the above message would be reduced to the raw JSON shown below.

{
    "orderId": "181c0000-6393-3630-36a4-08daf4e7c6da",
    "timestamp": "2023-01-12T21:55:53.714Z"
}

Learn more about using raw JSON messages in this video.

Options

MassTransit provides several options when dealing with raw JSON messages. The options can be specified on the UseRawJsonSerializer method.RawSerializerOptions includes the following flags:

In cases where MassTransit is used and raw JSON messages are preferred, the default options are recommended. When integrating with external systems (non-MassTransit generated messages), see below.

Headers

When the RawSerializerOptions.AddTransportHeaders option is specified, the following transport headers will be set (if not empty or default).

Configuration

To configure a receive endpoint so that it can receive raw JSON messages, specify the default content type and add the deserializer as shown below. When a raw JSON message is received, it will be delivered to every consumer configured on the receive endpoint.

endpointConfigurator.UseRawJsonDeserializer(isDefault: true);

If there is no Message-Type header that meets MassTransit's requirements (typical for messages not produced by MassTransit), specify the deserializer should return all message types consumed by the consumer. This should only be used when the consumer has only a single IConsumer<T> interface.

endpointConfigurator.UseRawJsonDeserializer(RawSerializerOptions.All, isDefault: true);

If messages produced by consumers on the receive endpoint should also be in the raw JSON format, UseRawJsonSerializer() may be used instead.

Setting the default content type tells MassTransit to use the raw JSON deserializer for messages that do not have a recognized Content-Type header.

To prevent MassTransit from creating exchanges or topics for the message types consumed on the endpoint, disable consume topology configuration.

endpointConfigurator.ConfigureConsumeTopology = false;