<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>