[API Proposal]: Json多态类型处理器，未知类型处理建议

[bunnyi116]

这是官方的例子

https://learn.microsoft.com/zh-cn/dotnet/standard/serialization/system-text-json/polymorphism?pivots=dotnet-7-0

[JsonPolymorphic(
    UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToNearestAncestor)]
[JsonDerivedType(typeof(BasePoint))]
[JsonDerivedType(typeof(IPointWithTimeSeries))]
public interface IPoint { }

public interface IPointWithTimeSeries : IPoint { }

public class BasePoint : IPoint { }

public class BasePointWithTimeSeries : BasePoint, IPointWithTimeSeries { }

提议

官方例子中，处理未知类型时，UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToBaseType返回上一个派生类，我觉得这样处理不太友好，比如我有一个专门处理未知的派生类，那我所有派生类都得继承这个未知处理的类，属实有点麻烦，且命名不方便。

诺能自定义未知处理类，就可以直接指定该类型。

比如在原有的基础上新增一个布尔属性[JsonDerivedType(typeof(UnknownMessage), bool unknownDefaultHandler = true)] 当然这个未知处理类得是抽象或接口实现的派生类。或者添加新的Attribute，如：JsonDefaultDerivedAttribute，至于怎么命名看你们怎么取了。

API Proposal

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

namespace System.Text.Json.Serialization
{
    /// <summary>
    /// When placed on a type declaration, indicates that the specified subtype should be opted into polymorphic serialization.
    /// </summary>
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface, AllowMultiple = true, Inherited = false)]
    public class JsonDerivedTypeAttribute : JsonAttribute
    {
        /// <summary>
        /// Initializes a new attribute with specified parameters.
        /// </summary>
        /// <param name="derivedType">A derived type that should be supported in polymorphic serialization of the declared based type.</param>
        public JsonDerivedTypeAttribute(Type derivedType)
        {
            DerivedType = derivedType;
        }

        /// <summary>
        /// Initializes a new attribute with specified parameters.
        /// </summary>
        /// <param name="derivedType">A derived type that should be supported in polymorphic serialization of the declared base type.</param>
        /// <param name="typeDiscriminator">The type discriminator identifier to be used for the serialization of the subtype.</param>
        public JsonDerivedTypeAttribute(Type derivedType, string typeDiscriminator)
        {
            DerivedType = derivedType;
            TypeDiscriminator = typeDiscriminator;
        }

        /// <summary>
        /// Initializes a new attribute with specified parameters.
        /// </summary>
        /// <param name="derivedType">A derived type that should be supported in polymorphic serialization of the declared base type.</param>
        /// <param name="typeDiscriminator">The type discriminator identifier to be used for the serialization of the subtype.</param>
        public JsonDerivedTypeAttribute(Type derivedType, int typeDiscriminator)
        {
            DerivedType = derivedType;
            TypeDiscriminator = typeDiscriminator;
        }


        public JsonDerivedTypeAttribute(Type derivedType, bool isDefaultHandler )
        {
            DerivedType = derivedType;
            TypeDiscriminator = typeDiscriminator;
IsDefaultHandler = isDefaultHandler ;
        }

        /// <summary>
        /// A derived type that should be supported in polymorphic serialization of the declared base type.
        /// </summary>
        public Type DerivedType { get; }

        /// <summary>
        /// The type discriminator identifier to be used for the serialization of the subtype.
        /// </summary>
        public object? TypeDiscriminator { get; }

        /// <summary>
        /// 是否默认处理
        /// </summary>
        public  bool  IsDefaultHandler { get; }

    }
}

API Usage

