-Documentation

This commit is contained in:
James Newton-King
2012-11-02 15:25:39 +13:00
parent 7191d9db10
commit 5edfc72d67
10 changed files with 212 additions and 175 deletions
+1 -1
View File
@@ -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
+10 -1
View File
@@ -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
View File
@@ -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>
+3 -8
View File
@@ -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&lt;T&gt;, Array</legacyBold></para></entry> <entry><para><legacyBold>IList, IEnumerable, IList&lt;T&gt;, 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&lt;TKey, TValue&gt;</legacyBold></para></entry> <entry><para><legacyBold>IDictionary, IDictionary&lt;TKey, TValue&gt;</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>
+33 -8
View File
@@ -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
View File
@@ -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)]