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"    }}
PropertyTypeNotesSet
messageIdGuidRecommendedY
correlationIdGuidOptional
requestIdGuidSituationalR
initiatorIdGuidOptional
conversationIdGuidOptionalY
sourceAddressUriOptionalY
destinationAddressUriOptionalY
responseAddressUriSituationalR
faultAddressUriOptional
expirationTimeISO-8601SituationalS
sentTimeISO-8601OptionalY
messageTypeUrn[]RequiredY

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.

Header NameTypeNotes
MessageIdGuid
CorrelationIdGuid
RequestIdGuid
MT-InitiatorIdGuid
ConversationIdGuid
MT-Source-AddressUri
MT-Response-AddressUri
MT-Fault-AddressUri
MT-MessageTypeUrn[]Multiple message types separated by ;
MT-Host-InfostringJSON serialized host info
MT-OriginalMessageIdGuidFor redelivered messages with a newly generated MessageId

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

OptionValueDefaultNotes
AnyMessageType1YMessages will match any consumed message type
AddTransportHeaders2YMassTransit will add the above headers to outbound messages
CopyHeaders4NReceived message headers will be copied to outbound messages

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.

Content TypeFormatConfiguration Method
application/vnd.masstransit+jsonJSON (w/envelope)UseJsonSerializer (default)
application/jsonJSONUseRawJsonSerializer

Newtonsoft

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

Content TypeFormatConfiguration Method
application/vnd.masstransit+jsonJSON (w/envelope)UseNewtonsoftJsonSerializer
application/jsonJSONUseNewtonsoftRawJsonSerializer
application/vnd.masstransit+bsonBSON (w/envelope)UseBsonSerializer
application/vnd.masstransit+xmlXML (w/envelope)UseXmlSerializer
application/xmlXMLUseRawXmlSerializer
application/vnd.masstransit+aesBinary (w/envelope)UseEncryptedSerializer
application/vnd.masstransit.v2+aesBinary (w/envelope)UseEncryptedSerializerV2