From 08296c5eca361ea4771f88d387497975b4d1ac65 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Wed, 10 Jun 2015 01:16:12 +1200 Subject: [PATCH] -Documentation --- .../Serializer/JsonConstructorAttribute.aml | 17 +++++ Doc/SelectToken.aml | 6 +- Doc/SerializationAttributes.aml | 17 ++++- Doc/doc.content | 5 +- Doc/doc.shfbproj | 1 + Src/Newtonsoft.Json.TestConsole/Program.cs | 3 +- .../Properties/AssemblyInfo.cs | 2 +- .../DiscriminatedUnionConverterTests.cs | 4 +- .../Serializer/JsonConstructorAttribute.cs | 76 +++++++++++++++++++ .../Newtonsoft.Json.Tests.csproj | 1 + .../Properties/AssemblyInfo.cs | 2 +- .../Properties/AssemblyInfo.cs | 2 +- 12 files changed, 120 insertions(+), 16 deletions(-) create mode 100644 Doc/Samples/Serializer/JsonConstructorAttribute.aml create mode 100644 Src/Newtonsoft.Json.Tests/Documentation/Samples/Serializer/JsonConstructorAttribute.cs diff --git a/Doc/Samples/Serializer/JsonConstructorAttribute.aml b/Doc/Samples/Serializer/JsonConstructorAttribute.aml new file mode 100644 index 00000000..21dfd30e --- /dev/null +++ b/Doc/Samples/Serializer/JsonConstructorAttribute.aml @@ -0,0 +1,17 @@ + + + + + This sample uses the + T:Newtonsoft.Json.JsonConstructorAttribute + to specify that a constrctor should be used to create a class during deserialization. + +
+ Sample + + + + +
+ + \ No newline at end of file diff --git a/Doc/SelectToken.aml b/Doc/SelectToken.aml index b83bdf18..aee0b528 100644 --- a/Doc/SelectToken.aml +++ b/Doc/SelectToken.aml @@ -16,10 +16,8 @@ SelectToken is a method on JToken and takes a string path to a child token. SelectToken returns the child token or a null reference if a token couldn't be found at the path's location. - The path is made up of property names and array indexes separated by periods. - Array indexes can use either square or round brackets. Both of the following are - valid paths and are equivalent to each other: Manufacturers[0].Name - and Manufacturers(0).Name. + The path is made up of property names and array indexes separated by periods, + e.g. Manufacturers[0].Name. diff --git a/Doc/SerializationAttributes.aml b/Doc/SerializationAttributes.aml index d21d4097..9ade3aed 100644 --- a/Doc/SerializationAttributes.aml +++ b/Doc/SerializationAttributes.aml @@ -12,6 +12,7 @@ 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. T:Newtonsoft.Json.JsonExtensionDataAttribute - Placed on a collection field or property to deserialize properties with no matching class member into the specified collection and write values during serialization. + T:Newtonsoft.Json.JsonConstructorAttribute - Placed on a constructor to specify that it should be used to create the class during deserialization. @@ -99,12 +100,10 @@ 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. - - + + This example shows the JsonConverterAttribute being applied to a property. - - To apply a JsonConverter to the items in a collection, use either T:Newtonsoft.Json.JsonArrayAttribute, T:Newtonsoft.Json.JsonDictionaryAttribute or @@ -124,6 +123,16 @@ + +
+ JsonConstructorAttribute + + The T:Newtonsoft.Json.JsonConstructorAttribute instructs the + T:Newtonsoft.Json.JsonSerializer to use a specific constructor when deserializing a class. It can be used to create a class using a parameterized constructor instead of the default constructor, or to pick which specific parameterized constructor to use if there are multiple. + + + +
diff --git a/Doc/doc.content b/Doc/doc.content index 78f3eb47..488e7977 100644 --- a/Doc/doc.content +++ b/Doc/doc.content @@ -30,7 +30,7 @@ - + @@ -67,6 +67,7 @@ + @@ -153,7 +154,7 @@ - + diff --git a/Doc/doc.shfbproj b/Doc/doc.shfbproj index b7fa3ebd..d206408f 100644 --- a/Doc/doc.shfbproj +++ b/Doc/doc.shfbproj @@ -100,6 +100,7 @@ + diff --git a/Src/Newtonsoft.Json.TestConsole/Program.cs b/Src/Newtonsoft.Json.TestConsole/Program.cs index 305b1e56..ebd74129 100644 --- a/Src/Newtonsoft.Json.TestConsole/Program.cs +++ b/Src/Newtonsoft.Json.TestConsole/Program.cs @@ -42,7 +42,7 @@ namespace Newtonsoft.Json.TestConsole { Console.WriteLine("Json.NET Test Console"); - string version = FileVersionInfo.GetVersionInfo(typeof (JsonConvert).Assembly.Location).FileVersion; + string version = FileVersionInfo.GetVersionInfo(typeof(JsonConvert).Assembly.Location).FileVersion; Console.WriteLine("Json.NET Version: " + version); Console.ReadKey(); @@ -58,6 +58,7 @@ namespace Newtonsoft.Json.TestConsole //ReadLargeJsonJavaScriptSerializer(); DiscriminatedUnionConverterTests t = new DiscriminatedUnionConverterTests(); t.SerializePerformance(); + t.DeserializePerformance(); Console.WriteLine(); Console.WriteLine("Finished"); diff --git a/Src/Newtonsoft.Json.TestConsole/Properties/AssemblyInfo.cs b/Src/Newtonsoft.Json.TestConsole/Properties/AssemblyInfo.cs index 0d44e57a..ccd14494 100644 --- a/Src/Newtonsoft.Json.TestConsole/Properties/AssemblyInfo.cs +++ b/Src/Newtonsoft.Json.TestConsole/Properties/AssemblyInfo.cs @@ -57,4 +57,4 @@ using System.Runtime.InteropServices; // You can specify all the values or you can default the Build and Revision Numbers // by using the '*' as shown below: [assembly: AssemblyVersion("7.0.0.0")] -[assembly: AssemblyFileVersion("7.0.1.18503")] +[assembly: AssemblyFileVersion("7.0.1.18610")] diff --git a/Src/Newtonsoft.Json.Tests/Converters/DiscriminatedUnionConverterTests.cs b/Src/Newtonsoft.Json.Tests/Converters/DiscriminatedUnionConverterTests.cs index d7a11f44..d018fd05 100644 --- a/Src/Newtonsoft.Json.Tests/Converters/DiscriminatedUnionConverterTests.cs +++ b/Src/Newtonsoft.Json.Tests/Converters/DiscriminatedUnionConverterTests.cs @@ -101,7 +101,7 @@ namespace Newtonsoft.Json.Tests.Converters Stopwatch ts = new Stopwatch(); ts.Start(); - for (int i = 0; i < 2000; i++) + for (int i = 0; i < 10000; i++) { JsonConvert.SerializeObject(values); } @@ -127,7 +127,7 @@ namespace Newtonsoft.Json.Tests.Converters Stopwatch ts = new Stopwatch(); ts.Start(); - for (int i = 0; i < 2000; i++) + for (int i = 0; i < 10000; i++) { JsonConvert.DeserializeObject>(json); } diff --git a/Src/Newtonsoft.Json.Tests/Documentation/Samples/Serializer/JsonConstructorAttribute.cs b/Src/Newtonsoft.Json.Tests/Documentation/Samples/Serializer/JsonConstructorAttribute.cs new file mode 100644 index 00000000..d8aa935f --- /dev/null +++ b/Src/Newtonsoft.Json.Tests/Documentation/Samples/Serializer/JsonConstructorAttribute.cs @@ -0,0 +1,76 @@ +#region License +// Copyright (c) 2007 James Newton-King +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the "Software"), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or sell +// copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +#endregion + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text; +using Newtonsoft.Json.Converters; +using NUnit.Framework; +using JsonConstructor = Newtonsoft.Json.JsonConstructorAttribute; + +namespace Newtonsoft.Json.Tests.Documentation.Samples.Serializer +{ + [TestFixture] + public class JsonConstructorAttribute : TestFixtureBase + { + #region Types + public class User + { + public string UserName { get; private set; } + public bool Enabled { get; private set; } + + public User() + { + } + + [JsonConstructor] + public User(string userName, bool enabled) + { + UserName = userName; + Enabled = enabled; + } + } + #endregion + + [Test] + public void Example() + { + #region Usage + string json = @"{ + ""UserName"": ""domain\\username"", + ""Enabled"": true + }"; + + User user = JsonConvert.DeserializeObject(json); + + Console.WriteLine(user.UserName); + // domain\username + #endregion + + Assert.AreEqual(@"domain\username", user.UserName); + } + } +} \ No newline at end of file diff --git a/Src/Newtonsoft.Json.Tests/Newtonsoft.Json.Tests.csproj b/Src/Newtonsoft.Json.Tests/Newtonsoft.Json.Tests.csproj index db81190e..39826abe 100644 --- a/Src/Newtonsoft.Json.Tests/Newtonsoft.Json.Tests.csproj +++ b/Src/Newtonsoft.Json.Tests/Newtonsoft.Json.Tests.csproj @@ -170,6 +170,7 @@ Code + diff --git a/Src/Newtonsoft.Json.Tests/Properties/AssemblyInfo.cs b/Src/Newtonsoft.Json.Tests/Properties/AssemblyInfo.cs index 315fbfb6..337b3edd 100644 --- a/Src/Newtonsoft.Json.Tests/Properties/AssemblyInfo.cs +++ b/Src/Newtonsoft.Json.Tests/Properties/AssemblyInfo.cs @@ -76,4 +76,4 @@ using System.Security; // by using the '*' as shown below: [assembly: AssemblyVersion("7.0.0.0")] -[assembly: AssemblyFileVersion("7.0.1.18503")] +[assembly: AssemblyFileVersion("7.0.1.18610")] diff --git a/Src/Newtonsoft.Json/Properties/AssemblyInfo.cs b/Src/Newtonsoft.Json/Properties/AssemblyInfo.cs index 9da0f2f2..fffb2610 100644 --- a/Src/Newtonsoft.Json/Properties/AssemblyInfo.cs +++ b/Src/Newtonsoft.Json/Properties/AssemblyInfo.cs @@ -92,5 +92,5 @@ using System.Security; // by using the '*' as shown below: [assembly: AssemblyVersion("7.0.0.0")] -[assembly: AssemblyFileVersion("7.0.1.18503")] +[assembly: AssemblyFileVersion("7.0.1.18610")] [assembly: CLSCompliant(true)]