[JsonPolymorphic(TypeDiscriminatorPropertyName = "type"]
[JsonDerivedType(typeof(UnknownMessage) , true)]
public abstract record Message
{    
    [JsonPropertyName("type")]
    public required string RawType { get; init; }
}

public record UnknownMessage : Message
{    
......
}

Alternative Designs

No response

Risks

No response

[ghost]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[bunnyi116]

希望能直接定义未知类型处理派生类

[huoyaoyuan]

Native translation:

This is the official example:
[pic]
In the official example, when handling unknown type, UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToBaseType returns its base type, which looks unfriendly to me. For example I have a base class that handles unknown types, all my classes needs to derive from that class, which is bothersome and hard to name.

If unknown type handler can be customized, I can specify that class directly.

For example, adding a new bool property on the original attribute [JsonDerivedType(typeof(UnknownMessage), bool unknownDefaultHandler = true)]. Of course the unknown handling type needs to be abstract or interface-implementing derived class. The attribute design and naming are up to you.

[ghost]

Tagging subscribers to this area: @dotnet/area-system-text-json, @gregsdennis
See info in area-owners.md if you want to be subscribed.

Issue Details

---

这是官方的例子

https://learn.microsoft.com/zh-cn/dotnet/standard/serialization/system-text-json/polymorphism?pivots=dotnet-7-0

[JsonPolymorphic(
    UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToNearestAncestor)]
[JsonDerivedType(typeof(BasePoint))]
[JsonDerivedType(typeof(IPointWithTimeSeries))]
public interface IPoint { }

public interface IPointWithTimeSeries : IPoint { }

public class BasePoint : IPoint { }

public class BasePointWithTimeSeries : BasePoint, IPointWithTimeSeries { }

提议

官方例子中，处理未知类型时，UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToBaseType返回上一个派生类，我觉得这样处理不太友好，比如我有一个专门处理未知的派生类，那我所有派生类都得继承这个未知处理的类，属实有点麻烦，且命名不方便。

诺能自定义未知处理类，就可以直接指定该类型。

比如在原有的基础上新增一个布尔属性[JsonDerivedType(typeof(UnknownMessage), bool unknownDefaultHandler = true)] 当然这个未知处理类得是抽象或接口实现的派生类。或者添加新的Attribute，如：JsonDefaultDerivedAttribute，至于怎么命名看你们怎么取了。

API Proposal

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

namespace System.Text.Json.Serialization
{
    /// <summary>
    /// When placed on a type declaration, indicates that the specified subtype should be opted into polymorphic serialization.
    /// </summary>
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface, AllowMultiple = true, Inherited = false)]
    public class JsonDerivedTypeAttribute : JsonAttribute
    {
        /// <summary>
        /// Initializes a new attribute with specified parameters.
        /// </summary>
        /// <param name="derivedType">A derived type that should be supported in polymorphic serialization of the declared based type.</param>
        public JsonDerivedTypeAttribute(Type derivedType)
        {
            DerivedType = derivedType;
        }

        /// <summary>
        /// Initializes a new attribute with specified parameters.
        /// </summary>
        /// <param name="derivedType">A derived type that should be supported in polymorphic serialization of the declared base type.</param>
        /// <param name="typeDiscriminator">The type discriminator identifier to be used for the serialization of the subtype.</param>
        public JsonDerivedTypeAttribute(Type derivedType, string typeDiscriminator)
        {
            DerivedType = derivedType;
            TypeDiscriminator = typeDiscriminator;
        }

        /// <summary>
        /// Initializes a new attribute with specified parameters.
        /// </summary>
        /// <param name="derivedType">A derived type that should be supported in polymorphic serialization of the declared base type.</param>
        /// <param name="typeDiscriminator">The type discriminator identifier to be used for the serialization of the subtype.</param>
        public JsonDerivedTypeAttribute(Type derivedType, int typeDiscriminator)
        {
            DerivedType = derivedType;
            TypeDiscriminator = typeDiscriminator;
        }


        public JsonDerivedTypeAttribute(Type derivedType, bool isDefaultHandler )
        {
            DerivedType = derivedType;
            TypeDiscriminator = typeDiscriminator;
IsDefaultHandler = isDefaultHandler ;
        }

        /// <summary>
        /// A derived type that should be supported in polymorphic serialization of the declared base type.
        /// </summary>
        public Type DerivedType { get; }

        /// <summary>
        /// The type discriminator identifier to be used for the serialization of the subtype.
        /// </summary>
        public object? TypeDiscriminator { get; }

        /// <summary>
        /// 是否默认处理
        /// </summary>
        public  bool  IsDefaultHandler { get; }

    }
}

API Usage

