513 lines
17 KiB
HTML
513 lines
17 KiB
HTML
|
<html>
|
||
|
|
|
||
|
|
<head>
|
||
|
|
<title>Serialization Settings</title>
|
||
|
|
<link href="styles.css" rel="stylesheet" type="text/css" />
|
||
|
|
<link href="custom.css" rel="stylesheet" type="text/css" />
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body>
|
||
|
|
|
||
|
|
<div id="control">
|
||
|
|
<span class="productTitle">Json.NET - Quick Starts & API Documentation</span><br />
|
||
|
|
<span class="topicTitle">Serialization Settings</span></div>
|
||
|
|
|
||
|
|
<div id="content">
|
||
|
|
<span style="color: DarkGray"> </span>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<h3>DateFormatHandling</h3>
|
||
|
|
<p>DateFormatHandling controls how dates are serialized.</p>
|
||
|
|
<table class="members">
|
||
|
|
<tbody>
|
||
|
|
<tr>
|
||
|
|
<th class="nameColumn">
|
||
|
|
Member
|
||
|
|
</th>
|
||
|
|
<th class="descriptionColumn">
|
||
|
|
Description
|
||
|
|
</th>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>
|
||
|
|
<b>IsoDateFormat</b>
|
||
|
|
</td>
|
||
|
|
<td>
|
||
|
|
<div class="summary">
|
||
|
|
By default Json.NET writes dates in the ISO 8601 format, e.g. "2012-03-21T05:40Z".
|
||
|
|
</div>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>
|
||
|
|
<b>MicrosoftDateFormat</b>
|
||
|
|
</td>
|
||
|
|
<td>
|
||
|
|
<div class="summary">
|
||
|
|
Dates are written in the Microsoft JSON format, e.g. "\/Date(1198908717056)\/".
|
||
|
|
</div>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<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.
|
||
|
|
</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.
|
||
|
|
</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>
|
||
|
|
<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.
|
||
|
|
</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>
|
||
|
|
<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.
|
||
|
|
</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.
|
||
|
|
</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>
|
||
|
|
<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.
|
||
|
|
</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>
|
||
|
|
<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.
|
||
|
|
</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>
|
||
|
|
<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.
|
||
|
|
</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>
|
||
|
|
<h3>Binder</h3>
|
||
|
|
<p>The serialization binder is used to resolve type names to a .NET type.</p>
|
||
|
|
<p>Read more about the serialization binder here:
|
||
|
|
<a href="http://msdn.microsoft.com/en-us/library/ffas09b2" target="_blank">SerializationBinder</a></p>
|
||
|
|
<h3>ConstructorHandling</h3>
|
||
|
|
<p>ConstructorHandling controls how constructors are used when initializing objects
|
||
|
|
during deserialization.</p>
|
||
|
|
<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), then check if
|
||
|
|
the class has a single public constructor with arguments and finally check
|
||
|
|
for a non-public default constructor. 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.
|
||
|
|
</div>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>
|
||
|
|
<b>AllowNonPublicDefaultConstructor</b>
|
||
|
|
</td>
|
||
|
|
<td>
|
||
|
|
<div class="summary">
|
||
|
|
Json.NET will use a classes private default constructor before constructors
|
||
|
|
with arguments 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>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>To create your own custom converter inherit from the JsonConverter class. Read
|
||
|
|
more about the built-in JsonConverters below:</p>
|
||
|
|
<ul>
|
||
|
|
<li><a href="DatesInJSON.html">Serializing Dates in JSON</a></li>
|
||
|
|
<li><a href="ConvertingJSONandXML.html">Converting between JSON and XML</a></li>
|
||
|
|
<li><a href="CustomCreationConverter.html">CustomCreationConverter</a></li>
|
||
|
|
<li><a href="html/T_Newtonsoft_Json_Converters_StringEnumConverter.htm">
|
||
|
|
StringEnumConverter</a></li>
|
||
|
|
</ul>
|
||
|
|
<h3>ContractResolver</h3>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>Read more about Contract Resolvers here: <a href="ContractResolver.html">Contract
|
||
|
|
Resolvers</a></p>
|
||
|
|
<h3>Error</h3>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>Read more about error handling here: <a href="SerializationErrorHandling.html">
|
||
|
|
Serialization Error Handling</a></p>
|
||
|
|
|
||
|
|
|
||
|
|
<div id="footer">
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
|
||
|
|
</html>
|