[Internal] SystemTextJsonSerializer: Adds STJ Serializer

[kundadebdatta]

Pull Request Template

Description

NOTE: this PR has INTERNAL details for usage please check PR-4589 which explains the steps to use the CosmosSystemTextJsonSerializer publicly by setting UseSystemTextJsonSerializerWithOptions parameter in the CosmosClientOpions for both preview and GA contract. ]

This PR adds a Default System.Text.JSON Implementation for CosmosLinqSerializer. This default serializer can be used along with the CosmosClientOptions to set the runtime serializer. Please take a look at the example below for usage:

        CosmosClientOptions clientOptions = new CosmosClientOptions()
        {
            Serializer = new CosmosDefaultSystemTextJsonSerializer(
                new System.Text.Json.JsonSerializerOptions())
        };

Note that this is just a default implementation which handles the basic scenarios. Any JsonSerializerOptions passed in here may not going to be reflected in SerializeMemberName().

To handle special cases, please create a custom serializer which inherits from the CosmosDefaultSystemTextJsonSerializer and overrides the SerializeMemberName() method to add any special handling.

Below is an example of a custom serializer, which is inherits the CosmosDefaultSystemTextJsonSerializer to cover the special handling for camel case naming property.

    public class CustomSystemTextJsonSerializer : CosmosDefaultSystemTextJsonSerializer
    {
        /// <summary>
        /// Initializes a new instance of the <see cref="CustomSystemTextJsonSerializer "/> class.
        /// </summary>
        /// <param name="jsonSerializerOptions"></param>
        public CustomSystemTextJsonSerializer (JsonSerializerOptions jsonSerializerOptions)
            : base(jsonSerializerOptions)
        {
        }

        /// <inheritdoc/>
        public override string SerializeMemberName(MemberInfo memberInfo)
        {
            System.Text.Json.Serialization.JsonExtensionDataAttribute jsonExtensionDataAttribute =
                memberInfo.GetCustomAttribute<System.Text.Json.Serialization.JsonExtensionDataAttribute>(true);
            if (jsonExtensionDataAttribute != null)
            {
                return null;
            }

            JsonPropertyNameAttribute jsonPropertyNameAttribute = memberInfo.GetCustomAttribute<JsonPropertyNameAttribute>(true);
            if (!string.IsNullOrEmpty(jsonPropertyNameAttribute?.Name))
            {
                return jsonPropertyNameAttribute.Name;
            }

            return System.Text.Json.JsonNamingPolicy.CamelCase.ConvertName(memberInfo.Name);
        }
    }

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)

Closing issues

To automatically close an issue: closes #4330

[adityasa]

🕐

[Arcalise08]

Any update on this PR? It's been a few weeks and this is a much-anticipated change.

[kirankumarkolli]

Any update on this PR? It's been a few weeks and this is a much-anticipated change.

@Arcalise08 due to some reprioritizations this work was paused. We expect it to resume it after 2 weeks.
We will try to opportunistically accelerate its close as soon as possible.

[aavasthy]

👍

[itsawindup]

Forgive me if I am being a bit slow, but since the change from public to internal in commit 1ff1f06, I can't see a way to use this in my own code. Have I missed something obvious?

[bartelink]

@kirankumarkolli @kundadebdatta Please follow up by adding a quick summary as to the final state of play here.
Thousands of people will hit this issue via search, and this saga had lots of twists and turns along the way!

[kirankumarkolli]

@bartelink apologies, we change the usage model towards the end of the PR stage and missed to reflect that in the description.
@kundadebdatta can you please refresh the description.

[kundadebdatta]

@kirankumarkolli @kundadebdatta Please follow up by adding a quick summary as to the final state of play here. Thousands of people will hit this issue via search, and this saga had lots of twists and turns along the way!

Thanks for bringing this up @bartelink ! I have updated the summary to explain how to use this serializer publicly by default. For your reference:

There is a separate PR-4589 which explains the steps to use the CosmosSystemTextJsonSerializer publicly by setting UseSystemTextJsonSerializerWithOptions parameter in the CosmosClientOpions for both preview and GA contract.

I hope this will be helpful! Please feel free to reach out, if you have any questions.

[bartelink]

I guess the problem is that over the years there's been lots of PRs and/or snippets, and it's very easy to land on an issue like this which does not point to a final summary of how it worked out in the end.

I know this PR has [Internal] in the title, but the average person without context won't appreciate what that implies, and will instead focus on the "Adds Default STJ Serializer" part of the title and say "OK, it was merged some time ago and I'm on latest, and I can't see this CosmosDefaultSystemTextJsonSerializer anywhere".

---

So the problem is that someoe scanning even the current overview might conclude that there is a CosmosDefaultSystemTextJsonSerializer. For very good reasons I agree with, that has has wound up not being public. So I guess I was hoping that the last piece of info on this thread (and maybe a prominent note in the overview) could summarise the key points:

• There are two abstract classes in Microsoft.Azure.Cosmos: CosmosSerializer and CosmosLinqSerializer that allow you to customize everything
• Normally you don't want to do that though:

  1. The CosmosDefaultSystemTextJsonSerializer in the overview exists, but it ultimately ended up being internal

  2. But, that's OK - there's a newer API (see SystemTextJsonSerializer: Adds UseSystemTextJsonSerializerWithOptions in CosmosClientOptions to Set the Default STJ Serializer #4589) that provides access by doing

     var opts = new CosmosClientOptions {
         UseSystemTextJsonSerializerWithOptions = System.Text.Json.JsonSerializerOptions.Default };
     

---

Maybe something like this, but written in proper English ;) ?

To apply the CosmosDefaultSystemTextJsonSerializer in the overview of this issue on 3.43.0 or later, you set the value of the CosmosClientOptions.UseSystemTextJsonSerializerWithOptions property to an instance of System.Text.Json.JsonSerializerOptions , e.g.:

 var opts = new CosmosClientOptions { UseSystemTextJsonSerializerWithOptions = System.Text.Json.JsonSerializerOptions.Default };
 var client = new CosmosClient(...., opts);

[kirankumarkolli]

Updated the title to remove default and also the updated PR description to reference the PR which made the contracts public.