JsonConverter: Implement Default Write For Inherited Properties

Aug 23, 2025 by Chloe Fitzgerald 64 views

JsonConverter: Nicest Way to Implement Default "Write" Discussion

Hey guys! Today, we're diving deep into a challenge many of us face when working with System.Text.Json in C# and .NET: handling inherited properties on interfaces. The current version of the serializer doesn't natively support this, so we need to get creative. Let's explore the neatest ways to mock this behavior in the Write method of a JsonConverter.

The Challenge: Serializing Inherited Properties on Interfaces

So, what's the big deal? Well, when you have an interface with properties, and a class that implements that interface and inherits from another class, System.Text.Json can stumble when it comes to serializing those inherited properties. Imagine you have an interface IAnimal with a Name property, a class Mammal that inherits from some base class and implements IAnimal, and a class Dog that inherits from Mammal. You'd expect the serializer to pick up the Name property from the IAnimal interface, right? But sometimes, it just doesn't work as expected without some extra help.

This limitation can be a real headache, especially in complex systems where you rely heavily on interfaces and inheritance for structuring your data models. You might find yourself missing crucial data in your serialized JSON, leading to bugs and unexpected behavior. That's why understanding how to work around this limitation is essential for any .NET developer working with System.Text.Json.

Why Does This Happen?

To understand the problem, it's helpful to peek under the hood of how System.Text.Json works. The serializer relies on reflection to discover the properties of the object you're trying to serialize. When it encounters an interface, it typically looks at the properties declared directly on that interface. It might not automatically traverse the inheritance hierarchy to find properties inherited from other classes. This is a design choice that prioritizes performance and simplicity, but it does mean we need to step in and provide some guidance when dealing with inherited properties.

The Goal: A Clean and Maintainable Solution

Our goal here isn't just to make the serialization work; we want to do it in a way that's clean, maintainable, and doesn't introduce a ton of boilerplate code. We want a solution that feels like a natural extension of the System.Text.Json serializer, not a clunky workaround that will make our code harder to read and maintain. This means we'll be focusing on creating a custom JsonConverter that elegantly handles the serialization of inherited properties without sacrificing performance or code clarity.

Diving into JsonConverter

The key to solving this puzzle lies in creating a custom JsonConverter. A JsonConverter is a powerful tool in System.Text.Json that allows you to take complete control over the serialization and deserialization process for a specific type or a family of types. By creating our own converter, we can tell the serializer exactly how to handle inherited properties on interfaces.

What is a JsonConverter?

Think of a JsonConverter as a translator between your .NET objects and their JSON representation. It provides two crucial methods:

Read: This method handles deserialization, taking a JSON string and turning it back into a .NET object.
Write: This method handles serialization, taking a .NET object and turning it into a JSON string.

By overriding these methods, we can customize how the serializer handles specific types. In our case, we'll be focusing on the Write method to ensure that inherited properties are correctly included in the JSON output.

The Basic Structure of a Custom JsonConverter

Here's the basic structure of a custom JsonConverter in C#:

using System;
using System.Text.Json;
using System.Text.Json.Serialization;

public class MyCustomConverter : JsonConverter<T> // Replace T with the type you want to handle
{
    public override T Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        // Deserialization logic here
        throw new NotImplementedException();
    }

    public override void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options)
    {
        // Serialization logic here
    }

    public override bool CanConvert(Type typeToConvert)
    {
        //Determine if this converter can handle the given type
        return typeof(MyType).IsAssignableFrom(typeToConvert); // Replace MyType with your target type
    }
}

Let's break down the key parts:

JsonConverter<T>: This is the base class we inherit from. The T specifies the type that this converter will handle. It's a generic class, so you'll replace T with the actual type you want to convert (e.g., IAnimal, Mammal, or a custom interface).
Read: This method is responsible for deserialization. Since our focus is on serialization, we'll leave it as throw new NotImplementedException() for now. We'll come back to deserialization later if needed.
Write: This is the heart of our solution. This is where we'll implement the logic to handle inherited properties.
CanConvert: This method is crucial. It tells the serializer whether this converter can handle a given type. This is especially important when you have multiple converters registered. You should implement this method to ensure your converter only handles the types it's designed for. Using IsAssignableFrom is a good way to check if the type to convert is your desired type or a derived type or implementation.

Implementing the Write Method: Mocking Inherited Properties

Now, let's get to the core of the problem: how to implement the Write method to handle inherited properties. The basic idea is that we need to manually inspect the properties of the object we're serializing and write them to the JSON writer.

