-Updated documentation
This commit is contained in:
JamesNK
+322
-226
@@ -1,228 +1,324 @@
|
|||||||
<html>
|
<html>
|
||||||
|
<head>
|
||||||
<head>
|
<title>Serialization Guide</title>
|
||||||
<title>Customizing JSON serialization with attributes</title>
|
<link href="styles.css" rel="stylesheet" type="text/css" />
|
||||||
<link href="styles.css" rel="stylesheet" type="text/css" />
|
<link href="custom.css" rel="stylesheet" type="text/css" />
|
||||||
<link href="custom.css" rel="stylesheet" type="text/css" />
|
<style type="text/css">
|
||||||
<style type="text/css">
|
.style1
|
||||||
.style1
|
{
|
||||||
{
|
width: 100%;
|
||||||
width: 100%;
|
}
|
||||||
}
|
</style>
|
||||||
</style>
|
</head>
|
||||||
</head>
|
<body>
|
||||||
|
<div id="control">
|
||||||
<body>
|
<span class="productTitle">Json.NET - Quick Starts & API Documentation</span><br />
|
||||||
|
<span class="topicTitle">Serialization Guide</span></div>
|
||||||
<div id="control">
|
<div id="content">
|
||||||
<span class="productTitle">Json.NET - Quick Starts & API Documentation</span><br />
|
<span style="color: DarkGray"></span>
|
||||||
<span class="topicTitle">Serialization Guide</span></div>
|
<p>
|
||||||
|
The Json.NET serializer can serialize a wide variety of .NET objects. This guide
|
||||||
<div id="content">
|
looks at how it works at a high level and in more detail.</p>
|
||||||
<span style="color: DarkGray"> </span>
|
<h3>
|
||||||
|
Summary</h3>
|
||||||
<p>The Json.NET serializer can serialize a wide variety of .NET objects. This guide
|
<p>
|
||||||
looks at how it works at a high level and in more detail.</p>
|
At a high level, the Json.NET serializer will convert primitive .NET values into
|
||||||
<h3>Summary</h3>
|
primitive JSON values, .NET arrays and collections to JSON arrays and everything
|
||||||
<p>At a high level, the Json.NET serializer will convert primitive .NET values into
|
else to JSON objects.</p>
|
||||||
primitive JSON values, .NET arrays and collections to JSON arrays and everything
|
<p>
|
||||||
else to JSON objects.</p>
|
Json.NET will throw an error if it encounters incorrect JSON when deserializing
|
||||||
<p>Json.NET will throw an error if it encounters incorrect JSON when deserializing a
|
a value. For example if the serializer encounters a JSON property with an array
|
||||||
value. For example if the serializer encounters a JSON property with an array of
|
of values and the type of matching .NET property is not a collection then an error
|
||||||
values and the type of matching .NET property is not a collection then an error
|
will be thrown, and vice-versa.
|
||||||
will be thrown, and vice-versa. </p>
|
</p>
|
||||||
<h4><strong>Complex Types</strong></h4>
|
<h4>
|
||||||
<table class="style1">
|
<strong>Complex Types</strong></h4>
|
||||||
<tr>
|
<table class="members">
|
||||||
<td>
|
<tbody>
|
||||||
.NET</td>
|
<tr>
|
||||||
<td>
|
<th class="nameColumn">
|
||||||
JSON</td>
|
.NET
|
||||||
</tr>
|
</th>
|
||||||
<tr>
|
<th class="descriptionColumn">
|
||||||
<td>
|
JSON
|
||||||
IList, IEnumerable, IList<T>, Array</td>
|
</th>
|
||||||
<td>
|
</tr>
|
||||||
Array</td>
|
<tr>
|
||||||
</tr>
|
<td>
|
||||||
<tr>
|
<b>IList, IEnumerable, IList<T>, Array</b>
|
||||||
<td>
|
</td>
|
||||||
IDictionary, IDictionary<TKey,
|
<td>
|
||||||
TValue></td>
|
<div class="summary">
|
||||||
<td>
|
Array
|
||||||
Object</td>
|
</div>
|
||||||
</tr>
|
<br>
|
||||||
<tr>
|
</td>
|
||||||
<td>
|
</tr>
|
||||||
Object
|
<tr>
|
||||||
(more detail below)</td>
|
<td>
|
||||||
<td>Object</td>
|
<b>IDictionary, IDictionary<TKey, TValue></b>
|
||||||
</tr>
|
</td>
|
||||||
</table>
|
<td>
|
||||||
<h4><strong>Primitive Types</strong></h4>
|
<div class="summary">
|
||||||
<table class="style1">
|
Object
|
||||||
<tr>
|
</div>
|
||||||
<td>
|
<br>
|
||||||
.NET .NET</td>
|
</td>
|
||||||
<td>
|
</tr>
|
||||||
JSON</td>
|
<tr>
|
||||||
</tr>
|
<td>
|
||||||
<tr>
|
<b>Object (more detail below)</b>
|
||||||
<td>
|
</td>
|
||||||
String</td>
|
<td>
|
||||||
<td>
|
<div class="summary">
|
||||||
String</td>
|
Object
|
||||||
</tr>
|
</div>
|
||||||
<tr>
|
<br>
|
||||||
<td>
|
</td>
|
||||||
Byte<br />
|
</tr>
|
||||||
SByte<br />
|
</tbody>
|
||||||
UInt16<br />
|
</table>
|
||||||
Int16<br />
|
<h4>
|
||||||
UInt32<br />
|
<strong>Primitive Types</strong></h4>
|
||||||
Int32<br />
|
<table class="members">
|
||||||
UInt64<br />
|
<tbody>
|
||||||
Int64</td>
|
<tr>
|
||||||
<td>
|
<th class="nameColumn">
|
||||||
Integer</td>
|
.NET
|
||||||
</tr>
|
</th>
|
||||||
<tr>
|
<th class="descriptionColumn">
|
||||||
<td>
|
JSON
|
||||||
Float<br />
|
</th>
|
||||||
Double<br />
|
</tr>
|
||||||
Decimal</td>
|
<tr>
|
||||||
<td>
|
<td>
|
||||||
Float</td>
|
<b>String</b>
|
||||||
</tr>
|
</td>
|
||||||
<tr>
|
<td>
|
||||||
<td>
|
<div class="summary">
|
||||||
Enum</td>
|
String
|
||||||
<td>
|
</div>
|
||||||
Integer (can be string with
|
<br>
|
||||||
<a href="html/T_Newtonsoft_Json_Converters_StringEnumConverter.htm">StringEnumConverter</a>)</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>
|
<td>
|
||||||
DateTime</td>
|
<b>Byte<br />
|
||||||
<td>
|
SByte<br />
|
||||||
String (<a href="DatesInJSON.html">Serializing Dates in JSON</a>)</td>
|
UInt16<br />
|
||||||
</tr>
|
Int16<br />
|
||||||
<tr>
|
UInt32<br />
|
||||||
<td>
|
Int32<br />
|
||||||
Byte[]</td>
|
UInt64<br />
|
||||||
<td>
|
Int64<br />
|
||||||
String (base 64 encoded)</td>
|
<br />
|
||||||
</tr>
|
</b>
|
||||||
<tr>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
Type</td>
|
<div class="summary">
|
||||||
<td>
|
Integer
|
||||||
String (type name)</td>
|
</div>
|
||||||
</tr>
|
<br>
|
||||||
<tr>
|
</td>
|
||||||
<td>
|
</tr>
|
||||||
Guid</td>
|
<tr>
|
||||||
<td>
|
<td>
|
||||||
String</td>
|
<b>Float<br />
|
||||||
</tr>
|
Double<br />
|
||||||
<tr>
|
Decimal<br />
|
||||||
<td>
|
<br />
|
||||||
<a href="http://msdn.microsoft.com/en-us/library/system.componentmodel.typeconverter.aspx" target="_blank">
|
</b>
|
||||||
TypeConverter</a> (convertible to String)</td>
|
</td>
|
||||||
<td>String</td>
|
<td>
|
||||||
</tr>
|
<div class="summary">
|
||||||
</table>
|
Float
|
||||||
<h3>Breakdown of Type Serialization</h3>
|
</div>
|
||||||
<h4><strong>Objects</strong></h4>
|
<br>
|
||||||
<p>.NET types that don’t fall into any other category listed below (i.e. aren’t
|
</td>
|
||||||
lists, dictionaries, dynamic, implement ISerializable, etc) are serialized as
|
</tr>
|
||||||
JSON objects.</p>
|
<tr>
|
||||||
<p>By default types are serialized in opt-out mode. What that means is all public
|
<td>
|
||||||
fields and properties with getters are automatically serialized to JSON and
|
<b>Enum</b>
|
||||||
members that shouldn’t be serialized are opted-out using the
|
</td>
|
||||||
JsonIgnoreAttribute. To serialize private members the JsonPropertyAttribute can
|
<td>
|
||||||
be placed on private fields and properties or the DefaultMembersSearchFlags can
|
<div class="summary">
|
||||||
be changed on DefaultContractResolver to change how members are serialized on
|
Integer (can be string with <a href="html/T_Newtonsoft_Json_Converters_StringEnumConverter.htm">
|
||||||
all types.</p>
|
StringEnumConverter</a>)
|
||||||
<p>Types can also be serialized using opt-in mode. Only fields that have a
|
</div>
|
||||||
JsonPropertyAttribute or DataMemberAttribute on them will be serialized. Opt-in
|
<br>
|
||||||
mode for an object is specified using the JsonObjectAttribute on the class. </p>
|
</td>
|
||||||
<h4><strong>IEnumerable, Lists and Arrays</strong></h4>
|
</tr>
|
||||||
<p>.NET lists (types that inherit from IEnumerable) and .NET arrays are converted to
|
<tr>
|
||||||
JSON arrays. Because JSON arrays only support a range of values and not
|
<td>
|
||||||
properties, any additional properties and fields declared on .NET collections
|
<b>DateTime</b>
|
||||||
are not serialized. In situations where a JSON array is not wanted the
|
</td>
|
||||||
JsonObjectAttribute can be placed on a .NET type that implements IEnumerable to
|
<td>
|
||||||
force the type to be serialized as a JSON object instead.</p>
|
<div class="summary">
|
||||||
<p>Note that if TypeNameHandling or PreserveReferencesHandling has been enabled for
|
String (<a href="DatesInJSON.html">Serializing Dates in JSON</a>)
|
||||||
JSON arrays on the serializer then JSON arrays are wrapped it a containing
|
</div>
|
||||||
object. The object will have the type name/reference properties and a $values
|
<br>
|
||||||
property which will have the collection data.</p>
|
</td>
|
||||||
<p>When deserializing if a member is typed as the interface IList<T> then it will be
|
</tr>
|
||||||
deserialized as a List<T>.</p>
|
<tr>
|
||||||
<p>Read more about serializing collections here:
|
<td>
|
||||||
<a href="SerializingCollections.html">Serializing Collections </a></p>
|
<b>Byte[]</b>
|
||||||
<h4><strong>Dictionarys and Hashtables</strong></h4>
|
</td>
|
||||||
<p>.NET dictionaries (types that inherit from IDictionary) are converted to JSON
|
<td>
|
||||||
objects. Note that only the dictionary name/values will be written to the JSON
|
<div class="summary">
|
||||||
object when serializing and properties on the JSON object will be added to the
|
String (base 64 encoded)
|
||||||
dictionary’s name/values when deserializing. Additional members on the .NET
|
</div>
|
||||||
dictionary are ignored during serialization.</p>
|
<br>
|
||||||
<p>When deserializing if a member is typed as the interface IDictionary<TKey, Value>
|
</td>
|
||||||
then it will be deserialized as a Dictionary<TKey, TValue>.</p>
|
</tr>
|
||||||
<p>Read more about serializing collections here:
|
<tr>
|
||||||
<a href="SerializingCollections.html">Serializing Collections</a></p>
|
<td>
|
||||||
<h4><strong>Untyped Objects</strong></h4>
|
<b>Type</b>
|
||||||
<p>.NET properties on a class that don’t specify a type (i.e. they are just object)
|
</td>
|
||||||
are serialized as usual. When untyped properties are deserialized the serializer
|
<td>
|
||||||
has no way to know what type to create (unless type name handling is enabled and
|
<div class="summary">
|
||||||
the JSON contains the type names).</p>
|
String (type name)
|
||||||
<p>For these untyped properties the Json.NET serializer will read the JSON into LINQ
|
</div>
|
||||||
to JSON objects and set them to the property. </p>
|
<br>
|
||||||
<h4><strong>Dynamic</strong></h4>
|
</td>
|
||||||
<p>.NET dynamic objects (introduced in .NET 4) are serialized as JSON objects. A
|
</tr>
|
||||||
property is written for every member name returned by
|
<tr>
|
||||||
IDynamicMetaObjectProvider.GetDynamicMemberNames.</p>
|
<td>
|
||||||
<p>When deserializing the serializer first attempts to set JSON property values on a
|
<b>Guid</b>
|
||||||
normal .NET member with the matching name. If no .NET member is found with the
|
</td>
|
||||||
property name then the serializer will call SetMember on the dynamic object.</p>
|
<td>
|
||||||
<p>Because a dynamic property on a class doesn’t specify a type, Json.NET has no way
|
<div class="summary">
|
||||||
to know what type to create for it when deserializing (unless type name handling
|
String
|
||||||
is enabled and the JSON contains the type name). LINQ to JSON objects will be
|
</div>
|
||||||
created for the JSON. </p>
|
<br>
|
||||||
<h4><strong>ISerializable</strong></h4>
|
</td>
|
||||||
<p>Types that implement ISerializable are serialized as JSON objects. When
|
</tr>
|
||||||
serializing only the values returned from ISerializable.GetObjectData are used;
|
<tr>
|
||||||
members on the type are ignored. When deserializing the constructor with a
|
<td>
|
||||||
SerializationInfo and StreamingContext is called, passing the JSON object’s
|
<b><a href="http://msdn.microsoft.com/en-us/library/system.componentmodel.typeconverter.aspx"
|
||||||
values.</p>
|
target="_blank">TypeConverter</a> (convertible to String)</b>
|
||||||
<p>In situations where this behaviour is not wanted the JsonObjectAttribute can be
|
</td>
|
||||||
placed on a .NET type that implements ISerializable to force it to be serialized
|
<td>
|
||||||
as a normal JSON object. </p>
|
<div class="summary">
|
||||||
<h4><strong>LINQ to JSON</strong></h4>
|
String
|
||||||
<p>LINQ to JSON types (e.g. JObject, JArray) are automatically serialized and
|
</div>
|
||||||
deserialized to their equivalent JSON when encountered by the Json.NET
|
<br>
|
||||||
serializer. </p>
|
</td>
|
||||||
<h4><strong>JsonConverter</strong></h4>
|
</tr>
|
||||||
<p>Serialization of values that are convertible by a JsonConverter (i.e. CanConvert
|
</tbody>
|
||||||
returns true for its type) is completely overridden by the JsonConverter. The
|
</table>
|
||||||
test to see whether a value can be converted by a JsonSerializer takes
|
<h3>
|
||||||
precedence over all other tests.</p>
|
Breakdown of Type Serialization</h3>
|
||||||
<p>JsonConverters can be defined and specified in a number of places: in an
|
<h4>
|
||||||
attribute on a member, in an attribute on a class and added to the
|
<strong>Objects</strong></h4>
|
||||||
JsonSerializer’s converters collection. The priority of which JsonConverter is
|
<p>
|
||||||
used is the JsonConverter defined by attribute on a member then the
|
.NET types that don’t fall into any other category listed below (i.e. aren’t lists,
|
||||||
JsonConverter defined by an attribute on a class and finally any converters
|
dictionaries, dynamic, implement ISerializable, etc) are serialized as JSON objects.</p>
|
||||||
passed to the JsonSerializer.</p>
|
<p>
|
||||||
|
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
|
||||||
<div id="footer">
|
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.</p>
|
||||||
</div>
|
<p>
|
||||||
|
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.
|
||||||
|
</p>
|
||||||
|
<h4>
|
||||||
|
<strong>IEnumerable, Lists and Arrays</strong></h4>
|
||||||
|
<p>
|
||||||
|
.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.</p>
|
||||||
|
<p>
|
||||||
|
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.</p>
|
||||||
|
<p>
|
||||||
|
When deserializing if a member is typed as the interface IList<T> then it
|
||||||
|
will be deserialized as a List<T>.</p>
|
||||||
|
<p>
|
||||||
|
Read more about serializing collections here: <a href="SerializingCollections.html">
|
||||||
|
Serializing Collections </a>
|
||||||
|
</p>
|
||||||
|
<h4>
|
||||||
|
<strong>Dictionarys and Hashtables</strong></h4>
|
||||||
|
<p>
|
||||||
|
.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.</p>
|
||||||
|
<p>
|
||||||
|
When deserializing if a member is typed as the interface IDictionary<TKey, TValue>
|
||||||
|
then it will be deserialized as a Dictionary<TKey, TValue>.</p>
|
||||||
|
<p>
|
||||||
|
Read more about serializing collections here: <a href="SerializingCollections.html">
|
||||||
|
Serializing Collections</a></p>
|
||||||
|
<h4>
|
||||||
|
<strong>Untyped Objects</strong></h4>
|
||||||
|
<p>
|
||||||
|
.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).</p>
|
||||||
|
<p>
|
||||||
|
For these untyped properties the Json.NET serializer will read the JSON into LINQ
|
||||||
|
to JSON objects and set them to the property.
|
||||||
|
</p>
|
||||||
|
<h4>
|
||||||
|
<strong>Dynamic</strong></h4>
|
||||||
|
<p>
|
||||||
|
.NET dynamic objects (introduced in .NET 4) are serialized as JSON objects. A property
|
||||||
|
is written for every member name returned by IDynamicMetaObjectProvider.GetDynamicMemberNames.</p>
|
||||||
|
<p>
|
||||||
|
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.</p>
|
||||||
|
<p>
|
||||||
|
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.
|
||||||
|
</p>
|
||||||
|
<h4>
|
||||||
|
<strong>ISerializable</strong></h4>
|
||||||
|
<p>
|
||||||
|
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.</p>
|
||||||
|
<p>
|
||||||
|
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.
|
||||||
|
</p>
|
||||||
|
<h4>
|
||||||
|
<strong>LINQ to JSON</strong></h4>
|
||||||
|
<p>
|
||||||
|
LINQ to JSON types (e.g. JObject, JArray) are automatically serialized and deserialized
|
||||||
|
to their equivalent JSON when encountered by the Json.NET serializer.
|
||||||
|
</p>
|
||||||
|
<h4>
|
||||||
|
<strong>JsonConverter</strong></h4>
|
||||||
|
<p>
|
||||||
|
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.</p>
|
||||||
|
<p>
|
||||||
|
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.</p>
|
||||||
|
<div id="footer">
|
||||||
</div>
|
</div>
|
||||||
|
</div>
|
||||||
</body>
|
</body>
|
||||||
|
</html>
|
||||||
</html>
|
|
||||||
|
|||||||
+355
-58
@@ -1,7 +1,7 @@
|
|||||||
<html>
|
<html>
|
||||||
|
|
||||||
<head>
|
<head>
|
||||||
<title>Customizing JSON serialization with attributes</title>
|
<title>Serialization Settings</title>
|
||||||
<link href="styles.css" rel="stylesheet" type="text/css" />
|
<link href="styles.css" rel="stylesheet" type="text/css" />
|
||||||
<link href="custom.css" rel="stylesheet" type="text/css" />
|
<link href="custom.css" rel="stylesheet" type="text/css" />
|
||||||
</head>
|
</head>
|
||||||
@@ -22,95 +22,361 @@
|
|||||||
<h3>MissingMemberHandling</h3>
|
<h3>MissingMemberHandling</h3>
|
||||||
<p>MissingMemberHandling controls how missing members, e.g. JSON contains a property
|
<p>MissingMemberHandling controls how missing members, e.g. JSON contains a property
|
||||||
that isn't a member on the object, are handled during deserialization.</p>
|
that isn't a member on the object, are handled during deserialization.</p>
|
||||||
<ul>
|
<table class="members">
|
||||||
<li><strong>Ignore</strong> - By default Json.NET ignores JSON if there is no field
|
<tbody>
|
||||||
or property for its value to be set to during deserialization.</li>
|
<tr>
|
||||||
<li><strong>Error</strong> - Json.NET errors when there is a missing member during
|
<th class="nameColumn">
|
||||||
deserialization.</li>
|
Member
|
||||||
</ul>
|
</th>
|
||||||
|
<th class="descriptionColumn">
|
||||||
|
Description
|
||||||
|
</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Ignore</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
By default Json.NET ignores JSON if there is no field
|
||||||
|
or property for its value to be set to during deserialization.
|
||||||
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Error</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
Json.NET errors when there is a missing member during
|
||||||
|
deserialization.
|
||||||
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
<h3>ReferenceLoopHandling</h3>
|
<h3>ReferenceLoopHandling</h3>
|
||||||
<p>ReferenceLoopHandling controls how circular referencing objects, e.g. a Person
|
<p>ReferenceLoopHandling controls how circular referencing objects, e.g. a Person
|
||||||
object referencing itself via a Manager property, are serialized.</p>
|
object referencing itself via a Manager property, are serialized.</p>
|
||||||
<ul>
|
<table class="members">
|
||||||
<li><strong>Error</strong> - By default Json.NET will error if a reference loop is
|
<tbody>
|
||||||
encountered (otherwise the serializer will get into an infinite loop).</li>
|
<tr>
|
||||||
<li><strong>Ignore</strong> - Json.NET will ignore objects in reference loops and
|
<th class="nameColumn">
|
||||||
|
Member
|
||||||
|
</th>
|
||||||
|
<th class="descriptionColumn">
|
||||||
|
Description
|
||||||
|
</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Error</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
By default Json.NET will error if a reference loop is
|
||||||
|
encountered (otherwise the serializer will get into an infinite loop).
|
||||||
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Ignore</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
Json.NET will ignore objects in reference loops and
|
||||||
not serialize them. The first time an object is encountered it will be
|
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
|
serialized as usual but if the object is encountered as a child object of itself
|
||||||
the serializer will skip serializing it.</li>
|
the serializer will skip serializing it.
|
||||||
<li><strong>Serialize</strong> - This option forces Json.NET to serialize objects in
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Serialize</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
This option forces Json.NET to serialize objects in
|
||||||
reference loops. This is useful if objects are nested but not indefinitely.
|
reference loops. This is useful if objects are nested but not indefinitely.
|
||||||
</li>
|
</div>
|
||||||
</ul>
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
<p>ReferenceLoopHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
|
<p>ReferenceLoopHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
|
||||||
<h3>NullValueHandling</h3>
|
<h3>NullValueHandling</h3>
|
||||||
<p>NullValueHandling controls how null values on .NET objects are handled during
|
<p>NullValueHandling controls how null values on .NET objects are handled during
|
||||||
serialization and how null values in JSON are handled during deserialization.</p>
|
serialization and how null values in JSON are handled during deserialization.</p>
|
||||||
<ul>
|
<table class="members">
|
||||||
<li><strong>Include</strong> - By default Json.NET writes null values to JSON when
|
<tbody>
|
||||||
serializing and sets null values to fields/properties when deserializing.</li>
|
<tr>
|
||||||
<li><strong>Ignore</strong> - Json.NET will skip writing JSON properties if the .NET
|
<th class="nameColumn">
|
||||||
|
Member
|
||||||
|
</th>
|
||||||
|
<th class="descriptionColumn">
|
||||||
|
Description
|
||||||
|
</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Include</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
By default Json.NET writes null values to JSON when
|
||||||
|
serializing and sets null values to fields/properties when deserializing.
|
||||||
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Ignore</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
Json.NET will skip writing JSON properties if the .NET
|
||||||
value is null when serializing and will skip setting fields/properties if the
|
value is null when serializing and will skip setting fields/properties if the
|
||||||
JSON property is null when deserializing. </li>
|
JSON property is null when deserializing.
|
||||||
</ul>
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
<p>NullValueHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
|
<p>NullValueHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
|
||||||
<h3>
|
<h3>
|
||||||
DefaultValueHandling</h3>
|
DefaultValueHandling</h3>
|
||||||
<p>
|
<p>
|
||||||
DefaultValueHandling controls how Json.NET uses default values set using the .NET
|
DefaultValueHandling controls how Json.NET uses default values set using the .NET
|
||||||
DefaultValueAttribute when serializing and deserializing.</p>
|
DefaultValueAttribute when serializing and deserializing.</p>
|
||||||
<ul>
|
<table class="members">
|
||||||
<li><strong>Include</strong> - By default Json.NET will write a field/property value
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<th class="nameColumn">
|
||||||
|
Member
|
||||||
|
</th>
|
||||||
|
<th class="descriptionColumn">
|
||||||
|
Description
|
||||||
|
</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Include</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
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
|
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
|
default value. The Json.NET deserializer will continue setting a field/property
|
||||||
if the JSON value is the same as the default value.</li>
|
if the JSON value is the same as the default value.
|
||||||
<li><strong>Ignore</strong> - Json.NET will skip writing a field/property value to
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Ignore</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
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 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.NET deserializer will skip setting a .NET object’s field/property if the
|
||||||
JSON value is the same as the default value. </li>
|
JSON value is the same as the default value.
|
||||||
</ul>
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
<p>DefaultValueHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
|
<p>DefaultValueHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
|
||||||
<h3>ObjectCreationHandling</h3>
|
<h3>ObjectCreationHandling</h3>
|
||||||
<p>ObjectCreationHandling controls how objects are created and deserialized to
|
<p>ObjectCreationHandling controls how objects are created and deserialized to
|
||||||
during deserialization.</p>
|
during deserialization.</p>
|
||||||
<ul>
|
<table class="members">
|
||||||
<li><strong>Auto</strong> - By default Json.NET will attempt to set JSON values onto
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<th class="nameColumn">
|
||||||
|
Member
|
||||||
|
</th>
|
||||||
|
<th class="descriptionColumn">
|
||||||
|
Description
|
||||||
|
</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Auto</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
By default Json.NET will attempt to set JSON values onto
|
||||||
existing objects and add JSON values to existing collections during
|
existing objects and add JSON values to existing collections during
|
||||||
deserialization.</li>
|
deserialization.
|
||||||
<li><strong>Reuse</strong> - Same behaviour as auto.</li>
|
</div>
|
||||||
<li><strong>Replace</strong> - Json.NET will always recreate objects and collections
|
<br>
|
||||||
before setting values to them during deserialization. </li>
|
</td>
|
||||||
</ul>
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Reuse</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
Same behaviour as auto.
|
||||||
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Replace</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
Json.NET will always recreate objects and collections
|
||||||
|
before setting values to them during deserialization.
|
||||||
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
<p>ObjectCreationHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
|
<p>ObjectCreationHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
|
||||||
<h3>TypeNameHandling</h3>
|
<h3>TypeNameHandling</h3>
|
||||||
<p>TypeNameHandling controls whether Json.NET includes .NET type names during
|
<p>TypeNameHandling controls whether Json.NET includes .NET type names during
|
||||||
serialization with a $type property and reads .NET type names from that property
|
serialization with a $type property and reads .NET type names from that property
|
||||||
to determine what type to create during deserialization.</p>
|
to determine what type to create during deserialization.</p>
|
||||||
<ul>
|
<table class="members">
|
||||||
<li><strong>None</strong> - By default Json.NET does not read or write type names
|
<tbody>
|
||||||
during deserialization.</li>
|
<tr>
|
||||||
<li><strong>Objects</strong> - Json.NET will write and use type names for objects
|
<th class="nameColumn">
|
||||||
but not collections.</li>
|
Member
|
||||||
<li><strong>Arrays</strong> - Json.NET will write and use type names for collections
|
</th>
|
||||||
but not objects.</li>
|
<th class="descriptionColumn">
|
||||||
<li><strong>Auto</strong> - Json.NET will check whether an object/collection matches
|
Description
|
||||||
|
</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>None</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
By default Json.NET does not read or write type names
|
||||||
|
during deserialization.
|
||||||
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Objects</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
Json.NET will write and use type names for objects
|
||||||
|
but not collections.
|
||||||
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Arrays</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
Json.NET will write and use type names for collections
|
||||||
|
but not objects.
|
||||||
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Auto</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
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
|
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
|
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
|
ensure that type information isn’t lost when serializing/deserializing
|
||||||
automatically without having to write type names for every object.</li>
|
automatically without having to write type names for every object.
|
||||||
<li><strong>All</strong> - Json.NET will write and use type names for objects and
|
</div>
|
||||||
collections. </li>
|
<br>
|
||||||
</ul>
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>All</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
Json.NET will write and use type names for objects and
|
||||||
|
collections.
|
||||||
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
<p>TypeNameHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
|
<p>TypeNameHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
|
||||||
<h3>TypeNameAssemblyFormat</h3>
|
<h3>TypeNameAssemblyFormat</h3>
|
||||||
<p>TypeNameAssemblyFormat controls how type names are written during serialization.</p>
|
<p>TypeNameAssemblyFormat controls how type names are written during serialization.</p>
|
||||||
<ul>
|
<table class="members">
|
||||||
<li><strong>Simple</strong> - By default Json.NET writes the partial assembly name
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<th class="nameColumn">
|
||||||
|
Member
|
||||||
|
</th>
|
||||||
|
<th class="descriptionColumn">
|
||||||
|
Description
|
||||||
|
</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Simple</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
By default Json.NET writes the partial assembly name
|
||||||
with the type, e.g. System.Data.DataSet, System.Data. Note that Silverlight and
|
with the type, e.g. System.Data.DataSet, System.Data. Note that Silverlight and
|
||||||
Windows Phone are not able to use this format.</li>
|
Windows Phone are not able to use this format.
|
||||||
<li><strong>Full</strong> - Json.NET will write the full assembly name, including
|
</div>
|
||||||
version number, culture and public key token.</li>
|
<br>
|
||||||
</ul>
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Full</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
Json.NET will write the full assembly name, including
|
||||||
|
version number, culture and public key token.
|
||||||
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
<p>Read more about the valid values at
|
<p>Read more about the valid values at
|
||||||
<a href="http://msdn.microsoft.com/en-us/library/tt9xha1h" target="_blank">
|
<a href="http://msdn.microsoft.com/en-us/library/tt9xha1h" target="_blank">
|
||||||
FormatterAssemblyStyle</a>. </p>
|
FormatterAssemblyStyle</a>. </p>
|
||||||
@@ -121,16 +387,47 @@ DefaultValueHandling controls how Json.NET uses default values set using the .NE
|
|||||||
<h3>ConstructorHandling</h3>
|
<h3>ConstructorHandling</h3>
|
||||||
<p>ConstructorHandling controls how constructors are used when initializing objects
|
<p>ConstructorHandling controls how constructors are used when initializing objects
|
||||||
during deserialization.</p>
|
during deserialization.</p>
|
||||||
<ul>
|
<table class="members">
|
||||||
<li><strong>Default</strong> - By default Json.NET will first look for a constructor
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<th class="nameColumn">
|
||||||
|
Member
|
||||||
|
</th>
|
||||||
|
<th class="descriptionColumn">
|
||||||
|
Description
|
||||||
|
</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>Default</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
By default Json.NET will first look for a constructor
|
||||||
marked with the JsonConstructorAttribute, then look for a public default
|
marked with the JsonConstructorAttribute, then look for a public default
|
||||||
constructor (a constructor that doesn’t take any arguments) and finally check if
|
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
|
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
|
multiple public constructors with arguments an error will be thrown. This can be
|
||||||
fixed by marking one of the constructors with the JsonConstructorAttribute.</li>
|
fixed by marking one of the constructors with the JsonConstructorAttribute.
|
||||||
<li><strong>AllowNonPublicDefaultConstructor</strong> - Json.NET will fallback to
|
</div>
|
||||||
using a classes private default constructor if available. </li>
|
<br>
|
||||||
</ul>
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<b>AllowNonPublicDefaultConstructor</b>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<div class="summary">
|
||||||
|
Json.NET will fallback to
|
||||||
|
using a classes private default constructor if available.
|
||||||
|
</div>
|
||||||
|
<br>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
<h3>Converters</h3>
|
<h3>Converters</h3>
|
||||||
<p>This is the collection of JsonConverters that will be used during serialization
|
<p>This is the collection of JsonConverters that will be used during serialization
|
||||||
and deserialization. </p>
|
and deserialization. </p>
|
||||||
|
|||||||
Reference in New Issue
Block a user