-Updated documentation
-Added complete ADO.NET Entities serialization and deserialization
This commit is contained in:
@@ -50,8 +50,8 @@
|
||||
</div>
|
||||
</div></div>
|
||||
<p>In most cases this is the desired result but in certain scenarios writing the second item in the list as a reference to the first is a better solution.
|
||||
If the above JSON was deserialized now then returned list would contain two
|
||||
completely seperate Person objects with the same values. Writing references by value will also cause problems on objects where a
|
||||
If the above JSON was deserialized now then the returned list would contain two
|
||||
completely separate Person objects with the same values. Writing references by value will also cause problems on objects where a
|
||||
circular reference occurs.</p>
|
||||
|
||||
<h3>PreserveReferencesHandling</h3>
|
||||
@@ -93,14 +93,18 @@
|
||||
</div>
|
||||
</div></div>
|
||||
|
||||
<p>Now only one Person object is created and the deserialized list contains two references to it, mirroring what serialized.</p>
|
||||
<p>The first Person in the list is serizlied with the addition of an object Id. The
|
||||
second Person in JSON is now only a reference to the first.</p>
|
||||
<p>With PreserveReferencesHandling on now only one Person object is created on
|
||||
deserialization and the list contains two references to it, mirroring what we
|
||||
started with.</p>
|
||||
|
||||
<h3>IsReference on JsonObjectAttribute, JsonArrayAttribute and JsonPropertyAttribute</h3>
|
||||
|
||||
|
||||
<p>The PreserveReferencesHandling setting on the JsonSerializer will change
|
||||
how all objects are serialized and deserialized. For fine grain control over which
|
||||
objects and members should be serialized there is the IsReference property on
|
||||
objects and members should be serialized as a reference there is the IsReference property on
|
||||
the JsonObjectAttribute, JsonArrayAttribute and JsonPropertyAttribute.</p>
|
||||
<p>Setting IsReference on JsonObjectAttribute or JsonArrayAttribute to true will
|
||||
mean the JsonSerializer will always serialize the type the attribute is against
|
||||
|
||||
@@ -0,0 +1,118 @@
|
||||
<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">Customizing JSON serialization with attributes</span></div>
|
||||
|
||||
<div id="content">
|
||||
<span style="color: DarkGray"> </span>
|
||||
|
||||
<p>Attributes can be used to control how Json.NET serializes and deserializes .NET objects.</p>
|
||||
<ul>
|
||||
<li><a href="./html/T_Newtonsoft_Json_JsonObjectAttribute.htm">JsonObjectAttribute</a> - Placed on classes to control how it should be serialized as a JSON object.</li>
|
||||
<li><a href="./html/T_Newtonsoft_Json_JsonArrayAttribute.htm">JsonArrayAttribute</a> - Placed on collections to control how it should be serialized as a JSON array.</li>
|
||||
<li><a href="./html/T_Newtonsoft_Json_JsonPropertyAttribute.htm">JsonPropertyAttribute</a> - Placed on fields and properties to control how it should be serialized as a property in a JSON object.</li>
|
||||
<li><a href="./html/T_Newtonsoft_Json_JsonConverterAttribute.htm">JsonConverterAttribute</a> - Placed on either classes or fields and properties to specify which JsonConverter should be used during serialization.</li>
|
||||
</ul>
|
||||
<p>As well as using the built-in Json.NET attributes, Json.NET also looks for the
|
||||
<a href="http://msdn.microsoft.com/en-us/library/system.runtime.serialization.datacontractattribute.aspx" target="_blank">DataContract</a> and
|
||||
<a href="http://msdn.microsoft.com/en-us/library/system.runtime.serialization.datacontractattribute.aspx" target="_blank">DataMember</a> attributes when determining how JSON is to be serialized and deserialized. If both are present the Json.NET serialization attributes take precedence.</p>
|
||||
|
||||
<div class="overflowpanel"> <div class="code">
|
||||
|
||||
<div style="font-family: Courier New; font-size: 10pt; color: black;">
|
||||
<pre style="margin: 0px;">[<span style="color: #2b91af;">JsonObject</span>(<span style="color: #2b91af;">MemberSerialization</span>.OptIn)]</pre>
|
||||
<pre style="margin: 0px;"><span style="color: blue;">public</span> <span style="color: blue;">class</span> <span style="color: #2b91af;">Person</span></pre>
|
||||
<pre style="margin: 0px;">{</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: green;">// "John Smith"</span></pre>
|
||||
<pre style="margin: 0px;"> [<span style="color: #2b91af;">JsonProperty</span>]</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">public</span> <span style="color: blue;">string</span> Name { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
<pre style="margin: 0px;"> <span style="color: green;">// "2000-12-15T22:11:03"</span></pre>
|
||||
<pre style="margin: 0px;"> [<span style="color: #2b91af;">JsonProperty</span>]</pre>
|
||||
<pre style="margin: 0px;"> [<span style="color: #2b91af;">JsonConverter</span>(<span style="color: blue;">typeof</span>(<span style="color: #2b91af;">IsoDateTimeConverter</span>))]</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">public</span> <span style="color: #2b91af;">DateTime</span> BirthDate { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
<pre style="margin: 0px;"> <span style="color: green;">// new Date(976918263055)</span></pre>
|
||||
<pre style="margin: 0px;"> [<span style="color: #2b91af;">JsonProperty</span>]</pre>
|
||||
<pre style="margin: 0px;"> [<span style="color: #2b91af;">JsonConverter</span>(<span style="color: blue;">typeof</span>(<span style="color: #2b91af;">JavaScriptDateTimeConverter</span>))]</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">public</span> <span style="color: #2b91af;">DateTime</span> LastModified { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
<pre style="margin: 0px;"> <span style="color: green;">// not serialized</span></pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">public</span> <span style="color: blue;">string</span> Department { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
|
||||
<pre style="margin: 0px;">}</pre>
|
||||
</div>
|
||||
|
||||
</div></div>
|
||||
|
||||
<h5>JsonObjectAttribute</h5>
|
||||
<p>The MemberSerialization flag on this attribute specifies whether member serialization is opt-in (a member must have the JsonProperty or DataMember attribute to be serialized) or opt-out (everything is serialized by default but can be ignored with the JsonIgnoreAttribute,
|
||||
Json.NET's default behavor).</p>
|
||||
<p>Json.NET serializes .NET classes that implement IEnumerable as an
|
||||
JSON array populated with the IEnumerable values. Placing the JsonPropertyAttribute overrides this
|
||||
behavor and forces the serializer to serialize the class's fields and properties.</p>
|
||||
<h5>JsonPropertyAttribute</h5>
|
||||
<p>Allows the name of the serialized member to be customized. The attribute also indicates that a member should be serialized when member serialization is set to opt-in.</p>
|
||||
<h5>JsonIgnoreAttribute</h5>
|
||||
<p>Excludes a field or property from serialization.</p>
|
||||
<h5>JsonConverterAttribute</h5>
|
||||
<p>The JsonConverterAttribute specifies which JsonSerializer is used to convert an object.</p>
|
||||
<p>The attribute can be placed on a class or a member. When placed on a class the JsonConverter
|
||||
specified by the attribute will be the default way of serializing that class. When the attribute is on a field
|
||||
or property then the specified JsonConverter will always be used to serialize that value.</p>
|
||||
<p>The priority of which JsonConverter is used is member attribute then class attribute and
|
||||
finally any converters passed to the JsonSerializer.</p>
|
||||
|
||||
<div class="overflowpanel"> <div class="code">
|
||||
<div style="font-family: Courier New; font-size: 10pt; color: black;">
|
||||
<pre style="margin: 0px;"><span style="color: blue;">public</span> <span style="color: blue;">class</span> <span style="color: #2b91af;">MemberConverterClass</span></pre>
|
||||
<pre style="margin: 0px;">{</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">public</span> <span style="color: #2b91af;">DateTime</span> DefaultConverter { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
|
||||
<pre style="margin: 0px;"> [<span style="color: #2b91af;">JsonConverter</span>(<span style="color: blue;">typeof</span>(<span style="color: #2b91af;">IsoDateTimeConverter</span>))]</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">public</span> <span style="color: #2b91af;">DateTime</span> MemberConverter { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
|
||||
<pre style="margin: 0px;">}</pre>
|
||||
</div>
|
||||
</div></div>
|
||||
<p>This example shows the JsonConverterAttribute being applied to a property.</p>
|
||||
|
||||
|
||||
<div class="overflowpanel"> <div class="code">
|
||||
<div style="font-family: Courier New; font-size: 10pt; color: black;">
|
||||
<pre style="margin: 0px;"><span style="color: #2b91af;">DateTime</span> date = <span style="color: #2b91af;">Convert</span>.ToDateTime(<span style="color: #a31515;">"1970-01-01T00:00:00Z"</span>).ToUniversalTime();</pre>
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
<pre style="margin: 0px;"><span style="color: #2b91af;">MemberConverterClass</span> c = <span style="color: blue;">new</span> <span style="color: #2b91af;">MemberConverterClass</span></pre>
|
||||
<pre style="margin: 0px;"> {</pre>
|
||||
<pre style="margin: 0px;"> DefaultConverter = date,</pre>
|
||||
<pre style="margin: 0px;"> MemberConverter = date</pre>
|
||||
<pre style="margin: 0px;"> };</pre>
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
<pre style="margin: 0px;"><span style="color: blue;">string</span> json = <span style="color: #2b91af;">JsonConvert</span>.SerializeObject(c, <span style="color: #2b91af;">Formatting</span>.Indented);</pre>
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
<pre style="margin: 0px;"><span style="color: #2b91af;">Console</span>.WriteLine(json);</pre>
|
||||
<pre style="margin: 0px;"><span style="color: green;">//{</span></pre>
|
||||
<pre style="margin: 0px;"><span style="color: green;">// "DefaultConverter": "\/Date(0)\/",</span></pre>
|
||||
<pre style="margin: 0px;"><span style="color: green;">// "MemberConverter": "1970-01-01T00:00:00Z"</span></pre>
|
||||
<pre style="margin: 0px;"><span style="color: green;">//}</span></pre>
|
||||
</div>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div id="footer">
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@@ -98,87 +98,7 @@ the member's DefaultValueAttribute. Include or ignore.</p>
|
||||
<h5>TypeNameHandling</h5>
|
||||
<p>Controls how .NET type names are used when serializing and deserializing JSON. If
|
||||
type names are SDFSDFSDF</p>
|
||||
<h3>Serialization Attributes</h3>
|
||||
<p>There are a number of attributes that can be placed on a class to control how it is serialized.</p>
|
||||
<p>Note that as well as using the built-in Json.NET attributes, Json.NET also looks for the
|
||||
<a href="http://msdn.microsoft.com/en-us/library/system.runtime.serialization.datacontractattribute.aspx" target="_blank">DataContract</a> and
|
||||
<a href="http://msdn.microsoft.com/en-us/library/system.runtime.serialization.datacontractattribute.aspx" target="_blank">DataMember</a> attributes when determining how JSON is to be serialized and deserialized. If both are present the Json.NET serialization attributes take precedence.</p>
|
||||
|
||||
<div class="overflowpanel"> <div class="code">
|
||||
|
||||
<div style="font-family: Courier New; font-size: 10pt; color: black;">
|
||||
<pre style="margin: 0px;">[<span style="color: #2b91af;">JsonObject</span>(<span style="color: #2b91af;">MemberSerialization</span>.OptIn)]</pre>
|
||||
<pre style="margin: 0px;"><span style="color: blue;">public</span> <span style="color: blue;">class</span> <span style="color: #2b91af;">Person</span></pre>
|
||||
<pre style="margin: 0px;">{</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: green;">// "John Smith"</span></pre>
|
||||
<pre style="margin: 0px;"> [<span style="color: #2b91af;">JsonProperty</span>]</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">public</span> <span style="color: blue;">string</span> Name { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
<pre style="margin: 0px;"> <span style="color: green;">// "2000-12-15T22:11:03"</span></pre>
|
||||
<pre style="margin: 0px;"> [<span style="color: #2b91af;">JsonProperty</span>]</pre>
|
||||
<pre style="margin: 0px;"> [<span style="color: #2b91af;">JsonConverter</span>(<span style="color: blue;">typeof</span>(<span style="color: #2b91af;">IsoDateTimeConverter</span>))]</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">public</span> <span style="color: #2b91af;">DateTime</span> BirthDate { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
<pre style="margin: 0px;"> <span style="color: green;">// new Date(976918263055)</span></pre>
|
||||
<pre style="margin: 0px;"> [<span style="color: #2b91af;">JsonProperty</span>]</pre>
|
||||
<pre style="margin: 0px;"> [<span style="color: #2b91af;">JsonConverter</span>(<span style="color: blue;">typeof</span>(<span style="color: #2b91af;">JavaScriptDateTimeConverter</span>))]</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">public</span> <span style="color: #2b91af;">DateTime</span> LastModified { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
<pre style="margin: 0px;"> <span style="color: green;">// not serialized</span></pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">public</span> <span style="color: blue;">string</span> Department { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
|
||||
<pre style="margin: 0px;">}</pre>
|
||||
</div>
|
||||
|
||||
</div></div>
|
||||
|
||||
<h5>JsonObjectAttribute</h5>
|
||||
<p>The MemberSerialization flag on this attribute specifies whether member serialization is opt-in (a member must have the JsonProperty or DataMember attribute to be serialized) or opt-out (everything is serialized by default but can be ignored with the JsonIgnoreAttribute).</p>
|
||||
<p>.NET classes that implement IEnumerable are automatically serialized as an array, populated with the IEnumerable values. Placing the JsonPropertyAttribute will override this and force the serializer to serialize the class's fields and properties.</p>
|
||||
<h5>JsonPropertyAttribute</h5>
|
||||
<p>Allows the name of the serialized member to be customized. The attribute also indicates that a member should be serialized when member serialization is set to opt-in.</p>
|
||||
<h5>JsonIgnoreAttribute</h5>
|
||||
<p>Excludes a field or property from serialization.</p>
|
||||
<h5>JsonConverterAttribute</h5>
|
||||
<p>The JsonConverterAttribute specifies which JsonSerializer is used to convert an object.</p>
|
||||
<p>The attribute can be placed on a class or a member. When placed on a class the JsonConverter
|
||||
specified by the attribute will be the default way of serializing that class. When the attribute is on a field
|
||||
or property then the specified JsonConverter will always be used to serialize that value.</p>
|
||||
<p>The priority of which JsonConverter is used is member attribute then class attribute and
|
||||
finally any converters passed to the JsonSerializer.</p>
|
||||
|
||||
<div class="overflowpanel"> <div class="code">
|
||||
<div style="font-family: Courier New; font-size: 10pt; color: black;">
|
||||
<pre style="margin: 0px;"><span style="color: blue;">public</span> <span style="color: blue;">class</span> <span style="color: #2b91af;">MemberConverterClass</span></pre>
|
||||
<pre style="margin: 0px;">{</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">public</span> <span style="color: #2b91af;">DateTime</span> DefaultConverter { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
|
||||
<pre style="margin: 0px;"> [<span style="color: #2b91af;">JsonConverter</span>(<span style="color: blue;">typeof</span>(<span style="color: #2b91af;">IsoDateTimeConverter</span>))]</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">public</span> <span style="color: #2b91af;">DateTime</span> MemberConverter { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
|
||||
<pre style="margin: 0px;">}</pre>
|
||||
</div>
|
||||
</div></div>
|
||||
<p>This example shows the JsonConverterAttribute being applied to a property.</p>
|
||||
|
||||
|
||||
<div class="overflowpanel"> <div class="code">
|
||||
<div style="font-family: Courier New; font-size: 10pt; color: black;">
|
||||
<pre style="margin: 0px;"><span style="color: #2b91af;">DateTime</span> date = <span style="color: #2b91af;">Convert</span>.ToDateTime(<span style="color: #a31515;">"1970-01-01T00:00:00Z"</span>).ToUniversalTime();</pre>
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
<pre style="margin: 0px;"><span style="color: #2b91af;">MemberConverterClass</span> c = <span style="color: blue;">new</span> <span style="color: #2b91af;">MemberConverterClass</span></pre>
|
||||
<pre style="margin: 0px;"> {</pre>
|
||||
<pre style="margin: 0px;"> DefaultConverter = date,</pre>
|
||||
<pre style="margin: 0px;"> MemberConverter = date</pre>
|
||||
<pre style="margin: 0px;"> };</pre>
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
<pre style="margin: 0px;"><span style="color: blue;">string</span> json = <span style="color: #2b91af;">JsonConvert</span>.SerializeObject(c, <span style="color: #2b91af;">Formatting</span>.Indented);</pre>
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
<pre style="margin: 0px;"><span style="color: #2b91af;">Console</span>.WriteLine(json);</pre>
|
||||
<pre style="margin: 0px;"><span style="color: green;">//{</span></pre>
|
||||
<pre style="margin: 0px;"><span style="color: green;">// "DefaultConverter": "\/Date(0)\/",</span></pre>
|
||||
<pre style="margin: 0px;"><span style="color: green;">// "MemberConverter": "1970-01-01T00:00:00Z"</span></pre>
|
||||
<pre style="margin: 0px;"><span style="color: green;">//}</span></pre>
|
||||
</div>
|
||||
|
||||
</div></div>
|
||||
|
||||
<h3>JsonConverters</h3>
|
||||
<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>
|
||||
|
||||
@@ -23,6 +23,7 @@
|
||||
<contentItem sourcePath=".\PreserveObjectReferences.html" destPath="" excludeItems="False" />
|
||||
<contentItem sourcePath=".\ContractResolver.html" destPath="" excludeItems="False" />
|
||||
<contentItem sourcePath=".\SerializationCallbacks.html" destPath="" excludeItems="False" />
|
||||
<contentItem sourcePath=".\SerializationAttributes.html" destPath="" excludeItems="False" />
|
||||
</additionalContent>
|
||||
<ProjectSummary />
|
||||
<MissingTags>Summary, Parameter, Returns, AutoDocumentCtors, Namespace, TypeParameter</MissingTags>
|
||||
|
||||
+2
-1
@@ -2,9 +2,10 @@
|
||||
<siteMap xmlns="http://schemas.microsoft.com/AspNet/SiteMap-File-1.0">
|
||||
<siteMapNode title="Introduction" url=".\Introduction.html" isDefault="true" />
|
||||
<siteMapNode title="Serializing and deserializing JSON" url=".\SerializingJSON.html">
|
||||
<siteMapNode title="Customizing JSON serialization with attributes" url=".\SerializationAttributes.html" />
|
||||
<siteMapNode title="Serializing dates in JSON" url=".\DatesInJSON.html" />
|
||||
<siteMapNode title="Serialization Callbacks" url=".\SerializationCallbacks.html" />
|
||||
<siteMapNode title="Preserve Object References" url=".\PreserveObjectReferences.html" />
|
||||
<siteMapNode title="Serialization and Preserving Object References" url=".\PreserveObjectReferences.html" />
|
||||
<siteMapNode title="CustomCreationConverter" url=".\CustomCreationConverter.html" />
|
||||
<siteMapNode title="Contract Resolvers" url=".\ContractResolver.html" />
|
||||
</siteMapNode>
|
||||
|
||||
Reference in New Issue
Block a user