-Documentation

2015-06-10 01:16:12 +12:00
parent f4e8c3d2ca
commit 08296c5eca
12 changed files with 120 additions and 16 deletions
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<topic id="JsonConstructorAttribute" revisionNumber="1">
+  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <introduction>
+      <para>This sample uses the
+      <codeEntityReference>T:Newtonsoft.Json.JsonConstructorAttribute</codeEntityReference>
+      to specify that a constrctor should be used to create a class during deserialization.</para>
+    </introduction>
+    <section>
+      <title>Sample</title>
+      <content>
+        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConstructorAttribute.cs" region="Types" title="Types" />
+        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConstructorAttribute.cs" region="Usage" title="Usage" />
+      </content>
+    </section>
+  </developerConceptualDocument>
+</topic>
@@ -16,10 +16,8 @@
        <para>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.</para>
-        <para>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: <codeInline>Manufacturers[0].Name</codeInline>
-        and <codeInline>Manufacturers(0).Name</codeInline>.</para>
+        <para>The path is made up of property names and array indexes separated by periods,
+        e.g. <codeInline>Manufacturers[0].Name</codeInline>.</para>

 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\LinqToJsonTests.cs" region="SelectTokenComplex" title="SelectToken Example" />
      </content>
@@ -12,6 +12,7 @@
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference> - Placed on fields and properties to control how they should be serialized as a property in a JSON object.</para></listItem>
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference> - Placed on either classes or fields and properties to specify which JsonConverter should be used during serialization.</para></listItem>
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonExtensionDataAttribute</codeEntityReference> - Placed on a collection field or property to deserialize properties with no matching class member into the specified collection and write values during serialization.</para></listItem>
+  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonConstructorAttribute</codeEntityReference> - Placed on a constructor to specify that it should be used to create the class during deserialization.</para></listItem>
 </list>

    </introduction>
@@ -99,12 +100,10 @@
        on a field or property, then the specified JsonConverter will always be used to serialize that value.</para>
        <para>The priority of which JsonConverter is used is member attribute, then class attribute, and finally
        any converters passed to the JsonSerializer.</para>
-        
- <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationCallbacksObject" title="JsonConverter Attribute" />
+
+<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConverterAttributeProperty.cs" region="Types" title="JsonConverterAttribute Property Example" />
       
        <para>This example shows the JsonConverterAttribute being applied to a property.</para>
-        
-<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationCallbacksExample" title="JsonConverter Example" />
                
        <para>To apply a JsonConverter to the items in a collection, use either <codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference>,
        <codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference> or
@@ -124,6 +123,16 @@
        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\DeserializeExtensionData.cs" region="Usage" title="Usage" />
      </content>
    </section>
+        
+    <section>
+      <title>JsonConstructorAttribute</title>
+      <content>
+        <para>The <codeEntityReference>T:Newtonsoft.Json.JsonConstructorAttribute</codeEntityReference> instructs the
+        <codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference> 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.</para>
+        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConstructorAttribute.cs" region="Types" title="Types" />
+        <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConstructorAttribute.cs" region="Usage" title="Usage" />
+      </content>
+    </section>
    
    </sections>
    </section>
@@ -30,7 +30,7 @@
  <Topic id="JsonNetVsDotNetSerializers" visible="True" title="Json.NET vs .NET Serializers" />
  <Topic id="JsonNetVsWindowsDataJson" visible="True" title="Json.NET vs Windows.Data.Json" />
  <Topic id="Samples" visible="True" isExpanded="true" title="Samples">
-    <Topic id="d6e185d5-c992-44fc-8d8f-d9acc2bbec2f" visible="True" noFile="true" title="Serializing JSON">
+    <Topic id="d6e185d5-c992-44fc-8d8f-d9acc2bbec2f" visible="True" noFile="true" isExpanded="true" title="Serializing JSON">
      <Topic id="SerializeObject" visible="True" title="Serialize an Object" />
      <Topic id="SerializeCollection" visible="True" title="Serialize a Collection" />
      <Topic id="SerializeDictionary" visible="True" title="Serialize a Dictionary" />
@@ -67,6 +67,7 @@
      <Topic id="CustomContractResolver" visible="True" title="Custom IContractResolver" />
      <Topic id="CustomTraceWriter" visible="True" title="Custom ITraceWriter" />
      <Topic id="SerializeSerializationBinder" visible="True" title="Custom SerializationBinder" />
+      <Topic id="JsonConstructorAttribute" visible="True" isSelected="true" />
      <Topic id="JsonConverterAttributeClass" visible="True" title="JsonConverterAttribute on a class" />
      <Topic id="JsonConverterAttributeProperty" visible="True" title="JsonConverterAttribute on a property" />
      <Topic id="JsonObjectAttributeOptIn" visible="True" title="JsonObjectAttribute opt-in serialization" />
@@ -153,7 +154,7 @@
    <Topic id="ca145ed0-f377-4f1c-9479-d1629082fc6e" visible="True" noFile="true" isExpanded="true" title="Reading and Writing JSON">
      <Topic id="ReadJsonWithJsonTextReader" visible="True" title="Read JSON with JsonTextReader" />
      <Topic id="WriteJsonWithJsonTextWriter" visible="True" title="Write JSON with JsonTextWriter" />
-      <Topic id="ReadMultipleContentWithJsonReader" visible="True" isSelected="true" title="Read Multiple Fragments With JsonReader" />
+      <Topic id="ReadMultipleContentWithJsonReader" visible="True" title="Read Multiple Fragments With JsonReader" />
      <Topic id="CustomJsonReader" visible="True" title="Custom JsonReader" />
      <Topic id="CustomJsonWriter" visible="True" title="Custom JsonWriter" />
    </Topic>
@@ -100,6 +100,7 @@
  </ItemGroup>
  <ItemGroup>
    <Content Include="icons\favicon.ico" />
+    <None Include="Samples\Serializer\JsonConstructorAttribute.aml" />
    <None Include="Samples\Json\ReadMultipleContentWithJsonReader.aml" />
    <None Include="Samples\Serializer\SerializeImmutableCollections.aml" />
    <None Include="Samples\Serializer\SerializeExtensionData.aml" />
@@ -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");
@@ -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")]
@@ -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<List<Shape>>(json);
            }
@@ -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<User>(json);
+
+            Console.WriteLine(user.UserName);
+            // domain\username
+            #endregion
+
+            Assert.AreEqual(@"domain\username", user.UserName);
+        }
+    }
+}
@@ -170,6 +170,7 @@
      <SubType>Code</SubType>
    </Compile>
    <Compile Include="Documentation\Samples\Serializer\DeserializeMetadataPropertyHandling.cs" />
+    <Compile Include="Documentation\Samples\Serializer\JsonConstructorAttribute.cs" />
    <Compile Include="Documentation\Samples\Serializer\SerializeDateFormatString.cs" />
    <Compile Include="Documentation\Samples\Serializer\DeserializeCollection.cs" />
    <Compile Include="Documentation\Samples\Serializer\DeserializeConstructorHandling.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")]
@@ -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)]