Adding "Registering custom System.Text.Json converters"

Author: stevejgordon

docs/client-concepts/serialization/custom-serialization.asciidoc

@@ -3,7 +3,7 @@
 
 The built-in source serializer handles most POCO document models correctly. Sometimes, you may need further control over how your types are serialized.
 
-NOTE: The built-in source serializer uses the Microsoft https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/overview[`System.Text.Json` library] internally. You can apply `System.Text.Json` attributes and converters to control serialization of your document types.
+NOTE: The built-in source serializer uses the https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/overview[Microsoft `System.Text.Json` library] internally. You can apply `System.Text.Json` attributes and converters to control the serialization of your document types.
 
 [[system-text-json-attributes]]
 ===== Using `System.Text.Json` attributes
@@ -17,8 +17,8 @@ We can model a document to represent data about a person using a regular class (
 include::{doc-tests-src}/ClientConcepts/Serialization/CustomSerializationTests.cs[tag=usings-serialization]
 include::{doc-tests-src}/ClientConcepts/Serialization/CustomSerializationTests.cs[tag=person-class-with-attributes]
 ----
-<1> The `JsonPropertyName` attribute is used to ensure the `FirstName` property uses the JSON property name `forename` when serialized.
-<2> The `JsonIgnore` attribute is used to prevent the `Age` property from appearing in the serialized JSON.
+<1> The `JsonPropertyName` attribute ensures the `FirstName` property uses the JSON name `forename` when serialized.
+<2> The `JsonIgnore` attribute prevents the `Age` property from appearing in the serialized JSON.
 
 We can then index an instance of the document into {es}.
 
@@ -37,15 +37,10 @@ The index request is serialized, with the source serializer handling the `Person
 }
 ----
 
-[[registering-custom-converters]]
-===== Registering custom `System.Text.Json` converters
-
-TODO
-
 [[configuring-custom-jsonserializeroptions]]
 ===== Configuring custom `JsonSerializerOptions`
 
-The default source serializer applies a set of standard `JsonSerializerOptions` when serializing source document types. In some circumstances, you may wish to override some of our defaults. This is possible by creating an instance of `DefaultSourceSerializer` and passing an `Action<JsonSerializerOptions>` which is applied after our defaults have been set. This mechanism allows you to apply additional settings, or change the value of our defaults.
+The default source serializer applies a set of standard `JsonSerializerOptions` when serializing source document types. In some circumstances, you may need to override some of our defaults. This is achievable by creating an instance of `DefaultSourceSerializer` and passing an `Action<JsonSerializerOptions>`, which is applied after our defaults have been set. This mechanism allows you to apply additional settings or change the value of our defaults.
 
 The `DefaultSourceSerializer` includes a constructor that accepts the current `IElasticsearchClientSettings` and a `configureOptions` `Action`.
 
@@ -61,7 +56,7 @@ Our application defines the following `Person` class, which models a document we
 include::{doc-tests-src}/ClientConcepts/Serialization/CustomSerializationTests.cs[tag=person-class]
 ----
 
-We want to serialize our source document using Pascal Casing for the JSON properties. Since the options applied in the `DefaultSouceSerializer` set the `PropertyNamingPolicy` to `JsonNamingPolicy.CamelCase`, we must override this setting.
+We want to serialize our source document using Pascal Casing for the JSON properties. Since the options applied in the `DefaultSouceSerializer` set the `PropertyNamingPolicy` to `JsonNamingPolicy.CamelCase`, we must override this setting. After configuring the `ElasticsearchClientSettings`, we index our document to {es}.
 
 [source,csharp]
 ----
@@ -92,6 +87,49 @@ As an alternative to using a local function, we could store an `Action<JsonSeria
 include::{doc-tests-src}/ClientConcepts/Serialization/CustomSerializationTests.cs[tag=custom-options-action]
 ----
 
+[[registering-custom-converters]]
+===== Registering custom `System.Text.Json` converters
+
+In certain more advanced situations, you may have types which require further customization during serialization than is possible using `System.Text.Json` property attributes. In these cases, the recommendation from Microsoft is to leverage a custom `JsonConverter`. Source document types serialized using the  `DefaultSourceSerializer` can leverage the power of custom converters.
+
+For this example, our application has a document class that should use a legacy JSON structure to continue operating with existing indexed documents. Several options are available, but we'll apply a custom converter in this case.
+
+Our class is defined, and the `JsonConverter` attribute is applied to the class type, specifying the type of a custom converter.
+
+[source,csharp]
+----
+include::{doc-tests-src}/ClientConcepts/Serialization/CustomSerializationTests.cs[tag=usings-serialization]
+include::{doc-tests-src}/ClientConcepts/Serialization/CustomSerializationTests.cs[tag=customer-with-jsonconverter-attribute]
+----
+<1> The `JsonConverter` attribute signals to `System.Text.Json` that it should use a converter of type `CustomerConverter` when serializing instances of this class.
+
+When serializing this class, rather than include a string value representing the value of the `CustomerType` property, we must send a boolean property named `isStandard`. This requirement can be achieved with a custom JsonConverter implementation.
+
+[source,csharp]
+----
+include::{doc-tests-src}/ClientConcepts/Serialization/CustomSerializationTests.cs[tag=converter-usings]
+include::{doc-tests-src}/ClientConcepts/Serialization/CustomSerializationTests.cs[tag=customer-converter]
+----
+<1> When reading, this converter will read the `isStandard` boolean and translate this to the correct `CustomerType` enum value.
+<2> When writing, this converter will translate the `CustomerType` enum value to an `isStandard` boolean property.
+
+We can then index a customer document into {es}.
+
+[source,csharp]
+----
+include::{doc-tests-src}/ClientConcepts/Serialization/CustomSerializationTests.cs[tag=index-customer-with-converter]
+----
+
+The `Customer` instance is serialized using the custom converter, creating the following JSON document.
+
+[source,javascript]
+----
+{
+  "customerName": "Customer Ltd",
+  "isStandard": false
+}
+----
+
 [[injecting-custom-serializer]]
 ===== Injecting a custom serializer
 

tests/Tests/Documentation/ClientConcepts/Serialization/CustomSerializationTests.cs

@@ -10,11 +10,13 @@
 
 #pragma warning disable IDE0005
 //tag::usings[]
+//tag::converter-usings[]
 using System;
 using System.Text.Json;
 //tag::usings-serialization[]
 using System.Text.Json.Serialization;
 //end::usings-serialization[]
+//end::converter-usings[]
 using System.Threading.Tasks;
 using Elastic.Transport;
 using Elastic.Clients.Elasticsearch;
@@ -37,7 +39,8 @@ public async Task CustomizingJsonSerializerOptions()
 
     #pragma warning disable format
     //tag::custom-options-local-function[]
-    static void ConfigureOptions(JsonSerializerOptions o) => o.PropertyNamingPolicy = null; // <1>
+    static void ConfigureOptions(JsonSerializerOptions o) => // <1>
+        o.PropertyNamingPolicy = null; 
     //end::custom-options-local-function[]
 
     //tag::create-client[]
@@ -64,8 +67,7 @@ public async Task CustomizingJsonSerializerOptions()
     #pragma warning disable format
     //tag::index-person[]
     var person = new Person { FirstName = "Steve" };
-    var indexResponse = await client.IndexAsync(person, "my-index-name");
-    //end::index-person[]
+    var indexResponse = await client.IndexAsync(person, "my-index-name"); //end::index-person[]
     #pragma warning restore format
 
         var requestJson = Encoding.UTF8.GetString(indexResponse.ApiCallDetails.RequestBodyInBytes);
@@ -77,13 +79,13 @@ public async Task CustomizingJsonSerializerOptions()
 
 // Alternative example using an Action
 //tag::custom-options-action[]
-Action<JsonSerializerOptions> configureOptions = o => o.PropertyNamingPolicy = null; // <3>
+Action<JsonSerializerOptions> configureOptions = o => o.PropertyNamingPolicy = null;
 //end::custom-options-action[]
     }
 
 #pragma warning disable format
 //tag::person-class[]
