Cheap Windows Hosting Review

System.Text.Json in .NET: An explanation

Posted on by Pablo Francesco

In.NET9, the System.Text.Json package has been greatly improved to give developers more powerful and adaptable JSON processing capabilities. Support for JSON schemas, clever application features, and more customization choices for serialization and deserialization procedures are the main focuses of these enhancements.

Other features of.NET9 are covered in my previous writings. For ease of comprehension and explanation, sample source code projects are also connected to the following articles.

Agenda

In this article, we will understand most of the features supported in System.Text.Json Library. Those details are,

  • Json Schema Exporter
  • Nullable Reference Type Support
  • Customizing Serialization Indentation
  • JsonSerializerOptions.Web
  • JsonObject Property Ordering
  • JsonElement DeepEquals Method
  • Customizing Enum Member Names

Json Schema Exporter

A notable addition is the JsonSchemaExporter class, which enables the extraction of JSON schema documents from .NET types. This feature facilitates the validation and documentation of JSON data structures, ensuring consistency across applications. The code snippet below helps to get the schema format as output.

Employee class file

public class Employee
{
    public int Id { get; set; }
    public string Name { get; set; }
    public int YearJoin { get; set; }
}

The below code helps to get the schema as output.

public static void JsonExporterExample()
{
    JsonSerializerOptions options = JsonSerializerOptions.Default;
    JsonNode schema = options.GetJsonSchemaAsNode(typeof(Employee));
    Console.WriteLine(schema.ToString());
}

The output schema defines the structure of the Employee class, specifying property types and nullability, which aids in maintaining data integrity.

Nullable Reference Type Support

To align with C#’s nullable reference type annotations, System.Text.Json now offers the RespectNullableAnnotations option. When enabled, the serializer enforces non-nullable reference types during serialization and deserialization, throwing exceptions if a non-nullable property is assigned a null value.

So, the code below shows a clear example of this property usage and its results.

public static void JsonRespectNullableAnnotations()
{
    var emp = new Employee { Id = 1, Name = null, YearJoin = 2024 };

    //Print the emp object WITHOUT applying Nullable notation
    var empObject = JsonSerializer.Serialize(emp);
    Console.WriteLine(empObject);

    //Set Serailization options with Nullable notation as true
    JsonSerializerOptions options = new()
    {
        RespectNullableAnnotations = true
    };

    try
    {
        //emp object searialiization WITH applying Nullable notation
        var empObjectNotation = JsonSerializer.Serialize(emp, options);
        // Throws System.Text.Json.JsonException
    }
    catch (Exception ex)
    {
        Console.WriteLine("Serialization error :: {0}", ex.Message);
    }


    try
    {
        JsonSerializer.Deserialize<Employee>("""{"Id":1,"Name":null,"YearJoin":2024}""", options);
        // Throws System.Text.Json.JsonException
    }
    catch (Exception ex)
    {
        Console.WriteLine("De Serialization error :: {0}", ex.Message);
    }

}

The output of the aforesaid code is as follows.

Customizing Serialization Indentation

To offer more flexibility in JSON formatting, System.Text.Json introduces options to customize indentation. We can specify the character and size used for indentation, allowing the JSON output to meet specific formatting requirements. This helps to read/beautify the json in an easy and understandable way.

IndentCharacter only supports space and horizontal tab formats only.

public static void JsonIdentation()
{
    var emp = new Employee { Id = 1, Name = "Michael", YearJoin = 2024 };

    //print the object WITH OUT indentation
    string empObject = JsonSerializer.Serialize(emp);
    Console.WriteLine(empObject);

    var options = new JsonSerializerOptions
    {
        WriteIndented = true,
        IndentCharacter = '\t',
        IndentSize = 1
    };
    //print the object WITH indentation
    string empObjectOptions = JsonSerializer.Serialize(emp, options);
    Console.WriteLine(empObjectOptions);
}

JsonSerializerOptions.Web

The introduction of JsonSerializerOptions.Web provides a predefined set of options tailored for web applications. This includes settings like camel-casing of property names and flexible number handling, aligning JSON serialization with common web API practices.

public static void JsonSearializeWeb()
{
    var emp = new Employee { Id = 1, Name = "Michael", YearJoin = 2024 };
    var empWebJson = JsonSerializer.Serialize(emp, JsonSerializerOptions.Web);
    Console.WriteLine(empWebJson);
}

JsonObject Property Ordering

