5.0 updates to System.Text.Json docs (#21108)

docs/standard/serialization/snippets/system-text-json-how-to-5-0/csharp/CopyOptions.cs

@@ -0,0 +1,44 @@
+using System;
+using System.Text.Json;
+
+namespace CopyOptions
+{
+    public class Forecast
+    {
+        public DateTime Date { get; init; }
+        public int TemperatureC { get; set; }
+        public string Summary { get; set; }
+    };
+
+    public class Program
+    {
+        public static void Main()
+        {
+            Forecast forecast = new()
+            {
+                Date = DateTime.Now,
+                TemperatureC = 40,
+                Summary = "Hot"
+            };
+
+            JsonSerializerOptions options = new()
+            {
+                WriteIndented = true
+            };
+
+            JsonSerializerOptions optionsCopy = new(options);
+            string forecastJson = JsonSerializer.Serialize<Forecast>
+                (forecast, optionsCopy);
+            Console.WriteLine($"Output JSON:\n{forecastJson}");
+        }
+    }
+}
+
+// Produces output like the following example:
+//
+//Output JSON:
+//{
+//  "Date": "2020-10-21T15:40:06.8998502-07:00",
+//  "TemperatureC": 40,
+//  "Summary": "Hot"
+//}

docs/standard/serialization/snippets/system-text-json-how-to-5-0/csharp/CustomConverterHandleNull.cs

@@ -0,0 +1,53 @@
+using System;
+using System.Collections.Generic;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace CustomConverterHandleNull
+{
+    public class Point
+    {
+        public int X { get; set; }
+        public int Y { get; set; }
+
+        [JsonConverter(typeof(DescriptionConverter))]
+        public string Description { get; set; }
+    }
+
+    public class DescriptionConverter : JsonConverter<string>
+    {
+        public override bool HandleNull => true;
+
+        public override string Read(
+            ref Utf8JsonReader reader, 
+            Type typeToConvert, 
+            JsonSerializerOptions options)
+        {
+            string val = reader.GetString();
+            return val ?? "No description provided.";
+        }
+
+        public override void Write(
+            Utf8JsonWriter writer, 
+            string value, 
+            JsonSerializerOptions options)
+        {
+            writer.WriteStringValue(value);
+        }
+    }
+
+    public class Program
+    {
+        public static void Main()
+        {
+            string json = "{\"x\":1,\"y\":2,\"Description\":null}";
+
+            Point point = JsonSerializer.Deserialize<Point>(json);
+            Console.WriteLine($"Description: {point.Description}");
+        }
+    }
+}
+
+// Produces output like the following example:
+//
+//Description: No description provided.

docs/standard/serialization/snippets/system-text-json-how-to-5-0/csharp/Fields.cs

@@ -0,0 +1,67 @@
+using System;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Fields
+{
+    public class Forecast
+    {
+        public DateTime Date;
+        public int TemperatureC;
+        public string Summary;
+    }
+    public class Forecast2
+    {
+        [JsonInclude]
+        public DateTime Date;
+        [JsonInclude]
+        public int TemperatureC;
+        [JsonInclude]
+        public string Summary;
+    }
+    public class Program
+    {
+        public static void Main()
+        {
+            var json = "{\"Date\":\"2020-09-06T11:31:01.923395-07:00\",\"TemperatureC\":-1,\"Summary\":\"Cold\"} ";
+            Console.WriteLine($"Input JSON: {json}");
+
+            var options = new JsonSerializerOptions()
+            {
+                IncludeFields = true,
+            };
+            var forecast = JsonSerializer.Deserialize<Forecast>(json, options);
+
+            Console.WriteLine($"forecast.Date: {forecast.Date}");
+            Console.WriteLine($"forecast.TemperatureC: {forecast.TemperatureC}");
+            Console.WriteLine($"forecast.Summary: {forecast.Summary}");
+
+            var roundTrippedJson = JsonSerializer.Serialize<Forecast>
+                (forecast, options);
+            Console.WriteLine($"Output JSON: {roundTrippedJson}");
+
+            options = new JsonSerializerOptions(JsonSerializerDefaults.Web);
+            var forecast2 = JsonSerializer.Deserialize<Forecast2>(json);
+
+            Console.WriteLine($"forecast2.Date: {forecast2.Date}");
+            Console.WriteLine($"forecast2.TemperatureC: {forecast2.TemperatureC}");
+            Console.WriteLine($"forecast2.Summary: {forecast2.Summary}");
+
+            roundTrippedJson = JsonSerializer.Serialize<Forecast2>
+                (forecast2, options);
+            Console.WriteLine($"Output JSON: {roundTrippedJson}");
+        }
+    }
+}
+
+// Produces output like the following example:
+//
+//Input JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"}
+//forecast.Date: 9/6/2020 11:31:01 AM
+//forecast.TemperatureC: -1
+//forecast.Summary: Cold
+//Output JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"}
+//forecast2.Date: 9/6/2020 11:31:01 AM
+//forecast2.TemperatureC: -1
+//forecast2.Summary: Cold
+//Output JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"}

docs/standard/serialization/snippets/system-text-json-how-to-5-0/csharp/GuidReferenceResolverExample.cs

@@ -0,0 +1,100 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace GuidReferenceResolverExample
+{
+    public class Person
+    {
+        internal Guid Id { get; set; }
+        public string Name { get; set; }
+        public Person Spouse { get; set; }
+    }
+
+    public class GuidReferenceResolver : ReferenceResolver
+    {
+        private readonly IDictionary<Guid, Person> _people = new Dictionary<Guid, Person>();
+
+        public override object ResolveReference(string referenceId)
+        {
+            Guid id = new Guid(referenceId);
+
+            _people.TryGetValue(id, out Person p);
+
+            return p;
+        }
+
+        public override string GetReference(object value, out bool alreadyExists)
+        {
+            Person p = (Person)value;
+
+            if (!(alreadyExists = _people.ContainsKey(p.Id)))
+            {
+                _people[p.Id] = p;
+            }
+
+            return p.Id.ToString();
+        }
+
+        public override void AddReference(string reference, object value)
+        {
+            Guid id = new Guid(reference);
+            Person person = (Person)value;
+            person.Id = id;
+            _people[id] = person;
+        }
+    }
+
+    static class Program
+    {
+        public static void Main()
+        {
+            Person tyler = new() { Id = Guid.NewGuid(), Name = "Tyler" };
+            Person adrian = new() { Id = Guid.NewGuid(), Name = "Adrian" };
+            tyler.Spouse = adrian;
+            adrian.Spouse = tyler;
+            var people = ImmutableArray.Create(tyler, adrian);
+
+            var options = new JsonSerializerOptions
+            {
+                WriteIndented = true,
+                ReferenceHandler = new ReferenceHandler<GuidReferenceResolver>()
+            };
+
+            string json = JsonSerializer.Serialize(people, options);
+            Console.WriteLine($"Output JSON {json}");
+
+            List<Person> peopleDeserialized =
+                JsonSerializer.Deserialize<List<Person>>(json, options);
+
+            Person tylerDeserialized = people[0];
+            Person adrianDeserialized = people[1];
+
+            Console.WriteLine($"Adrian is Tyler's spouse: {tylerDeserialized.Equals(adrianDeserialized.Spouse)}");
+            Console.WriteLine($"Tyler is Adrian's spouse: {adrianDeserialized.Equals(tylerDeserialized.Spouse)}");
+        }
+    }
+}
+
+// Produces output like the following example:
+//
+//Output JSON[
+//  {
+//    "$id": "79301726-9d94-499a-8cdc-0c8bcc4c9b63",
+//    "Name": "Tyler",
+//    "Spouse": {
+//      "$id": "94833059-35f2-4fdd-96ee-94fd0484969a",
+//      "Name": "Adrian",
+//      "Spouse": {
+//        "$ref": "79301726-9d94-499a-8cdc-0c8bcc4c9b63"
+//      }
+//  }
+//  },
+//  {
+//    "$ref": "94833059-35f2-4fdd-96ee-94fd0484969a"
+//  }
+//]
+//Adrian is Tyler's spouse: True
+//Tyler is Adrian's spouse: True

docs/standard/serialization/snippets/system-text-json-how-to-5-0/csharp/HttpClientExtensionMethods.cs

@@ -0,0 +1,44 @@
+using System;
+using System.Net.Http;
+using System.Net.Http.Json;
+using System.Threading.Tasks;
+
+namespace HttpClientExtensionMethods
+{
+    public class User
+    {
+        public int Id { get; set; }
+        public string Name { get; set; }
+        public string Username { get; set; }
+        public string Email { get; set; }
+    }
+    public class Program
+    {
+        public static async Task Main()
+        {
+            var client = new HttpClient();
+            client.BaseAddress = new Uri("https://jsonplaceholder.typicode.com");
+
+            // Get the user information.
+            User user = await client.GetFromJsonAsync<User>("users/1");
+            Console.WriteLine($"Id: {user.Id}");
+            Console.WriteLine($"Name: {user.Name}");
+            Console.WriteLine($"Username: {user.Username}");
+            Console.WriteLine($"Email: {user.Email}");
+
+            // Post a new user.
+            HttpResponseMessage response = await client.PostAsJsonAsync("users", user);
+            Console.WriteLine(
+                (response.IsSuccessStatusCode ? "Success" : "Error")
+                    + $" - {response.StatusCode}");
+        }
+    }
+}
+
+// Produces output like the following example but with different names:
+//
+//Id: 1
+//Name: Tyler King
+//Username: Tyler
+//Email: Tyler @contoso.com
+//Success - Created

docs/standard/serialization/snippets/system-text-json-how-to-5-0/csharp/IgnoreNullOnSerialize.cs

@@ -0,0 +1,40 @@
+#nullable enable
+using System;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace IgnoreNullOnSerialize
+{
+    public class Forecast
+    {
+        public DateTime Date { get; set; }
+        public int TemperatureC { get; set; }
+        public string? Summary { get; set; }
+    };
+
+    public class Program
+    {
+        public static void Main()
+        {
+            Forecast forecast = new()
+            {
+                Date = DateTime.Now,
+                Summary = null,
+                TemperatureC = default(int)
+            };
+
+            JsonSerializerOptions options = new()
+            {
+                DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
+            };
+
+            string forecastJson = JsonSerializer.Serialize<Forecast>
+                (forecast, options);
+            Console.WriteLine(forecastJson);
+        }
+    }
+}
+
+// Produces output like the following example:
+//
+//{"Date":"2020-10-30T10:11:40.2359135-07:00","TemperatureC":0}

docs/standard/serialization/snippets/system-text-json-how-to-5-0/csharp/IgnoreValueDefaultOnSerialize.cs

@@ -0,0 +1,40 @@
+#nullable enable
+using System;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace IgnoreValueDefaultOnSerialize
+{
+    public class Forecast
+    {
+        public DateTime Date { get; set; }
+        public int TemperatureC { get; set; }
+        public string? Summary { get; set; }
+    };
+
+    public class Program
+    {
+        public static void Main()
+        {
+            Forecast forecast = new()
+            {
+                Date = DateTime.Now,
+                Summary = null,
+                TemperatureC = default(int)
+            };
+
+            JsonSerializerOptions options = new()
+            {
+                DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
+            };
+
+            string forecastJson = JsonSerializer.Serialize<Forecast>
+                (forecast, options);
+            Console.WriteLine(forecastJson);
+        }
+    }
+}
+
+// Produces output like the following example:
+//
+//{ "Date":"2020-10-21T15:40:06.8920138-07:00"}