PolymorphicJsonTypeInfoResolver 7.1.0-alpha.1

Polymorphic Json Type Info Resolver

Polymorphic Json Type Info Resolver allows you to configure polymorphism on the contract model without polluting the domain model with attributes. This library leverages the polymorphic type serialization feature introduced in .NET7.

Installation

You can install the Polymorphic Json Type Info Resolver via NuGet Package Manager or by using the .NET CLI.

NuGet Package Manager:

1. Search for "PolymorphicJsonTypeInfoResolver" in the NuGet Package Manager in Visual Studio.
2. Click "Install".

.NET CLI:

dotnet add package PolymorphicJsonTypeInfoResolver

Usage

Stable contracts

Here's an example of how to use Polymorphic Json Type Info Resolver:

var options = new JsonSerializerOptions {
    TypeInfoResolver = new PolymorphicTypeInfoResolver()
        .Type<Shape>(x => x
            .DerivedTypes
            .Add<Square>("square")
            .Add<Circle>("circle"))
};
        
var json = JsonSerializer.Serialize(new Box(new Circle(10)), options);

The result will look like this:

{
    "Shape": {
        "$type":"circle",
        "Radius":10
    }
}

In the above code snippet, we create a new instance of JsonSerializerOptions and set its TypeInfoResolver property to an instance of PolymorphicTypeInfoResolver. We then configure the resolver to serialize objects of type Shape with a $type property that specifies the derived type (Square or Circle).

Verify

To make sure you added all derived types of specific contract you add Verify<T>([...]) invocations:

new PolymorphicTypeInfoResolver()
    .Type<Shape>(x => x
        .DerivedTypes
        .Add<Square>("square")
        .Add<Circle>("circle")
        .Verify<Shape>() // using the assembly of Shape
        .Verify<Shape, SomeOtherLibrary.Polygon>() // using the assembly of Polygon
        .Verify<Shape>([assemblies]));
)

The verification is optional, but it saves you from runtime exceptions when serializing/deserializing data:

System.NotSupportedException 
  Runtime type 'SomeOtherLibrary.Polygon' is not supported by polymorphic type 'YourLibrary.Shape'. Path: $.Shape.

Add All Derived Types

To opt-in to all derived types from its own assembly or the specified assembly, you can use the following code:

new JsonSerializerOptions {
    TypeInfoResolver = new PolymorphicTypeInfoResolver()
        .Type<Shape>(x => x
            .DerivedTypes
            .AddAllAssignableTo<Shape>(t => t.Name)
            .AddAllAssignableTo<Shape, SomeOtherLibrary.Parallelogram>(t => t.Name)
            .AddAllAssignableTo<Shape>([assemblies], t => t.Name))
};

In the above code snippet, we create a new instance of JsonSerializerOptions and set its TypeInfoResolver property to an instance of PolymorphicTypeInfoResolver. We then configure the resolver to serialize objects of type Shape with all derived types assignable to Shape from its own assembly and the assembly where Parallelogram is located with their name as the type discriminator.

Note: Using the type name for discriminator may result in unstable contracts since you will not be able to deserialize data when you change the type name as part of some refactoring! Instead consider to add all types individually and verify for completeness.

Advanced Features

To supply a factory for the polymorphic JSON options, you can use the following code:

var options = new JsonSerializerOptions {
    TypeInfoResolver = new PolymorphicTypeInfoResolver(options: () => new JsonPolymorphismOptions {
        TypeDiscriminatorPropertyName = "$TYPE"
    })
};

In the above code snippet, we create a new instance of JsonSerializerOptions and set its TypeInfoResolver property to an instance of PolymorphicTypeInfoResolver. We then supply a factory function that returns an instance of JsonPolymorphismOptions with a custom $TYPE type discriminator property name.

Remark: this readme was peer-reviewed by ChatGPT.

Happy coding!