[JsonPolymorphic(TypeDiscriminatorPropertyName = "type"]
[JsonDerivedType(typeof(UnknownMessage) , true)]
public abstract record Message
{    
    [JsonPropertyName("type")]
    public required string RawType { get; init; }
}

public record UnknownMessage : Message
{    
......
}

Alternative Designs

No response

Risks

No response

Author:	Bunnui
Assignees:	-
Labels:	api-suggestion, area-System.Text.Json, untriaged
Milestone:	-

[eiriktsarpalis]

Note that UnknownDerivedTypeHandling only controls serialization behavior. Your screenshot suggests you're trying to deserialize, so you might want turn on the IgnoreUnrecognizedTypeDiscriminators property instead.

[bunnyi116]

Note that UnknownDerivedTypeHandling only controls serialization behavior. Your screenshot suggests you're trying to deserialize, so you might want turn on the IgnoreUnrecognizedTypeDiscriminators property instead.

Approximate structure

No unknown type

Unknown type

Other

Although it can catch exceptions and solve them, I hope it can handle them by default

Code block

/// <summary>
/// 消息
/// </summary>
[JsonPolymorphic(TypeDiscriminatorPropertyName = "type",
    UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToNearestAncestor,
    IgnoreUnrecognizedTypeDiscriminators = true)]
[JsonDerivedType(typeof(UnknownMessage))]
[JsonDerivedType(typeof(SourceMessage), "Source")]
[JsonDerivedType(typeof(QuoteMessage), "Quote")]
// ......
public abstract record Message
{
    /// <summary>
    /// 消息类型（原始）
    /// </summary>
    [JsonPropertyName("type")]
    public required string TypeString { get; init; }

    /// <summary>
    /// 消息类型
    /// </summary>
    [JsonIgnore]
    public MessageType Type
    {
        get
        {
            if (Enum.TryParse<MessageType>(TypeString, true, out var type))
            {
                return type;
            }
            return MessageType.Unknown;
        }
    }
    
    /// <summary>
    /// 构造函数
    /// </summary>
    [SetsRequiredMembers]
    public Message()
    {
        TypeString = MessageType.Unknown.GetEnumName();
    }
    
    /// <summary>
    /// 构造函数
    /// </summary>
    /// <param name="typeString">消息类型</param>
    [JsonConstructor]
    [SetsRequiredMembers]
    public Message(string typeString)
    {
        TypeString = typeString;
    }
    
    /// <summary>
    /// 构造函数
    /// </summary>
    /// <param name="messageType">消息类型</param>
    [SetsRequiredMembers]
    public Message(MessageType messageType) : this(messageType.GetEnumName())
    {
    }
}

public record UnknownMessage : Message
{

    [JsonConstructor]
    [SetsRequiredMembers]
    public UnknownMessage() : base(MessageType.Unknown.GetEnumName())
    {
    }
    
    [SetsRequiredMembers]
    public UnknownMessage(string typeString) : base(typeString)
    {
    }
    
    protected override bool PrintMembers(StringBuilder builder)
    {
        base.PrintMembers(builder);
    
        var sb = new StringBuilder();
        //if (RawData != null)
        //{
        //    sb.Append(", ");
        //    sb.Append($"{nameof(RawData)} = {RawData}");
        //}
    
        var append = sb.ToString();
        if (base.PrintMembers(builder))
        {
            if (append.Length > 0)
            {
                builder.Append(append.TrimStart(',', ' '));
            }
        }
        else
        {
            if (append.Length > 0)
            {
                builder.Append(append);
            }
        }
        return true;
    }
}

Error

Deserialization of types without a parameterless constructor, a singular parameterized constructor, or a parameterized constructor annotated with 'JsonConstructorAttribute' is not supported. Type 'MiraiNet.Models.Datas.Messages.Message'. Path: $[19] | LineNumber: 115 | BytePositionInLine: 11.

[bunnyi116]

[eiriktsarpalis]

The exception message occurs because your Message record is abstract, and therefore does not support deserialization. When enabling IgnoreUnrecognizedTypeDiscriminators I you would generally speaking need a base type that is deserializable. You can do that either by removing the abstract keyword from message, or alternatively use contract customization to manually set the CreateObject delegate so that it initializes an instance of Message that suits your use case.

[bunnyi116]

I deleted the abstract keyword, made him a basic type, and set IgnoreUnrecognizedTypeDiscriminators to enable, I tried to pass in an unknown type, the polymorphic discriminator did not deserialize him into a basic type and the value of "type" in the basic type changed is of empty type.

You can only use the parameterless constructor to pass in the default value, and you can't get the original "type" value

I tried to add the discriminator again using the interface, the value of the basic type "type" is deserialized normally, it is his type that is not deserialized correctly to the derived class, so the type conversion cannot be performed.

[bunnyi116]

Test demo

using System.Diagnostics.CodeAnalysis;
using System.Text.Json;
using System.Text.Json.Serialization;
var json = """
    [
      {
        "type": "Source",
        "id": 123456,
        "time": 1678349426
      },
      {
        "type": "Plain",
        "text": "TestPlain"
      },
      {
        "type": "Abc",
        "text": "TestAbc"
      }
    ]
    """;

var root = JsonSerializer.Deserialize<MessageMetadata[]>(json);
foreach (var metadata in root!)
{
    if (metadata.Type == Constants.Plain)
    {
        Console.WriteLine((PlainMessage)metadata);
    }
    else
    {
        Console.WriteLine(metadata);
    }
}

public class Constants
{
    public const string Source = "Source";
    public const string Plain = "Plain";
    public const string Unknown = "Unknown";
    // ...
}

//[JsonPolymorphic(TypeDiscriminatorPropertyName = "type", IgnoreUnrecognizedTypeDiscriminators = true, UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToNearestAncestor)]
//[JsonDerivedType(typeof(MessageMetadata))]
//// [JsonDerivedType(typeof(UnknownMessage))]
//[JsonDerivedType(typeof(SourceMessage), Constants.Source)]
//[JsonDerivedType(typeof(PlainMessage), Constants.Plain)]
public interface IMessageMetadata
{
    [JsonPropertyOrder(-1)]
    [JsonPropertyName("type")]
    string Type { get; }
}


[JsonPolymorphic(TypeDiscriminatorPropertyName = "type", IgnoreUnrecognizedTypeDiscriminators = true, UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToNearestAncestor)]
[JsonDerivedType(typeof(MessageMetadata))]
// [JsonDerivedType(typeof(UnknownMessage))]
[JsonDerivedType(typeof(SourceMessage), Constants.Source)]
[JsonDerivedType(typeof(PlainMessage), Constants.Plain)]
public record MessageMetadata : IMessageMetadata
{
    [JsonPropertyOrder(-1)]
    [JsonPropertyName("type")]
    public required string Type { get; init; } = Constants.Unknown;

    [SetsRequiredMembers]
    public MessageMetadata(string type)
    {
        Type = type;
    }
}


public record SourceMessage : MessageMetadata
{
    [JsonPropertyName("id")]
    public required int Id { get; init; }

    [JsonPropertyName("time")]
    public required int Time { get; init; }

    [SetsRequiredMembers]
    public SourceMessage(int id, int time) : base(Constants.Source)
    {
        Id = id;
        Time = time;
    }
}

public record PlainMessage : MessageMetadata
{
    [JsonPropertyName("text")]
    public required string Text { get; init; }

    [SetsRequiredMembers]
    public PlainMessage(string text) : base(Constants.Plain)
    {
        Text = text;
    }
}

public record UnknownMessage : MessageMetadata
{
    // ...
    [SetsRequiredMembers]
    public UnknownMessage() : base(Constants.Unknown)
    {
    }
}

[bunnyi116]

IgnoreUnrecognizedTypeDiscriminators just ignored the unknown type exception, he returned to the basic type, but in fact he did not deserialize the existing content

[bunnyi116]

Currently I can turn off IgnoreUnrecognizedTypeDiscriminators and then catch the exception and handle it. The System.Text.Json polymorphic discriminator does not seem to work well when deserializing. What I hope is that I can directly specify a class in JsonDerivedTypeAttribute to handle this type of unknown exception, and fall back to the basic type if it is not specified.

[bunnyi116]

谢谢你的提醒，我这边创建了一个接口，Message记承了这个接口作为基类（非抽象），虽然是他已经正常工作，但他没有达到我的预期。他仅返回到了基类，但我希望他能够使用我用基类实现的未知处理类（[JsonDerivedType(typeof(UnknownMessage))]）。
，所以我才会请求新增指定自定义未知处理类型功能以便更快的达到自定义处理未知的类型，就不需要再次类型交换

Machine translation

Thank you for your reminder. I have created an interface here, and Message has inherited this interface as a base class (non-abstract). Although it has been working normally, it has not met my expectations. He just falls back to the base class, but I want him to be able to use the unknown handler class ([JsonDerivedType(typeof(UnknownMessage))]) that I implemented with the base class.
, so I will request to add the function of specifying a custom unknown processing type so that the custom processing unknown type can be reached faster, and there is no need to exchange types again

Image

[bunnyi116]

我觉得可以在 JsonDerivedTypeAttribute 中添加一个布尔类型属性，或是创建一个新的Attribute，或TypeDiscriminator为null时，序列化与反序列化遇到未知的类型名称使用这个类型进行序列化和反序列化时，如果没有这个标识，在做退回到基类处理。

I think you can add a Boolean type attribute to JsonDerivedTypeAttribute, or create a new Attribute, or when TypeDiscriminator is null, serialization and deserialization encounter unknown type names and use this type for serialization and deserialization When , if there is no such flag, it will return to the base class for processing.

[bunnyi116]

This is just a suggestion. JsonSerializer.Deserialize can directly deserialize the customization derived from this base class, so why let us convert the type in an extra layer.

[bunnyi116]

By the way, in addition to referring to the custom unknown processing class, can you add a function to return the data of this segment. Similar to [JsonPolymorphic(TypeDiscriminatorPropertyName = "type"], get a raw data of this segment [JsonPolymorphic(XXXX = "data")] `

[Xyncgas]

https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/polymorphism?pivots=dotnet-7-0