Serialization Settings

DateFormatHandling controls how dates are serialized.

MissingMemberHandling controls how missing members, e.g. JSON contains a property that isn't a member on the object, are handled during deserialization.

ReferenceLoopHandling controls how circular referencing objects, e.g. a Person object referencing itself via a Manager property, are serialized.

The Equals(Object) method is used to test whether an object is in a circular reference. By default Object.Equals(Object) will test whether the references are equal for reference types and private and public values are equal for value types. Classes and structs can override this method.

ReferenceLoopHandling can be used as an argument when calling the serializer, it can be set on an object's properties or a collection's items using ItemReferenceLoopHandling, customized on a property with ReferenceLoopHandling or a property's object properties or collection items using ItemReferenceLoopHandling.

NullValueHandling controls how null values on .NET objects are handled during serialization and how null values in JSON are handled during deserialization.

NullValueHandling can also be customized on individual properties with JsonPropertyAttribute.

DefaultValueHandling controls how Json.NET uses default values set using the .NET DefaultValueAttribute when serializing and deserializing.

DefaultValueHandling can also be customized on individual properties with JsonPropertyAttribute.

ObjectCreationHandling controls how objects are created and deserialized to during deserialization.

ObjectCreationHandling can also be customized on individual properties with JsonPropertyAttribute.

Caution
TypeNameHandling should be used with caution when your application deserializes JSON from an external source. Incoming types should be validated with a custom ISerializationBinder when deserializing with a value other than TypeNameHandling.None.

TypeNameHandling controls whether Json.NET includes .NET type names during serialization with a $type property and reads .NET type names from that property to determine what type to create during deserialization.

Metadata properties like $type must be located at the beginning of a JSON object to be successfully detected during deserialization. If you can't control the order of properties in your JSON object then MetadataPropertyHandling can be used to remove this restriction.

The value of the $type property can be customized and validated by creating your own ISerializationBinder.

TypeNameHandling can be used as an argument when calling the serializer, it can be set on an object's properties or a collection's items using ItemTypeNameHandling, customized on a property with TypeNameHandling or a property's object properties or collection items using ItemTypeNameHandling.

FormatterAssemblyStyle controls how type names are written during serialization.

Read more about the valid values at FormatterAssemblyStyle.

The ISerializationBinder is used to resolve .NET types to type names during serialization and type names to .NET types during deserialization.

If TypeNameHandling is enabled then it is strongly recommended that a custom ISerializationBinder is used to validate incoming type names for security reasons.

MetadataPropertyHandling controls how metadata properties like $type and $id are read during deserialization.

For performance reasons by default the JsonSerializer assumes that any metadata properties are located at the beginning of a JSON object. If you are unable to guarantee the order of properties in JSON you are deserializing then MetadataPropertyHandling.ReadAhead removes this restriction at the cost of some performance.

ConstructorHandling controls how constructors are used when initializing objects during deserialization.

This is the collection of JsonConverters that will be used during serialization and deserialization.

A JsonConverter allows JSON to be manually written during serialization and read during deserialization. This is useful for particularly complex JSON structures or for when you want to change how a type is serialized.

When a JsonConverter has been added to a JsonSerializer it will be checked for every value that is being serialized/deserialized using its CanConvert to see if it should be used. If CanConvert returns true then the JsonConverter will be used to read or write the JSON for that value. Note that while a JsonConverter gives you complete control over that values JSON, many Json.NET serialization features are no longer available like type name and reference handling.

JsonConverters can be used as an argument when calling the serializer, it can be set on an object or property using JsonConverterAttribute, it be set on an object's properties or a collection's items using ItemConverterType, or a property's object properties or collection items using ItemConverterType.

To create your own custom converter inherit from the JsonConverter class. Read more about the built-in JsonConverters below:

• Serializing Dates in JSON

• Converting between JSON and XML

• CustomCreationConverter

• StringEnumConverter

Internally for every .NET type the JsonSerializer will create a contract of how the type should be serialized and deserialized, based on type metadata and attributes applied to the class. Specifying a custom IContractResolver allows the creation of contracts to be customized.

Read more about Contract Resolvers here: Serialization using ContractResolver

The Json.NET serializer supports logging and debugging using the ITraceWriter interface. By assigning a trace writer you can debug what happens inside the Json.NET serializer when serializing and deserializing JSON.

Read more about TraceWriters here: Debugging with Serialization Tracing

The Error event can catch errors during serialization and either handle the event and continue with serialization or let the error bubble up and be thrown to the application.

Read more about error handling here: Serialization Error Handling

Reference

Other Resources