Skip to content

Commit

Permalink
Merge branch 'docs'
Browse files Browse the repository at this point in the history
  • Loading branch information
JamesNK committed Jun 28, 2016
2 parents e5ac9a8 + 146e582 commit 98678eb
Show file tree
Hide file tree
Showing 15 changed files with 559 additions and 6 deletions.
2 changes: 1 addition & 1 deletion Build/build.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
$packageId = "Newtonsoft.Json"
$signAssemblies = $false
$signKeyPath = "C:\Development\Releases\newtonsoft.snk"
$buildDocumentation = $false
$buildDocumentation = $true
$buildNuGet = $true
$treatWarningsAsErrors = $false
$workingName = if ($workingName) {$workingName} else {"Working"}
Expand Down
16 changes: 16 additions & 0 deletions Doc/Samples/Serializer/NamingStrategyAttributes.aml
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="NamingStrategyAttributes" 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 <codeEntityReference>T:Newtonsoft.Json.Serialization.NamingStrategy</codeEntityReference>
types specified on attributes to control serialized property names.</para>
</introduction>
<section>
<title>Sample</title>
<content>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\NamingStrategyAttributes.cs" region="Types" title="Types" />
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\NamingStrategyAttributes.cs" region="Usage" title="Usage" />
</content>
</section>
</developerConceptualDocument>
</topic>
16 changes: 16 additions & 0 deletions Doc/Samples/Serializer/NamingStrategyCamelCase.aml
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="NamingStrategyCamelCase" 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 a <codeEntityReference>T:Newtonsoft.Json.Serialization.CamelCaseNamingStrategy</codeEntityReference>
specified using a contract resolver to camel case serialized property names.</para>
</introduction>
<section>
<title>Sample</title>
<content>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\NamingStrategyCamelCase.cs" region="Types" title="Types" />
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\NamingStrategyCamelCase.cs" region="Usage" title="Usage" />
</content>
</section>
</developerConceptualDocument>
</topic>
16 changes: 16 additions & 0 deletions Doc/Samples/Serializer/NamingStrategySkipDictionaryKeys.aml
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="NamingStrategySkipDictionaryKeys" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>This sample configures a <codeEntityReference>T:Newtonsoft.Json.Serialization.CamelCaseNamingStrategy</codeEntityReference>
to not camel case dictionary keys.</para>
</introduction>
<section>
<title>Sample</title>
<content>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\NamingStrategySkipDictionaryKeys.cs" region="Types" title="Types" />
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\NamingStrategySkipDictionaryKeys.cs" region="Usage" title="Usage" />
</content>
</section>
</developerConceptualDocument>
</topic>
16 changes: 16 additions & 0 deletions Doc/Samples/Serializer/NamingStrategySkipSpecifiedNames.aml
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="NamingStrategySkipSpecifiedNames" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>This sample configures a <codeEntityReference>T:Newtonsoft.Json.Serialization.CamelCaseNamingStrategy</codeEntityReference>
to not camel case properties that already have a name specified with an attribute.</para>
</introduction>
<section>
<title>Sample</title>
<content>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\NamingStrategySkipSpecifiedNames.cs" region="Types" title="Types" />
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\NamingStrategySkipSpecifiedNames.cs" region="Usage" title="Usage" />
</content>
</section>
</developerConceptualDocument>
</topic>
16 changes: 16 additions & 0 deletions Doc/Samples/Serializer/NamingStrategySnakeCase.aml
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="NamingStrategySnakeCase" 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 a <codeEntityReference>T:Newtonsoft.Json.Serialization.SnakeCaseNamingStrategy</codeEntityReference>
specified using a contract resolver to snake case serialized property names.</para>
</introduction>
<section>
<title>Sample</title>
<content>
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\NamingStrategySnakeCase.cs" region="Types" title="Types" />
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\NamingStrategySnakeCase.cs" region="Usage" title="Usage" />
</content>
</section>
</developerConceptualDocument>
</topic>
3 changes: 3 additions & 0 deletions Doc/SerializationAttributes.aml
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@
(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 behavior) or
fields (all public and private fields are serialized and properties are ignored).</para>
<para>The NamingStrategy setting on this attributes can be set to a <codeEntityReference>T:Newtonsoft.Json.Serialization.NamingStrategy</codeEntityReference>
type that specifies how property names are serialized.</para>
<para>Json.NET serializes .NET classes that implement IEnumerable as a JSON array populated with the
IEnumerable values. Placing the <codeEntityReference>T:Newtonsoft.Json.JsonObjectAttribute</codeEntityReference>
overrides this behavior and forces the serializer to serialize the class's fields and properties.</para>
Expand Down Expand Up @@ -77,6 +79,7 @@
<listItem><para>JsonPropertyAttribute indicates that a property should be serialized when member serialization is set to opt-in.</para></listItem>
<listItem><para>It includes non-public properties in serialization and deserialization.</para></listItem>
<listItem><para>It can be used to customize type name, reference, null, and default value handling for the property value.</para></listItem>
<listItem><para>It can be used to customize the <codeEntityReference>T:Newtonsoft.Json.Serialization.NamingStrategy</codeEntityReference> of the serialized property name.</para></listItem>
<listItem><para>It can be used to customize the property's collection items JsonConverter, type name handling, and reference handling.</para></listItem>
</list>

