The Json.NET serializer can serialize a wide variety of .NET objects. This guide
+ looks at how it works at a high level and in more detail.
+
Summary
+
At a high level, the Json.NET serializer will convert primitive .NET values into
+ primitive JSON values, .NET arrays and collections to JSON arrays and everything
+ else to JSON objects.
+
Json.NET will throw an error if it encounters incorrect JSON when deserializing a
+ value. For example if the serializer encounters a JSON property with an array of
+ values and the type of matching .NET property is not a collection then an error
+ will be thrown, and vice-versa.
.NET types that don’t fall into any other category listed below (i.e. aren’t
+ lists, dictionaries, dynamic, implement ISerializable, etc) are serialized as
+ JSON objects.
+
By default types are serialized in opt-out mode. What that means is all public
+ fields and properties with getters are automatically serialized to JSON and
+ members that shouldn’t be serialized are opted-out using the
+ JsonIgnoreAttribute. To serialize private members the JsonPropertyAttribute can
+ be placed on private fields and properties or the DefaultMembersSearchFlags can
+ be changed on DefaultContractResolver to change how members are serialized on
+ all types.
+
Types can also be serialized using opt-in mode. Only fields that have a
+ JsonPropertyAttribute or DataMemberAttribute on them will be serialized. Opt-in
+ mode for an object is specified using the JsonObjectAttribute on the class.
+
IEnumerable, Lists and Arrays
+
.NET lists (types that inherit from IEnumerable) and .NET arrays are converted to
+ JSON arrays. Because JSON arrays only support a range of values and not
+ properties, any additional properties and fields declared on .NET collections
+ are not serialized. In situations where a JSON array is not wanted the
+ JsonObjectAttribute can be placed on a .NET type that implements IEnumerable to
+ force the type to be serialized as a JSON object instead.
+
Note that if TypeNameHandling or PreserveReferencesHandling has been enabled for
+ JSON arrays on the serializer then JSON arrays are wrapped it a containing
+ object. The object will have the type name/reference properties and a $values
+ property which will have the collection data.
+
When deserializing if a member is typed as the interface IList then it will be
+ deserialized as a List.
.NET dictionaries (types that inherit from IDictionary) are converted to JSON
+ objects. Note that only the dictionary name/values will be written to the JSON
+ object when serializing and properties on the JSON object will be added to the
+ dictionary’s name/values when deserializing. Additional members on the .NET
+ dictionary are ignored during serialization.
+
When deserializing if a member is typed as the interface IDictionary
+ then it will be deserialized as a Dictionary.
.NET properties on a class that don’t specify a type (i.e. they are just object)
+ are serialized as usual. When untyped properties are deserialized the serializer
+ has no way to know what type to create (unless type name handling is enabled and
+ the JSON contains the type names).
+
For these untyped properties the Json.NET serializer will read the JSON into LINQ
+ to JSON objects and set them to the property.
+
Dynamic
+
.NET dynamic objects (introduced in .NET 4) are serialized as JSON objects. A
+ property is written for every member name returned by
+ IDynamicMetaObjectProvider.GetDynamicMemberNames.
+
When deserializing the serializer first attempts to set JSON property values on a
+ normal .NET member with the matching name. If no .NET member is found with the
+ property name then the serializer will call SetMember on the dynamic object.
+
Because a dynamic property on a class doesn’t specify a type, Json.NET has no way
+ to know what type to create for it when deserializing (unless type name handling
+ is enabled and the JSON contains the type name). LINQ to JSON objects will be
+ created for the JSON.
+
ISerializable
+
Types that implement ISerializable are serialized as JSON objects. When
+ serializing only the values returned from ISerializable.GetObjectData are used;
+ members on the type are ignored. When deserializing the constructor with a
+ SerializationInfo and StreamingContext is called, passing the JSON object’s
+ values.
+
In situations where this behaviour is not wanted the JsonObjectAttribute can be
+ placed on a .NET type that implements ISerializable to force it to be serialized
+ as a normal JSON object.
+
LINQ to JSON
+
LINQ to JSON types (e.g. JObject, JArray) are automatically serialized and
+ deserialized to their equivalent JSON when encountered by the Json.NET
+ serializer.
+
JsonConverter
+
Serialization of values that are convertible by a JsonConverter (i.e. CanConvert
+ returns true for its type) is completely overridden by the JsonConverter. The
+ test to see whether a value can be converted by a JsonSerializer takes
+ precedence over all other tests.
+
JsonConverters can be defined and specified in a number of places: in an
+ attribute on a member, in an attribute on a class and added to the
+ JsonSerializer’s converters collection. The priority of which JsonConverter is
+ used is the JsonConverter defined by attribute on a member then the
+ JsonConverter defined by an attribute on a class and finally any converters
+ passed to the JsonSerializer.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/Doc/SerializationSettings.html b/Doc/SerializationSettings.html
new file mode 100644
index 00000000..bd32746b
--- /dev/null
+++ b/Doc/SerializationSettings.html
@@ -0,0 +1,174 @@
+
+
+
+ Customizing JSON serialization with attributes
+
+
+
+
+
+
+
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
+ JsonSerializerSettings overloads.
+
ReferenceLoopHandling
+
ReferenceLoopHandling controls how circular referencing objects, e.g. a Person
+ object referencing itself via a Manager property, are serialized.
+
+
Error - By default Json.NET will error if a reference loop is
+ encountered (otherwise the serializer will get into an infinite loop).
+
Ignore - Json.NET will ignore objects in reference loops and
+ not serialize them. The first time an object is encountered it will be
+ serialized as usual but if the object is encountered as a child object of itself
+ the serializer will skip serializing it.
+
Serialize - This option forces Json.NET to serialize objects in
+ reference loops. This is useful if objects are nested but not indefinitely.
+
+
+
+
MissingMemberHandling
+
MissingMemberHandling controls how missing members, e.g. JSON contains a property
+ that isn't a member on the object, are handled during deserialization.
+
+
Ignore - By default Json.NET ignores JSON if there is no field
+ or property for its value to be set to during deserialization.
+
Error - Json.NET errors when there is a missing member during
+ deserialization
+
+
NullValueHandling
+
NullValueHandling controls how null values on .NET objects are handled during
+ serialization and how null values in JSON are handled during deserialization.
+
+
Include - By default Json.NET writes null values to JSON when
+ serializing and sets null values to fields/properties when deserializing.
+
Ignore - Json.NET will skip writing JSON properties if the .NET
+ value is null when serializing and will skip setting fields/properties if the
+ JSON property is null when deserializing.
+
+
+ DefaultValueHandling
+
+ DefaultValueHandling controls how Json.NET uses default values set using the .NET
+ DefaultValueAttribute when serializing and deserializing.
+
+
Include - By default Json.NET will write a field/property value
+ to JSON when serializing if the value is the same as the field/property’s
+ default value. The Json.NET deserializer will continue setting a field/property
+ if the JSON value is the same as the default value.
+
Ignore - Json.NET will skip writing a field/property value to
+ JSON if the value is the same as the field/property’s default value. The
+ Json.NET deserializer will skip setting a .NET object’s field/property if the
+ JSON value is the same as the default value.
+
+
ObjectCreationHandling
+
ObjectCreationHandling controls how objects are created and deserialized to
+ during deserialization.
+
+
Auto - By default Json.NET will attempt to set JSON values onto
+ existing objects and add JSON values to existing collections during
+ deserialization.
+
Reuse - Same behaviour as auto.
+
Replace - Json.NET will always recreate objects and collections
+ before setting values to them during deserialization.
+
+
TypeNameHandling
+
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.
+
+
None - By default Json.NET does not read or write type names
+ during deserialization.
+
Objects - Json.NET will write and use type names for objects
+ but not collections.
+
Arrays - Json.NET will write and use type names for collections
+ but not objects.
+
Auto - Json.NET will check whether an object/collection matches
+ its declared property and writes the type name if they do not match, e.g. a
+ property with a type of Mammal has a derived instance of Dog assigned. Auto will
+ ensure that type information isn’t lost when serializing/deserializing
+ automatically without having to write type names for every object.
+
All - Json.NET will write and use type names for objects and
+ collections.
+
+
TypeNameAssemblyFormat
+
TypeNameAssemblyFormat controls how type names are written during serialization.
+
+
Simple - By default Json.NET writes the partial assembly name
+ with the type, e.g. System.Data.DataSet, System.Data. Note that Silverlight and
+ Windows Phone are not able to use this format.
+
Full - Json.NET will write the full assembly name, including
+ version number, culture and public key token.
ConstructorHandling controls how constructors are used when initializing objects
+ during deserialization.
+
+
Default - By default Json.NET will first look for a constructor
+ marked with the JsonConstructorAttribute, then look for a public default
+ constructor (a constructor that doesn’t take any arguments) and finally check if
+ the class has a single public constructor with arguments. If the class has
+ multiple public constructors with arguments an error will be thrown. This can be
+ fixed by marking one of the constructors with the JsonConstructorAttribute.
+
AllowNonPublicDefaultConstructor - Json.NET will fallback to
+ using a classes private default constructor if available.
+
+
Converters
+
This is the collection of JsonConverters that will be used during serialization
+ and deserialization.
+
JsonConverters 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.
+
To create your own custom converter inherit from the JsonConverter class. Read
+ more about the built-in JsonConverters below:
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.
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.
+
+
+
+
\ No newline at end of file
diff --git a/Doc/SerializingJSON.html b/Doc/SerializingJSON.html
index c2913961..ab6b2dc4 100644
--- a/Doc/SerializingJSON.html
+++ b/Doc/SerializingJSON.html
@@ -1,7 +1,7 @@
- Serializing and deserializing JSON
+ Serializing and Deserializing JSON
@@ -10,7 +10,7 @@
Json.NET - Quick Starts & API Documentation
- Serializing and deserializing JSON
+ Serializing and Deserializing JSON
@@ -51,6 +51,11 @@
+
+ SerializeObject and DeserializeObject both have overloads that take a
+ JsonSerializerSettings object. JsonSerializerSettings lets you use many of the JsonSerializer settings listed below while still using the simple serialization methods.
+
+
JsonSerializer
@@ -83,56 +88,8 @@
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
JsonSerializerSettings overloads.
-
-
ReferenceLoopHandling
-
Controls how circular referencing objects are serialized. Error, ignore or
- serialize.
-
MissingMemberHandling
-
Controls how missing members (e.g. JSON contains a property that isn't a member
- on the object) are handled during deserialization. Ignore or error.
-
NullValueHandling
-
Controls how null values are handled during serialization and deserialization.
- Include or ignore.
-
DefaultValueHandling
-
Controls whether a value will be written to JSON or not if it matches the value specified in
-the member's DefaultValueAttribute. Include or ignore.
-
ObjectCreationHandling
-
Controls how objects are created during deserialization. Auto, reuse, replace.
-
TypeNameHandling
-
Controls whether .NET type names are included in serialized JSON and read during deserialization when creating objects. None, Objects, Arrays or All.
-
ConstructorHandling
-
Controls how constructors are used when initializing objects during deserialization. Default or AllowNonPublicDefaultConstructor.
-
Converters
-
A collection of JsonConverters that will be used during serialization and
- deserialization.
-
-
-
JsonConverters
-
JsonConverters 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.
-
To create your own custom converter inherit from the JsonConverter class. Json.NET also comes with a number of JsonConverters:
-
-
-
-
DateTime JSON Converters
-
Json.NET comes with a number of JsonConverters for serializing and deserializing DateTimes. Read
- more about dates and Json.NET here.
-
-
XmlNodeConverter
-
Converts an XmlNode to and from JSON. Note that to convert a JSON object it must have only a single property
- or you must define a root node name to be inserted when using this converter. This is required because properties are converted into nodes and
- well formed XML can only have one root node. XmlNodeConverter has an option to
- insert a root node for you.
-
-
-
BinaryConverter
-
Converts binary data like the SqlBinary object to JSON. The binary
- data is written as a string in JSON and is encoded in Base64.
-
-
CustomCreationConverter
-
An abstract JsonConverter for customizing how an object is create during deserialization.
- Inherit from this class and implement the Create method with your own code to create and return an object.
- The object will then be populated with JSON values by the serializer.
-
A possible example of using this converter would be to call out to a dependency injection framework to resolve what object should be created.