-Updated documentation
This commit is contained in:
JamesNK
+322
-226
@@ -1,228 +1,324 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<title>Customizing JSON serialization with attributes</title>
|
||||
<link href="styles.css" rel="stylesheet" type="text/css" />
|
||||
<link href="custom.css" rel="stylesheet" type="text/css" />
|
||||
<style type="text/css">
|
||||
.style1
|
||||
{
|
||||
width: 100%;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<div id="control">
|
||||
<span class="productTitle">Json.NET - Quick Starts & API Documentation</span><br />
|
||||
<span class="topicTitle">Serialization Guide</span></div>
|
||||
|
||||
<div id="content">
|
||||
<span style="color: DarkGray"> </span>
|
||||
|
||||
<p>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.</p>
|
||||
<h3>Summary</h3>
|
||||
<p>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.</p>
|
||||
<p>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. </p>
|
||||
<h4><strong>Complex Types</strong></h4>
|
||||
<table class="style1">
|
||||
<tr>
|
||||
<td>
|
||||
.NET</td>
|
||||
<td>
|
||||
JSON</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
IList, IEnumerable, IList<T>, Array</td>
|
||||
<td>
|
||||
Array</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
IDictionary, IDictionary<TKey,
|
||||
TValue></td>
|
||||
<td>
|
||||
Object</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
Object
|
||||
(more detail below)</td>
|
||||
<td>Object</td>
|
||||
</tr>
|
||||
</table>
|
||||
<h4><strong>Primitive Types</strong></h4>
|
||||
<table class="style1">
|
||||
<tr>
|
||||
<td>
|
||||
.NET .NET</td>
|
||||
<td>
|
||||
JSON</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
String</td>
|
||||
<td>
|
||||
String</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
Byte<br />
|
||||
SByte<br />
|
||||
UInt16<br />
|
||||
Int16<br />
|
||||
UInt32<br />
|
||||
Int32<br />
|
||||
UInt64<br />
|
||||
Int64</td>
|
||||
<td>
|
||||
Integer</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
Float<br />
|
||||
Double<br />
|
||||
Decimal</td>
|
||||
<td>
|
||||
Float</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
Enum</td>
|
||||
<td>
|
||||
Integer (can be string with
|
||||
<a href="html/T_Newtonsoft_Json_Converters_StringEnumConverter.htm">StringEnumConverter</a>)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
DateTime</td>
|
||||
<td>
|
||||
String (<a href="DatesInJSON.html">Serializing Dates in JSON</a>)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
Byte[]</td>
|
||||
<td>
|
||||
String (base 64 encoded)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
Type</td>
|
||||
<td>
|
||||
String (type name)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
Guid</td>
|
||||
<td>
|
||||
String</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<a href="http://msdn.microsoft.com/en-us/library/system.componentmodel.typeconverter.aspx" target="_blank">
|
||||
TypeConverter</a> (convertible to String)</td>
|
||||
<td>String</td>
|
||||
</tr>
|
||||
</table>
|
||||
<h3>Breakdown of Type Serialization</h3>
|
||||
<h4><strong>Objects</strong></h4>
|
||||
<p>.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.</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 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>
|
||||
<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, Value>
|
||||
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>
|
||||
<head>
|
||||
<title>Serialization Guide</title>
|
||||
<link href="styles.css" rel="stylesheet" type="text/css" />
|
||||
<link href="custom.css" rel="stylesheet" type="text/css" />
|
||||
<style type="text/css">
|
||||
.style1
|
||||
{
|
||||
width: 100%;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div id="control">
|
||||
<span class="productTitle">Json.NET - Quick Starts & API Documentation</span><br />
|
||||
<span class="topicTitle">Serialization Guide</span></div>
|
||||
<div id="content">
|
||||
<span style="color: DarkGray"></span>
|
||||
<p>
|
||||
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.</p>
|
||||
<h3>
|
||||
Summary</h3>
|
||||
<p>
|
||||
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.</p>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
<h4>
|
||||
<strong>Complex Types</strong></h4>
|
||||
<table class="members">
|
||||
<tbody>
|
||||
<tr>
|
||||
<th class="nameColumn">
|
||||
.NET
|
||||
</th>
|
||||
<th class="descriptionColumn">
|
||||
JSON
|
||||
</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>IList, IEnumerable, IList<T>, Array</b>
|
||||
</td>
|
||||
<td>
|
||||
<div class="summary">
|
||||
Array
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>IDictionary, IDictionary<TKey, TValue></b>
|
||||
</td>
|
||||
<td>
|
||||
<div class="summary">
|
||||
Object
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Object (more detail below)</b>
|
||||
</td>
|
||||
<td>
|
||||
<div class="summary">
|
||||
Object
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h4>
|
||||
<strong>Primitive Types</strong></h4>
|
||||
<table class="members">
|
||||
<tbody>
|
||||
<tr>
|
||||
<th class="nameColumn">
|
||||
.NET
|
||||
</th>
|
||||
<th class="descriptionColumn">
|
||||
JSON
|
||||
</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>String</b>
|
||||
</td>
|
||||
<td>
|
||||
<div class="summary">
|
||||
String
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Byte<br />
|
||||
SByte<br />
|
||||
UInt16<br />
|
||||
Int16<br />
|
||||
UInt32<br />
|
||||
Int32<br />
|
||||
UInt64<br />
|
||||
Int64<br />
|
||||
<br />
|
||||
</b>
|
||||
</td>
|
||||
<td>
|
||||
<div class="summary">
|
||||
Integer
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Float<br />
|
||||
Double<br />
|
||||
Decimal<br />
|
||||
<br />
|
||||
</b>
|
||||
</td>
|
||||
<td>
|
||||
<div class="summary">
|
||||
Float
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Enum</b>
|
||||
</td>
|
||||
<td>
|
||||
<div class="summary">
|
||||
Integer (can be string with <a href="html/T_Newtonsoft_Json_Converters_StringEnumConverter.htm">
|
||||
StringEnumConverter</a>)
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>DateTime</b>
|
||||
</td>
|
||||
<td>
|
||||
<div class="summary">
|
||||
String (<a href="DatesInJSON.html">Serializing Dates in JSON</a>)
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Byte[]</b>
|
||||
</td>
|
||||
<td>
|
||||
<div class="summary">
|
||||
String (base 64 encoded)
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Type</b>
|
||||
</td>
|
||||
<td>
|
||||
<div class="summary">
|
||||
String (type name)
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Guid</b>
|
||||
</td>
|
||||
<td>
|
||||
<div class="summary">
|
||||
String
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b><a href="http://msdn.microsoft.com/en-us/library/system.componentmodel.typeconverter.aspx"
|
||||
target="_blank">TypeConverter</a> (convertible to String)</b>
|
||||
</td>
|
||||
<td>
|
||||
<div class="summary">
|
||||
String
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3>
|
||||
Breakdown of Type Serialization</h3>
|
||||
<h4>
|
||||
<strong>Objects</strong></h4>
|
||||
<p>
|
||||
.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.</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
|
||||
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>
|
||||
<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>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
+355
-58
@@ -1,7 +1,7 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<title>Customizing JSON serialization with attributes</title>
|
||||
<title>Serialization Settings</title>
|
||||
<link href="styles.css" rel="stylesheet" type="text/css" />
|
||||
<link href="custom.css" rel="stylesheet" type="text/css" />
|
||||
</head>
|
||||
@@ -22,95 +22,361 @@
|
||||
<h3>MissingMemberHandling</h3>
|
||||
<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>
|
||||
<ul>
|
||||
<li><strong>Ignore</strong> - By default Json.NET ignores JSON if there is no field
|
||||
or property for its value to be set to during deserialization.</li>
|
||||
<li><strong>Error</strong> - Json.NET errors when there is a missing member during
|
||||
deserialization.</li>
|
||||
</ul>
|
||||
<table class="members">
|
||||
<tbody>
|
||||
<tr>
|
||||
<th class="nameColumn">
|
||||
Member
|
||||
</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>
|
||||
<p>ReferenceLoopHandling controls how circular referencing objects, e.g. a Person
|
||||
object referencing itself via a Manager property, are serialized.</p>
|
||||
<ul>
|
||||
<li><strong>Error</strong> - By default Json.NET will error if a reference loop is
|
||||
encountered (otherwise the serializer will get into an infinite loop).</li>
|
||||
<li><strong>Ignore</strong> - Json.NET will ignore objects in reference loops and
|
||||
<table class="members">
|
||||
<tbody>
|
||||
<tr>
|
||||
<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
|
||||
serialized as usual but if the object is encountered as a child object of itself
|
||||
the serializer will skip serializing it.</li>
|
||||
<li><strong>Serialize</strong> - This option forces Json.NET to serialize objects in
|
||||
the serializer will skip serializing it.
|
||||
</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.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<p>ReferenceLoopHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
|
||||
<h3>NullValueHandling</h3>
|
||||
<p>NullValueHandling controls how null values on .NET objects are handled during
|
||||
serialization and how null values in JSON are handled during deserialization.</p>
|
||||
<ul>
|
||||
<li><strong>Include</strong> - By default Json.NET writes null values to JSON when
|
||||
serializing and sets null values to fields/properties when deserializing.</li>
|
||||
<li><strong>Ignore</strong> - Json.NET will skip writing JSON properties if the .NET
|
||||
<table class="members">
|
||||
<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 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
|
||||
JSON property is null when deserializing. </li>
|
||||
</ul>
|
||||
JSON property is null when deserializing.
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<p>NullValueHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
|
||||
<h3>
|
||||
DefaultValueHandling</h3>
|
||||
<p>
|
||||
DefaultValueHandling controls how Json.NET uses default values set using the .NET
|
||||
DefaultValueAttribute when serializing and deserializing.</p>
|
||||
<ul>
|
||||
<li><strong>Include</strong> - By default Json.NET will write a field/property value
|
||||
<table class="members">
|
||||
<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
|
||||
default value. The Json.NET deserializer will continue setting a field/property
|
||||
if the JSON value is the same as the default value.</li>
|
||||
<li><strong>Ignore</strong> - Json.NET will skip writing a field/property value to
|
||||
if the JSON value is the same as the default value.
|
||||
</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.NET deserializer will skip setting a .NET object’s field/property if the
|
||||
JSON value is the same as the default value. </li>
|
||||
</ul>
|
||||
JSON value is the same as the default value.
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<p>DefaultValueHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
|
||||
<h3>ObjectCreationHandling</h3>
|
||||
<p>ObjectCreationHandling controls how objects are created and deserialized to
|
||||
during deserialization.</p>
|
||||
<ul>
|
||||
<li><strong>Auto</strong> - By default Json.NET will attempt to set JSON values onto
|
||||
<table class="members">
|
||||
<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
|
||||
deserialization.</li>
|
||||
<li><strong>Reuse</strong> - Same behaviour as auto.</li>
|
||||
<li><strong>Replace</strong> - Json.NET will always recreate objects and collections
|
||||
before setting values to them during deserialization. </li>
|
||||
</ul>
|
||||
deserialization.
|
||||
</div>
|
||||
<br>
|
||||
</td>
|
||||
</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>
|
||||
<h3>TypeNameHandling</h3>
|
||||
<p>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.</p>
|
||||
<ul>
|
||||
<li><strong>None</strong> - By default Json.NET does not read or write type names
|
||||
during deserialization.</li>
|
||||
<li><strong>Objects</strong> - Json.NET will write and use type names for objects
|
||||
but not collections.</li>
|
||||
<li><strong>Arrays</strong> - Json.NET will write and use type names for collections
|
||||
but not objects.</li>
|
||||
<li><strong>Auto</strong> - Json.NET will check whether an object/collection matches
|
||||
<table class="members">
|
||||
<tbody>
|
||||
<tr>
|
||||
<th class="nameColumn">
|
||||
Member
|
||||
</th>
|
||||
<th class="descriptionColumn">
|
||||
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
|
||||
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.</li>
|
||||
<li><strong>All</strong> - Json.NET will write and use type names for objects and
|
||||
collections. </li>
|
||||
</ul>
|
||||
automatically without having to write type names for every object.
|
||||
</div>
|
||||
<br>
|
||||
</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>
|
||||
<h3>TypeNameAssemblyFormat</h3>
|
||||
<p>TypeNameAssemblyFormat controls how type names are written during serialization.</p>
|
||||
<ul>
|
||||
<li><strong>Simple</strong> - By default Json.NET writes the partial assembly name
|
||||
<table class="members">
|
||||
<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
|
||||
Windows Phone are not able to use this format.</li>
|
||||
<li><strong>Full</strong> - Json.NET will write the full assembly name, including
|
||||
version number, culture and public key token.</li>
|
||||
</ul>
|
||||
Windows Phone are not able to use this format.
|
||||
</div>
|
||||
<br>
|
||||
</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
|
||||
<a href="http://msdn.microsoft.com/en-us/library/tt9xha1h" target="_blank">
|
||||
FormatterAssemblyStyle</a>. </p>
|
||||
@@ -121,16 +387,47 @@ DefaultValueHandling controls how Json.NET uses default values set using the .NE
|
||||
<h3>ConstructorHandling</h3>
|
||||
<p>ConstructorHandling controls how constructors are used when initializing objects
|
||||
during deserialization.</p>
|
||||
<ul>
|
||||
<li><strong>Default</strong> - By default Json.NET will first look for a constructor
|
||||
<table class="members">
|
||||
<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
|
||||
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.</li>
|
||||
<li><strong>AllowNonPublicDefaultConstructor</strong> - Json.NET will fallback to
|
||||
using a classes private default constructor if available. </li>
|
||||
</ul>
|
||||
fixed by marking one of the constructors with the JsonConstructorAttribute.
|
||||
</div>
|
||||
<br>
|
||||
</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>
|
||||
<p>This is the collection of JsonConverters that will be used during serialization
|
||||
and deserialization. </p>
|
||||
|
||||
Reference in New Issue
Block a user