LiRuochen_WorkFlow/Newtonsoft.Json
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

-Documentation

Browse Source
This commit is contained in:
James Newton-King
2012-10-31 13:24:47 +13:00
parent 6365a9f555
commit d92b8ceeb5
11 changed files with 413 additions and 169 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Doc/ConditionalProperties.aml
+41
View File
@@ -0,0 +1,41 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="ConditionalProperties" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>Json.NET has the ability to conditionally serialize properties by placing a ShouldSerialize method on a class.
This funtionality is similar to the <externalLink>
<linkText>XmlSerializer ShouldSerialize feature</linkText>
<linkUri>http://msdn.microsoft.com/en-us/library/53b8022e.aspx</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink>.</para>
</introduction>
<section>
<title>ShouldSerialize</title>
<content>
<para>To conditionally serialize a property add a boolean method with the same name as the property and then prefixed the method name
with ShouldSerialize. The result of the method determines whether the property is serialized. If the method returns true then the
property will be serialized, if it returns false and the property will be skipped.</para>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ConditionalPropertiesTests.cs" region="EmployeeShouldSerializeExample" title="Employee class with a ShouldSerialize method" />
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ConditionalPropertiesTests.cs" region="ShouldSerializeClassTest" title="ShouldSerialize output" />
</content>
</section>
<section>
<title>IContractResolver</title>
<content>
<para>ShouldSerialize can also be set using an <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>.
Conditionally serializing a property using an IContractResolver is useful if you don't want to place a ShouldSerialize method on a class
or you didn't declare the class and are unable to.</para>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ConditionalPropertiesTests.cs" region="ShouldSerializeContractResolver" title="Conditional properties with IContractResolver" />
</content>
</section>
<relatedTopics>
<codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference>
<codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>
<codeEntityReference>M:Newtonsoft.Json.Serialization.JsonProperty.ShouldSerialize</codeEntityReference>
</relatedTopics>
</developerConceptualDocument>
</topic>
Doc/ContractResolver.aml
+70 -53
View File
@@ -1,54 +1,71 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="ContractResolver" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optional summary abstract</para>
</summary>
-->
<introduction>
<para>The <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>
interface provides a way to customize how the
JsonSerializer serializes and deserializes .NET objects to JSON.</para>
<para>Implementing the IContractResolver interface and then assigning an
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, how they are serialized and what they are called.</para>
</introduction>
<!-- Add one or more top-level section elements. These are collapsible.
If using <autoOutline />, add an address attribute to identify it
and specify a title so that it can be jumped to with a hyperlink. -->
<section>
<title>DefaultContractResolver</title>
<content>
<!-- Uncomment this to create a sub-section outline
<autoOutline /> -->
<para>The <codeEntityReference>T:Newtonsoft.Json.Serialization.DefaultContractResolver</codeEntityReference>
is the default resolver used by the
serializer. It provides many avenues of extensibility in the form of
virtual methods that can be overriden.</para>
</content>
</section>
<section>
<title>CamelCasePropertyNamesContractResolver</title>
<content>
<!-- Uncomment this to create a sub-section outline
<autoOutline /> -->
<para><codeEntityReference>T:Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver</codeEntityReference>
inherits from DefaultContractResolver and simply overrides the JSON
property name to be written in <externalLink>
<linkText>camelcase</linkText>
<linkUri>http://en.wikipedia.org/wiki/CamelCase</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink>.</para>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ContractResolver" title="ContractResolver" />
</content>
</section>
<relatedTopics>
<codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>
<codeEntityReference>T:Newtonsoft.Json.Serialization.DefaultContractResolver</codeEntityReference>
<codeEntityReference>T:Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver</codeEntityReference>
</relatedTopics>
</developerConceptualDocument>
<?xml version="1.0" encoding="utf-8"?>
<topic id="ContractResolver" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optional summary abstract</para>
</summary>
-->
<introduction>
<para>The <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>
interface provides a way to customize how the
JsonSerializer serializes and deserializes .NET objects to JSON.</para>
<para>Implementing the IContractResolver interface and then assigning an
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, how they are serialized and what they are called.</para>
</introduction>
<!-- Add one or more top-level section elements. These are collapsible.
If using <autoOutline />, add an address attribute to identify it
and specify a title so that it can be jumped to with a hyperlink. -->
<section>
<title>DefaultContractResolver</title>
<content>
<!-- Uncomment this to create a sub-section outline
<autoOutline /> -->
<para>The <codeEntityReference>T:Newtonsoft.Json.Serialization.DefaultContractResolver</codeEntityReference>
is the default resolver used by the
serializer. It provides many avenues of extensibility in the form of
virtual methods that can be overriden.</para>
</content>
</section>
<section>
<title>CamelCasePropertyNamesContractResolver</title>
<content>
<!-- Uncomment this to create a sub-section outline
<autoOutline /> -->
<para><codeEntityReference>T:Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver</codeEntityReference>
inherits from DefaultContractResolver and simply overrides the JSON
property name to be written in <externalLink>
<linkText>camelcase</linkText>
<linkUri>http://en.wikipedia.org/wiki/CamelCase</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink>.</para>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ContractResolver" title="ContractResolver" />
</content>
</section>
<section>
<title>Custom Examples</title>
<content>
<para>Setting a <codeEntityReference>T:Newtonsoft.Json.JsonConverter</codeEntityReference> on a type
using an IContractResolver.</para>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="JsonConverterContractResolver" title="Use JsonConverter with IContractResolver" />
<para><externalLink>
<linkText>Conditionally serializing properties</linkText>
<linkUri>ConditionalProperties.htm</linkUri>
<linkTarget>_self</linkTarget>
</externalLink> using an IContractResolver.</para>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ConditionalPropertiesTests.cs" region="ShouldSerializeContractResolver" title="Conditional properties with IContractResolver" />
</content>
</section>
<relatedTopics>
<codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>
<codeEntityReference>T:Newtonsoft.Json.Serialization.DefaultContractResolver</codeEntityReference>
<codeEntityReference>T:Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver</codeEntityReference>
</relatedTopics>
</developerConceptualDocument>
</topic>
Doc/Performance.aml
+83 -83
View File
@@ -1,84 +1,84 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="Performance" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>Out of the box Json.NET is faster than DataContractJsonSerializer and JavaScriptSerializer.
Here are some tips to make it go even faster.</para>
</introduction>
<section>
<title>Optimize Memory Usage</title>
<content>
<para>To keep an application consistantly fast it is important to minimize the
amount of time the .NET framework spends performing <externalLink>
<linkText>garbage collection</linkText>
<linkUri>http://msdn.microsoft.com/en-us/library/ms973837.aspx</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink>.
Allocating too many objects, or allocating very large objects can slow down or even
halt an application while garbage collection is in progress.
</para>
<para>To minimize memory usage and the number of objects allocated Json.NET supports
serializing and deserializing directly to a stream. Reading or writing JSON a piece at a time instead of having
the entire JSON string loaded into memory is especially important when working with JSON
documents greater than 85kb in size to avoid the JSON string ending up in the <externalLink>
<linkText>large object heap</linkText>
<linkUri>http://msdn.microsoft.com/en-us/magazine/cc534993.aspx</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink>.</para>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="DeserializeString" title="Deserialize String" />
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="DeserializeStream" title="Deserialize Stream" />
</content>
</section>
<section>
<title>JsonConverters</title>
<content>
<para>Passing a <codeEntityReference>T:Newtonsoft.Json.JsonConverter</codeEntityReference> to SerializeObject or DeserializeObject provides a simple way to completely
change how an object is serialized. There is however a small overhead; the CanConvert method is called for every
type to check whether serialization should be handled by that JsonConverter.</para>
<para>There are a couple of ways to continue to use JsonConverters without any overhead. The simplest way
is to specify the JsonConverter using the <codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference>. This attribute tells the serializer
to always use that converter when serializing and deserializing the type, without the check.</para>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="JsonConverterAttribute" title="Use JsonConverter with JsonConverterAttribute" />
<para>If the class you want to convert isn't your own and you're unable to use an attribute a JsonConverter can still be used by
creating your own <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>.</para>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="JsonConverterContractResolver" title="Use JsonConverter with IContractResolver" />
<para>The IContractResolver in the example above will set all DateTimes to use the JavaScriptDateConverter.</para>
</content>
</section>
<section>
<title>Manually Serialize</title>
<content>
<para>The absolute fastest way to read and write JSON is to use JsonTextReader and JsonTextWriter directly. Using a reader or writer
directly skips any of the overhead from a serializer such as reflection.</para>
<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>
</content>
</section>
<section>
<title>Benchmarks</title>
<content>
<mediaLink>
<image class="image" xlink:href="performance" mimeType="image/png" width="643" height="345" />
<summary>Json.NET Performance</summary>
</mediaLink>
</content>
</section>
<relatedTopics>
<codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference>
<codeEntityReference>T:Newtonsoft.Json.JsonConverter</codeEntityReference>
<codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference>
<codeEntityReference>T:Newtonsoft.Json.JsonTextWriter</codeEntityReference>
<codeEntityReference>T:Newtonsoft.Json.JsonTextReader</codeEntityReference>
</relatedTopics>
</developerConceptualDocument>
<?xml version="1.0" encoding="utf-8"?>
<topic id="Performance" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>Out of the box Json.NET is faster than DataContractJsonSerializer and JavaScriptSerializer.
Here are some tips to make it go even faster.</para>
</introduction>
<section>
<title>Optimize Memory Usage</title>
<content>
<para>To keep an application consistantly fast it is important to minimize the
amount of time the .NET framework spends performing <externalLink>
<linkText>garbage collection</linkText>
<linkUri>http://msdn.microsoft.com/en-us/library/ms973837.aspx</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink>.
Allocating too many objects, or allocating very large objects can slow down or even
halt an application while garbage collection is in progress.
</para>
<para>To minimize memory usage and the number of objects allocated Json.NET supports
serializing and deserializing directly to a stream. Reading or writing JSON a piece at a time instead of having
the entire JSON string loaded into memory is especially important when working with JSON
documents greater than 85kb in size to avoid the JSON string ending up in the <externalLink>
<linkText>large object heap</linkText>
<linkUri>http://msdn.microsoft.com/en-us/magazine/cc534993.aspx</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink>.</para>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="DeserializeString" title="Deserialize String" />
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="DeserializeStream" title="Deserialize Stream" />
</content>
</section>
<section>
<title>JsonConverters</title>
<content>
<para>Passing a <codeEntityReference>T:Newtonsoft.Json.JsonConverter</codeEntityReference> to SerializeObject or DeserializeObject provides a simple way to completely
change how an object is serialized. There is however a small overhead; the CanConvert method is called for every
value to check whether serialization should be handled by that JsonConverter.</para>
<para>There are a couple of ways to continue to use JsonConverters without any overhead. The simplest way
is to specify the JsonConverter using the <codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference>. This attribute tells the serializer
to always use that converter when serializing and deserializing the type, without the check.</para>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="JsonConverterAttribute" title="Use JsonConverter with JsonConverterAttribute" />
<para>If the class you want to convert isn't your own and you're unable to use an attribute a JsonConverter can still be used by
creating your own <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>.</para>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="JsonConverterContractResolver" title="Use JsonConverter with IContractResolver" />
<para>The IContractResolver in the example above will set all DateTimes to use the JavaScriptDateConverter.</para>
</content>
</section>
<section>
<title>Manually Serialize</title>
<content>
<para>The absolute fastest way to read and write JSON is to use JsonTextReader/JsonTextWriter directly to manually serialize types.
Using a reader or writer directly skips any of the overhead from a serializer such as reflection.</para>
<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>
</content>
</section>
<section>
<title>Benchmarks</title>
<content>
<mediaLink>
<image class="image" xlink:href="performance" mimeType="image/png" width="643" height="345" />
<summary>Json.NET Performance</summary>
</mediaLink>
</content>
</section>
<relatedTopics>
<codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference>
<codeEntityReference>T:Newtonsoft.Json.JsonConverter</codeEntityReference>
<codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference>
<codeEntityReference>T:Newtonsoft.Json.JsonTextWriter</codeEntityReference>
<codeEntityReference>T:Newtonsoft.Json.JsonTextReader</codeEntityReference>
</relatedTopics>
</developerConceptualDocument>
</topic>
Doc/doc.content
+28 -27
View File
@@ -1,28 +1,29 @@
<?xml version="1.0" encoding="utf-8"?>
<Topics>
<Topic id="Introduction" visible="True" isDefault="true" />
<Topic id="SerializingJSON" visible="True" title="Serializing and Deserializing JSON">
<Topic id="SerializationSettings" visible="True" title="Serialization Settings" />
<Topic id="SerializationGuide" visible="True" title="Serialization Guide" />
<Topic id="SerializationAttributes" visible="True" title="Serialization Attributes" />
<Topic id="SerializationCallbacks" visible="True" title="Serialization Callbacks" />
<Topic id="SerializationErrorHandling" visible="True" title="Serialization Error Handling" />
<Topic id="PreserveObjectReferences" visible="True" title="Preserving Object References" />
<Topic id="CustomCreationConverter" visible="True" />
<Topic id="ContractResolver" visible="True" />
<Topic id="SerializingCollections" visible="True" title="Serializing Collections" />
<Topic id="DatesInJSON" visible="True" title="Serializing Dates in JSON" />
<Topic id="ReducingSerializedJSONSize" visible="True" title="Reducing Serialized JSON Size" />
<Topic id="SerializingJSONFragments" visible="True" title="Serializing Partial JSON Fragments" />
</Topic>
<Topic id="LINQtoJSON" visible="True" title="LINQ to JSON">
<Topic id="ParsingLINQtoJSON" visible="True" title="Parsing JSON" />
<Topic id="CreatingLINQtoJSON" visible="True" title="Creating JSON" />
<Topic id="QueryingLINQtoJSON" visible="True" title="Querying JSON with LINQ" />
<Topic id="SelectToken" visible="True" title="Querying JSON with SelectToken" />
</Topic>
<Topic id="Performance" visible="True" isSelected="true" title="Performance" />
<Topic id="JsonSchema" visible="True" title="Validating JSON" />
<Topic id="ReadingWritingJSON" visible="True" title="Basic Reading and Writing JSON" />
<Topic id="ConvertingJSONandXML" visible="True" title="Converting between JSON and XML" />
<?xml version="1.0" encoding="utf-8"?>
<Topics>
<Topic id="Introduction" visible="True" isDefault="true" />
<Topic id="SerializingJSON" visible="True" isExpanded="true" title="Serializing and Deserializing JSON">
<Topic id="SerializationSettings" visible="True" title="Serialization Settings" />
<Topic id="SerializationGuide" visible="True" title="Serialization Guide" />
<Topic id="SerializationAttributes" visible="True" title="Serialization Attributes" />
<Topic id="SerializationCallbacks" visible="True" title="Serialization Callbacks" />
<Topic id="SerializationErrorHandling" visible="True" title="Serialization Error Handling" />
<Topic id="PreserveObjectReferences" visible="True" title="Preserving Object References" />
<Topic id="CustomCreationConverter" visible="True" />
<Topic id="SerializingCollections" visible="True" title="Serializing Collections" />
<Topic id="DatesInJSON" visible="True" title="Serializing Dates in JSON" />
<Topic id="ReducingSerializedJSONSize" visible="True" title="Reducing Serialized JSON Size" />
<Topic id="SerializingJSONFragments" visible="True" title="Serializing Partial JSON Fragments" />
<Topic id="ConditionalProperties" visible="True" title="Conditional Properties" />
<Topic id="ContractResolver" visible="True" isSelected="true" title="Serialization using ContractResolver" />
</Topic>
<Topic id="LINQtoJSON" visible="True" title="LINQ to JSON">
<Topic id="ParsingLINQtoJSON" visible="True" title="Parsing JSON" />
<Topic id="CreatingLINQtoJSON" visible="True" title="Creating JSON" />
<Topic id="QueryingLINQtoJSON" visible="True" title="Querying JSON with LINQ" />
<Topic id="SelectToken" visible="True" title="Querying JSON with SelectToken" />
</Topic>
<Topic id="Performance" visible="True" title="Performance" />
<Topic id="JsonSchema" visible="True" title="Validating JSON" />
<Topic id="ReadingWritingJSON" visible="True" title="Basic Reading and Writing JSON" />
<Topic id="ConvertingJSONandXML" visible="True" title="Converting between JSON and XML" />
</Topics>
Doc/doc.shfbproj
+3 -2
View File
@@ -8,7 +8,7 @@
<Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
<SchemaVersion>2.0</SchemaVersion>
<ProjectGuid>{fd19f68e-72c8-4576-9775-b4480b0db686}</ProjectGuid>
<SHFBSchemaVersion>1.9.3.0</SHFBSchemaVersion>
<SHFBSchemaVersion>1.9.5.0</SHFBSchemaVersion>
<!-- AssemblyName, Name, and RootNamespace are not used by SHFB but Visual
Studio adds them anyway -->
<AssemblyName>Documentation</AssemblyName>
@@ -32,7 +32,7 @@
<BuildLogFile>
</BuildLogFile>
<HelpFileFormat>Website</HelpFileFormat>
<FrameworkVersion>.NET 4.0.30319</FrameworkVersion>
<FrameworkVersion>.NET Framework 4.0</FrameworkVersion>
<HelpTitle>Json.NET - Documentation</HelpTitle>
<PresentationStyle>vs2005</PresentationStyle>
<NamingMethod>MemberName</NamingMethod>
@@ -137,6 +137,7 @@
<Content Include="donate.gif" />
</ItemGroup>
<ItemGroup>
<None Include="ConditionalProperties.aml" />
<None Include="CustomCreationConverter.aml" />
<None Include="ContractResolver.aml" />
<None Include="ConvertingJSONandXML.aml" />