Expand Down
13 changes: 9 additions & 4 deletions Doc/doc.content
Original file line number Diff line number Diff line change
Expand Up @@ -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" />
Expand Down Expand Up @@ -72,6 +72,7 @@
<Topic id="JsonConverterAttributeProperty" visible="True" title="JsonConverterAttribute on a property" />
<Topic id="JsonObjectAttributeOptIn" visible="True" title="JsonObjectAttribute opt-in serialization" />
<Topic id="JsonObjectAttributeOverrideIEnumerable" visible="True" title="JsonObjectAttribute force object serialization" />
<Topic id="NamingStrategyAttributes" visible="True" isSelected="true" title="JsonObjectAttribute NamingStrategy setting" />
<Topic id="JsonPropertyName" visible="True" title="JsonPropertyAttribute name" />
<Topic id="JsonPropertyOrder" visible="True" title="JsonPropertyAttribute order" />
<Topic id="JsonPropertyRequired" visible="True" title="JsonPropertyAttribute required" />
Expand All @@ -90,8 +91,12 @@
<Topic id="DeserializeExtensionData" visible="True" title="Deserialize ExtensionData" />
<Topic id="DeserializeDateFormatString" visible="True" title="Deserialize DateFormatString" />
<Topic id="SerializeDateFormatString" visible="True" title="Serialize DateFormatString" />
<Topic id="NamingStrategyCamelCase" visible="True" title="Camel case property names" />
<Topic id="NamingStrategySnakeCase" visible="True" title="Snake case property names" />
<Topic id="NamingStrategySkipDictionaryKeys" visible="True" title="Configure NamingStrategy dictionary serialiation" />
<Topic id="NamingStrategySkipSpecifiedNames" visible="True" title="Configure NamingStrategy property name serialization" />
</Topic>
<Topic id="68b9fad2-5436-4e35-a734-9b9d751cc3e5" visible="True" noFile="true" isExpanded="true" title="LINQ to JSON">
<Topic id="68b9fad2-5436-4e35-a734-9b9d751cc3e5" visible="True" noFile="true" title="LINQ to JSON">
<Topic id="CreateJsonManually" visible="True" title="Create JSON manually" />
<Topic id="CreateJsonCollectionInitializer" visible="True" title="Create JSON using Collection Initializers" />
<Topic id="CreateJsonDeclaratively" visible="True" title="Create JSON declaratively with LINQ" />
Expand All @@ -110,7 +115,7 @@
<Topic id="QueryJsonDynamic" visible="True" title="Querying JSON with dynamic" />
<Topic id="QueryJsonLinq" visible="True" title="Querying JSON with LINQ" />
<Topic id="QueryJsonSelectToken" visible="True" title="Querying JSON with SelectToken" />
<Topic id="QueryJsonSelectTokenEscaped" visible="True" isSelected="true" title="Querying JSON with SelectToken and escaped properties" />
<Topic id="QueryJsonSelectTokenEscaped" visible="True" title="Querying JSON with SelectToken and escaped properties" />
<Topic id="QueryJsonSelectTokenWithLinq" visible="True" title="Querying JSON with SelectToken and LINQ" />
<Topic id="QueryJsonSelectTokenJsonPath" visible="True" title="Querying JSON with JSONPath" />
<Topic id="ReadJson" visible="True" title="Read JSON from a file" />
Expand Down Expand Up @@ -152,7 +157,7 @@
<Topic id="DeserializeFromBson" visible="True" title="Deserialize from BSON" />
<Topic id="DeserializeFromBsonCollection" visible="True" title="Deserialize a Collection from BSON" />
</Topic>
<Topic id="ca145ed0-f377-4f1c-9479-d1629082fc6e" visible="True" noFile="true" isExpanded="true" title="Reading and Writing JSON">
<Topic id="ca145ed0-f377-4f1c-9479-d1629082fc6e" visible="True" noFile="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" title="Read Multiple Fragments With JsonReader" />
Expand Down
7 changes: 6 additions & 1 deletion Doc/doc.shfbproj
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
<SchemaVersion>2.0</SchemaVersion>
<ProjectGuid>{fd19f68e-72c8-4576-9775-b4480b0db686}</ProjectGuid>
<SHFBSchemaVersion>1.9.9.0</SHFBSchemaVersion>
<SHFBSchemaVersion>2015.6.5.0</SHFBSchemaVersion>
<!-- AssemblyName, Name, and RootNamespace are not used by SHFB but Visual
Studio adds them anyway -->
<AssemblyName>Documentation</AssemblyName>
Expand Down Expand Up @@ -100,6 +100,11 @@
</ItemGroup>
<ItemGroup>
<Content Include="icons\favicon.ico" />
<None Include="Samples\Serializer\NamingStrategyAttributes.aml" />
<None Include="Samples\Serializer\NamingStrategySnakeCase.aml" />
<None Include="Samples\Serializer\NamingStrategySkipSpecifiedNames.aml" />
<None Include="Samples\Serializer\NamingStrategySkipDictionaryKeys.aml" />
<None Include="Samples\Serializer\NamingStrategyCamelCase.aml" />
<None Include="Samples\Linq\QueryJsonSelectTokenEscaped.aml" />
<None Include="Samples\Serializer\JsonConstructorAttribute.aml" />
<None Include="Samples\Json\ReadMultipleContentWithJsonReader.aml" />
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
#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.Text;
using Newtonsoft.Json.Converters;
using Newtonsoft.Json.Serialization;
#if DNXCORE50
using Xunit;
using Test = Xunit.FactAttribute;
using Assert = Newtonsoft.Json.Tests.XUnitAssert;
#else
using NUnit.Framework;
#endif