-private class Person
+public class Person
 {
     public string FirstName { get; set; }
 }
@@ -115,7 +117,11 @@ public async Task UsingSystemTextJsonConverterAttributes()
     {
 #pragma warning disable format
 //tag::index-customer-with-converter[]
-var customer = new Customer { CustomerName = "Customer Ltd", Type = CustomerType.Enhanced };
+var customer = new Customer 
+{ 
+    CustomerName = "Customer Ltd", 
+    CustomerType = CustomerType.Enhanced 
+};
 var indexResponse = await Client.IndexAsync(customer, "my-index-name");
 //end::index-customer-with-converter[]
 #pragma warning restore format
@@ -126,12 +132,12 @@ public async Task UsingSystemTextJsonConverterAttributes()
         var ms = new MemoryStream(indexResponse.ApiCallDetails.RequestBodyInBytes);
         var deserializedCustomer = Client.SourceSerializer.Deserialize<Customer>(ms);
         deserializedCustomer.CustomerName.Should().Be("Customer Ltd");
-        deserializedCustomer.Type.Should().Be(CustomerType.Enhanced);
+        deserializedCustomer.CustomerType.Should().Be(CustomerType.Enhanced);
     }
 
 #pragma warning disable format
 //tag::person-class-with-attributes[]
-private class Person
+public class Person
 {
     [JsonPropertyName("forename")] // <1>
     public string FirstName { get; set; }
@@ -142,92 +148,103 @@ private class Person
 //end::person-class-with-attributes[]
 #pragma warning restore format
 
-    [JsonConverter(typeof(CustomerConverter))]
-    private class Customer
-    {
-        public string CustomerName { get; set; }
-        public CustomerType Type { get; set; }
-    }
+#pragma warning disable format
+//tag::customer-with-jsonconverter-attribute[]
+[JsonConverter(typeof(CustomerConverter))] // <1>
+public class Customer
+{
+    public string CustomerName { get; set; }
+    public CustomerType CustomerType { get; set; }
+}
 
-    private enum CustomerType
-    {
-        Standard,
-        Enhanced
-    }
+public enum CustomerType
+{
+    Standard,
+    Enhanced
+}
+//end::customer-with-jsonconverter-attribute[]
+#pragma warning restore format
 
-    private class CustomerConverter : JsonConverter<Customer>
+#pragma warning disable format
+//tag::customer-converter[]
+public class CustomerConverter : JsonConverter<Customer>
+{
+    public override Customer Read(ref Utf8JsonReader reader, 
+        Type typeToConvert, JsonSerializerOptions options)
     {
-        public override Customer Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
-        {
-            var customer = new Customer();
+        var customer = new Customer();
 
-            while (reader.Read() && reader.TokenType != JsonTokenType.EndObject)
+        while (reader.Read() && reader.TokenType != JsonTokenType.EndObject)
+        {
+            if (reader.TokenType == JsonTokenType.PropertyName)
             {
-                if (reader.TokenType == JsonTokenType.PropertyName)
+                if (reader.ValueTextEquals("customerName"))
                 {
-                    if (reader.ValueTextEquals("customerName"))
+                    reader.Read();
+                    customer.CustomerName = reader.GetString();
+                    continue;
+                }
+
+                if (reader.ValueTextEquals("isStandard")) // <1>
+                {
+                    reader.Read();
+                    var isStandard = reader.GetBoolean();
+
+                    if (isStandard)
                     {
-                        reader.Read();
-                        customer.CustomerName = reader.GetString();
-                        continue;
+                        customer.CustomerType = CustomerType.Standard;
                     }
-
-                    if (reader.ValueTextEquals("isStandard"))
+                    else
                     {
-                        reader.Read();
-                        var isStandard = reader.GetBoolean();
-
-                        if (isStandard)
-                        {
-                            customer.Type = CustomerType.Standard;
-                        }
-                        else
-                        {
-                            customer.Type = CustomerType.Enhanced;
-                        }
-
-                        continue;
+                        customer.CustomerType = CustomerType.Enhanced;
                     }
+
+                    continue;
                 }
             }
-
-            return customer;
         }
 
-        public override void Write(Utf8JsonWriter writer, Customer value, JsonSerializerOptions options)
+        return customer;
+    }
+
+    public override void Write(Utf8JsonWriter writer, 
+        Customer value, JsonSerializerOptions options)
+    {
+        if (value is null)
         {
-            if (value is null)
-            {
-                writer.WriteNullValue();
-                return;
-            }
+            writer.WriteNullValue();
+            return;
+        }
 
-            writer.WriteStartObject();
+        writer.WriteStartObject();
 
-            if (!string.IsNullOrEmpty(value.CustomerName))
-            {
-                writer.WritePropertyName("customerName");
-                writer.WriteStringValue(value.CustomerName);
-            }
+        if (!string.IsNullOrEmpty(value.CustomerName))
+        {
+            writer.WritePropertyName("customerName");
+            writer.WriteStringValue(value.CustomerName);
+        }
 
-            writer.WritePropertyName("isStandard");
+        writer.WritePropertyName("isStandard");
 
-            if (value.Type == CustomerType.Standard)
-            {
-                writer.WriteBooleanValue(true);
-            }
-            else
-            {
-                writer.WriteBooleanValue(false);
-            }
-
-            writer.WriteEndObject();
+        if (value.CustomerType == CustomerType.Standard) // <2>
+        {
+            writer.WriteBooleanValue(true);
+        }
+        else
+        {
+            writer.WriteBooleanValue(false);
         }
+
+        writer.WriteEndObject();
     }
+}
+//end::customer-converter[]
+#pragma warning restore format
 
     private class CustomerTypeConverter : JsonConverter<CustomerType>
     {
-        public override CustomerType Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        public override CustomerType Read(ref Utf8JsonReader reader, 
+            Type typeToConvert, JsonSerializerOptions options)
         {
             return reader.GetString() switch
             {
@@ -238,7 +255,8 @@ public override CustomerType Read(ref Utf8JsonReader reader, Type typeToConvert,
             };
         }
 
-        public override void Write(Utf8JsonWriter writer, CustomerType value, JsonSerializerOptions options)
+        public override void Write(Utf8JsonWriter writer, 
+            CustomerType value, JsonSerializerOptions options)
         {
             switch (value)
             {
@@ -296,19 +314,19 @@ public async Task DerivingFromSystemTextJsonSerializer_ToRegisterACustomEnumConv
         deserializedCustomer.Type.Should().Be(CustomerType.Enhanced);
     }
 
-    private class Customer
+    public class Customer
     {
         public string CustomerName { get; set; }
         public CustomerType Type { get; set; }
     }
 
-    private enum CustomerType
+    public enum CustomerType
     {
         Standard,
         Enhanced
     }
 
-    private class MyCustomSerializer : SystemTextJsonSerializer
+    public class MyCustomSerializer : SystemTextJsonSerializer
     {
         private readonly JsonSerializerOptions _options;
 
@@ -324,7 +342,7 @@ public MyCustomSerializer(IElasticsearchClientSettings settings) : base(settings
         protected override JsonSerializerOptions CreateJsonSerializerOptions() => _options;
     }
 
-    private class CustomerTypeConverter : JsonConverter<CustomerType>
+    public class CustomerTypeConverter : JsonConverter<CustomerType>
     {
         public override CustomerType Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
         {