-Documentation
This commit is contained in:
@@ -9,7 +9,7 @@
|
|||||||
<introduction>
|
<introduction>
|
||||||
<para>The <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>
|
<para>The <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>
|
||||||
interface provides a way to customize how the
|
interface provides a way to customize how the
|
||||||
JsonSerializer serializes and deserializes .NET objects to JSON.</para>
|
JsonSerializer serializes and deserializes .NET objects to JSON without placing attributes on your classes.</para>
|
||||||
<para>Implementing the IContractResolver interface and then assigning an
|
<para>Implementing the IContractResolver interface and then assigning an
|
||||||
instance to a JsonSerializer lets you control whether the object is
|
instance to a JsonSerializer lets you control whether the object is
|
||||||
serialized as a JSON object or JSON array, what object members should be
|
serialized as a JSON object or JSON array, what object members should be
|
||||||
|
|||||||
@@ -19,11 +19,20 @@
|
|||||||
<listItem><para>Single child text nodes are a value directly against an element, otherwise they are accessed via #text.</para></listItem>
|
<listItem><para>Single child text nodes are a value directly against an element, otherwise they are accessed via #text.</para></listItem>
|
||||||
<listItem><para>The XML declaration and processing instructions are prefixed with ?.</para></listItem>
|
<listItem><para>The XML declaration and processing instructions are prefixed with ?.</para></listItem>
|
||||||
<listItem><para>Charater data, comments, whitespace and significate whitespace nodes are accessed via
|
<listItem><para>Charater data, comments, whitespace and significate whitespace nodes are accessed via
|
||||||
#cdata-section, #comment, #whitespace and #significate-whitespace respectively. </para></listItem>
|
#cdata-section, #comment, #whitespace and #significate-whitespace respectively.</para></listItem>
|
||||||
<listItem><para>Multiple nodes with the same name at the same level are grouped together into an array.</para></listItem>
|
<listItem><para>Multiple nodes with the same name at the same level are grouped together into an array.</para></listItem>
|
||||||
<listItem><para>Empty elements are null.</para></listItem>
|
<listItem><para>Empty elements are null.</para></listItem>
|
||||||
</list>
|
</list>
|
||||||
|
|
||||||
|
<para>If the XML created from JSON doesn't match what you want then you will need to convert it manually.
|
||||||
|
The best approach to do this is to load your JSON into a LINQ to JSON object like JObject or JArray and then use LINQ to create
|
||||||
|
an XDocument. The opposite process, using LINQ with an XDocument to create a JObject or JArray, also works.
|
||||||
|
Find out more about using LINQ to JSON with LINQ <externalLink>
|
||||||
|
<linkText>here</linkText>
|
||||||
|
<linkUri>QueryingLINQtoJSON.htm</linkUri>
|
||||||
|
<linkTarget>_self</linkTarget>
|
||||||
|
</externalLink>.</para>
|
||||||
|
|
||||||
<alert class="note">
|
<alert class="note">
|
||||||
<para>The version of Json.NET being used in your application will change what XML conversion methods are available.
|
<para>The version of Json.NET being used in your application will change what XML conversion methods are available.
|
||||||
SerializeXmlNode/DeserializeXmlNode are available when the framework supports XmlDocument,
|
SerializeXmlNode/DeserializeXmlNode are available when the framework supports XmlDocument,
|
||||||
|
|||||||
+8
-1
@@ -59,7 +59,14 @@
|
|||||||
|
|
||||||
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="ReaderWriter" title="Manually serialize using JsonTextWriter" />
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="ReaderWriter" title="Manually serialize using JsonTextWriter" />
|
||||||
|
|
||||||
<para>If performance is important and you don't mind more code to get it then this is your best choice.</para>
|
<para>If performance is important and you don't mind more code to get it then this is your best choice. Read more about using JsonReader/JsonWriter here:
|
||||||
|
<externalLink>
|
||||||
|
<linkText>Basic Reading and Writing JSON</linkText>
|
||||||
|
<linkUri>ReadingWritingJSON.aml</linkUri>
|
||||||
|
<linkTarget>_self</linkTarget>
|
||||||
|
</externalLink>
|
||||||
|
|
||||||
|
</para>
|
||||||
</content>
|
</content>
|
||||||
</section>
|
</section>
|
||||||
<section>
|
<section>
|
||||||
|
|||||||
@@ -7,12 +7,7 @@
|
|||||||
</summary>
|
</summary>
|
||||||
-->
|
-->
|
||||||
<introduction>
|
<introduction>
|
||||||
<!-- Uncomment this to generate an outline of the section and sub-section
|
<para>The Json.NET serializer can serialize a wide variety of .NET objects. This guide looks at how it works, first at a high level and then in more detail.</para>
|
||||||
titles. Specify a numeric value as the inner text to limit it to
|
|
||||||
a specific number of sub-topics when creating the outline. Specify
|
|
||||||
zero (0) to limit it to top-level sections only. -->
|
|
||||||
<!-- <autoOutline /> -->
|
|
||||||
<para> The Json.NET serializer can serialize a wide variety of .NET objects. This guide looks at how it works, first at a high level and then in more detail.</para>
|
|
||||||
</introduction>
|
</introduction>
|
||||||
<!-- Add one or more top-level section elements. These are collapsible.
|
<!-- Add one or more top-level section elements. These are collapsible.
|
||||||
If using <autoOutline />, add an address attribute to identify it
|
If using <autoOutline />, add an address attribute to identify it
|
||||||
@@ -41,11 +36,11 @@
|
|||||||
</tableHeader>
|
</tableHeader>
|
||||||
<row>
|
<row>
|
||||||
<entry><para><legacyBold>IList, IEnumerable, IList<T>, Array</legacyBold></para></entry>
|
<entry><para><legacyBold>IList, IEnumerable, IList<T>, Array</legacyBold></para></entry>
|
||||||
<entry><para>Array</para></entry>
|
<entry><para>Array (properties on the collection will not be serialized)</para></entry>
|
||||||
</row>
|
</row>
|
||||||
<row>
|
<row>
|
||||||
<entry><para><legacyBold>IDictionary, IDictionary<TKey, TValue></legacyBold></para></entry>
|
<entry><para><legacyBold>IDictionary, IDictionary<TKey, TValue></legacyBold></para></entry>
|
||||||
<entry><para>Object</para></entry>
|
<entry><para>Object (dictionary name/values only, properties on the dictionary will not be serialized)</para></entry>
|
||||||
</row>
|
</row>
|
||||||
<row>
|
<row>
|
||||||
<entry><para><legacyBold>Object (more detail below)</legacyBold></para></entry>
|
<entry><para><legacyBold>Object (more detail below)</legacyBold></para></entry>
|
||||||
|
|||||||
@@ -61,8 +61,12 @@
|
|||||||
|
|
||||||
<section>
|
<section>
|
||||||
<title>ReferenceLoopHandling</title>
|
<title>ReferenceLoopHandling</title>
|
||||||
<content><para><codeEntityReference>T:Newtonsoft.Json.ReferenceLoopHandling</codeEntityReference> controls how circular referencing objects, e.g. a Person object referencing itself via a Manager property, are serialized.</para>
|
<content>
|
||||||
|
<para><codeEntityReference>T:Newtonsoft.Json.ReferenceLoopHandling</codeEntityReference> controls how circular referencing objects,
|
||||||
|
e.g. a Person object referencing itself via a Manager property, are serialized.</para>
|
||||||
|
<para>The <codeEntityReference>M:System.Object.Equals(System.Object)</codeEntityReference> method is used to test whether an object is in a circular reference.
|
||||||
|
By default <codeInline>Object.Equals(Object)</codeInline> will test whether the references are equal for reference types and private and public values
|
||||||
|
are equal for value types. Classes and structs can override this method.</para>
|
||||||
<table>
|
<table>
|
||||||
<tableHeader>
|
<tableHeader>
|
||||||
<row>
|
<row>
|
||||||
@@ -83,7 +87,11 @@
|
|||||||
<entry><para>This option forces Json.NET to serialize objects in reference loops. This is useful if objects are nested but not indefinitely.</para></entry>
|
<entry><para>This option forces Json.NET to serialize objects in reference loops. This is useful if objects are nested but not indefinitely.</para></entry>
|
||||||
</row>
|
</row>
|
||||||
</table>
|
</table>
|
||||||
<para>ReferenceLoopHandling can also be customized on individual properties with JsonPropertyAttribute.</para>
|
<para>ReferenceLoopHandling can be used as an argument when calling the serializer, it can be set on an object's properties or
|
||||||
|
a collection's items using <codeEntityReference>P:Newtonsoft.Json.JsonContainerAttribute.ItemReferenceLoopHandling</codeEntityReference>,
|
||||||
|
customized on a property with <codeEntityReference>P:Newtonsoft.Json.JsonPropertyAttribute.ReferenceLoopHandling</codeEntityReference>
|
||||||
|
or a property's object properties or collection items using
|
||||||
|
<codeEntityReference>P:Newtonsoft.Json.JsonPropertyAttribute.ItemReferenceLoopHandling</codeEntityReference>.</para>
|
||||||
</content>
|
</content>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
@@ -171,7 +179,16 @@
|
|||||||
|
|
||||||
<section>
|
<section>
|
||||||
<title>TypeNameHandling</title>
|
<title>TypeNameHandling</title>
|
||||||
<content><para><codeEntityReference>T:Newtonsoft.Json.TypeNameHandling</codeEntityReference> 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.</para>
|
<content>
|
||||||
|
<para>
|
||||||
|
<codeEntityReference>T:Newtonsoft.Json.TypeNameHandling</codeEntityReference> 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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The value of the $type property can be customized by creating your own
|
||||||
|
<codeEntityReference>T:System.Runtime.Serialization.SerializationBinder</codeEntityReference>.
|
||||||
|
</para>
|
||||||
|
|
||||||
<table>
|
<table>
|
||||||
<tableHeader>
|
<tableHeader>
|
||||||
@@ -201,8 +218,11 @@
|
|||||||
<entry><para>Json.NET will write and use type names for objects and collections.</para></entry>
|
<entry><para>Json.NET will write and use type names for objects and collections.</para></entry>
|
||||||
</row>
|
</row>
|
||||||
</table>
|
</table>
|
||||||
<para>TypeNameHandling can also be customized on individual properties with JsonPropertyAttribute.</para>
|
<para>TypeNameHandling can be used as an argument when calling the serializer, it can be set on an object's properties or
|
||||||
|
a collection's items using <codeEntityReference>P:Newtonsoft.Json.JsonContainerAttribute.ItemTypeNameHandling</codeEntityReference>,
|
||||||
|
customized on a property with <codeEntityReference>P:Newtonsoft.Json.JsonPropertyAttribute.TypeNameHandling</codeEntityReference>
|
||||||
|
or a property's object properties or collection items using
|
||||||
|
<codeEntityReference>P:Newtonsoft.Json.JsonPropertyAttribute.ItemTypeNameHandling</codeEntityReference>.</para>
|
||||||
</content>
|
</content>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
@@ -274,9 +294,14 @@
|
|||||||
using its CanConvert to see if it should be used. If CanConvert returns true then the JsonConverter will be used to read or write
|
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
|
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.</para>
|
features are no longer available like type name and reference handling.</para>
|
||||||
|
|
||||||
|
<para>JsonConverters can be used as an argument when calling the serializer, it can be set on an object or property
|
||||||
|
using <codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference>, it be set on an object's properties or
|
||||||
|
a collection's items using <codeEntityReference>P:Newtonsoft.Json.JsonContainerAttribute.ItemConverterType</codeEntityReference>,
|
||||||
|
or a property's object properties or collection items using
|
||||||
|
<codeEntityReference>P:Newtonsoft.Json.JsonPropertyAttribute.ItemConverterType</codeEntityReference>.</para>
|
||||||
|
|
||||||
<para>To create your own custom converter inherit from the JsonConverter class. Read more about the built-in JsonConverters below:</para>
|
<para>To create your own custom converter inherit from the JsonConverter class. Read more about the built-in JsonConverters below:</para>
|
||||||
|
|
||||||
|
|
||||||
<list class="bullet">
|
<list class="bullet">
|
||||||
<listItem><para><externalLink>
|
<listItem><para><externalLink>
|
||||||
<linkText>Serializing Dates in JSON</linkText>
|
<linkText>Serializing Dates in JSON</linkText>
|
||||||
|
|||||||
+1
-1
@@ -26,6 +26,6 @@
|
|||||||
<Topic id="JsonSchema" visible="True" title="Validating JSON" />
|
<Topic id="JsonSchema" visible="True" title="Validating JSON" />
|
||||||
<Topic id="ReadingWritingJSON" visible="True" title="Basic Reading and Writing JSON" />
|
<Topic id="ReadingWritingJSON" visible="True" title="Basic Reading and Writing JSON" />
|
||||||
<Topic id="ConvertingJSONandXML" visible="True" title="Converting between JSON and XML" />
|
<Topic id="ConvertingJSONandXML" visible="True" title="Converting between JSON and XML" />
|
||||||
<Topic id="JsonNetVsWindowsDataJson" visible="True" title="Json.NET vs Windows.Data.Json" />
|
|
||||||
<Topic id="JsonNetVsDotNetSerializers" visible="True" isSelected="true" title="Json.NET vs .NET Serializers" />
|
<Topic id="JsonNetVsDotNetSerializers" visible="True" isSelected="true" title="Json.NET vs .NET Serializers" />
|
||||||
|
<Topic id="JsonNetVsWindowsDataJson" visible="True" title="Json.NET vs Windows.Data.Json" />
|
||||||
</Topics>
|
</Topics>
|
||||||
@@ -118,6 +118,7 @@
|
|||||||
<Compile Include="Converters\VersionConverterTests.cs" />
|
<Compile Include="Converters\VersionConverterTests.cs" />
|
||||||
<Compile Include="Documentation\ConvertingJsonAndXmlTests.cs" />
|
<Compile Include="Documentation\ConvertingJsonAndXmlTests.cs" />
|
||||||
<Compile Include="Documentation\ConditionalPropertiesTests.cs" />
|
<Compile Include="Documentation\ConditionalPropertiesTests.cs" />
|
||||||
|
<Compile Include="Documentation\JsonNetVsWindowsDataJsonTests.cs" />
|
||||||
<Compile Include="Documentation\PerformanceTests.cs" />
|
<Compile Include="Documentation\PerformanceTests.cs" />
|
||||||
<Compile Include="Documentation\JsonSchemaTests.cs" />
|
<Compile Include="Documentation\JsonSchemaTests.cs" />
|
||||||
<Compile Include="Documentation\ReadingAndWritingJsonTests.cs" />
|
<Compile Include="Documentation\ReadingAndWritingJsonTests.cs" />
|
||||||
|
|||||||
@@ -64,8 +64,8 @@ namespace Newtonsoft.Json.Tests
|
|||||||
[TestFixture]
|
[TestFixture]
|
||||||
public class PerformanceTests : TestFixtureBase
|
public class PerformanceTests : TestFixtureBase
|
||||||
{
|
{
|
||||||
//private const int Iterations = 100;
|
private const int Iterations = 100;
|
||||||
private const int Iterations = 5000;
|
//private const int Iterations = 5000;
|
||||||
|
|
||||||
#region Data
|
#region Data
|
||||||
|
|
||||||
|
|||||||
@@ -76,5 +76,5 @@ using System.Security;
|
|||||||
// by using the '*' as shown below:
|
// by using the '*' as shown below:
|
||||||
[assembly: AssemblyVersion("4.5.0.0")]
|
[assembly: AssemblyVersion("4.5.0.0")]
|
||||||
#if !PocketPC
|
#if !PocketPC
|
||||||
[assembly: AssemblyFileVersion("4.5.10.15501")]
|
[assembly: AssemblyFileVersion("4.5.10.15502")]
|
||||||
#endif
|
#endif
|
||||||
|
|||||||
@@ -90,7 +90,7 @@ using System.Security;
|
|||||||
// by using the '*' as shown below:
|
// by using the '*' as shown below:
|
||||||
[assembly: AssemblyVersion("4.5.0.0")]
|
[assembly: AssemblyVersion("4.5.0.0")]
|
||||||
#if !PocketPC
|
#if !PocketPC
|
||||||
[assembly: AssemblyFileVersion("4.5.10.15501")]
|
[assembly: AssemblyFileVersion("4.5.10.15502")]
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
[assembly: CLSCompliant(true)]
|
[assembly: CLSCompliant(true)]
|
||||||
|
|||||||
Reference in New Issue
Block a user