174 lines
10 KiB
HTML
174 lines
10 KiB
HTML
<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" />
|
||
</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>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
|
||
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
|
||
reference loops. This is useful if objects are nested but not indefinitely.
|
||
</li>
|
||
</ul>
|
||
|
||
<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>
|
||
<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
|
||
value is null when serializing and will skip setting fields/properties if the
|
||
JSON property is null when deserializing. </li>
|
||
</ul>
|
||
<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
|
||
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
|
||
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>
|
||
<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
|
||
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>
|
||
<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
|
||
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>
|
||
<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
|
||
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>
|
||
<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>
|
||
<ul>
|
||
<li><strong>Default</strong> - 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>
|
||
<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> |