A Naive Approach (and why it's not ideal)

One way to do this is to use reflection to get all the properties of the object and then write them individually. Here's a simplified example:

using System;
using System.Reflection;
using System.Text.Json;
using System.Text.Json.Serialization;

public class AnimalConverter : JsonConverter<IAnimal>
{
    public override IAnimal Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        throw new NotImplementedException();
    }

    public override void Write(Utf8JsonWriter writer, IAnimal value, JsonSerializerOptions options)
    {
        writer.WriteStartObject();

        foreach (PropertyInfo property in value.GetType().GetProperties())
        {
            object propValue = property.GetValue(value);
            if (propValue != null)
            {
                writer.WritePropertyName(property.Name);
                JsonSerializer.Serialize(writer, propValue, propValue.GetType(), options);
            }
        }

        writer.WriteEndObject();
    }

    public override bool CanConvert(Type typeToConvert)
    {
        return typeof(IAnimal).IsAssignableFrom(typeToConvert);
    }
}

This code gets all the properties of the object using GetType().GetProperties(), iterates through them, gets their values, and writes them to the JSON writer. While this works, it has some drawbacks:

Performance: Reflection can be slow, especially if you're serializing a lot of objects.
Type Handling: We're using JsonSerializer.Serialize recursively, which can lead to issues if the properties themselves contain complex objects or circular references.
Maintainability: This code is verbose and can be harder to maintain as your object models evolve.

A Better Approach: Leveraging JsonSerializerOptions

A more elegant and efficient approach is to leverage the JsonSerializerOptions that are passed into the Write method. These options contain a wealth of information about how the serializer is configured, including any other converters that are registered. We can use this to our advantage by essentially asking the serializer to serialize each property for us, but with the added context of our custom converter.

Here's a refined version of the Write method that demonstrates this approach:

using System;
using System.Reflection;
using System.Text.Json;
using System.Text.Json.Serialization;

public class AnimalConverter : JsonConverter<IAnimal>
{
    public override IAnimal Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        throw new NotImplementedException();
    }

    public override void Write(Utf8JsonWriter writer, IAnimal value, JsonSerializerOptions options)
    {
        writer.WriteStartObject();

        foreach (PropertyInfo property in value.GetType().GetProperties())
        {
            object propValue = property.GetValue(value);
            if (propValue != null)
            {
                writer.WritePropertyName(property.Name);
                JsonSerializer.Serialize(writer, propValue, property.PropertyType, options);
            }
        }

        writer.WriteEndObject();
    }
    public override bool CanConvert(Type typeToConvert)
    {
        return typeof(IAnimal).IsAssignableFrom(typeToConvert);
    }

}

Let's break down what's happening here:

Iterate Through Properties: We still use reflection to get the properties of the object.
Write Property Name: We write the name of the property using writer.WritePropertyName(property.Name). This tells the serializer which property we're about to serialize.
Serialize Property Value: Instead of recursively calling JsonSerializer.Serialize with propValue.GetType(), we now use property.PropertyType. This is crucial because it ensures that the serializer uses the correct type information when serializing the property value. This is particularly important for inherited properties, as it allows the serializer to pick up any custom converters that are registered for the property's type.
Pass Options: We pass the original options to the JsonSerializer.Serialize method. This ensures that any custom converters or other serialization settings are applied to the property value.

Why is this better?

This approach is significantly better for several reasons:

Type Safety: By using property.PropertyType, we ensure that the serializer has the correct type information for the property, allowing it to handle complex types and custom converters correctly.
Maintainability: This code is cleaner and easier to understand, making it more maintainable in the long run.
Performance: While we're still using reflection, we're avoiding the overhead of recursive serialization and allowing the serializer to handle the actual serialization logic, which it's optimized for.

Going the Extra Mile: Handling ReadOnly Properties and Custom Attributes

Our solution is already pretty good, but we can make it even better by handling a few more edge cases.

ReadOnly Properties

Sometimes, you might have properties that should only be deserialized, not serialized. These are often marked with a [JsonIgnore] or have a private setter. Our current code will still try to serialize these properties, which might not be what we want. We can easily fix this by checking if the property has a setter before serializing it:

if (property.GetSetMethod() != null && propValue != null)
{
    writer.WritePropertyName(property.Name);
    JsonSerializer.Serialize(writer, propValue, property.PropertyType, options);
}

This ensures that we only serialize properties that have a public setter, effectively skipping read-only properties.

Custom Attributes

You might also have custom attributes on your properties that influence serialization, such as [JsonPropertyName] to specify a different JSON name or [JsonIgnore] to completely ignore the property. Our current code doesn't take these attributes into account. To handle them, we need to inspect the attributes on the property and adjust our serialization logic accordingly.

Here's an example of how you might handle the [JsonPropertyName] attribute:

