[API Proposal]: Add JsonSerializer overloads accepting non-generic JsonTypeInfo

[eiriktsarpalis]

Background and motivation

The JsonSerializer class exposes serialization and deserialization overloads that accept JsonTypeInfo<T>. These overloads are generally marked AOT/linker-safe and provide the only entrypoint for serializing using materialized metadata instances. We are however missing non-generic overloads for doing the same thing.

API Proposal

namespace System.Text.Json;

public partial static class JsonSerializer
{
    public static object? Deserialize(string json, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(ReadOnlySpan<byte> utf8Json, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(ref Utf8JsonReader reader, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(Stream utf8Json, JsonTypeInfo jsonTypeInfo);
    public static ValueTask<object?> DeserializeAsync(Stream utf8Json, JsonTypeInfo jsonTypeInfo, CancellationToken cancellationToken = default);
    public static object? Deserialize(JsonDocument document, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(JsonElement element, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(JsonNode node, JsonTypeInfo jsonTypeInfo);

    public static string Serialize(object? value, JsonTypeInfo jsonTypeInfo);
    public static byte[] SerializeToUtf8Bytes(object? value, JsonTypeInfo jsonTypeInfo);
    public static void Serialize(Utf8JsonWriter writer, object? value, JsonTypeInfo jsonTypeInfo);
    public static void Serialize(Stream utf8Json, object? value, JsonTypeInfo jsonTypeInfo);
    public static Task SerializeAsync(Stream utf8Json, object? value, JsonTypeInfo jsonTypeInfo, CancellationToken cancellationToken = default);
    public static JsonDocument SerializeToDocument(object? value, JsonTypeInfo jsonTypeInfo);
    public static JsonElement SerializeToElement(object? value, JsonTypeInfo jsonTypeInfo);
    public static JsonNode SerializeToNode(object? value, JsonTypeInfo jsonTypeInfo);
}

API Usage

The following example shows how we can perform non-generic serialization without invoking any of the RequiresUnreferencedCode APIs:

var options = new JsonSerializerOptions 
{ 
    TypeInfoResolver = JsonTypeInfoResolver.Combine(ContextA.Default, ContextB.Default)
};

JsonTypeInfo typeInfo = options.GetTypeInfo(typeof(SupportedPoco));
object? result = JsonSerializer.Deserialize("{}", typeInfo);
Console.WriteLine(result is SupportedPoco); // True

Alternative Designs

No response

Risks

No response

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

---

Background and motivation

The JsonSerializer class exposes serialization and deserialization overloads that accept JsonTypeInfo<T>. These overloads are generally marked AOT/linker-safe and provide the only entrypoint for serializing using materialized metadata instances. We are however missing non-generic overloads for doing the same thing.

API Proposal

namespace System.Text.Json;

public partial static class JsonSerializer
{
    public static object? Deserialize(string json, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(ReadOnlySpan<byte> utf8Json, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(ref Utf8JsonReader reader, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(Stream utf8Json, JsonTypeInfo jsonTypeInfo);
    public static ValueTask<object?> DeserializeAsync(Stream utf8Json, JsonTypeInfo jsonTypeInfo, CancellationToken cancellationToken = default);
    public static object? Deserialize(JsonDocument document, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(JsonElement element, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(JsonNode node, JsonTypeInfo jsonTypeInfo);

    public static string Serialize(object? value, JsonTypeInfo jsonTypeInfo);
    public static byte[] SerializeToUtf8Bytes(object? value, JsonTypeInfo jsonTypeInfo);
    public static void Serialize(Utf8JsonWriter writer, object? value, JsonTypeInfo jsonTypeInfo);
    public static void Serialize(Stream utf8Json, object? value, JsonTypeInfo jsonTypeInfo);
    public static Task SerializeAsync(Stream utf8Json, object? value, JsonTypeInfo jsonTypeInfo, CancellationToken cancellationToken = default);
    public static JsonDocument SerializeToDocument(object? value, JsonTypeInfo jsonTypeInfo);
    public static JsonElement SerializeToElement(object? value, JsonTypeInfo jsonTypeInfo);
    public static JsonNode SerializeToNode(object? value, JsonTypeInfo jsonTypeInfo);
}

API Usage

The following example shows how we can perform non-generic serialization without invoking any of the RequiresUnreferencedCode APIs:

var options = new JsonSerializerOptions 
{ 
    TypeInfoResolver = JsonTypeInfoResolver.Combine(ContextA.Default, ContextB.Default)
};

JsonTypeInfo typeInfo = options.GetTypeInfo(typeof(SupportedPoco));
object? result = JsonSerializer.Deserialize("{}", typeInfo);
Console.WriteLine(result is SupportedPoco); // True

Alternative Designs

No response

Risks

No response

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

[eiriktsarpalis]

cc @eerhardt @brunolins16 the APIs above would provide a mechanism to perform untyped, linker-safe serialization.

They can be used as an alternative to the proposal in #74492, via the workaround proposed in #74492 (comment)

[bartonjs]

• As these are just the weakly typed variant of the existing JsonTypeInfo overloads, looks good as proposed.
• We caught two missing members (Deserialize(ROS<char>), DeserializeAsyncEnumerable) and added them.

namespace System.Text.Json;

public static partial class JsonSerializer
{
    public static object? Deserialize(string json, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(ReadOnlySpan<byte> utf8Json, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(ReadOnlySpan<char> json, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(ref Utf8JsonReader reader, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(Stream utf8Json, JsonTypeInfo jsonTypeInfo);
    public static ValueTask<object?> DeserializeAsync(Stream utf8Json, JsonTypeInfo jsonTypeInfo, CancellationToken cancellationToken = default);
    public static IAsyncEnumerable<object?> DeserializeAsyncEnumerable(Stream utf8Json, JsonTypeInfo jsonTypeInfo, CancellationToken cancellationToken = default);
    public static object? Deserialize(JsonDocument document, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(JsonElement element, JsonTypeInfo jsonTypeInfo);
    public static object? Deserialize(JsonNode node, JsonTypeInfo jsonTypeInfo);

    public static string Serialize(object? value, JsonTypeInfo jsonTypeInfo);
    public static byte[] SerializeToUtf8Bytes(object? value, JsonTypeInfo jsonTypeInfo);
    public static void Serialize(Utf8JsonWriter writer, object? value, JsonTypeInfo jsonTypeInfo);
    public static void Serialize(Stream utf8Json, object? value, JsonTypeInfo jsonTypeInfo);
    public static Task SerializeAsync(Stream utf8Json, object? value, JsonTypeInfo jsonTypeInfo, CancellationToken cancellationToken = default);
    public static JsonDocument SerializeToDocument(object? value, JsonTypeInfo jsonTypeInfo);
    public static JsonElement SerializeToElement(object? value, JsonTypeInfo jsonTypeInfo);
    public static JsonNode? SerializeToNode(object? value, JsonTypeInfo jsonTypeInfo);
}