From 29f1ed9cd0e6be937c268a0bc8be529b5507f9c0 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 27 Jul 2012 22:57:08 +1200 Subject: [PATCH] -Improved documentation --- Doc/LINQtoJSON.aml | 28 +++++++----- Doc/ReadingWritingJSON.aml | 24 ++++++++++- Doc/SerializationGuide.aml | 5 +++ Doc/SerializationSettings.aml | 35 ++++++++------- Doc/SerializingCollections.aml | 5 +++ Doc/SerializingJSON.aml | 2 +- .../Documentation/LinqToJsonTests.cs | 17 +++++++- .../ReadingAndWritingJsonTests.cs | 43 ++++++++++++++++++- .../Documentation/SerializationTests.cs | 26 +++++------ .../Properties/AssemblyInfo.cs | 2 +- Src/Newtonsoft.Json/DefaultValueHandling.cs | 4 ++ Src/Newtonsoft.Json/JsonConvert.cs | 3 ++ Src/Newtonsoft.Json/Linq/JArray.cs | 6 +++ Src/Newtonsoft.Json/Linq/JObject.cs | 6 +++ Src/Newtonsoft.Json/NullValueHandling.cs | 4 ++ .../PreserveReferencesHandling.cs | 3 ++ .../Properties/AssemblyInfo.cs | 2 +- .../Serialization/IContractResolver.cs | 4 ++ 18 files changed, 173 insertions(+), 46 deletions(-) diff --git a/Doc/LINQtoJSON.aml b/Doc/LINQtoJSON.aml index decfa80c..8e5987f0 100644 --- a/Doc/LINQtoJSON.aml +++ b/Doc/LINQtoJSON.aml @@ -9,13 +9,26 @@ namespace. +
+ Reading JSON + + JSON values can be read from a string use the + M:Newtonsoft.Json.Linq.JToken.Parse(System.String) + method. + + + + +
Creating JSON There are a number of different options when it comes to creating - JSON using LINQ to JSON. The first to create objects imperatively. You + JSON using LINQ to JSON. + + The first to create objects imperatively. You have total control but it is more verbose than other options. @@ -24,17 +37,12 @@ - You can create a JSON object from a non-JSON type using the + Finally you can create a JSON object from a non-JSON type using the Overload:Newtonsoft.Json.Linq.JObject.FromObject - method. + method. The example below is creating a JSON object from an anonymous object but any + .NET type can be used with FromObject. - - - Finally JSON objects can be created from a string use the - M:Newtonsoft.Json.Linq.JToken.Parse(System.String) - method. - - +
diff --git a/Doc/ReadingWritingJSON.aml b/Doc/ReadingWritingJSON.aml index d92c0918..d9f0f9bf 100644 --- a/Doc/ReadingWritingJSON.aml +++ b/Doc/ReadingWritingJSON.aml @@ -5,11 +5,29 @@ To manually read and write JSON Json.NET provides the T:Newtonsoft.Json.JsonReader and - T:Newtonsoft.Json.JsonWriter classes. These are low level classes and used internally by Json.NET. + T:Newtonsoft.Json.JsonWriter classes. +
JsonTextReader and JsonTextWriter + + + JsonReader and JsonWriter are low level classes and used internally by Json.NET. + To quickly work with JSON either the serializer - + + Serializing and Deserializing JSON + SerializingJSON.htm + _self + + or using + LINQ to JSON + LINQtoJSON.htm + _self + is recommended. + + + T:Newtonsoft.Json.JsonTextReader and T:Newtonsoft.Json.JsonTextWriter are used to read and write JSON text. @@ -18,6 +36,10 @@ count and quote character. + + JsonTextReader has settings on it for reading different date formats and time zones, and + the culture used when reading text values. +
diff --git a/Doc/SerializationGuide.aml b/Doc/SerializationGuide.aml index f05286ee..9c9531a7 100644 --- a/Doc/SerializationGuide.aml +++ b/Doc/SerializationGuide.aml @@ -193,6 +193,11 @@ dictionary name/values will be written to the JSON object when serializing and properties on the JSON object will be added to the dictionary's name/values when deserializing. Additional members on the .NET dictionary are ignored during serialization. + When serializing a dictionary the keys of the dictionary are converted to strings and used as the + JSON object property names. The string written for a key can be customized by either overriding + M:System.Object.ToString for the key type or by implementing a + T:System.ComponentModel.TypeConverter. A TypeConverter will also + support converting a custom string back again when deserializing a dictionary. JsonDictionaryAttribute has options on it to customize the JsonConverter, type name handling and reference handling that are applied to collection items. When deserializing if a member is typed as the interface IDictionary<TKey, TValue> then it will be diff --git a/Doc/SerializationSettings.aml b/Doc/SerializationSettings.aml index 9a55e06d..ed77ea59 100644 --- a/Doc/SerializationSettings.aml +++ b/Doc/SerializationSettings.aml @@ -13,7 +13,7 @@
DateFormatHandling - DateFormatHandling controls how dates are serialized. + T:Newtonsoft.Json.DateFormatHandling controls how dates are serialized. @@ -24,11 +24,11 @@ IsoDateFormat - By default Json.NET writes dates in the ISO 8601 format, e.g. "2012-03-21T05:40Z". + By default Json.NET writes dates in the ISO 8601 format, e.g. "2012-03-21T05:40Z". MicrosoftDateFormat - Dates are written in the Microsoft JSON format, e.g. "\/Date(1198908717056)\/". + Dates are written in the Microsoft JSON format, e.g. "\/Date(1198908717056)\/".
@@ -37,7 +37,7 @@
MissingMemberHandling - MissingMemberHandling controls how missing members, e.g. JSON contains a property that isn't a member on the object, are handled during deserialization. + T:Newtonsoft.Json.MissingMemberHandling controls how missing members, e.g. JSON contains a property that isn't a member on the object, are handled during deserialization. @@ -61,7 +61,7 @@
ReferenceLoopHandling - ReferenceLoopHandling controls how circular referencing objects, e.g. a Person object referencing itself via a Manager property, are serialized. + T:Newtonsoft.Json.ReferenceLoopHandling controls how circular referencing objects, e.g. a Person object referencing itself via a Manager property, are serialized.
@@ -89,7 +89,7 @@
NullValueHandling - NullValueHandling controls how null values on .NET objects are handled during serialization and how null values in JSON are handled during deserialization. + T:Newtonsoft.Json.NullValueHandling controls how null values on .NET objects are handled during serialization and how null values in JSON are handled during deserialization.
@@ -114,7 +114,7 @@
DefaultValueHandling - DefaultValueHandling controls how Json.NET uses default values set using the .NET DefaultValueAttribute when serializing and deserializing. + T:Newtonsoft.Json.DefaultValueHandling controls how Json.NET uses default values set using the .NET T:System.ComponentModel.DefaultValueAttribute when serializing and deserializing.
@@ -139,7 +139,7 @@
ObjectCreationHandling - ObjectCreationHandling controls how objects are created and deserialized to during deserialization. + T:Newtonsoft.Json.ObjectCreationHandling controls how objects are created and deserialized to during deserialization.
@@ -168,7 +168,7 @@
TypeNameHandling - TypeNameHandling 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. + T:Newtonsoft.Json.TypeNameHandling 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.
@@ -205,7 +205,7 @@
TypeNameAssemblyFormat - TypeNameAssemblyFormat controls how type names are written during serialization. + T:System.Runtime.Serialization.Formatters.FormatterAssemblyStyle controls how type names are written during serialization.
@@ -230,14 +230,14 @@
Binder - The serialization binder is used to resolve type names to a .NET type. + The T:System.Runtime.Serialization.SerializationBinder is used to resolve type names to a .NET type. Read more about the serialization binder here: T:System.Runtime.Serialization.SerializationBinder
ConstructorHandling - ConstructorHandling controls how constructors are used when initializing objects during deserialization. + T:Newtonsoft.Json.ConstructorHandling controls how constructors are used when initializing objects during deserialization.
@@ -265,7 +265,7 @@
Converters This is the collection of JsonConverters that will be used during serialization and deserialization. - JsonConverters allows JSON to be manually written during serialization and read during deserialization. + A T:Newtonsoft.Json.JsonConverter allows JSON to be manually written during serialization and read during deserialization. This is useful for particularly complex JSON structures or for when you want to change how a type is serialized. When a JsonConverter has been added to a JsonSerializer it will be checked for every value that is being serialized/deserialized using its CanConvert to see if it should be used. If CanConvert returns true then the JsonConverter will be used to read or write @@ -300,7 +300,8 @@
ContractResolver Internally for every .NET type the JsonSerializer will create a contract of how the type should be serialized and deserialized, - based on type metadata and attributes applied to the class. Specifying a custom IContractResolver allows the creation of contracts to be customized. + based on type metadata and attributes applied to the class. Specifying a custom T:Newtonsoft.Json.Serialization.IContractResolver + allows the creation of contracts to be customized. Read more about Contract Resolvers here: Contract Resolvers ContractResolver.htm @@ -311,7 +312,7 @@
Error - The Error event can catch errors during serialization and either handle the event and continue with + The E:Newtonsoft.Json.JsonSerializer.Error event can catch errors during serialization and either handle the event and continue with serialization or let the error bubble up and be thrown to the application. Read more about error handling here: Serialization Error Handling @@ -337,9 +338,11 @@ DatesInJSON.htm _self - + T:Newtonsoft.Json.JsonSerializer T:Newtonsoft.Json.JsonSerializerSettings + T:Newtonsoft.Json.JsonConverter + T:System.Runtime.Serialization.SerializationBinder \ No newline at end of file diff --git a/Doc/SerializingCollections.aml b/Doc/SerializingCollections.aml index 79f12f15..d870f03e 100644 --- a/Doc/SerializingCollections.aml +++ b/Doc/SerializingCollections.aml @@ -54,6 +54,11 @@
+ + Serialization Guide + SerializationGuide.htm + _self + T:Newtonsoft.Json.JsonConvert T:Newtonsoft.Json.JsonSerializer diff --git a/Doc/SerializingJSON.aml b/Doc/SerializingJSON.aml index ac51e76e..3ccd7864 100644 --- a/Doc/SerializingJSON.aml +++ b/Doc/SerializingJSON.aml @@ -19,7 +19,7 @@ Overload:Newtonsoft.Json.JsonConvert.SerializeObject and Overload:Newtonsoft.Json.JsonConvert.DeserializeObject methods on JsonConvert provide an easy to use wrapper over JsonSerializer. - + SerializeObject and DeserializeObject both have overloads that take a T:Newtonsoft.Json.JsonSerializerSettings object. JsonSerializerSettings lets you use many of the JsonSerializer settings listed below while still using the simple serialization methods. diff --git a/Src/Newtonsoft.Json.Tests/Documentation/LinqToJsonTests.cs b/Src/Newtonsoft.Json.Tests/Documentation/LinqToJsonTests.cs index f316c4d1..75bb7b6d 100644 --- a/Src/Newtonsoft.Json.Tests/Documentation/LinqToJsonTests.cs +++ b/Src/Newtonsoft.Json.Tests/Documentation/LinqToJsonTests.cs @@ -64,7 +64,7 @@ namespace Newtonsoft.Json.Tests.Documentation string json = array.ToString(); // [ // "Manual text", - // "\/Date(958996800000+1200)\/" + // "2000-05-23T00:00:00" // ] #endregion } @@ -173,7 +173,7 @@ namespace Newtonsoft.Json.Tests.Documentation CPU: 'Intel', Drives: [ 'DVD read/writer', - ""500 gigabyte hard drive"" + '500 gigabyte hard drive' ] }"; @@ -181,6 +181,19 @@ namespace Newtonsoft.Json.Tests.Documentation #endregion } + public void LinqToJsonCreateParseArray() + { + #region LinqToJsonCreateParseArray + string json = @"[ + 'Small', + 'Medium', + 'Large' + ]"; + + JArray a = JArray.Parse(json); + #endregion + } + public void LinqToJsonQuerying() { JObject rss = new JObject(); diff --git a/Src/Newtonsoft.Json.Tests/Documentation/ReadingAndWritingJsonTests.cs b/Src/Newtonsoft.Json.Tests/Documentation/ReadingAndWritingJsonTests.cs index def2b0af..3de4f2e9 100644 --- a/Src/Newtonsoft.Json.Tests/Documentation/ReadingAndWritingJsonTests.cs +++ b/Src/Newtonsoft.Json.Tests/Documentation/ReadingAndWritingJsonTests.cs @@ -49,7 +49,8 @@ using ErrorEventArgs = Newtonsoft.Json.Serialization.ErrorEventArgs; namespace Newtonsoft.Json.Tests.Documentation { - public class ReadingAndWritingJsonTests + [TestFixture] + public class ReadingAndWritingJsonTests : TestFixtureBase { public void ReadingAndWritingJsonText() { @@ -89,6 +90,46 @@ namespace Newtonsoft.Json.Tests.Documentation #endregion } + [Test] + public void ReadingJsonText() + { + #region ReadingJsonText + string json = @"{ + 'CPU': 'Intel', + 'PSU': '500W', + 'Drives': [ + 'DVD read/writer' + /*(broken)*/, + '500 gigabyte hard drive', + '200 gigabype hard drive' + ] + }"; + + JsonTextReader reader = new JsonTextReader(new StringReader(json)); + while (reader.Read()) + { + if (reader.Value != null) + Console.WriteLine("Token: {0}, Value: {1}", reader.TokenType, reader.Value); + else + Console.WriteLine("Token: {0}", reader.TokenType); + } + + // Token: StartObject + // Token: PropertyName, Value: CPU + // Token: String, Value: Intel + // Token: PropertyName, Value: PSU + // Token: String, Value: 500W + // Token: PropertyName, Value: Drives + // Token: StartArray + // Token: String, Value: DVD read/writer + // Token: Comment, Value: (broken) + // Token: String, Value: 500 gigabyte hard drive + // Token: String, Value: 200 gigabype hard drive + // Token: EndArray + // Token: EndObject + #endregion + } + public void ReadingAndWritingJsonLinq() { #region ReadingAndWritingJsonLinq diff --git a/Src/Newtonsoft.Json.Tests/Documentation/SerializationTests.cs b/Src/Newtonsoft.Json.Tests/Documentation/SerializationTests.cs index da11c3bd..2964b6e7 100644 --- a/Src/Newtonsoft.Json.Tests/Documentation/SerializationTests.cs +++ b/Src/Newtonsoft.Json.Tests/Documentation/SerializationTests.cs @@ -332,13 +332,13 @@ namespace Newtonsoft.Json.Tests.Documentation //[ // { // "Name": "James", - // "BirthDate": "\/Date(346377600000)\/", - // "LastModified": "\/Date(1235134761000)\/" + // "BirthDate": "1980-12-23T00:00:00Z", + // "LastModified": "2009-02-20T12:59:21Z" // }, // { // "Name": "James", - // "BirthDate": "\/Date(346377600000)\/", - // "LastModified": "\/Date(1235134761000)\/" + // "BirthDate": "1980-12-23T00:00:00Z", + // "LastModified": "2009-02-20T12:59:21Z" // } //] #endregion @@ -356,8 +356,8 @@ namespace Newtonsoft.Json.Tests.Documentation // { // "$id": "1", // "Name": "James", - // "BirthDate": "\/Date(346377600000)\/", - // "LastModified": "\/Date(1235134761000)\/" + // "BirthDate": "1983-03-08T00:00Z", + // "LastModified": "2012-03-21T05:40Z" // }, // { // "$ref": "1" @@ -428,14 +428,14 @@ namespace Newtonsoft.Json.Tests.Documentation // { // "FirstName": "Maurice", // "LastName": "Moss", - // "BirthDate": "\/Date(252291661000)\/", + // "BirthDate": "1981-03-08T00:00Z", // "Department": "IT", // "JobTitle": "Support" // }, // { // "FirstName": "Jen", // "LastName": "Barber", - // "BirthDate": "\/Date(258771661000)\/", + // "BirthDate": "1985-12-10T00:00Z", // "Department": "IT", // "JobTitle": "Manager" // } @@ -478,7 +478,7 @@ namespace Newtonsoft.Json.Tests.Documentation //{ // "name": "Widget", - // "expiryDate": "\/Date(1292868060000)\/", + // "expiryDate": "2010-12-20T18:01Z", // "price": 9.99, // "sizes": [ // "Small", @@ -513,13 +513,13 @@ namespace Newtonsoft.Json.Tests.Documentation //[ // { // "Name": "Product 1", - // "ExpiryDate": "\/Date(978048000000)\/", + // "ExpiryDate": "2000-12-29T00:00Z", // "Price": 99.95, // "Sizes": null // }, // { // "Name": "Product 2", - // "ExpiryDate": "\/Date(1248998400000)\/", + // "ExpiryDate": "2009-07-31T00:00Z", // "Price": 12.50, // "Sizes": null // } @@ -533,13 +533,13 @@ namespace Newtonsoft.Json.Tests.Documentation string json = @"[ { 'Name': 'Product 1', - 'ExpiryDate': '\/Date(978048000000)\/', + 'ExpiryDate': '2000-12-29T00:00Z', 'Price': 99.95, 'Sizes': null }, { 'Name': 'Product 2', - 'ExpiryDate': '\/Date(1248998400000)\/', + 'ExpiryDate': '2009-07-31T00:00Z', 'Price': 12.50, 'Sizes': null } diff --git a/Src/Newtonsoft.Json.Tests/Properties/AssemblyInfo.cs b/Src/Newtonsoft.Json.Tests/Properties/AssemblyInfo.cs index c8b7eb2a..fbe53564 100644 --- a/Src/Newtonsoft.Json.Tests/Properties/AssemblyInfo.cs +++ b/Src/Newtonsoft.Json.Tests/Properties/AssemblyInfo.cs @@ -72,5 +72,5 @@ using System.Security; // by using the '*' as shown below: [assembly: AssemblyVersion("4.5.0.0")] #if !PocketPC -[assembly: AssemblyFileVersion("4.5.7.15122")] +[assembly: AssemblyFileVersion("4.5.7.15127")] #endif diff --git a/Src/Newtonsoft.Json/DefaultValueHandling.cs b/Src/Newtonsoft.Json/DefaultValueHandling.cs index 153a4a4a..91d37381 100644 --- a/Src/Newtonsoft.Json/DefaultValueHandling.cs +++ b/Src/Newtonsoft.Json/DefaultValueHandling.cs @@ -30,6 +30,10 @@ namespace Newtonsoft.Json /// /// Specifies default value handling options for the . /// + /// + /// + /// + /// [Flags] public enum DefaultValueHandling { diff --git a/Src/Newtonsoft.Json/JsonConvert.cs b/Src/Newtonsoft.Json/JsonConvert.cs index c50e9ef6..5d3aa920 100644 --- a/Src/Newtonsoft.Json/JsonConvert.cs +++ b/Src/Newtonsoft.Json/JsonConvert.cs @@ -45,6 +45,9 @@ namespace Newtonsoft.Json /// /// Provides methods for converting between common language runtime types and JSON types. /// + /// + /// + /// public static class JsonConvert { /// diff --git a/Src/Newtonsoft.Json/Linq/JArray.cs b/Src/Newtonsoft.Json/Linq/JArray.cs index 949c134d..d91254f4 100644 --- a/Src/Newtonsoft.Json/Linq/JArray.cs +++ b/Src/Newtonsoft.Json/Linq/JArray.cs @@ -34,6 +34,9 @@ namespace Newtonsoft.Json.Linq /// /// Represents a JSON array. /// + /// + /// + /// public class JArray : JContainer, IList { private readonly IList _values = new List(); @@ -135,6 +138,9 @@ namespace Newtonsoft.Json.Linq /// /// A that contains JSON. /// A populated from the string that contains JSON. + /// + /// + /// public static new JArray Parse(string json) { JsonReader reader = new JsonTextReader(new StringReader(json)); diff --git a/Src/Newtonsoft.Json/Linq/JObject.cs b/Src/Newtonsoft.Json/Linq/JObject.cs index 0c311199..9c427079 100644 --- a/Src/Newtonsoft.Json/Linq/JObject.cs +++ b/Src/Newtonsoft.Json/Linq/JObject.cs @@ -48,6 +48,9 @@ namespace Newtonsoft.Json.Linq /// /// Represents a JSON object. /// + /// + /// + /// public class JObject : JContainer, IDictionary, INotifyPropertyChanged #if !(SILVERLIGHT || NETFX_CORE || PORTABLE) , ICustomTypeDescriptor @@ -315,6 +318,9 @@ namespace Newtonsoft.Json.Linq /// /// A that contains JSON. /// A populated from the string that contains JSON. + /// + /// + /// public static new JObject Parse(string json) { JsonReader reader = new JsonTextReader(new StringReader(json)); diff --git a/Src/Newtonsoft.Json/NullValueHandling.cs b/Src/Newtonsoft.Json/NullValueHandling.cs index 48f078f1..08c4f831 100644 --- a/Src/Newtonsoft.Json/NullValueHandling.cs +++ b/Src/Newtonsoft.Json/NullValueHandling.cs @@ -28,6 +28,10 @@ namespace Newtonsoft.Json /// /// Specifies null value handling options for the . /// + /// + /// + /// + /// public enum NullValueHandling { /// diff --git a/Src/Newtonsoft.Json/PreserveReferencesHandling.cs b/Src/Newtonsoft.Json/PreserveReferencesHandling.cs index f74d15cf..cb9f5beb 100644 --- a/Src/Newtonsoft.Json/PreserveReferencesHandling.cs +++ b/Src/Newtonsoft.Json/PreserveReferencesHandling.cs @@ -32,6 +32,9 @@ namespace Newtonsoft.Json /// /// Specifies reference handling options for the . /// + /// + /// + /// [Flags] public enum PreserveReferencesHandling { diff --git a/Src/Newtonsoft.Json/Properties/AssemblyInfo.cs b/Src/Newtonsoft.Json/Properties/AssemblyInfo.cs index 963a32a8..e9b31471 100644 --- a/Src/Newtonsoft.Json/Properties/AssemblyInfo.cs +++ b/Src/Newtonsoft.Json/Properties/AssemblyInfo.cs @@ -90,7 +90,7 @@ using System.Security; // by using the '*' as shown below: [assembly: AssemblyVersion("4.5.0.0")] #if !PocketPC -[assembly: AssemblyFileVersion("4.5.7.15122")] +[assembly: AssemblyFileVersion("4.5.7.15127")] #endif [assembly: CLSCompliant(true)] diff --git a/Src/Newtonsoft.Json/Serialization/IContractResolver.cs b/Src/Newtonsoft.Json/Serialization/IContractResolver.cs index 83a16c51..a5c5c597 100644 --- a/Src/Newtonsoft.Json/Serialization/IContractResolver.cs +++ b/Src/Newtonsoft.Json/Serialization/IContractResolver.cs @@ -30,6 +30,10 @@ namespace Newtonsoft.Json.Serialization /// /// Used by to resolves a for a given . /// + /// + /// + /// + /// public interface IContractResolver { ///