Json.NET Serializer

Project Hosting
NuGet NServiceBus.Newtonsoft.Json (1.x)
Target NServiceBus Version: 6.x

Using JSON via a NuGet dependency on Json.NET.

How the NServiceBus core uses Json.net

The core of NServiceBus uses Json.net. However it is ILMerged where this library has a standard dll and NuGet dependency. While ILMerging reduces versioning issues in the core it does cause several restrictions:

  • Can't use a different version of Json.net
  • Can't use Json.net attributes
  • Can't customize the Json.net serialization behaviors.

These restrictions do not apply to this serializer.

Compatibility with the core JSON serializer

The only incompatibility with the core serializer is that this serializer does not support the serialization of XContainer and XDocument properties. If XML properties are required on messages strings should be used instead.

This serializer is not compatible with multiple bundled messages (when using the Send(object[] messages) APIs) sent from Versions 3 and below of NServiceBus. If this scenario is detected then an exception with the following message will be thrown:

Multiple messages in the same stream are not supported.

The AddDeserializer API can help transition between serializers. See the Multiple Deserializers Sample for more information.



Json.net attributes

Json.net attributes are supported.

For example

public class CreatePersonMessage :
    // "John Smith"
    public string Name { get; set; }

    // "2000-12-15T22:11:03"
    public DateTime BirthDate { get; set; }

    // new Date(976918263055)
    public DateTime LastModified { get; set; }

    // not serialized because mode is opt-in
    public string Department { get; set; }

Custom Settings

Customizes the instance of JsonSerializerSettings used for serialization.

var settings = new JsonSerializerSettings
    TypeNameHandling = TypeNameHandling.Auto,
    Converters =
        new IsoDateTimeConverter
            DateTimeStyles = DateTimeStyles.RoundtripKind
var serialization = endpointConfiguration.UseSerialization<NewtonsoftSerializer>();

Custom Reader

Customize the creation of the JsonReader.

var serialization = endpointConfiguration.UseSerialization<NewtonsoftSerializer>();
serialization.ReaderCreator(stream =>
    var streamReader = new StreamReader(stream, Encoding.UTF8);
    return new JsonTextReader(streamReader);

Custom Writer

Customize the creation of the JsonWriter.

var serialization = endpointConfiguration.UseSerialization<NewtonsoftSerializer>();
serialization.WriterCreator(stream =>
    var streamWriter = new StreamWriter(stream, Encoding.UTF8);
    return new JsonTextWriter(streamWriter)
        Formatting = Formatting.None

Custom Content Key

When using additional deserializers or transitioning between different versions of the same serializer it can be helpful to take explicit control over the content type a serializer passes to NServiceBus (to be used for the ContentType header).

var serialization = endpointConfiguration.UseSerialization<NewtonsoftSerializer>();


Customize to use the Newtonsoft Bson serialization.

var serialization = endpointConfiguration.UseSerialization<NewtonsoftSerializer>();
serialization.ReaderCreator(stream => new BsonDataReader(stream));
serialization.WriterCreator(stream => new BsonDataWriter(stream));


Last modified