Skip to content

Latest commit

 

History

History
100 lines (56 loc) · 3.93 KB

newtonsoft.md

File metadata and controls

100 lines (56 loc) · 3.93 KB
title summary component reviewed related
Json.NET Serializer
A JSON serializer that uses Newtonsoft Json.NET.
Newtonsoft
2023-06-28
samples/serializers/newtonsoft
samples/serializers/newtonsoft-bson

This serialiser uses JSON via a NuGet dependency on Json.NET.

Usage

snippet: NewtonsoftSerialization

Json.NET attributes

Json.NET attributes are supported.

For example

snippet: NewtonsoftAttributes

Note

By default, the Json.NET serializer adds a Byte Order Mark (BOM). To disable it, see the custom writer section.

Custom settings

Customize the instance of JsonSerializerSettings used for serialization.

snippet: NewtonsoftCustomSettings

Custom reader

Customize the creation of the JsonReader.

snippet: NewtonsoftCustomReader

Custom writer

Customize the creation of the JsonWriter.

In the example below, the custom writer omits the Byte Order Mark (BOM).

snippet: NewtonsoftCustomWriter

include: custom-contenttype-key

snippet: NewtonsoftContentTypeKey

partial: typenamehandling

Inferring message type from $type

For integration scenarios where the sender is unable to add message headers, the serializer is able to infer the message type from the $type property supported by Json.NET. This feature requires the TypeNameHandling setting to be set to Auto or All.

See native integration with SqlTransport sample for more details.

BSON

Customize to use the Newtonsoft Bson serialization.

snippet: NewtonsoftBson

Compatibility with the core JSON serializer

Up to NServiceBus version 6, a JSON serializer based on Json.NET was bundled with the core package. This section outlines the compatibility considerations when switching to this serializer.

No support for XContainer and XDocument properties

In contrast to the bundled serializer XContainer and XDocument properties are no longer supported. If XContainer and XDocument properties are required use a JsonConverter as shown below:

snippet: XContainerJsonConverter

Configure the converter as follows:

snippet: UseConverter

No support for bundled logical messages

This serializer is not compatible with multiple bundled messages (when using the Send(object[] messages) APIs) sent from NServiceBus version 3 and below. 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.

Use of $type requires an assembly qualified name

The bundled serializer registers a custom serialization binder in order to not require the assembly name to be present when inferring message type from the $type property supported by json.net. Not having to specify the assembly name can be useful to reduce coupling when using the serializer for native integration scenarios as demonstrated in this sample.

To make the serializer compatible with this behavior use the following serialization binder:

snippet: KnownTypesBinder

and configured as follows:

snippet: KnownTypesBinderConfig