The JsonObject class now allows developers to control the order of properties in JSON objects. This is particularly beneficial when the property order is significant, such as in certain serialization scenarios or when interfacing with systems that are sensitive to property ordering.

public static void JsonObjectOrdering()
{
    JsonObject emp = new(){ ["Id"] = 1, ["Name"] = "Michael", ["YearJoin"] = 2024 };
    emp.Insert(0, "Org", "ABC Ltd");
    Console.WriteLine(emp);
}

JsonElement DeepEquals Method

In .NET 9, the System.Text.Json library introduces the JsonElement.DeepEquals method, enabling deep comparison between two JsonElement instances. This method determines if two JSON elements are structurally and semantically identical.

public static void JsonDeepEquals()
{
    var empJson = """{"Id":1,"Name":"Michael","YearJoin":2024}""";
    JsonElement left = JsonDocument.Parse(empJson).RootElement;
    JsonElement right = JsonDocument.Parse(empJson).RootElement;

    //Prints - TRUE as both the elments have same elements
    Console.WriteLine(JsonElement.DeepEquals(left, right));

    var empJson1 = """{"Id":1,"FullName":"Michael","YearJoin":2024}""";
    right = JsonDocument.Parse(empJson1).RootElement;
    //Prints - FALSE as the elments have different elements data.
    Console.WriteLine(JsonElement.DeepEquals(left, right));

}

Prior to .NET 9, developers often relied on external libraries like Newtonsoft.Json’s JToken.DeepEquals for deep JSON comparisons. The inclusion of JsonElement.DeepEquals in System.Text.Json provides a built-in solution, reducing the need for third-party dependencies.

Customizing Enum Member Names

In .NET 9, The System.Text.Json library introduces the JsonStringEnumMemberName attribute, allowing us to customize the JSON representation of individual enum members. This enhancement provides greater flexibility when serializing enums, especially in scenarios where specific naming conventions or formats are required.

To customize the JSON output of an enum member, apply the JsonStringEnumMemberName attribute to the desired enum fields. Ensure that the enum is decorated with the [JsonConverter(typeof(JsonStringEnumConverter))] attribute to enable string-based serialization.

[Flags]
[JsonConverter(typeof(JsonStringEnumConverter))]
enum EmpState
{
    OnBoarding = 1,

    [JsonStringEnumMemberName("In Progress")]
    InProgress = 2,

    [JsonStringEnumMemberName("Ready For Dev")]
    ReadyForDev = 3
}

public static void JsonEnumTypes()
{
    var state = EmpState.ReadyForDev;
    var empJson = JsonSerializer.Serialize(state);
    Console.WriteLine(empJson);
}

In this example, the ReadyForDev enum member is serialized as “Ready For Dev” in the JSON output, as specified by the JsonStringEnumMemberName attribute.

Benefits of This Enhancement

  • Consistency: Aligns JSON output with specific naming conventions required by external systems or APIs.
  • Clarity: Provides more descriptive or user-friendly names in the serialized JSON, improving readability.
  • Compatibility: Ensures that the JSON output matches expected formats without altering the underlying enum definitions.

Considerations

  • Deserialization: When customizing enum member names, ensure that the JSON input during deserialization matches the specified names to avoid errors.
  • Flags Attribute: For enums decorated with the [Flags] attribute, the JsonStringEnumConverter correctly handles combined flag values, serializing them as a comma-separated list of names.

Summary

.NET 9 brings several improvements to the System.Text.Json library, making it more powerful, flexible, and performant for JSON serialization and deserialization. The aforesaid discussed source code examples are attached as a JsonFeaturesDemo.zip file in this article.

Best ASP.NET Core 8.0.11 Hosting

The feature and reliability are the most important things when choosing a good ASP.NET Core 8.0.11 hosting. HostForLIFE is the leading provider of Windows hosting and affordable ASP.NET Core , their servers are optimized for PHP web applications such as the latest ASP.NET Core 8.0.11 version. The performance and the uptime of the ASP.NET Core  hosting service are excellent, and the features of the web hosting plan are even greater than what many hosting providers ask you to pay for. At HostForLIFEASP.NET, customers can also experience fast ASP.NET Core hosting. The company invested a lot of money to ensure the best and fastest performance of the datacenters, servers, network and other facilities. Its data centers are equipped with top equipment like cooling system, fire detection, high-speed Internet connection, and so on. That is why HostForLIFEASP.NET guarantees 99.9% uptime for ASP.NET Core . And the engineers do regular maintenance and monitoring works to assure its ASP.NET Core  hosting are security and always up.

hostforlifebanner