From 5edfc72d6712c9cdd27c6dd931f0c32575b6df72 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 2 Nov 2012 15:25:39 +1300 Subject: [PATCH] -Documentation --- Doc/ContractResolver.aml | 140 +++++++------- Doc/ConvertingJSONandXML.aml | 11 +- Doc/Performance.aml | 173 +++++++++--------- Doc/SerializationGuide.aml | 11 +- Doc/SerializationSettings.aml | 41 ++++- Doc/doc.content | 2 +- .../Newtonsoft.Json.Tests.csproj | 1 + Src/Newtonsoft.Json.Tests/PerformanceTests.cs | 4 +- .../Properties/AssemblyInfo.cs | 2 +- .../Properties/AssemblyInfo.cs | 2 +- 10 files changed, 212 insertions(+), 175 deletions(-) diff --git a/Doc/ContractResolver.aml b/Doc/ContractResolver.aml index 4589c6d5..6c628322 100644 --- a/Doc/ContractResolver.aml +++ b/Doc/ContractResolver.aml @@ -1,71 +1,71 @@ - - - - - - The T:Newtonsoft.Json.Serialization.IContractResolver - interface provides a way to customize how the - JsonSerializer serializes and deserializes .NET objects to JSON. - 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. - - -
- DefaultContractResolver - - - The T:Newtonsoft.Json.Serialization.DefaultContractResolver - is the default resolver used by the - serializer. It provides many avenues of extensibility in the form of - virtual methods that can be overriden. - -
-
- CamelCasePropertyNamesContractResolver - - - T:Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver - inherits from DefaultContractResolver and simply overrides the JSON - property name to be written in -camelcase -http://en.wikipedia.org/wiki/CamelCase -_blank -. - - - -
-
- Custom Examples - - Setting a T:Newtonsoft.Json.JsonConverter on a type - using an IContractResolver. - - - - - Conditionally serializing properties - ConditionalProperties.htm - _self - using an IContractResolver. - - - -
- - T:Newtonsoft.Json.Serialization.IContractResolver - T:Newtonsoft.Json.Serialization.DefaultContractResolver - T:Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver - - + + + + + + The T:Newtonsoft.Json.Serialization.IContractResolver + interface provides a way to customize how the + JsonSerializer serializes and deserializes .NET objects to JSON without placing attributes on your classes. + 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. + + +
+ DefaultContractResolver + + + The T:Newtonsoft.Json.Serialization.DefaultContractResolver + is the default resolver used by the + serializer. It provides many avenues of extensibility in the form of + virtual methods that can be overriden. + +
+
+ CamelCasePropertyNamesContractResolver + + + T:Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver + inherits from DefaultContractResolver and simply overrides the JSON + property name to be written in +camelcase +http://en.wikipedia.org/wiki/CamelCase +_blank +. + + + +
+
+ Custom Examples + + Setting a T:Newtonsoft.Json.JsonConverter on a type + using an IContractResolver. + + + + + Conditionally serializing properties + ConditionalProperties.htm + _self + using an IContractResolver. + + + +
+ + T:Newtonsoft.Json.Serialization.IContractResolver + T:Newtonsoft.Json.Serialization.DefaultContractResolver + T:Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver + + \ No newline at end of file diff --git a/Doc/ConvertingJSONandXML.aml b/Doc/ConvertingJSONandXML.aml index 7312b80a..83e06b2f 100644 --- a/Doc/ConvertingJSONandXML.aml +++ b/Doc/ConvertingJSONandXML.aml @@ -19,11 +19,20 @@ Single child text nodes are a value directly against an element, otherwise they are accessed via #text. The XML declaration and processing instructions are prefixed with ?. Charater data, comments, whitespace and significate whitespace nodes are accessed via - #cdata-section, #comment, #whitespace and #significate-whitespace respectively. + #cdata-section, #comment, #whitespace and #significate-whitespace respectively. Multiple nodes with the same name at the same level are grouped together into an array. Empty elements are null. +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 +here +QueryingLINQtoJSON.htm +_self +. + 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, diff --git a/Doc/Performance.aml b/Doc/Performance.aml index 0115f609..751daf65 100644 --- a/Doc/Performance.aml +++ b/Doc/Performance.aml @@ -1,84 +1,91 @@ - - - - - Out of the box Json.NET is faster than DataContractJsonSerializer and JavaScriptSerializer. - Here are some tips to make it go even faster. - -
- Optimize Memory Usage - - To keep an application consistantly fast it is important to minimize the - amount of time the .NET framework spends performing -garbage collection -http://msdn.microsoft.com/en-us/library/ms973837.aspx -_blank -. - Allocating too many objects, or allocating very large objects can slow down or even - halt an application while garbage collection is in progress. - - 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 -large object heap -http://msdn.microsoft.com/en-us/magazine/cc534993.aspx -_blank -. - - - - - -
-
- JsonConverters - - Passing a T:Newtonsoft.Json.JsonConverter 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. - There are a couple of ways to continue to use JsonConverters without any overhead. The simplest way - is to specify the JsonConverter using the T:Newtonsoft.Json.JsonConverterAttribute. This attribute tells the serializer - to always use that converter when serializing and deserializing the type, without the check. - - - - 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 T:Newtonsoft.Json.Serialization.IContractResolver. - - - - The IContractResolver in the example above will set all DateTimes to use the JavaScriptDateConverter. - -
-
- Manually Serialize - - 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. - - - - If performance is important and you don't mind more code to get it then this is your best choice. - -
-
- Benchmarks - - - - - Json.NET Performance - - - -
- - T:Newtonsoft.Json.JsonSerializer - T:Newtonsoft.Json.JsonConverter - T:Newtonsoft.Json.JsonConverterAttribute - T:Newtonsoft.Json.JsonTextWriter - T:Newtonsoft.Json.JsonTextReader - - + + + + + Out of the box Json.NET is faster than DataContractJsonSerializer and JavaScriptSerializer. + Here are some tips to make it go even faster. + +
+ Optimize Memory Usage + + To keep an application consistantly fast it is important to minimize the + amount of time the .NET framework spends performing +garbage collection +http://msdn.microsoft.com/en-us/library/ms973837.aspx +_blank +. + Allocating too many objects, or allocating very large objects can slow down or even + halt an application while garbage collection is in progress. + + 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 +large object heap +http://msdn.microsoft.com/en-us/magazine/cc534993.aspx +_blank +. + + + + + +
+
+ JsonConverters + + Passing a T:Newtonsoft.Json.JsonConverter 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. + There are a couple of ways to continue to use JsonConverters without any overhead. The simplest way + is to specify the JsonConverter using the T:Newtonsoft.Json.JsonConverterAttribute. This attribute tells the serializer + to always use that converter when serializing and deserializing the type, without the check. + + + + 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 T:Newtonsoft.Json.Serialization.IContractResolver. + + + + The IContractResolver in the example above will set all DateTimes to use the JavaScriptDateConverter. + +
+
+ Manually Serialize + + 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. + + + + 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: + + Basic Reading and Writing JSON + ReadingWritingJSON.aml + _self + + + + +
+
+ Benchmarks + + + + + Json.NET Performance + + + +
+ + T:Newtonsoft.Json.JsonSerializer + T:Newtonsoft.Json.JsonConverter + T:Newtonsoft.Json.JsonConverterAttribute + T:Newtonsoft.Json.JsonTextWriter + T:Newtonsoft.Json.JsonTextReader + + \ No newline at end of file diff --git a/Doc/SerializationGuide.aml b/Doc/SerializationGuide.aml index ea29dc1b..4ee4a118 100644 --- a/Doc/SerializationGuide.aml +++ b/Doc/SerializationGuide.aml @@ -7,12 +7,7 @@ --> - - - 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. + 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.