Permalink
Browse files

-Documentation

  • Loading branch information...
1 parent 6365a9f commit d92b8ceeb56d938887e1a12b03f8b393b32ecbc8 @JamesNK committed Oct 31, 2012
View
@@ -4,4 +4,7 @@
TestResults/
AppPackages/
*.suo
-*.user
+*.user
+_ReSharper.*
+*.ReSharper.user
+*.resharper.user
@@ -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>
View
@@ -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>
View
@@ -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>
Oops, something went wrong.

0 comments on commit d92b8ce

Please sign in to comment.