Board Review: ObjectSerializer C#

[pakrym]

Extracted from #1454

The Basics

We'd like to add ObjectSerializer abstraction and Syste.Text.Json-based implementation for .NET.

• Service team: The ADP .NET folks
• ApiView: https://apiview.dev/Assemblies/Review/8f2e023e377f4627a4ec815f6e11d013#Azure.Core.ObjectSerializer
• Contact: @pakrym, and @KrzysztofCwalina

Champion Scenarios

We’re introducing a Bring Your Own Serializer model because there a lot of customers who wont come to Track 2 without it. ObjectSerializer is the base abstraction. We’re shipping JsonObjectSerializer : ObjectSerializer to wrap using System.Text.Json. As a customer you’ll still use all the System.Text.Json attributes, naming policies, options, documentation, etc., for your type T. You’ll just tell our client libraries which serializer you’re using via clientOptions.Serializer = new JsonObjectSerializer(new System.Text.Json.JsonSerializerOptions(...)) and we’ll use it for all your custom model types in our clients. You can see more example usage in the tests.

Sample

Using clients with a custom model and default serializer

class MyModel
{
     public string Name { get; }
}

SearchClient client = new SearchClient(new Uri("<endpoint>"), "<index>", new AzureKeyCredential("<key>"));
Response<SearchResults<MyModel>> results = client.Search<MyModel>("search text");

Using clients with a custom model with System.Text.Json attributes and default serializer

class MyModel
{
     [JsonPropertyName("name")]
     public string Name { get; }
}

SearchClient client = new SearchClient(new Uri("<endpoint>"), "<index>", new AzureKeyCredential("<key>"));
// client.Search<MyModel> would deserialize `Name` property from `name` JSON property.
Response<SearchResults<MyModel>> results = client.Search<MyModel>("search text");

Using clients with a custom model with customized default serializer

class MyModel
{
     public string Name { get; }
}

var searchClientOptions = new SearchClientOptions();

// configure the serializer
searchClientOptions.ObjectSerializer = new JsonObjectSerializer(new JsonSerializerOptions()
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
});

SearchClient client = new SearchClient(new Uri("<endpoint>"), "<index>", new AzureKeyCredential("<key>"), searchClientOptions);

// client.Search<MyModel> would deserialize `Name` property from `name` JSON property (because of naming policy).
Response<SearchResults<MyModel>> results = client.Search<MyModel>("search text");

Using clients with a custom model with Newtonsoft.Json serializer

// Existing customer model from Track 1 library
class MyModel
{
     // Newtonsoft-specific attribute
     [JsonProperty("name")]
     public string Name { get; }
}

var searchClientOptions = new SearchClientOptions();

// configure the serializer
// NOTE: we don't ship NewtonsoftJsonObjectSerializer yet
searchClientOptions.ObjectSerializer = new NewtonsoftJsonObjectSerializer();

SearchClient client = new SearchClient(new Uri("<endpoint>"), "<index>", new AzureKeyCredential("<key>"), searchClientOptions);

// client.Search<MyModel> would deserialize `Name` property from `name` JSON property (because NewtonsoftJsonObjectSerializer knows about it).
Response<SearchResults<MyModel>> results = client.Search<MyModel>("search text");

[pakrym]

C# API Approved by @KrzysztofCwalina post review-board review.

[ramya-rao-a]

@bterlson, @johanste, @JonathanGiles,

We won't be having a separate meeting to review this API.
Since it is already been approved by the .Net architect @KrzysztofCwalina, can the rest of you take a look and provide your approval if you have no concerns with the proposed design?

Please note that this is being shipped in less than 2 weeks

[ramya-rao-a]

cc @annatisch, @srnagar, @xirzec

[JonathanGiles]

What level of confidence is there that this API will be sufficient to also support JSON.net?

[pakrym]

We have an implementation. The level of confidence is high.

[johanste]

I have no concerns about the C# design.

[bterlson]

I also have no concerns about the C# design.