[API Proposal]: JsonSourceGenerationOptions should support ReferenceHandler

[petro2050]

Background and motivation

Provide a way to specify a reference handler using compile-time configuration.

API Proposal

The ReferenceHandler type is a class and therefore it cannot be specified in literal annotations. If we wanted to add support for that it would require introducing a proxy enum type, in the style of JsonKnownEnumPolicy. However that would leave out support for user-defined reference handlers in case that matters:

namespace System.Text.Json.Serialization;

public enum KnownReferenceHandler // Naming follows the ReferenceHandler type which misses a Json prefix
{ 
     IgnoreCycles = 1,
     Preserve = 2,
     Unspecified = 0,
}

public partial class JsonSourceGenerationOptionsAttribute
{
    public JsonKnownReferenceHandler ReferenceHandler { get; set; }
}

API Usage

[JsonSourceGenerationOptions(WriteIndented = true, ReferenceHandler = KnownReferenceHandler.IgnoreCycles)]
[JsonSerializable(typeof(WeatherForecast))]
partial class SourceGenerationContext : JsonSerializerContext;

Alternative Designs

No response

Risks

No response

[dotnet-policy-service]

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

[eiriktsarpalis]

The ReferenceHandler type is a class and therefore it cannot be specified in literal annotations. If we wanted to add support for that it would required introducing a proxy enum type, in the style of JsonKnownEnumPolicy. However that would leave out support for user-defined reference handlers in case that matters:

namespace System.Text.Json.Serialization;

public enum JsonKnownReferenceHandler 
{ 
     IgnoreCycles = 1,
     Preserve = 2,
     Unspecified = 0,
}

public partial class JsonSourceGenerationOptionsAttribute
{
    public JsonKnownReferenceHandler ReferenceHandler { get; set; }
}

Would that cover your use case?

[huoyaoyuan]

User-defined handler type could be specified with typeof in attributes.

BTW, is it actionable to support user-defined naming style in SG mode? Since generated metadata needs to materialize the type info, the serialized field names can no longer be generated as constants.

[eiriktsarpalis]

User-defined handler type could be specified with typeof in attributes.

The implementation types are not public I'm afraid: https://learn.microsoft.com/en-us/dotnet/api/system.text.json.serialization.referencehandler?view=net-8.0

BTW, is it actionable to support user-defined naming style in SG mode? Since generated metadata needs to materialize the type info, the serialized field names can no longer be generated as constants.

I'm not sure I follow the question, could you give an example?

[petro2050]

@eiriktsarpalis JsonKnownReferenceHandler would cover my case.

Just wondering if this can be prioritized. I'm trying to switch to AOT, but Serialize<TValue>(TValue value, JsonSerializerOptions? options = null) (which I'm using today) requires unreferenced/dynamic code, so I'd like to pass a JsonTypeInfo<T> to a shared serializer project that gets referenced by multiple other projects. In other words, I'm looking for a generic solution. I'd also like to avoid passing the context itself since JsonTypeInfo<T> provides type safety.

definition:
public static string Serialize<T>(T value, JsonTypeInfo<T> typeInfo);

usage:
JsonHelper.Serialize(car, ProjectXContext.Default.Car);

[huoyaoyuan]

BTW, is it actionable to support user-defined naming style in SG mode? Since generated metadata needs to materialize the type info, the serialized field names can no longer be generated as constants.

I'm not sure I follow the question, could you give an example?

For this code snippet:

public class MyType
{
    public string SomeProperty { get; set; }
}

[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.SnakeCaseLower)]
[JsonSerializable(typeof(MyType))]
public partial class MyContext : JsonSerializerContext { }

Currently there will be PropName_some_property = JsonEncodedText.Encode("some_property"); generated, which executes the known naming policy at compile time. However for custom naming policy, it can't be executed so.

It was desired because snake case wasn't even a built-in naming policy in previous versions.

[eiriktsarpalis]

Just wondering if this can be prioritized.

It's still possible to use reference handling with the source generator, but it requires slightly more boilerplate. This works with Native AOT:

JsonSerializer.Serialize(new MyPoco("John", 30), MyContext.Custom.MyPoco); // {"$id":"1","Name":"John","Age":30}

record MyPoco(string Name, int Age);

[JsonSerializable(typeof(MyPoco))]
partial class MyContext : JsonSerializerContext
{
    public static MyContext Custom { get; } = new(new JsonSerializerOptions 
    { 
        ReferenceHandler = ReferenceHandler.Preserve,
        WriteIndented = true,
    });
}

I'm not sure I follow the question, could you give an example?

For this code snippet:

I see, the naming policy is run at compile time as a performance optimization for the fast-path serializer but it doesn't need to do so. Assuming we had an API where either the naming policies or reference handlers were exposed as named types (they are not today) we might conceivably have an API that lets users nominate their own implementations (as is the case with the JsonSourceGenerationOptionsAttribute.Converters property today), but I'm not super convinced we want to do this.