From d815dc77496d8ce1a4d2d57abd4add8021965b95 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Mon, 7 May 2012 23:16:24 +1200 Subject: [PATCH] -Documentation -Added Path to JsonWriterException --- Doc/DatesInJSON.html | 19 +++-- Doc/SerializationAttributes.html | 32 ++++++-- Doc/SerializationGuide.html | 20 +++-- .../Bson/BsonWriterTests.cs | 10 +-- .../JsonTextWriterTest.cs | 6 +- Src/Newtonsoft.Json.Tests/PerformanceTests.cs | 61 ++++++++------ .../Properties/AssemblyInfo.cs | 2 +- .../Serialization/JsonSerializerTest.cs | 82 +++++++++++++++++-- .../PreserveReferencesHandlingTests.cs | 4 +- Src/Newtonsoft.Json/Bson/BsonWriter.cs | 16 ++-- Src/Newtonsoft.Json/JsonException.cs | 19 +++++ Src/Newtonsoft.Json/JsonPropertyAttribute.cs | 14 +++- Src/Newtonsoft.Json/JsonReaderException.cs | 18 ---- .../JsonSerializationException.cs | 2 +- Src/Newtonsoft.Json/JsonTextWriter.cs | 2 +- Src/Newtonsoft.Json/JsonWriter.cs | 28 +++---- Src/Newtonsoft.Json/JsonWriterException.cs | 24 ++++++ .../Properties/AssemblyInfo.cs | 2 +- .../Serialization/DefaultContractResolver.cs | 5 +- .../Serialization/JsonProperty.cs | 19 +++++ .../JsonSerializerInternalWriter.cs | 23 ++++-- Src/Newtonsoft.Json/Utilities/StringUtils.cs | 15 ++++ 22 files changed, 299 insertions(+), 124 deletions(-) diff --git a/Doc/DatesInJSON.html b/Doc/DatesInJSON.html index a9d8713e..d9d86266 100644 --- a/Doc/DatesInJSON.html +++ b/Doc/DatesInJSON.html @@ -16,13 +16,16 @@

DateTimes in JSON are hard.

- The problem comes from the JSON spec itself, there is no literal 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.

+ The problem comes from the JSON spec itself: there is no literal 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.

The default format used by Json.NET is the ISO 8601 standard: 2012-03-19T07:22Z. You can read more about it here.

Prior to Json.NET 4.5 dates were written using the Microsoft format: "\/Date(1198908717056)\/". If you want to use this format, or you want to maintain compatibility with Microsoft JSON serializers or older versions of - Json.NET then change the DateFormatHandling setting to MicrosoftDateFormat.

+ Json.NET then change the DateFormatHandling setting to MicrosoftDateFormat.

+

Json.NET also has the DateTimeZoneHandling setting. This can be used to convert + DateTime's kind when serializing, e.g. set DateTimeZoneHandling to Utc to + serialize all DateTimes as UTC dates.

DateTime JsonConverters

With no standard for dates in JSON, the number of possible different formats when interoping with other systems is endless. Fortunately Json.NET has a solution to deal with reading and writing custom dates: JsonConverters. A JsonConverter is used to override how a type is serialized.

@@ -49,16 +52,16 @@ 
  };
 
-
  // Default as of Json.NET 4.5
+
  // default as of Json.NET 4.5
  string isoJson = JsonConvert.SerializeObject(entry);
  // {"Details":"Application started.","LogDate":"2009-02-15T00:00:00Z"}
 
-
  JsonSerializerSettings settingsWithMicrosoftDateFormat = new JsonSerializerSettings
+
  JsonSerializerSettings microsoftDateFormatSettings = new JsonSerializerSettings
  {
    DateFormatHandling = DateFormatHandling.MicrosoftDateFormat
  };
-
  string microsoftJson = JsonConvert.SerializeObject(entry, settingsWithMicrosoftDateFormat);
+
  string microsoftJson = JsonConvert.SerializeObject(entry, microsoftDateFormatSettings);
  // {"Details":"Application started.","LogDate":"\/Date(1234656000000)\/"}
 
@@ -71,7 +74,7 @@

Simply pass the JsonConverter you wish to use to the Json.NET serializer.

JavaScriptDateTimeConverter

-

The JavaScriptDateTimeConverter class is one of the two DateTime JsonConverters that come with Json.NET. This converter serializes a DateTime as a JavaScript Date object.

+

The JavaScriptDateTimeConverter class is one of the two DateTime JsonConverters that come with Json.NET. This converter serializes a DateTime as a JavaScript Date object.

@@ -80,7 +83,7 @@
-

Technically this is invalid JSON according to the spec but all browsers, and some JSON frameworks including Json.NET, support it.

+

Technically this is invalid JSON according to the spec but all browsers, and some JSON frameworks, including Json.NET, support it.

IsoDateTimeConverter

IsoDateTimeConverter seralizes a DateTime to an ISO 8601 formatted string. Note that since Json.NET 4.5 dates are written using the ISO 8601 format by @@ -94,8 +97,6 @@

The IsoDateTimeConverter class has a property, DateTimeFormat, to further customize the formatted string.

-

 

-

One final thing to note is all date values returned by Json.NET are in UTC time.

diff --git a/Doc/SerializationAttributes.html b/Doc/SerializationAttributes.html index 756919d9..03b55bc2 100644 --- a/Doc/SerializationAttributes.html +++ b/Doc/SerializationAttributes.html @@ -25,8 +25,15 @@
  • JsonConverterAttribute - Placed on either classes or fields and properties to specify which JsonConverter should be used during serialization.

    • As well as using the built-in Json.NET attributes, Json.NET also looks for the - DataContract and - DataMember attributes when determining how JSON is to be serialized and deserialized. If both are present the Json.NET serialization attributes take precedence.

    + + Serializable (if IgnoreSerializableAttribute on DefaultContractResolver is + set to false) + DataContract, + DataMember + and + + NotSerialized and + attributes when determining how JSON is to be serialized and deserialized. If both are present the Json.NET serialization attributes take precedence.

    @@ -40,7 +47,6 @@ 
     
      // "2000-12-15T22:11:03"
      [JsonProperty]
    -
      [JsonConverter(typeof(IsoDateTimeConverter))]
      public DateTime BirthDate { get; set; }
     
      // new Date(976918263055)
    @@ -48,7 +54,7 @@ 
      [JsonConverter(typeof(JavaScriptDateTimeConverter))]
      public DateTime LastModified { get; set; }
     
    -
      // not serialized
    +
      // not serialized because mode is opt-in
      public string Department { get; set; }
    }
    @@ -56,11 +62,14 @@
    JsonObjectAttribute
    -

    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) or opt-out (everything is serialized by default but can be ignored with the JsonIgnoreAttribute, - Json.NET's default behavor).

    +

    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 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.

    JsonArrayAttribute/JsonDictionaryAttribute

    The JsonArrayAttribute and JsonDictionaryAttributes are used to specified @@ -75,9 +84,14 @@

  • 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.
    • +

    + The DataMemberAttribute can be used as substitute for JsonPropertyAttribute.

    JsonIgnoreAttribute

    Excludes a field or property from serialization.

    +

    The NotSerializedAttribute can be used as substitute for JsonIgnoreAttribute.

    JsonConverterAttribute

    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 @@ -120,6 +134,12 @@ finally any converters passed to the JsonSerializer.

    +

    To apply a JsonConverter to the items in a collection use either + JsonArrayAttribute, + + JsonDictionaryAttribute or + JsonPropertyAttribute and set + the ItemConverterType property to the converter type you want to use.