JsonSerializer has a number of properties on it to customize how it serializes JSON. These can also be used with the methods on JsonConvert via the Argon.JsonSerializerSettings overloads.
Argon.DateFormatHandling controls how dates are serialized.
Argon.MissingMemberHandling controls how missing members, e.g. JSON contains a property that isn't a member on the object, are handled during deserialization.
Argon.ReferenceLoopHandling controls how circular referencing objects, e.g. a Person object referencing itself via a Manager property, are serialized.
The System.Object.Equals(System.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 Argon.JsonContainerAttribute.ItemReferenceLoopHandling, customized on a property with Argon.JsonPropertyAttribute.ReferenceLoopHandling or a property's object properties or collection items using Argon.JsonPropertyAttribute.ItemReferenceLoopHandling.
Argon.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.
Argon.DefaultValueHandling controls how Json.NET uses default values set using the .NET System.ComponentModel.DefaultValueAttribute when serializing and deserializing.
DefaultValueHandling can also be customized on individual properties with JsonPropertyAttribute.
Argon.ObjectCreationHandling controls how objects are created and deserialized to during deserialization.
Argon.TypeNameHandling should be used with caution when your application deserializes JSON from an external source.
Incoming types should be validated with a custom Argon.ISerializationBinder when deserializing with a value other than TypeNameHandling.None.
Argon.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 Argon.MetadataPropertyHandling can be used to remove this restriction.
The value of the $type property can be customized and validated by creating your own Argon.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 Argon.JsonContainerAttribute.ItemTypeNameHandling, customized on a property with Argon.JsonPropertyAttribute.TypeNameHandling or a property's object properties or collection items using Argon.JsonPropertyAttribute.ItemTypeNameHandling.
A C# 15 closed type records its permitted descendants at compile time. InferClosedTypePolymorphism
uses that recorded list to write and read a type discriminator, so a closed hierarchy round trips
without TypeNameHandling and without an Argon.ISerializationBinder. It is off by default.
public closed record class PaymentEvent(string PaymentId);
public sealed record class PaymentAuthorized(string PaymentId, decimal Amount) : PaymentEvent(PaymentId);
var settings = new JsonSerializerSettings
{
InferClosedTypePolymorphism = true
};A value whose declared type is the closed base is written with a $type property holding the simple
name of its runtime type, which is the same shape System.Text.Json produces for its own
InferClosedTypePolymorphism option:
{"$type":"PaymentAuthorized","Amount":42.5,"PaymentId":"p-123"}Unlike TypeNameHandling, the set of types an incoming discriminator can name is fixed by the
compiler. A payload can only ever select one of the hierarchy's declared descendants, so there is no
need for an Argon.ISerializationBinder to validate type names, and the warning above about
deserializing JSON from an external source does not apply.
Points worth knowing:
- Only terminal descendants carry a discriminator. A closed type nested inside a closed hierarchy is expanded through, and a branch that is not itself closed is where inference stops. Serializing a type below that boundary throws rather than emitting JSON that cannot be read back.
- A discriminator is only written where there is a declared type to compare against: a property, a
collection item, a dictionary value, or a root serialized with an explicit type. As with
TypeNameHandling.Auto, a root passed without a type carries no discriminator, so useJsonConvert.SerializeObject(value, typeof(PaymentEvent), settings). - Discriminators are simple type names, so two descendants of the same hierarchy cannot share a name even when they are in different namespaces. Attempting it throws.
- Where both this setting and
TypeNameHandlingapply to the same value, the inferred simple name wins. Types that are not part of a closed hierarchy are unaffected and keep usingTypeNameHandlingand the binder. - The
$typeproperty has to be the first property of the object, which is where Argon writes it.Argon.MetadataPropertyHandling.ReadAheadlifts that restriction for payloads from other producers, andArgon.MetadataPropertyHandling.Ignoredisables the feature on read.
See Unions and closed type hierarchies for union support, which is unrelated and needs no configuration.
System.Runtime.Serialization.Formatters.FormatterAssemblyStyle controls how type names are written during serialization.
The Argon.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 Argon.ISerializationBinder is used to validate incoming type names for security reasons.
Argon.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.
Argon.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 Argon.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 Argon.JsonConverterAttribute, it be set on an object's properties or a collection's items using Argon.JsonContainerAttribute.ItemConverterType, or a property's object properties or collection items usingArgon.JsonPropertyAttribute.ItemConverterType.
To create your own custom converter inherit from the JsonConverter class. Read more about the built-in JsonConverters below:
- DatesInJSON
- ConvertingJSONandXML
- CustomCreationConverter
Argon.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 Argon.IContractResolver allows the creation of contracts to be customized.
See also: [ContractResolver]
The Json.NET serializer supports logging and debugging using the Argon.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: [SerializationTracing]
The Argon.JsonSerializer.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: [SerializationErrorHandling]
- [SerializationGuide]
- [SerializationAttributes]
- [DatesInJSON]
Argon.JsonSerializerArgon.JsonSerializerSettingsArgon.JsonConverterSystem.Runtime.Serialization.SerializationBinder