using System.Reflection;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Linq;

public class AnimalConverter : JsonConverter<IAnimal>
{
    public override IAnimal Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        throw new NotImplementedException();
    }

    public override void Write(Utf8JsonWriter writer, IAnimal value, JsonSerializerOptions options)
    {
        writer.WriteStartObject();

        foreach (PropertyInfo property in value.GetType().GetProperties())
        {
            object propValue = property.GetValue(value);
            if (propValue != null && property.GetSetMethod() != null)
            {
                // Check for JsonPropertyName attribute
                JsonPropertyNameAttribute jsonPropertyNameAttribute = property.GetCustomAttributes(typeof(JsonPropertyNameAttribute), true)
                    .FirstOrDefault() as JsonPropertyNameAttribute;

                string propertyName = jsonPropertyNameAttribute?.Name ?? property.Name;

                writer.WritePropertyName(propertyName);
                JsonSerializer.Serialize(writer, propValue, property.PropertyType, options);
            }
        }

        writer.WriteEndObject();
    }

    public override bool CanConvert(Type typeToConvert)
    {
        return typeof(IAnimal).IsAssignableFrom(typeToConvert);
    }
}

This code checks if the property has a [JsonPropertyName] attribute. If it does, it uses the name specified in the attribute; otherwise, it uses the property's name. You can extend this pattern to handle other custom attributes as needed.

Putting It All Together: A Robust JsonConverter

Here's the complete JsonConverter that handles inherited properties, read-only properties, and the [JsonPropertyName] attribute:

using System;
using System.Reflection;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Linq;

public class AnimalConverter : JsonConverter<IAnimal>
{
    public override IAnimal Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        throw new NotImplementedException();
    }

    public override void Write(Utf8JsonWriter writer, IAnimal value, JsonSerializerOptions options)
    {
        writer.WriteStartObject();

        foreach (PropertyInfo property in value.GetType().GetProperties())
        {
            object propValue = property.GetValue(value);
            if (propValue != null && property.GetSetMethod() != null)
            {
                // Check for JsonPropertyName attribute
                JsonPropertyNameAttribute jsonPropertyNameAttribute = property.GetCustomAttributes(typeof(JsonPropertyNameAttribute), true)
                    .FirstOrDefault() as JsonPropertyNameAttribute;

                string propertyName = jsonPropertyNameAttribute?.Name ?? property.Name;

                writer.WritePropertyName(propertyName);
                JsonSerializer.Serialize(writer, propValue, property.PropertyType, options);
            }
        }

        writer.WriteEndObject();
    }

    public override bool CanConvert(Type typeToConvert)
    {
        return typeof(IAnimal).IsAssignableFrom(typeToConvert);
    }
}

This JsonConverter provides a robust and maintainable solution for serializing inherited properties on interfaces with System.Text.Json. It leverages the serializer's built-in capabilities while providing the necessary customization to handle the specific challenges of inherited properties. By following this approach, you can ensure that your JSON serialization is accurate, efficient, and easy to maintain.

Registering the JsonConverter

Of course, a JsonConverter is only useful if the serializer knows about it. You need to register your custom converter with the JsonSerializerOptions. There are a couple of ways to do this.

Globally

You can register the converter globally by modifying the default JsonSerializerOptions. This is useful if you want the converter to be applied to all instances of a specific type throughout your application.

var options = new JsonSerializerOptions
{
    Converters = { new AnimalConverter() }
};

string json = JsonSerializer.Serialize(myAnimal, options);

Locally

You can also register the converter for a specific serialization operation by creating a new JsonSerializerOptions instance and passing it to the Serialize method.

var options = new JsonSerializerOptions();
options.Converters.Add(new AnimalConverter());

string json = JsonSerializer.Serialize(myAnimal, options);

The choice between global and local registration depends on your application's needs. If you need the converter to be applied consistently across your application, global registration is the way to go. If you only need it for specific serialization operations, local registration is more flexible.

Conclusion

Serializing inherited properties on interfaces with System.Text.Json can be a bit tricky, but with a custom JsonConverter, it becomes much more manageable. By leveraging the JsonSerializerOptions and carefully handling property types and attributes, you can create a robust and maintainable solution. Remember, the key is to let the serializer do as much of the work as possible while providing the necessary guidance to handle the specific challenges of inherited properties.

I hope this deep dive into JsonConverter has been helpful, guys! Happy coding, and may your JSON serialization be ever smooth and accurate!

JsonConverter
System.Text.Json
C#
.NET
Serialization
Inherited properties
Interfaces
Write method
Custom converter
JsonPropertyName attribute
ReadOnly properties