Message Serialization

In MassTransit, developers specify types for messages. MassTransit's serializers then perform the hard work of converting the types to the serializer format ( such as JSON, XML, BSON, etc.) and then back again.

To interoperate with other languages and platforms, the message structure is important.

Message Envelope

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.

Message Type

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.

Raw JSON

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

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

If the RawSerializerOptions.AddTransportHeaders option is specified when configuring a raw JSON serializer, the following transport headers will be set if the header value is present.

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 non-default options are recommended.

cfg.UseRawJsonSerializer(RawSerializerOptions.AddTransportHeaders | RawSerializerOptions.CopyHeaders);

Serializers

MassTransit include support for several commonly used serialization packages.

System Text Json

MassTransit uses System.Text.Json by default to serialize and deserialize JSON messages.

Newtonsoft

The MassTransit.Newtonsoft package adds the following serializer types. Prior to MassTransit v8, Newtonsoft was the default message serializer.