-Documentation
-Added Path to JsonWriterException
This commit is contained in:
James Newton-King
+10
-9
@@ -16,13 +16,16 @@
|
||||
<span style="color: DarkGray"> </span>
|
||||
<p>DateTimes in JSON are hard.</p>
|
||||
<p>
|
||||
The problem comes from the <a href="http://www.ietf.org/rfc/rfc4627.txt" target="_blank">JSON spec</a> itself, there is no literal syntax for dates in JSON. The spec has objects, arrays, strings, integers and floats, but it defines no standard for what a date looks like.</p>
|
||||
The problem comes from the <a href="http://www.ietf.org/rfc/rfc4627.txt" target="_blank">JSON spec</a> itself: there is no literal syntax for dates in JSON. The spec has objects, arrays, strings, integers and floats, but it defines no standard for what a date looks like.</p>
|
||||
<p>The default format used by <a href="http://james.newtonking.com/projects/json-net.aspx" target="_blank">Json.NET</a>
|
||||
is the ISO 8601 standard: 2012-03-19T07:22Z. You can read more about it <a href="http://en.wikipedia.org/wiki/ISO_8601" target="_blank">here</a>.</p>
|
||||
<p>Prior to Json.NET 4.5 dates were written using the Microsoft format:
|
||||
"\/Date(1198908717056)\/". If you want to use this format, or you want to
|
||||
maintain compatibility with Microsoft JSON serializers or older versions of
|
||||
Json.NET then change the DateFormatHandling setting to MicrosoftDateFormat.</p>
|
||||
Json.NET then change the <a href="html/T_Newtonsoft_Json_DateFormatHandling.htm">DateFormatHandling</a> setting to MicrosoftDateFormat.</p>
|
||||
<p>Json.NET also has the <a href="html/T_Newtonsoft_Json_DateTimeZoneHandling.htm">DateTimeZoneHandling</a> setting. This can be used to convert
|
||||
DateTime's kind when serializing, e.g. set DateTimeZoneHandling to Utc to
|
||||
serialize all DateTimes as UTC dates.</p>
|
||||
|
||||
<h3>DateTime JsonConverters</h3>
|
||||
<p>With no standard for dates in JSON, the number of possible different formats when interoping with other systems is endless. Fortunately Json.NET has a solution to deal with reading and writing custom dates: JsonConverters. A JsonConverter is used to override how a type is serialized.</p>
|
||||
@@ -49,16 +52,16 @@
|
||||
<pre style="margin: 0px;"> };</pre>
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
|
||||
<pre style="margin: 0px;"> <span style="color: green;">// Default as of Json.NET 4.5</span></pre>
|
||||
<pre style="margin: 0px;"> <span style="color: green;">// default as of Json.NET 4.5</span></pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">string</span> isoJson = <span style="color: rgb(43, 145, 175);">JsonConvert</span>.SerializeObject(entry);</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: green;">// {"Details":"Application started.","LogDate":"2009-02-15T00:00:00Z"}</span></pre>
|
||||
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
<pre style="margin: 0px;"> <span style="color: rgb(43, 145, 175);">JsonSerializerSettings</span> settingsWithMicrosoftDateFormat = <span style="color: blue;">new</span> <span style="color: rgb(43, 145, 175);">JsonSerializerSettings</span></pre>
|
||||
<pre style="margin: 0px;"> <span style="color: rgb(43, 145, 175);">JsonSerializerSettings</span> microsoftDateFormatSettings = <span style="color: blue;">new</span> <span style="color: rgb(43, 145, 175);">JsonSerializerSettings</span></pre>
|
||||
<pre style="margin: 0px;"> {</pre>
|
||||
<pre style="margin: 0px;"> DateFormatHandling = <span style="color: rgb(43, 145, 175);">DateFormatHandling</span>.MicrosoftDateFormat</pre>
|
||||
<pre style="margin: 0px;"> };</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">string</span> microsoftJson = <span style="color: rgb(43, 145, 175);">JsonConvert</span>.SerializeObject(entry, settingsWithMicrosoftDateFormat);</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: blue;">string</span> microsoftJson = <span style="color: rgb(43, 145, 175);">JsonConvert</span>.SerializeObject(entry, microsoftDateFormatSettings);</pre>
|
||||
<pre style="margin: 0px;"> <span style="color: green;">// {"Details":"Application started.","LogDate":"\/Date(1234656000000)\/"}</span></pre>
|
||||
|
||||
<pre style="margin: 0px;"> </pre>
|
||||
@@ -71,7 +74,7 @@
|
||||
</div>
|
||||
<p>Simply pass the JsonConverter you wish to use to the Json.NET serializer.</p>
|
||||
<h4>JavaScriptDateTimeConverter</h4>
|
||||
<p>The JavaScriptDateTimeConverter class is one of the two DateTime JsonConverters that come with Json.NET. This converter serializes a DateTime as a <a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Date" target="_blank">JavaScript Date object</a>.</p>
|
||||
<p>The JavaScriptDateTimeConverter class is one of the two DateTime JsonConverters that come with Json.NET. This converter serializes a DateTime as a <a href="http://msdn.microsoft.com/en-us/library/cd9w2te4.aspx" target="_blank">JavaScript Date object</a>.</p>
|
||||
<div class="overflowpanel">
|
||||
<div class="code">
|
||||
<div style="font-size: 10pt; color: black; font-family: courier new;">
|
||||
@@ -80,7 +83,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<p>Technically this is invalid JSON according to the spec but all browsers, and some JSON frameworks including Json.NET, support it. </p>
|
||||
<p>Technically this is invalid JSON according to the spec but all browsers, and some JSON frameworks, including Json.NET, support it. </p>
|
||||
<h4>IsoDateTimeConverter</h4>
|
||||
<p>IsoDateTimeConverter seralizes a DateTime to an <a href="http://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601</a> formatted string.
|
||||
Note that since Json.NET 4.5 dates are written using the ISO 8601 format by
|
||||
@@ -94,8 +97,6 @@
|
||||
</div>
|
||||
</div>
|
||||
<p>The IsoDateTimeConverter class has a property, DateTimeFormat, to further customize the formatted string.</p>
|
||||
<p> </p>
|
||||
<p>One final thing to note is all date values returned by Json.NET are in <a href="http://en.wikipedia.org/wiki/Utc" target="_blank">UTC time</a>.</p>
|
||||
|
||||
|
||||
<div id="footer"></div>
|
||||
|
||||
@@ -25,8 +25,15 @@
|
||||
<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>
|
||||
<a href="http://msdn.microsoft.com/en-us/library/system.serializableattribute.aspx" target="_blank">
|
||||
Serializable</a> (if IgnoreSerializableAttribute on DefaultContractResolver is
|
||||
set to false)
|
||||
<a href="http://msdn.microsoft.com/en-us/library/system.runtime.serialization.datacontractattribute.aspx" target="_blank">DataContract</a>,
|
||||
<a href="http://msdn.microsoft.com/en-us/library/system.runtime.serialization.datacontractattribute.aspx" target="_blank">DataMember</a>
|
||||
and
|
||||
<a href="http://msdn.microsoft.com/en-us/library/system.nonserializedattribute.aspx" target="_blank">
|
||||
NotSerialized</a> and
|
||||
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">
|
||||
|
||||
@@ -40,7 +47,6 @@
|
||||
<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>
|
||||
@@ -48,7 +54,7 @@
|
||||
<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: green;">// not serialized because mode is opt-in</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>
|
||||
@@ -56,11 +62,14 @@
|
||||
</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>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), opt-out (everything is serialized by default but can be ignored with the JsonIgnoreAttribute,
|
||||
Json.NET's default behavor) or fields (all public and private fields are
|
||||
serialized, properties are ignored).</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>
|
||||
<p>The DataContractAttribute can be used as substitute for JsonObjectAttribute.
|
||||
The DataContractAttribute will default member serialization to opt-in.</p>
|
||||
|
||||
<h5>JsonArrayAttribute/JsonDictionaryAttribute</h5>
|
||||
<p>The JsonArrayAttribute and JsonDictionaryAttributes are used to specified
|
||||
@@ -75,9 +84,14 @@
|
||||
<li>Includes non-public properties in serialization and deserialization.</li>
|
||||
<li>Customize type name, reference, null and default value handling for the
|
||||
property value.</li>
|
||||
<li>Customize the property's collection items JsonConverter, type name handing and
|
||||
reference handling.</li>
|
||||
</ul>
|
||||
<p>
|
||||
The DataMemberAttribute can be used as substitute for JsonPropertyAttribute.</p>
|
||||
<h5>JsonIgnoreAttribute</h5>
|
||||
<p>Excludes a field or property from serialization.</p>
|
||||
<p>The NotSerializedAttribute can be used as substitute for JsonIgnoreAttribute.</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
|
||||
@@ -120,6 +134,12 @@ finally any converters passed to the JsonSerializer.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
<p>To apply a JsonConverter to the items in a collection use either
|
||||
<a href="html/T_Newtonsoft_Json_JsonArrayAttribute.htm">JsonArrayAttribute</a>,
|
||||
<a href="html/T_Newtonsoft_Json_JsonDictionaryAttribute.htm">
|
||||
JsonDictionaryAttribute</a> or
|
||||
<a href="html/T_Newtonsoft_Json_JsonPropertyAttribute.htm">JsonPropertyAttribute</a> and set
|
||||
the ItemConverterType property to the converter type you want to use.</p>
|
||||
|
||||
<div id="footer">
|
||||
|
||||
|
||||
@@ -3,13 +3,7 @@
|
||||
<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>
|
||||
</head>
|
||||
<body>
|
||||
<div id="control">
|
||||
<span class="productTitle">Json.NET - Quick Starts & API Documentation</span><br />
|
||||
@@ -221,12 +215,20 @@
|
||||
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
|
||||
Types can also be serialized using opt-in mode. Only
|
||||
properties and 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>
|
||||
<p>
|
||||
Finally types can be serialized using a fields mode. All fields, both public and
|
||||
private, are serialized and properties are ignored. This can be specified by
|
||||
setting MemberSerialization.Fields on a type with the JsonObject attribute or by the .NET
|
||||
<a href="http://msdn.microsoft.com/en-us/library/system.serializableattribute.aspx" target="_blank">
|
||||
Serializable</a> attribute and setting IgnoreSerializableAttribute on
|
||||
DefaultContractResolver to false.</p>
|
||||
<h4>
|
||||
<strong>IEnumerable, Lists and Arrays</strong></h4>
|
||||
<strong>IEnumerable, Lists and Arrayss</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,
|
||||
|
||||
Reference in New Issue
Block a user