From 7c57b1663cc9e24aad03b82019400f0348d69346 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Sun, 15 Feb 2015 13:57:37 +1300 Subject: [PATCH] -Merge documentation proof read --- Doc/ConditionalProperties.aml | 6 +- Doc/ContractResolver.aml | 2 +- Doc/ConvertingJSONandXML.aml | 26 ++++----- Doc/CreatingLINQtoJSON.aml | 6 +- Doc/CustomCreationConverter.aml | 2 +- Doc/DatesInJSON.aml | 14 ++--- Doc/Introduction.aml | 20 +++---- Doc/JsonNetVsWindowsDataJson.aml | 6 +- Doc/JsonSchema.aml | 6 +- Doc/LINQtoJSON.aml | 2 +- Doc/Performance.aml | 18 +++--- Doc/PreserveObjectReferences.aml | 16 ++--- Doc/QueryingLINQtoJSON.aml | 2 +- Doc/ReadingWritingJSON.aml | 16 ++--- Doc/ReducingSerializedJSONSize.aml | 29 +++++----- Doc/SerializationAttributes.aml | 46 +++++++-------- Doc/SerializationCallbacks.aml | 2 +- Doc/SerializationErrorHandling.aml | 22 +++---- Doc/SerializationGuide.aml | 90 ++++++++++++++--------------- Doc/SerializationTracing.aml | 10 ++-- Doc/SerializingCollections.aml | 2 +- Doc/SerializingJSON.aml | 17 +++--- Doc/SerializingJSONFragments.aml | 8 +-- Doc/doc.content | 10 ++-- Doc/icons/favicon.ico | Bin 22382 -> 22382 bytes 25 files changed, 188 insertions(+), 190 deletions(-) diff --git a/Doc/ConditionalProperties.aml b/Doc/ConditionalProperties.aml index d87357b9..08cc4ea5 100644 --- a/Doc/ConditionalProperties.aml +++ b/Doc/ConditionalProperties.aml @@ -3,7 +3,7 @@ Json.NET has the ability to conditionally serialize properties by placing a ShouldSerialize method on a class. - This funtionality is similar to the + This functionality is similar to the XmlSerializer ShouldSerialize feature http://msdn.microsoft.com/en-us/library/53b8022e.aspx _blank @@ -12,9 +12,9 @@
ShouldSerialize - To conditionally serialize a property add a boolean method with the same name as the property and then prefixed the method name + To conditionally serialize a property, add a method that returns boolean with the same name as the property and then prefix 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. + property will be serialized, if it returns false then the property will be skipped. diff --git a/Doc/ContractResolver.aml b/Doc/ContractResolver.aml index 639ceeb2..4a4d14bd 100644 --- a/Doc/ContractResolver.aml +++ b/Doc/ContractResolver.aml @@ -25,7 +25,7 @@ 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. + virtual methods that can be overridden.
diff --git a/Doc/ConvertingJSONandXML.aml b/Doc/ConvertingJSONandXML.aml index e34ddbe3..082506ec 100644 --- a/Doc/ConvertingJSONandXML.aml +++ b/Doc/ConvertingJSONandXML.aml @@ -5,7 +5,7 @@ Json.NET supports converting JSON to XML and vice versa using the T:Newtonsoft.Json.Converters.XmlNodeConverter. Elements, attributes, text, comments, character data, processing instructions, - namespaces and the XML declaration are all preserved when converting between the two. The + namespaces, and the XML declaration are all preserved when converting between the two. The only caveat is that it is possible to lose the order of differently named nodes at the same level when they are grouped together into an array. @@ -18,20 +18,20 @@ Attributes are prefixed with an @ and should be at the start of the object. 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. + Character data, comments, whitespace and significant whitespace nodes are accessed via + #cdata-section, #comment, #whitespace and #significant-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. +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. +You can find out more about using LINQ to JSON with LINQ here. 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; SerializeXNode/DeserializeXNode are available when the framework supports XDocument. @@ -47,11 +47,11 @@ Find out more about using LINQ to JSON with LINQ - Because multiple nodes with a the same name at the same level are grouped together into an array - the convernsion process can produce different JSON depending on the number of nodes. For example if some - XML for a user has a single <Role> node then that role will be text against + Because multiple nodes with the same name at the same level are grouped together into an array, + the conversion process can produce different JSON depending on the number of nodes. For example, if some + XML for a user has a single <Role> node, then that role will be text against a JSON "Role" property, but if the user has multiple <Role> - nodes then the role values will be placed in a JSON array. + nodes, then the role values will be placed in a JSON array. To fix this situation a custom XML attribute can be added to force a JSON array to be created. @@ -64,10 +64,10 @@ Find out more about using LINQ to JSON with LINQ @@ -29,9 +29,9 @@ The last option is to create a JSON object from a non-JSON type using the Overload:Newtonsoft.Json.Linq.JObject.FromObject - method. Internally FromObject will use the JsonSerializer to serialize the object to LINQ to JSON objects instead of text. + method. Internally, FromObject will use the JsonSerializer to serialize the object to LINQ to JSON objects instead of text. - The example below is creating a JSON object from an anonymous object but any + The example below shows creating a JSON object from an anonymous object, but any .NET type can be used with FromObject to create JSON. diff --git a/Doc/CustomCreationConverter.aml b/Doc/CustomCreationConverter.aml index 065d678a..4af3e084 100644 --- a/Doc/CustomCreationConverter.aml +++ b/Doc/CustomCreationConverter.aml @@ -18,7 +18,7 @@ This is an extremely simple example. A more complicated scenario - could involve an object factory or service locator which resolves the + could involve an object factory or service locator that resolves the object at runtime. diff --git a/Doc/DatesInJSON.aml b/Doc/DatesInJSON.aml index f92a721f..f0e97cfd 100644 --- a/Doc/DatesInJSON.aml +++ b/Doc/DatesInJSON.aml @@ -13,7 +13,7 @@ http://www.ietf.org/rfc/rfc4627.txt _blank itself: there is no literal - syntax for dates in JSON. The spec has objects, arrays, strings, integers + syntax for dates in JSON. The spec has objects, arrays, strings, integers, and floats, but it defines no standard for what a date looks like. By default Json.NET will serialize all objects it encounters by value. - If a list contains two Person references, and both references point to the - same object then the JsonSerializer will write out all the names and values + If a list contains two Person references and both references point to the + same object, then the JsonSerializer will write out all the names and values for each reference. - In most cases this is the desired result but in certain scenarios + In most cases this is the desired result, but in certain scenarios writing the second item in the list as a reference to the first is a better - solution. If the above JSON was deserialized now then the returned list would + solution. If the above JSON was deserialized now, then the returned list would contain two completely separate Person objects with the same values. Writing references by value will also cause problems on objects where a circular reference occurs. @@ -32,14 +32,14 @@ - The first Person in the list is serizlied with the addition of an - object Id. The second Person in JSON is now only a reference to the first. - With PreserveReferencesHandling on now only one Person object is created + The first Person in the list is serialized with the addition of an + object ID. The second Person in JSON is now only a reference to the first. + With PreserveReferencesHandling on, now only one Person object is created on deserialization and the list contains two references to it, mirroring what we started with. References cannot be preserved when a value is set via a non-default constructor. - With a non-default constructor child values must be created before the parent value so they can be passed into + With a non-default constructor, child values must be created before the parent value so they can be passed into the constructor, making tracking reference impossible. T:System.Runtime.Serialization.ISerializable types are an example of a class whose values are populated with a non-default constructor and won't work with PreserveReferencesHandling. diff --git a/Doc/QueryingLINQtoJSON.aml b/Doc/QueryingLINQtoJSON.aml index c8a7a95a..b079dbc2 100644 --- a/Doc/QueryingLINQtoJSON.aml +++ b/Doc/QueryingLINQtoJSON.aml @@ -30,7 +30,7 @@ M:Newtonsoft.Json.Linq.JToken.Children returns all the children of a token. If it is a - JObject it will return a collection of properties to work with and if + JObject it will return a collection of properties to work with, and if it is a JArray you will get a collection of the array's values. diff --git a/Doc/ReadingWritingJSON.aml b/Doc/ReadingWritingJSON.aml index fb9731e5..74bea348 100644 --- a/Doc/ReadingWritingJSON.aml +++ b/Doc/ReadingWritingJSON.aml @@ -2,7 +2,7 @@ - To manually read and write JSON Json.NET provides the + To manually read and write JSON, Json.NET provides the T:Newtonsoft.Json.JsonReader and T:Newtonsoft.Json.JsonWriter classes. @@ -13,8 +13,8 @@ - JsonReader and JsonWriter are low level classes and used internally by Json.NET. - To quickly work with JSON either the serializer - or using is recommended. + JsonReader and JsonWriter are low-level classes and are primarily for internal use by Json.NET. + To quickly work with JSON, either the serializer - - or using is recommended. @@ -22,13 +22,13 @@ and T:Newtonsoft.Json.JsonTextWriter are used to read and write JSON text. The JsonTextWriter has a number of settings on it to control how JSON is formatted - when it is written. These options include formatting, indention character, indent - count and quote character. + when it is written. These options include formatting, indentation character, indent + 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. + JsonTextReader has settings on it for reading different date formats, time zones, and + the cultures when reading text values.
@@ -40,7 +40,7 @@ read and write LINQ to JSON objects. They are located in the N:Newtonsoft.Json.Linq namespace. These objects allow you to use LINQ to JSON objects with objects that - read and write JSON such as the JsonSerializer. For example you can deserialize + read and write JSON, such as the JsonSerializer. For example you can deserialize from a LINQ to JSON object into a regular .NET object and vice versa. diff --git a/Doc/ReducingSerializedJSONSize.aml b/Doc/ReducingSerializedJSONSize.aml index 247c98ac..abb99146 100644 --- a/Doc/ReducingSerializedJSONSize.aml +++ b/Doc/ReducingSerializedJSONSize.aml @@ -14,10 +14,10 @@ One of the common problems encountered when serializing .NET objects to JSON is that the JSON ends up containing a lot of unwanted properties and values. - This can be especially important when returning JSON to the client. More JSON + This can be especially significant when returning JSON to the client. More JSON means more bandwidth and a slower website. - To solve the issue of unwanted JSON Json.NET has a range of built in - options to fine tune what gets written from a serialized object. + To solve the issue of unwanted JSON, Json.NET has a range of built-in + options to fine-tune what gets written from a serialized object. - By default Json.NET will include all of a classes public properties and fields + By default Json.NET will include all of a class's public properties and fields in the JSON it creates. Adding the T:Newtonsoft.Json.JsonIgnoreAttribute to a property tells the serializer to always skip writing it to the JSON result. @@ -35,13 +35,13 @@ If a class has many properties and you only want to serialize a small subset - of them then adding JsonIgnore to all the others will be tedious and error prone. + of them, then adding JsonIgnore to all the others will be tedious and error prone. The way to tackle this scenario is to add the T:System.Runtime.Serialization.DataContractAttribute to the class and T:System.Runtime.Serialization.DataMemberAttribute to the properties to serialize. This is opt-in - serialization, only the properties you mark up with be serialized, compared to + serialization - only the properties you mark up will be serialized, unlike opt-out serialization using JsonIgnoreAttribute. @@ -53,8 +53,8 @@ JSON written by the serializer with an option of T:Newtonsoft.Json.Formatting set to Indented produces - nicely formatted, easy to read JSON that is great for readability when you are - developing. Formatting.None on the other hand keeps the JSON result small, skipping + nicely formatted, easy-to-read JSON that is great for readability when you are + developing. Formatting.None on the other hand keeps the JSON result small, skipping all unnecessary spaces and line breaks to produce the most compact and efficient JSON possible. @@ -72,7 +72,7 @@ NullValueHandling can also be customized on individual properties - using the a + using the T:Newtonsoft.Json.JsonPropertyAttribute. The JsonPropertyAttribute value of NullValueHandling will override the setting on the JsonSerializer for that @@ -93,9 +93,9 @@ Json.NET also allows you to customize what the default value of an individual property is using the T:System.ComponentModel.DefaultValueAttribute. - For example if a string property called - Department always returns an empty string in its default state and you didn't want - that empty string in your JSON then placing the DefaultValueAttribute on Department + For example, if a string property called + Department always returns an empty string in its default state and you don't want + that empty string in your JSON, then placing the DefaultValueAttribute on Department with that value will mean Department is no longer written to JSON unless it has a value. @@ -103,8 +103,7 @@ DefaultValueHandling can also be customized on individual properties using - the a - T:Newtonsoft.Json.JsonPropertyAttribute. + the T:Newtonsoft.Json.JsonPropertyAttribute. The JsonPropertyAttribute value of DefaultValueHandling will override the setting on the JsonSerializer for that property. @@ -112,7 +111,7 @@
IContractResolver - For more flexibility the + For more flexibility, the T:Newtonsoft.Json.Serialization.IContractResolver provides an interface to customize almost every aspect of how a .NET object gets serialized to JSON, including changing diff --git a/Doc/SerializationAttributes.aml b/Doc/SerializationAttributes.aml index 91bf708b..e4bac083 100644 --- a/Doc/SerializationAttributes.aml +++ b/Doc/SerializationAttributes.aml @@ -15,10 +15,10 @@ Attributes can be used to control how Json.NET serializes and deserializes .NET objects. - T:Newtonsoft.Json.JsonObjectAttribute - Placed on classes to control how it should be serialized as a JSON object. - T:Newtonsoft.Json.JsonArrayAttribute - Placed on collections to control how it should be serialized as a JSON array. - T:Newtonsoft.Json.JsonDictionaryAttribute - Placed on dictionaries to control how it should be serialized as a JSON object. - T:Newtonsoft.Json.JsonPropertyAttribute - Placed on fields and properties to control how it should be serialized as a property in a JSON object. + T:Newtonsoft.Json.JsonObjectAttribute - Placed on classes to control how they should be serialized as a JSON object. + T:Newtonsoft.Json.JsonArrayAttribute - Placed on collections to control how they should be serialized as a JSON array. + T:Newtonsoft.Json.JsonDictionaryAttribute - Placed on dictionaries to control how they should be serialized as a JSON object. + T:Newtonsoft.Json.JsonPropertyAttribute - Placed on fields and properties to control how they should be serialized as a property in a JSON object. T:Newtonsoft.Json.JsonConverterAttribute - Placed on either classes or fields and properties to specify which JsonConverter should be used during serialization. @@ -32,15 +32,15 @@ As well as using the built-in Json.NET attributes, Json.NET also looks for the T:System.SerializableAttribute (if IgnoreSerializableAttribute on DefaultContractResolver is set to false) T:System.Runtime.Serialization.DataContractAttribute, - T:System.Runtime.Serialization.DataMemberAttribute + T:System.Runtime.Serialization.DataMemberAttribute, and T:System.NonSerializedAttribute and attributes when determining how JSON is to be serialized and deserialized. - Json.NET attributes take presidence over standard .NET serialization attributes, e.g. if both JsonPropertyAttribute + Json.NET attributes take precedence over standard .NET serialization attributes (e.g. if both JsonPropertyAttribute and DataMemberAttribute are present on a property and both customize the name, - the name from JsonPropertyAttribute will be used. + the name from JsonPropertyAttribute will be used). @@ -58,10 +58,10 @@ --> The MemberSerialization flag on this attribute specifies whether member serialization is opt-in (a member must have the JsonProperty or DataMember attribute to be serialized), opt-out (everything is - serialized by default but can be ignored with the JsonIgnoreAttribute, Json.NET's default behavor) or - fields (all public and private fields are serialized, properties are ignored). - Json.NET serializes .NET classes that implement IEnumerable as an JSON array populated with the - IEnumerable values. Placing the JsonPropertyAttribute overrides this behavor and forces the serializer + serialized by default but can be ignored with the JsonIgnoreAttribute, Json.NET's default behavior) or + fields (all public and private fields are serialized and properties are ignored). + Json.NET serializes .NET classes that implement IEnumerable as a JSON array populated with the + IEnumerable values. Placing the JsonPropertyAttribute overrides this behavior and forces the serializer to serialize the class's fields and properties. The DataContractAttribute can be used as substitute for JsonObjectAttribute. The DataContractAttribute will default member serialization to opt-in. @@ -73,8 +73,8 @@ - The JsonArrayAttribute and JsonDictionaryAttributes are used to specified whether a class is serialized as that collection type. - The collection attributes have options to customize the JsonConverter, type name handling and reference handling that are applied to collection items. + The JsonArrayAttribute and JsonDictionaryAttributes are used to specify whether a class is serialized as that collection type. + The collection attributes have options to customize the JsonConverter, type name handling, and reference handling that are applied to collection items.
@@ -86,14 +86,14 @@ JsonPropertyAttribute has a number of uses: - By default the JSON property will have the same name as the .NET property. This attribute allows the name to be customized. - Indicates that a property should be serialized when member serialization is set to opt-in. - Includes non-public properties in serialization and deserialization. - Customize type name, reference, null and default value handling for the property value. - Customize the property's collection items JsonConverter, type name handing and reference handling. + By default, the JSON property will have the same name as the .NET property. This attribute allows the name to be customized. + JsonPropertyAttribute indicates that a property should be serialized when member serialization is set to opt-in. + It includes non-public properties in serialization and deserialization. + It can be used to customize type name, reference, null, and default value handling for the property value. + It can be used to customize the property's collection items JsonConverter, type name handling, and reference handling. - The DataMemberAttribute can be used as substitute for JsonPropertyAttribute. + The DataMemberAttribute can be used as a substitute for JsonPropertyAttribute. @@ -114,10 +114,10 @@ The JsonConverterAttribute specifies which JsonSerializer is used to convert an object. - The attribute can be placed on a class or a member. When placed on a class the JsonConverter + The attribute can be placed on a class or a member. When placed on a class, the JsonConverter specified by the attribute will be the default way of serializing that class. When the attribute is - on a field or property then the specified JsonConverter will always be used to serialize that value. - The priority of which JsonConverter is used is member attribute then class attribute and finally + on a field or property, then the specified JsonConverter will always be used to serialize that value. + The priority of which JsonConverter is used is member attribute, then class attribute, and finally any converters passed to the JsonSerializer. @@ -126,7 +126,7 @@ - To apply a JsonConverter to the items in a collection use either T:Newtonsoft.Json.JsonArrayAttribute, + To apply a JsonConverter to the items in a collection, use either T:Newtonsoft.Json.JsonArrayAttribute, T:Newtonsoft.Json.JsonDictionaryAttribute or T:Newtonsoft.Json.JsonPropertyAttribute and set the ItemConverterType property to the converter type you want to use. diff --git a/Doc/SerializationCallbacks.aml b/Doc/SerializationCallbacks.aml index 7ede501f..5340a55b 100644 --- a/Doc/SerializationCallbacks.aml +++ b/Doc/SerializationCallbacks.aml @@ -22,7 +22,7 @@ To tell the serializer which methods should be called during the object's -serialization lifecycle, decorate a method with the appropraite attribute +serialization lifecycle, decorate a method with the appropriate attribute (T:System.Runtime.Serialization.OnSerializingAttribute, T:System.Runtime.Serialization.OnSerializedAttribute, T:System.Runtime.Serialization.OnDeserializingAttribute, diff --git a/Doc/SerializationErrorHandling.aml b/Doc/SerializationErrorHandling.aml index 2716a0e2..10b0aeca 100644 --- a/Doc/SerializationErrorHandling.aml +++ b/Doc/SerializationErrorHandling.aml @@ -16,8 +16,8 @@ deserialization. Error handling lets you catch an error and choose whether to handle it and continue with serialization or let the error bubble up and be thrown in your application. - Error handling is defined through two methods: the Error event on - JsonSerializer and the OnErrorAttribute. + Error handling is defined through two methods: the E:Newtonsoft.Json.JsonSerializer.Error event on + JsonSerializer and the T:Newtonsoft.Json.Serialization.OnErrorAttribute. At a high level, the Json.NET serializer will convert primitive .NET values into primitive JSON values, - .NET arrays and collections to JSON arrays and everything else to JSON objects. - Json.NET will throw an error if it encounters incorrect JSON when deserializing a value. For example if + will convert .NET arrays and collections to JSON arrays, and will convert everything else to JSON objects. + Json.NET will throw an error if it encounters incorrect JSON when deserializing a value. For example, if the serializer encounters a JSON property with an array of values and the type of matching .NET property is not - a collection then an error will be thrown, and vice-versa. + a collection, then an error will be thrown, and vice-versa.
@@ -134,62 +134,62 @@ .NET types that don't fall into any other category listed below - (i.e. aren't lists, dictionaries, dynamic, implement ISerializable, etc) + (i.e. aren't lists, dictionaries, dynamic, implement ISerializable, etc.) are serialized as JSON objects. You can also force a type to be serialized as a JSON object by placing the JsonObjectAttribute on the type. - By default a type's properties are serialized in opt-out mode. What that means is all public fields and properties with + By default a type's properties are serialized in opt-out mode. What that means is that all public fields and properties with getters are automatically serialized to JSON, and fields and properties that shouldn't be serialized are opted-out by placing - JsonIgnoreAttribute on them. To serialize private members the JsonPropertyAttribute can be placed on private fields and + JsonIgnoreAttribute on them. To serialize private members, the JsonPropertyAttribute can be placed on private fields and properties. Types can also be serialized using opt-in mode. Only properties and fields that have a JsonPropertyAttribute or DataMemberAttribute on them will be serialized. Opt-in mode for an object is specified by placing the JsonObjectAttribute or DataContractAttribute on the type. - Finally types can be serialized using a fields mode. All fields, both public and private, are serialized + Finally, types can be serialized using a fields mode. All fields, both public and private, are serialized and properties are ignored. This can be specified by setting MemberSerialization.Fields on a type with the JsonObjectAttribute - or by the .NET T:System.SerializableAttribute + or by using the .NET T:System.SerializableAttribute and setting IgnoreSerializableAttribute on DefaultContractResolver to false.
- IEnumerable, Lists and Arrays + IEnumerable, Lists, and Arrays .NET lists (types that inherit from IEnumerable) and .NET arrays are converted to JSON arrays. Because JSON arrays only support a range of values and not properties, any additional properties and fields declared on .NET - collections are not serialized. In situations where a type implements IEnumerable but a JSON array is not wanted then - the JsonObjectAttribute can be placed the type to force it to be serialized as a JSON object instead. - JsonArrayAttribute has options on it to customize the JsonConverter, type name handling and reference handling + collections are not serialized. In situations where a type implements IEnumerable but a JSON array is not wanted, then + the JsonObjectAttribute can be placed on the type to force it to be serialized as a JSON object instead. + JsonArrayAttribute has options on it to customize the JsonConverter, type name handling, and reference handling that are applied to collection items. - Note that if TypeNameHandling or PreserveReferencesHandling has been enabled for JSON arrays on the serializer - then JSON arrays are wrapped it a containing object. The object will have the type name/reference properties and a - $values property which will have the collection data. - When deserializing if a member is typed as the interface IList<T> then it will be deserialized as a + Note that if TypeNameHandling or PreserveReferencesHandling has been enabled for JSON arrays on the serializer, + then JSON arrays are wrapped in a containing object. The object will have the type name/reference properties and a + $values property, which will have the collection data. + When deserializing, if a member is typed as the interface IList<T>, then it will be deserialized as a List<T>. - Read more about serializing collections here: + You can read more about serializing collections here:
- Dictionarys and Hashtables + Dictionaries and Hashtables .NET dictionaries (types that inherit from IDictionary) are converted to JSON objects. Note that only the - dictionary name/values will be written to the JSON object when serializing and properties on the JSON object will + 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 + 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 + 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 + When deserializing, if a member is typed as the interface IDictionary<TKey, TValue> then it will be deserialized as a Dictionary<TKey, TValue>. - Read more about serializing collections here: + You can read more about serializing collections here:
@@ -198,12 +198,12 @@ - .NET properties on a class that don't specify a type (i.e. they are just object) are serialized as usual. When - untyped properties are deserialized the serializer has no way to know what type to create (unless type name handling + .NET properties on a class that don't specify a type (i.e. they are just object) are serialized as usual. When + untyped properties are deserialized, the serializer has no way of knowing what type to create (unless type name handling is enabled and the JSON contains the type names). - For these untyped properties the Json.NET serializer will read the JSON into LINQ to JSON objects and set them - to the property. JObject will be created for JSON objects, JArray will be created for JSON arrays and JValue for - primitive JSON values. + For these untyped properties, the Json.NET serializer will read the JSON into LINQ to JSON objects and set them + to the property. JObject will be created for JSON objects; JArray will be created for JSON arrays, and JValue will be + created for primitive JSON values. @@ -212,14 +212,14 @@ - There are two different usages of dynamic (introduced in .NET 4) in .NET. The first are .NET properties with a - type of dynamic. Dynamic proeprties behave like properties declared as object, any value can be assigned to it, but - the difference being that properties and methods can be called on a dynamic property without casting. In Json.NET + There are two different usages of dynamic (introduced in .NET 4) in .NET. The first are .NET properties with a + type of dynamic. Dynamic properties behave like properties declared as object: any value can be assigned to it, but + the difference being that properties and methods can be called on a dynamic property without casting. In Json.NET, dynamic properties are serialized and deserialized exactly the same as untyped objects: because dynamic isn't an actual - type Json.NET falls back to deserializing the JSON as LINQ to JSON objects. - The second usage of dynamic in .NET are types that implement + type, Json.NET falls back to deserializing the JSON as LINQ to JSON objects. + The second usage of dynamic in .NET are by the types that implement T:System.Dynamic.IDynamicMetaObjectProvider. This interface lets - the implementor create dynamic objects that intercept the property and method calls on an object and use them. + the implementer create dynamic objects that intercept the property and method calls on an object and use them. T:System.Dynamic.ExpandoObject is a good example of a dynamic object. Dynamic objects are serialized as JSON objects. A property is written for every member name returned by @@ -227,9 +227,9 @@ A dynamic object's normal properties aren't serialized by default but can be included by placing the JsonPropertyAttribute on them. - When deserializing dynamic objects the serializer first attempts to set JSON property values on a normal .NET - member with the matching name. If no .NET member is found with the property name then the serializer will call - SetMember on the dynamic object. Because there is no type information for dynamic members on a dynamic object the + When deserializing dynamic objects, the serializer first attempts to set JSON property values on a normal .NET + member with the matching name. If no .NET member is found with the property name, then the serializer will call + SetMember on the dynamic object. Because there is no type information for dynamic members on a dynamic object, the values assigned to them will be LINQ to JSON objects. @@ -239,10 +239,10 @@ - Types that implement ISerializable are serialized as JSON objects. When serializing only the values returned from - ISerializable.GetObjectData are used; members on the type are ignored. When deserializing the constructor with a + Types that implement ISerializable are serialized as JSON objects. When serializing, only the values returned from + ISerializable.GetObjectData are used; members on the type are ignored. When deserializing, the constructor with a SerializationInfo and StreamingContext is called, passing the JSON object's values. - In situations where this behavior is not wanted the JsonObjectAttribute can be placed on a .NET type that + In situations where this behavior is not wanted, the JsonObjectAttribute can be placed on a .NET type that implements ISerializable to force it to be serialized as a normal JSON object. @@ -252,7 +252,7 @@ - LINQ to JSON types (e.g. JObject, JArray) are automatically serialized and deserialized to their equivalent JSON + LINQ to JSON types (e.g. JObject and JArray) are automatically serialized and deserialized to their equivalent JSON when encountered by the Json.NET serializer. @@ -264,15 +264,15 @@ --> Serialization of values that are convertible by a T:Newtonsoft.Json.JsonConverter (i.e. CanConvert returns true for its type) is - completely overridden by the JsonConverter. The test to see whether a value can be converted by a JsonSerializer takes + completely overridden by the JsonConverter. The test to see whether a value can be converted by the JsonSerializer takes precedence over all other tests. JsonConverters can be defined and specified in a number of places: in an attribute on a member, in an attribute - on a class and added to the JsonSerializer's converters collection. The priority of which JsonConverter is used is the - JsonConverter defined by attribute on a member then the JsonConverter defined by an attribute on a class and finally + on a class, and added to the JsonSerializer's converters collection. The priority of which JsonConverter is used is the + JsonConverter defined by attribute on a member, then the JsonConverter defined by an attribute on a class, and finally any converters passed to the JsonSerializer. - Because a JsonConverter creates a new value a converter will not work with readonly properties because there is no way to assign the new + Because a JsonConverter creates a new value, a converter will not work with readonly properties because there is no way to assign the new value to the property. Either change the property to have a public setter or place a JsonPropertyAttribute or DataMemberAttribute on the property. diff --git a/Doc/SerializationTracing.aml b/Doc/SerializationTracing.aml index 1a22831f..ee11e9a7 100644 --- a/Doc/SerializationTracing.aml +++ b/Doc/SerializationTracing.aml @@ -4,7 +4,7 @@ The Json.NET serializer supports logging and debugging using the T:Newtonsoft.Json.Serialization.ITraceWriter interface. - By assigning a trace writer you can capture serialization messages and errors, and debug what happens inside the + By assigning a trace writer you can capture serialization messages and errors and debug what happens inside the Json.NET serializer when serializing and deserializing JSON.
@@ -14,16 +14,16 @@ - Json.NET has two implementations of ITraceWriter: T:Newtonsoft.Json.Serialization.MemoryTraceWriter - which keeps messages in memory for simple debugging like the example - above, and T:Newtonsoft.Json.Serialization.DiagnosticsTraceWriter which writes messages to any + Json.NET has two implementations of ITraceWriter: T:Newtonsoft.Json.Serialization.MemoryTraceWriter, + which keeps messages in memory for simple debugging, like the example + above, and T:Newtonsoft.Json.Serialization.DiagnosticsTraceWriter, which writes messages to any System.Diagnostics.TraceListeners your application is using.
Custom ITraceWriter - To write messages using your existing logging framework just implement a custom version of ITraceWriter. + To write messages using your existing logging framework, just implement a custom version of ITraceWriter. diff --git a/Doc/SerializingCollections.aml b/Doc/SerializingCollections.aml index dae29437..c67e45d7 100644 --- a/Doc/SerializingCollections.aml +++ b/Doc/SerializingCollections.aml @@ -36,7 +36,7 @@ - To deserialize JSON into a .NET collection just specify the collection + To deserialize JSON into a .NET collection, just specify the collection type you want to deserialize to. Json.NET supports a wide range of collection types. diff --git a/Doc/SerializingJSON.aml b/Doc/SerializingJSON.aml index a0de987a..fbc2e0ef 100644 --- a/Doc/SerializingJSON.aml +++ b/Doc/SerializingJSON.aml @@ -16,10 +16,10 @@ at least one procedure or code example -->
JsonConvert - For simple scenarios where you want to convert to and from a JSON string the + For simple scenarios where you want to convert to and from a JSON string, the Overload:Newtonsoft.Json.JsonConvert.SerializeObject and Overload:Newtonsoft.Json.JsonConvert.DeserializeObject - methods on JsonConvert provide an easy to use wrapper over JsonSerializer. + 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. @@ -30,19 +30,18 @@
JsonSerializer - For more control over how an object is serialized the T:Newtonsoft.Json.JsonSerializer can be used directly. + For more control over how an object is serialized, the T:Newtonsoft.Json.JsonSerializer can be used directly. The JsonSerializer is able to read and write JSON text directly to a stream via T:Newtonsoft.Json.JsonTextReader and T:Newtonsoft.Json.JsonTextWriter. -Other kinds of JsonWriters can also be used such as -T:Newtonsoft.Json.Linq.JTokenReader/T:Newtonsoft.Json.Linq.JTokenWriter -to convert your object to and from -LINQ to JSON objects or -T:Newtonsoft.Json.Bson.BsonReader/T:Newtonsoft.Json.Bson.BsonWriter to convert to and from BSON. +Other kinds of JsonWriters can also be used, such as +T:Newtonsoft.Json.Linq.JTokenReader/T:Newtonsoft.Json.Linq.JTokenWriter, +to convert your object to and from LINQ to JSON objects, or +T:Newtonsoft.Json.Bson.BsonReader/T:Newtonsoft.Json.Bson.BsonWriter, to convert to and from BSON. JsonSerializer has a number of properties on it to customize how it serializes JSON. These can also be used with the methods on JsonConvert via the JsonSerializerSettings overloads. -Read more about the available JsonSerializer settings here: +You can read more about the available JsonSerializer settings here:
diff --git a/Doc/SerializingJSONFragments.aml b/Doc/SerializingJSONFragments.aml index 42b40bab..832c7ae6 100644 --- a/Doc/SerializingJSONFragments.aml +++ b/Doc/SerializingJSONFragments.aml @@ -4,15 +4,15 @@ Often when working with large JSON documents you're only interested in a small - fragment of information. This scenario can be annoying when you want to serialize - that Json.NET into .NET objects because you have to define .NET classes for the + fragment of information. This scenario can be annoying when you want to deserialize + that JSON fragment into .NET objects because you have to define .NET classes for the entire JSON result. With Json.NET it is easy to get around this problem. Using LINQ to JSON you - can extract the pieces of JSON you want to serialize before passing them to the + can extract the pieces of JSON you want to deserialize before passing them to the Json.NET serializer. - + diff --git a/Doc/doc.content b/Doc/doc.content index 2740af2f..34f5d768 100644 --- a/Doc/doc.content +++ b/Doc/doc.content @@ -1,7 +1,7 @@  - + @@ -12,7 +12,7 @@ - + @@ -29,8 +29,8 @@ - - + + @@ -53,7 +53,7 @@ - + diff --git a/Doc/icons/favicon.ico b/Doc/icons/favicon.ico index 466716cf3cf6eb912d16090bcaa66a4f52f87689..a32b4be098bd713eb8a082ed6482a813d4eec0c0 100644 GIT binary patch delta 800 zcmYk2!AiqG5Qb+>G{*#_h^GWZ+Kb*S-jWLK3y4?sBKQ!6-B*xYi)Rm^BDs2q@8DVT z0HyR;A$0v`c7q-G^X<%TcK)69QmvP2Or$8FqF`n;x*64hsW)^j2gz|j2oLpZI85}ywkWh3N+H;7VR5r3&Kt-CHlhH}Rs3X@hH`@$G#DflwN3%v zrSLc&qJp;qzR-mp*%vN@HqaJQ_T}oke41XAV^xBK`bV9p!$p>!{g#&pX?+@mO0CL| pa8%C1wy9I+nSc~S5foGtqadm#9khci%Ro&v`2(-Ia0UPX delta 804 zcmYL_KT88a5XIkm#%qKG{8w&3#1yuQT@Ddj3nNw*c76!qwzRXjUR$e(q!rl@VX1Id zVj~foQ_dUT>}_!1;VTW zC^|<^=DIjDTgAetFfYuOC*#qY={)!C`gifzv6J`Xd1HR~Wl*f1EbZ6)@LLN|=al_d z#T=?G;8MURlmQw_7O6|hQ&UV%_XfRuDqkW}s)iy{OQo$UvPzg!CFK*jafu{Ig!aYp z5-R6qL&}z%IR#Qx10JfVng<)air`bkaf;7)8F(?(P;=t%cQ&)bI~th9RZKWvqcM@l zL(;%Tb|Yy{gN7o9#Y471XExL`x>(b!_GvP(j;td2fY9fI$T!^<>GiRs<6^wT9*5HM)^0H=&{H(lA_E2(_n?&)81nMQz{4NwidIM|a^O zJ()`0exb)OOP9nMyGqWemAt#%?u;(hKC;9`*uI+P`Cv||rj%+X&`0uMs5zk*5}ImR F;}6k&fo1>z