Adding "Registering custom System.Text.Json converters"

Author: stevejgordon

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

@@ -37,11 +37,6 @@ 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`
 
@@ -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 can 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 the example, we have a document class in our application which 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]
+include::{doc-tests-src}/ClientConcepts/Serialization/CustomSerializationTests.cs[tag=customer-with-jsonconverter-attribute]
+----
+<1> The `JsonConverter` is used to signal 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 are required to 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 a `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, resulting in 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[]
@@ -77,13 +80,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 +118,7 @@ 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 +129,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,88 +145,96 @@ 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)
-        {
-            if (value is null)
-            {
-                writer.WriteNullValue();
-                return;
-            }
+        return customer;
+    }
 
-            writer.WriteStartObject();
+    public override void Write(Utf8JsonWriter writer, Customer value, JsonSerializerOptions options)
+    {
+        if (value is null)
+        {
+            writer.WriteNullValue();
+            return;
+        }
 
-            if (!string.IsNullOrEmpty(value.CustomerName))
-            {
-                writer.WritePropertyName("customerName");
-                writer.WriteStringValue(value.CustomerName);
-            }
+        writer.WriteStartObject();
 
-            writer.WritePropertyName("isStandard");
+        if (!string.IsNullOrEmpty(value.CustomerName))
+        {
+            writer.WritePropertyName("customerName");
+            writer.WriteStringValue(value.CustomerName);
+        }
 
-            if (value.Type == CustomerType.Standard)
-            {
-                writer.WriteBooleanValue(true);
-            }
-            else
-            {
-                writer.WriteBooleanValue(false);
-            }
+        writer.WritePropertyName("isStandard");
 
-            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>
     {
@@ -296,19 +307,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 +335,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)
         {