namespace Newtonsoft.Json.Tests.Documentation.Samples.Serializer
{
[TestFixture]
public class NamingStrategyAttributes : TestFixtureBase
{
#region Types
[JsonObject(NamingStrategyType = typeof(CamelCaseNamingStrategy))]
public class User
{
public string FirstName { get; set; }
public string LastName { get; set; }
[JsonProperty(NamingStrategyType = typeof(SnakeCaseNamingStrategy))]
public int SnakeRating { get; set; }
}
#endregion

[Test]
public void Example()
{
#region Usage
User user = new User
{
FirstName = "Tom",
LastName = "Riddle",
SnakeRating = 10
};

string json = JsonConvert.SerializeObject(user, Formatting.Indented);

Console.WriteLine(json);
// {
// "firstName": "Tom",
// "lastName": "Riddle",
// "snake_rating": 10
// }
#endregion

StringAssert.AreEqual(@"{
""firstName"": ""Tom"",
""lastName"": ""Riddle"",
""snake_rating"": 10
}", json);
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
#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.Text;
using Newtonsoft.Json.Converters;
using Newtonsoft.Json.Serialization;
#if DNXCORE50
using Xunit;
using Test = Xunit.FactAttribute;
using Assert = Newtonsoft.Json.Tests.XUnitAssert;
#else
using NUnit.Framework;
#endif

namespace Newtonsoft.Json.Tests.Documentation.Samples.Serializer
{
[TestFixture]
public class NamingStrategyCamelCase : TestFixtureBase
{
#region Types
public class User
{
public string UserName { get; set; }
public bool Enabled { get; set; }
}
#endregion

[Test]
public void Example()
{
#region Usage
User user1 = new User
{
UserName = "jamesn",
Enabled = true
};

DefaultContractResolver contractResolver = new DefaultContractResolver
{
NamingStrategy = new CamelCaseNamingStrategy()
};

string json = JsonConvert.SerializeObject(user1, new JsonSerializerSettings
{
ContractResolver = contractResolver,
Formatting = Formatting.Indented
});

Console.WriteLine(json);
// {
// "userName": "jamesn",
// "enabled": true
// }
#endregion

StringAssert.AreEqual(@"{
""userName"": ""jamesn"",
""enabled"": true
}", json);
}
}
}
Loading

0 comments on commit 98678eb

Please sign in to comment.