Serialization

Component: NServiceBus
NuGet Package NServiceBus (5.x)
Standard support for version 5.x of NServiceBus has expired. For more information see our Support Policy.

NServiceBus takes instances of .NET objects (messages, events, and commands) and sends/receives them over a specified transport. As part of this process, the object must be serialized and deserialized. NServiceBus achieves this using serializers.

When transitioning to a new serializer, messages that are currently 'in-flight' are formatted using the previous serialization format. This includes saga timeout and deferred/delayed messages via timeout persistence.
Make sure all queues of all endpoints are drained and empty, including any failed messages in the error queue and messages that need to be retried in the ServiceControl queue. NServiceBus versions 5 and earlier only support a single serializer/deserializer. Live migration is only supported in NServiceBus versions 6 and above.

The Newtonsoft JSON Serializer provides an effective general-purpose serializer appropriate for most use cases based on the ubiquitous Json.NET package. The Newtonsoft package provides a good combination of compactness, human readability, and performance. Other serializers are supported in order to enable specific performance or integration requirements.

Supported serializers

Community-supported serializers

Configuring a serializer

A serializer can be configured using the endpointConfiguration.UseSerialization API. Refer to the dedicated documentation pages for each available serializer for more information about the specific configuration.

The same serializer must be used by the sending endpoint to serialize messages and by the receiving endpoint to deserialize them, unless additional deserializers are specified.

Using the default serializer

The default serializer used in NServiceBus projects is the custom XmlSerializer. Unless explicitly configured otherwise, NServiceBus will use XmlSerializer for serializing and deserializing all messages.

Using a custom serializer

Besides the officially supported and community maintained serializers, it is also possible to implement and register a custom serializer.

Immutable message types

It is possible to use immutable types as messages. NServiceBus does not restrict this; It depends on the chosen serializer implementation if it supports deserializing to non public properties and/or using non-default constructors to initialize types.

On the wire it makes no difference if mutable or immutable message types are used.

For example, the Newtonsoft JSON Serializer by default supports immutable messages types.

Samples

Related Articles


Last modified