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.
-Complex Types
-| - .NET | -- JSON | -
| - IList, IEnumerable, IList<T>, Array | -- Array | -
| - IDictionary, IDictionary<TKey, - TValue> | -- Object | -
| - Object - (more detail below) | -Object | -
Primitive Types
-| - .NET .NET | -- JSON | -
| - String | -- String | -
|
- Byte - SByte - UInt16 - Int16 - UInt32 - Int32 - UInt64 - Int64 |
- - Integer | -
|
- Float - Double - Decimal |
- - Float | -
| - Enum | -- Integer (can be string with - StringEnumConverter) | -
| - DateTime | -- String (Serializing Dates in JSON) | -
| - Byte[] | -- String (base 64 encoded) | -
| - Type | -- String (type name) | -
| - Guid | -- String | -
| - - TypeConverter (convertible to String) | -String | -
Breakdown of Type Serialization
-Objects
-.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
Read more about serializing collections here: - Serializing Collections
-Dictionarys and Hashtables
-.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
Read more about serializing collections here: - Serializing Collections
-Untyped Objects
-.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.
- - - + ++ Serialization Guide
+ 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. +
++ Complex Types
+| + .NET + | ++ JSON + | +
|---|---|
| + IList, IEnumerable, IList<T>, Array + | +
+
+ Array
+
+ + |
+
| + IDictionary, IDictionary<TKey, TValue> + | +
+
+ Object
+
+ + |
+
| + Object (more detail below) + | +
+
+ Object
+
+ + |
+
+ Primitive Types
+| + .NET + | ++ JSON + | +
|---|---|
| + String + | +
+
+ String
+
+ + |
+
|
+ Byte + SByte + UInt16 + Int16 + UInt32 + Int32 + UInt64 + Int64 + + + |
+
+
+ Integer
+
+ + |
+
|
+ Float + Double + Decimal + + + |
+
+
+ Float
+
+ + |
+
| + Enum + | +
+
+ Integer (can be string with
+ StringEnumConverter)
+
+ + |
+
| + DateTime + | +
+
+ String (Serializing Dates in JSON)
+
+ + |
+
| + Byte[] + | +
+
+ String (base 64 encoded)
+
+ + |
+
| + Type + | +
+
+ String (type name)
+
+ + |
+
| + Guid + | +
+
+ String
+
+ + |
+
| + TypeConverter (convertible to String) + | +
+
+ String
+
+ + |
+
+ Breakdown of Type Serialization
++ Objects
++ .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<T> then it + will be deserialized as a List<T>.
++ Read more about serializing collections here: + Serializing Collections +
++ Dictionarys and Hashtables
++ .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<TKey, TValue> + then it will be deserialized as a Dictionary<TKey, TValue>.
++ Read more about serializing collections here: + Serializing Collections
++ Untyped Objects
++ .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 +