Skip to content

Commit e04f006

Browse files
heathsheaths
authored
Prepare release of Azure.Core JSON helpers (Azure#17820)
* Prepare release of Azure.Core JSON helpers * Update CHANGELOGs * Resolve PR feedback
1 parent e886521 commit e04f006

File tree

12 files changed

+219
-22
lines changed

12 files changed

+219
-22
lines changed

‎sdk/core/Microsoft.Azure.Core.NewtonsoftJson/CHANGELOG.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# Release History
22

3-
## 1.0.0-preview.2 (2020-11-10)
3+
## 1.0.0 (2021-01-06)
44

55
### Added
6-
- `Newtonsoft.Json.JsonConverter` implementation for the `ETag`
76

7+
- `Newtonsoft.Json.JsonConverter` implementation for the `ETag`
88

99
## 1.0.0-preview.1 (2020-08-07)
1010

‎sdk/core/Microsoft.Azure.Core.NewtonsoftJson/README.md‎

Lines changed: 88 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,35 +5,107 @@ This library contains converters dependent on the [Newtonsoft.Json package][newt
55

66
## Getting started
77

8-
TODO
8+
Install this package if you want to use Newtonsoft.Json to serialize and deserialize model types with some Azure SDKs.
99

1010
### Install the package
1111

12-
TODO
12+
Install this package from [NuGet] using the .NET CLI:
1313

14-
### Prerequisites
14+
```bash
15+
dotnet add package Microsoft.Azure.Core.NewtonsoftJson
16+
```
1517

16-
TODO
18+
## Key concepts
1719

18-
### Authenticate the client
20+
This support package contains the `NewtonsoftJsonObjectSerializer` class which can be passed to some Azure SDKs' client options classes, as shown in the examples below.
1921

20-
TODO
22+
The following converters are added automatically to the `NewtonsoftJsonObjectSerializer` if you do not pass your own `JsonSerializerSettings`:
2123

22-
## Key concepts
24+
- `NewtonsoftJsonETagConverter` to convert `Azure.ETag` properties.
2325

24-
TODO
26+
See the example [Using default converters](#using-default-converters) below for getting an instance of `JsonSerializerSettings` with this default list you can then modify as needed.
2527

2628
## Examples
2729

28-
TODO
30+
The [Azure.Search.Documents package][azure_search_documents_package] is used in examples to show how search results can be deserialized. For more information and examples using Azure.Search.Documents, see its [README][azure_search_documents_readme].
31+
32+
### Deserializing models
33+
34+
Consider a model class containing information about movies:
35+
36+
```C# Snippet:Microsoft_Azure_Core_NewtonsoftJson_Samples_Readme_Model
37+
public class Movie
38+
{
39+
[JsonProperty("uuid")]
40+
public string Id { get; private set; } = Guid.NewGuid().ToString();
41+
42+
public string Title { get; set; }
43+
44+
public string Description { get; set; }
45+
46+
public float Rating { get; set; }
47+
}
48+
```
49+
50+
Our Azure Cognitive Search index is defined using camelCase fields, and the `Id` field is actually defined as "uuid"; however, we can provide an idiomatic model without having to attribute all properties by setting the `JsonSerializerSettings.ContractResolver` property as shown below:
51+
52+
```C# Snippet:Microsoft_Azure_Core_NewtonsoftJson_Samples_Readme_SearchSample
53+
// Get the Azure Cognitive Search endpoint and read-only API key.
54+
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
55+
AzureKeyCredential credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
56+
57+
// Create serializer options with default converters for Azure SDKs.
58+
JsonSerializerSettings serializerSettings = NewtonsoftJsonObjectSerializer.CreateJsonSerializerSettings();
59+
60+
// Serialize property names using camelCase by default.
61+
serializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
62+
63+
SearchClientOptions clientOptions = new SearchClientOptions
64+
{
65+
Serializer = new NewtonsoftJsonObjectSerializer(serializerSettings)
66+
};
67+
68+
SearchClient client = new SearchClient(endpoint, "movies", credential, clientOptions);
69+
Response<SearchResults<Movie>> results = client.Search<Movie>("Return of the King");
70+
71+
foreach (SearchResult<Movie> result in results.Value.GetResults())
72+
{
73+
Movie movie = result.Document;
74+
75+
Console.WriteLine(movie.Title);
76+
Console.WriteLine(movie.Description);
77+
Console.WriteLine($"Rating: {movie.Rating}\n");
78+
}
79+
```
80+
81+
If searching an index full of movies, the following may be printed:
82+
83+
```text
84+
The Lord of the Rings: The Return of the King
85+
Gandalf and Aragorn lead the World of Men against Sauron's army to draw his gaze from Frodo and Sam as they approach Mount Doom with the One Ring.
86+
Rating: 9.1
87+
```
88+
89+
### Using default converters
90+
91+
If you instantiate a `NewtonsoftJsonObjectSerializer` using the default constructor, some converters for common Azure SDKs are added automatically as listed above in [Key concepts](#key-concepts). To modify these default settings, you can create a new `JsonSerializerSettings` like in the following example:
92+
93+
```C# Snippet:Microsoft_Azure_Core_NewtonsoftJson_Samples_Readme_DefaultSerializerSettings
94+
JsonSerializerSettings serializerSettings = NewtonsoftJsonObjectSerializer.CreateJsonSerializerSettings();
2995

30-
## Troubleshooting
96+
// Serialize property names using camelCase by default.
97+
serializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
3198

32-
TODO
99+
// Add converters as needed, for example, to convert movie genres to an enum.
100+
serializerSettings.Converters.Add(new StringEnumConverter());
33101

34-
## Next steps
102+
SearchClientOptions clientOptions = new SearchClientOptions
103+
{
104+
Serializer = new NewtonsoftJsonObjectSerializer(serializerSettings)
105+
};
106+
```
35107

36-
TODO
108+
You can add or remove converters, set the `ContractResolver`, or any other members of `JsonSerializerSettings` you need.
37109

38110
## Contributing
39111

@@ -46,6 +118,9 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
46118
![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Fcore%2FMicrosoft.Azure.Core.NewtonsoftJson%2FREADME.png)
47119

48120
[azure_core_package]: https://www.nuget.org/packages/Azure.Core/
121+
[azure_search_documents_package]: https://www.nuget.org/packages/Azure.Search.Documents/
122+
[azure_search_documents_readme]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/search/Azure.Search.Documents/README.md
49123
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct
50124
[code_of_conduct_faq]: https://opensource.microsoft.com/codeofconduct/faq/
51125
[newtonsoft_json_package]: https://www.nuget.org/packages/Newtonsoft.Json/
126+
[NuGet]: https://www.nuget.org

‎sdk/core/Microsoft.Azure.Core.NewtonsoftJson/src/Microsoft.Azure.Core.NewtonsoftJson.csproj‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<PropertyGroup>
33
<AssemblyTitle>Newtonsoft.Json support for Azure Core shared client library for .NET</AssemblyTitle>
44
<RootNamespace>Azure.Core.Serialization</RootNamespace>
5-
<Version>1.0.0-preview.2</Version>
5+
<Version>1.0.0</Version>
66
<Description>This library contains converters dependent on the Newtonsoft.Json package for use with Azure.Core.</Description>
77
<PackageTags>Microsoft Azure SDK Newtonsoft Json</PackageTags>
88
<Nullable>enable</Nullable>

‎sdk/core/Microsoft.Azure.Core.NewtonsoftJson/src/NewtonsoftJsonObjectSerializer.cs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,10 @@ public NewtonsoftJsonObjectSerializer() : this(CreateJsonSerializerSettings())
4242
public static JsonSerializerSettings CreateJsonSerializerSettings()
4343
{
4444
var settings = new JsonSerializerSettings();
45+
46+
// NOTE: Update the README when converters are added by default.
4547
settings.Converters.Add(new NewtonsoftJsonETagConverter());
48+
4649
return settings;
4750
}
4851

‎sdk/core/Microsoft.Azure.Core.NewtonsoftJson/tests/Microsoft.Azure.Core.NewtonsoftJson.Tests.csproj‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,15 @@
55
</PropertyGroup>
66

77
<ItemGroup>
8+
<PackageReference Include="Azure.Search.Documents" />
89
<PackageReference Include="Microsoft.NET.Test.Sdk" />
910
<PackageReference Include="Newtonsoft.Json" />
1011
<PackageReference Include="NUnit" />
1112
<PackageReference Include="NUnit3TestAdapter" />
1213
</ItemGroup>
1314

1415
<ItemGroup>
16+
<ProjectReference Include="$(AzureCoreTestFramework)" />
1517
<ProjectReference Include="..\src\Microsoft.Azure.Core.NewtonsoftJson.csproj" />
1618
</ItemGroup>
1719
</Project>

‎sdk/core/Microsoft.Azure.Core.NewtonsoftJson/tests/Samples/Readme.cs‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
// Copyright (c) Microsoft Corporation. All rights reserved.
2+
// Licensed under the MIT License.
3+
4+
using System;
5+
using System.Linq;
6+
using Azure;
7+
using Azure.Core.Serialization;
8+
using Azure.Core.TestFramework;
9+
using Azure.Search.Documents;
10+
using Azure.Search.Documents.Indexes;
11+
using Azure.Search.Documents.Indexes.Models;
12+
using Azure.Search.Documents.Models;
13+
using Newtonsoft.Json;
14+
using Newtonsoft.Json.Converters;
15+
using Newtonsoft.Json.Serialization;
16+
using NUnit.Framework;
17+
18+
namespace Microsoft.Azure.Core.NewtonsoftJson.Tests.Samples
19+
{
20+
public class Readme
21+
{
22+
[Test]
23+
public void SearchSample()
24+
{
25+
MockResponse response = new MockResponse(200);
26+
response.SetContent(@"{
27+
""value"": [
28+
{
29+
""@search.score"": 1.0,
30+
""uuid"": ""efe8857f-1d74-41e2-9ff1-4943a9ad69d5"",
31+
""title"": ""The Lord of the Rings: The Return of the King"",
32+
""description"": ""Gandalf and Aragorn lead the World of Men against Sauron's army to draw his gaze from Frodo and Sam as they approach Mount Doom with the One Ring."",
33+
""rating"": 9.1
34+
}
35+
]
36+
}");
37+
38+
Environment.SetEnvironmentVariable("SEARCH_ENDPOINT", "https://sample.search.windows.net");
39+
Environment.SetEnvironmentVariable("SEARCH_API_KEY", "sample");
40+
41+
#region Snippet:Microsoft_Azure_Core_NewtonsoftJson_Samples_Readme_SearchSample
42+
// Get the Azure Cognitive Search endpoint and read-only API key.
43+
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
44+
AzureKeyCredential credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
45+
46+
// Create serializer options with default converters for Azure SDKs.
47+
JsonSerializerSettings serializerSettings = NewtonsoftJsonObjectSerializer.CreateJsonSerializerSettings();
48+
49+
// Serialize property names using camelCase by default.
50+
serializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
51+
52+
SearchClientOptions clientOptions = new SearchClientOptions
53+
{
54+
/*@@*/ Transport = new MockTransport(response),
55+
Serializer = new NewtonsoftJsonObjectSerializer(serializerSettings)
56+
};
57+
58+
SearchClient client = new SearchClient(endpoint, "movies", credential, clientOptions);
59+
Response<SearchResults<Movie>> results = client.Search<Movie>("Return of the King");
60+
61+
foreach (SearchResult<Movie> result in results.Value.GetResults())
62+
{
63+
Movie movie = result.Document;
64+
65+
Console.WriteLine(movie.Title);
66+
Console.WriteLine(movie.Description);
67+
Console.WriteLine($"Rating: {movie.Rating}\n");
68+
}
69+
#endregion Snippet:Microsoft_Azure_Core_NewtonsoftJson_Samples_Readme_SearchSample
70+
71+
Movie _movie = results.Value.GetResults().Single().Document;
72+
Assert.AreEqual("efe8857f-1d74-41e2-9ff1-4943a9ad69d5", _movie.Id);
73+
Assert.AreEqual("The Lord of the Rings: The Return of the King", _movie.Title);
74+
Assert.AreEqual("Gandalf and Aragorn lead the World of Men against Sauron's army to draw his gaze from Frodo and Sam as they approach Mount Doom with the One Ring.", _movie.Description);
75+
Assert.AreEqual(9.1, _movie.Rating, 0.01);
76+
}
77+
78+
[Test]
79+
public void DefaultSerializerSettings()
80+
{
81+
#region Snippet:Microsoft_Azure_Core_NewtonsoftJson_Samples_Readme_DefaultSerializerSettings
82+
JsonSerializerSettings serializerSettings = NewtonsoftJsonObjectSerializer.CreateJsonSerializerSettings();
83+
84+
// Serialize property names using camelCase by default.
85+
serializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
86+
87+
// Add converters as needed, for example, to convert movie genres to an enum.
88+
serializerSettings.Converters.Add(new StringEnumConverter());
89+
90+
SearchClientOptions clientOptions = new SearchClientOptions
91+
{
92+
Serializer = new NewtonsoftJsonObjectSerializer(serializerSettings)
93+
};
94+
#endregion Snippet:Microsoft_Azure_Core_NewtonsoftJson_Samples_Readme_DefaultSerializerSettings
95+
96+
Assert.AreEqual(2, serializerSettings.Converters.Count);
97+
Assert.That(serializerSettings.Converters, Has.Some.TypeOf(typeof(NewtonsoftJsonETagConverter)));
98+
Assert.That(serializerSettings.Converters, Has.Some.TypeOf(typeof(StringEnumConverter)));
99+
}
100+
101+
#region Snippet:Microsoft_Azure_Core_NewtonsoftJson_Samples_Readme_Model
102+
public class Movie
103+
{
104+
[JsonProperty("uuid")]
105+
public string Id { get; private set; } = Guid.NewGuid().ToString();
106+
107+
public string Title { get; set; }
108+
109+
public string Description { get; set; }
110+
111+
public float Rating { get; set; }
112+
}
113+
#endregion Snippet:Microsoft_Azure_Core_NewtonsoftJson_Samples_Readme_Model
114+
}
115+
}

‎sdk/core/Microsoft.Azure.Core.Spatial.NewtonsoftJson/CHANGELOG.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# Release History
22

3-
## 1.0.0-beta.2 (Unreleased)
3+
## 1.0.0 (2021-01-06)
44

5+
Released.
56

67
## 1.0.0-beta.1 (2020-10-08)
78

‎sdk/core/Microsoft.Azure.Core.Spatial.NewtonsoftJson/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Install this package if you use the Microsoft.Spatial package in your applicatio
1111
Install this package from [NuGet] using the .NET CLI:
1212

1313
```bash
14-
dotnet add package Microsoft.Azure.Core.Spatial.NewtonsoftJson --version 1.0.0-beta.1
14+
dotnet add package Microsoft.Azure.Core.Spatial.NewtonsoftJson
1515
```
1616

1717
## Key concepts

‎sdk/core/Microsoft.Azure.Core.Spatial.NewtonsoftJson/src/Microsoft.Azure.Core.Spatial.NewtonsoftJson.csproj‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<AssemblyTitle>Newtonsoft.Json support for the Microsoft.Spatial library</AssemblyTitle>
44
<Description>This library contains converters dependent on the Newtonsoft.Json package for use with Microsoft.Spatial when using the Azure SDK for .NET.</Description>
55
<RootNamespace>Azure.Core.Serialization</RootNamespace>
6-
<Version>1.0.0-beta.2</Version>
6+
<Version>1.0.0</Version>
77
<PackageTags>Microsoft Azure SDK Spatial Newtonsoft Json</PackageTags>
88
<TargetFrameworks>$(RequiredTargetFrameworks)</TargetFrameworks>
99
<EnableClientSdkAnalyzers>false</EnableClientSdkAnalyzers>

‎sdk/core/Microsoft.Azure.Core.Spatial/CHANGELOG.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# Release History
22

3-
## 1.0.0-beta.2 (Unreleased)
3+
## 1.0.0 (2021-01-06)
44

5+
Released.
56

67
## 1.0.0-beta.1 (2020-10-08)
78

0 commit comments

Comments
 (0)