Expose instance methods in JsonSerializer

[eiriktsarpalis]

Background & Motivation

The current design of the JsonSerializer class exposes all serialization functionality as static methods accepting configuration parametrically (and optionally). In hindsight, this design has contributed to a few ergonomic problems when using this API:

1. Forgetting to pass JsonSerializerOptions to the serialization methods:

   var options = new JsonSerializerOptions { Converters = { new JsonStringEnumConverter() }};
   JsonSerializer.Serialize(MyEnum.Value);

   This is probably the most common issue -- I've personally fallen for this too many times.

2. Creating a new JsonSerializerOptions instance on each serialization:

   foreach (MyPoco value in values)
   {
        var options = new JsonSerializerOptions  { Converters = { new JsonStringEnumConverter() }};
        JsonSerializer.Serialize(value, options); // recalculates JSON contracts from scratch on each iteration
   }

   Even though this anti-pattern has been explicitly documented as a potential performance bug, users keep falling for it. We've made attempts to mitigate the problem by implementing shared metadata caches but ultimately the underlying issue still affects users. See also Add an analyzer that warns on single-use JsonSerializerOptions instances #65396 for plans an adding an analyzer in this space.

3. Pervasive RequiresUnreferenceCode/RequiresDynamicCode annotations: all serialization methods accepting JsonSerializerOptions have been annotated as linker/AOT-unsafe even though legitimate scenaria exist where this is not the case:

   var options = new JsonSerializerOptions { TypeInfoResolver = MySourceGeneratedContext.Default };
   JsonSerializer.Serialize(value, options); // warning: JSON serialization and deserialization might require types that cannot be statically analyzed.

4. Bifurcation of API surface between reflection and source generation: users need to call into distinct methods depending on whether they use sourcegen or reflection. The distinction between JsonSerializerOptions and JsonSerializerContext has always been tenuous and has been rendered obsolete with the infrastructural changes introduced by Developers can customize the JSON serialization contracts of their types #63686. Arguably, the source of JSON contracts is a configuration detail that should be dealt with at the composition root and not concern any serialization methods.

API Proposal

This issue proposes we expose instance methods in JsonSerializer (or some different class):

namespace System.Text.Json;

public partial class JsonSerializerInstance // TODO come up with a better name
{
    public JsonSerializerOptions Options { get; }

    public JsonSerializer(JsonSerializerOptions options); // linker-safe constructor, throws if options.TypeInfoResolver == null;
                                                          // we might consider adding a linker-unsafe factory that populates TypeInfoResolver with the reflection resolver, like the existing serialization APIs do.

    [RequiresUnreferencedCode]
    public static JsonSerializer Default { get; } // serializer wrapping JsonSerializerOptions.Default


    /* Serialization APIs */

    public string Serialize<TValue>(TValue value);
    public byte[] SerializeToUtf8Bytes<TValue>(TValue value);
    public void Serialize<TValue>(Utf8JsonWriter utf8Json, TValue value);
    public void Serialize<TValue>(Stream utf8Json, TValue value);
    public void SerializeAsync<TValue>(Stream utf8Json, TValue value);
    public JsonDocument SerializeToDocument<TValue>(TValue value);
    public JsonElement SerializeToElement<TValue>(TValue value);
    public JsonNode SerializeToNode<TValue>(TValue value);

    public string Serialize(object? value, Type inputType);
    public byte[] SerializeToUtf8Bytes(object? value, Type inputType);
    public void Serialize(Utf8JsonWriter writer, object? value, Type inputType);
    public void Serialize(Stream utf8Json, object? value, Type inputType);
    public void SerializeAsync(Stream utf8Json, object? value, Type inputType);
    public JsonDocument SerializeToDocument(object? value, Type inputType);
    public JsonElement SerializeToElement(object? value, Type inputType);
    public JsonNode SerializeToNode(object? value, Type inputType);

    /* Deserialization APIs */

    public TValue? Deserialize<TValue>(string json);
    public TValue? Deserialize<TValue>(ReadOnlySpan<char> json);
    public TValue? Deserialize<TValue>(ReadOnlySpan<byte> utf8Json);
    public TValue? Deserialize<TValue>(ref Utf8JsonReader reader);
    public TValue? Deserialize<TValue>(Stream utf8Json);
    public ValueTask<TValue?> DeserializeAsync<TValue>(Stream utf8Json);
    public IAsyncEnumerable<TValue?> DeserializeAsyncEnumerable<TValue>(Stream utf8Json);
    public TValue? Deserialize<TValue>(JsonDocument document);
    public TValue? Deserialize<TValue>(JsonElement element);
    public TValue? Deserialize<TValue>(JsonNode node);

    public object? Deserialize(ReadOnlySpan<byte> utf8Json, Type returnType);
    public object? Deserialize(ReadOnlySpan<char> json, Type returnType);
    public object? Deserialize(string json, Type returnType);
    public object? Deserialize(JsonDocument document, Type returnType);
    public object? Deserialize(JsonElement element, Type returnType);
    public object? Deserialize(JsonNode node, Type returnType);
    public object? Deserialize(ref Utf8JsonReader reader, Type returnType);
    public object? Deserialize(Stream utf8Json, Type returnType);
    public ValueTask<object?> DeserializeAsync(Stream utf8Json, Type returnType);
}

namespace System.Text.Json.Serialization;

public partial class JsonSerializerContext
{
     public JsonSerializer Serializer { get; }
}

Usage Examples

Using the reflection-based serializer

/* composition root */
var options = new JsonSerializerOptions 
{ 
    Converters = new JsonStringEnumConverter(), 
    TypeInfoResolver = new DefaultJsonTypeInfoResolver() 
};

var serializer = new JsonSerializer(options);

/* usage */
serializer.Serialize(value); 

Using the source generator

JsonSerializer serializer = MyContext.Default.Serializer;
serializer.Serialize(new MyPoco()); // Serializes using the source generator 

[JsonSerializable(typeof(MyPoco))]
public partial class MyContext : JsonSerializerContext
{}

Open Questions

• Should we reuse the existing JsonSerializer class or introduce a new type?
• Should we have an obsoletion plan for static APIs accepting JsonSerializerOptions?

Related to #65396, #31094, #64646

cc @eerhardt @davidfowl @ericstj

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 & Motivation

The current design of the JsonSerializer class exposes all serialization functionality as static methods accepting configuration parametrically (and optionally). In hindsight, this design has contributed to a few ergonomic problems when using this API:

1. Forgetting to pass JsonSerializerOptions to the serialization methods:

   var options = new JsonSerializerOptions { Converters = { new JsonStringEnumConverter() }};
   JsonSerializer.Serialize(MyEnum.Value);

   This is probably the most common issue -- I've personally fallen for this too many times.

2. Creating a new JsonSerializerOptions instance on each serialization:

   foreach (MyPoco value in values)
   {
        var options = new JsonSerializerOptions  { Converters = { new JsonStringEnumConverter() }};
        JsonSerializer.Serialize(value, options); // recalculates JSON contracts from scratch on each iteration
   }

   Even though this anti-pattern has been explicitly documented as a potential performance bug, users keep falling for it. We've made attempts to mitigate the problem by implementing shared metadata caches but ultimately the underlying issue still affects users. See also Add an analyzer that warns on single-use JsonSerializerOptions instances #65396 for plans an adding an analyzer in this space.

3. Pervasive RequiresUnreferenceCode/RequiresDynamicCode annotations: all serialization methods accepting JsonSerializerOptions have been annotated as linker/AOT-unsafe even though legitimate scenaria exist where this is not the case:

   var options = new JsonSerializerOptions { TypeInfoResolver = MySourceGeneratedContext.Default };
   JsonSerializer.Serialize(value, options); // warning: JSON serialization and deserialization might require types that cannot be statically analyzed.

API Proposal

This issue proposes we expose instance methods in JsonSerializer (or some different class):

namespace System.Text.Json;

public partial class JsonSerializer // Changed from static class
{
    public JsonSerializerOptions Options { get; }

    public JsonSerializer(JsonSerializerOptions options); // linker-safe constructor, throws if options.TypeInfoResolver == null;
                                                          // we might consider adding a linker-unsafe factory that populates TypeInfoResolver with the reflection resolver, like the existing serialization APIs do.

    [RequiresUnreferencedCode]
    public static JsonSerializer Default { get; } // serializer wrapping JsonSerializerOptions.Default


    /* Serialization APIs */

    public string Serialize<TValue>(TValue value);
    public byte[] SerializeToUtf8Bytes<TValue>(TValue value);
    public void Serialize<TValue>(Utf8JsonWriter utf8Json, TValue value);
    public void Serialize<TValue>(Stream utf8Json, TValue value);
    public void SerializeAsync<TValue>(Stream utf8Json, TValue value);
    public JsonDocument SerializeToDocument<TValue>(TValue value);
    public JsonElement SerializeToElement<TValue>(TValue value);
    public JsonNode SerializeToNode<TValue>(TValue value);

    public string Serialize(object? value, Type inputType);
    public byte[] SerializeToUtf8Bytes(object? value, Type inputType);
    public void Serialize(Utf8JsonWriter writer, object? value, Type inputType);
    public void Serialize(Stream utf8Json, object? value, Type inputType);
    public void SerializeAsync(Stream utf8Json, object? value, Type inputType);
    public JsonDocument SerializeToDocument(object? value, Type inputType);
    public JsonElement SerializeToElement(object? value, Type inputType);
    public JsonNode SerializeToNode(object? value, Type inputType);

    /* Deserialization APIs */

    public TValue? Deserialize<TValue>(string json);
    public TValue? Deserialize<TValue>(ReadOnlySpan<char> json);
    public TValue? Deserialize<TValue>(ReadOnlySpan<byte> utf8Json);
    public TValue? Deserialize<TValue>(ref Utf8JsonReader reader);
    public TValue? Deserialize<TValue>(Stream utf8Json);
    public ValueTask<TValue?> DeserializeAsync<TValue>(Stream utf8Json);
    public IAsyncEnumerable<TValue?> DeserializeAsyncEnumerable<TValue>(Stream utf8Json);
    public TValue? Deserialize<TValue>(JsonDocument document);
    public TValue? Deserialize<TValue>(JsonElement element);
    public TValue? Deserialize<TValue>(JsonNode node);

    public object? Deserialize(ReadOnlySpan<byte> utf8Json, Type returnType);
    public object? Deserialize(ReadOnlySpan<char> json, Type returnType);
    public object? Deserialize(string json, Type returnType);
    public object? Deserialize(JsonDocument document, Type returnType);
    public object? Deserialize(JsonElement element, Type returnType);
    public object? Deserialize(JsonNode node, Type returnType);
    public object? Deserialize(ref Utf8JsonReader reader, Type returnType);
    public object? Deserialize(Stream utf8Json, Type returnType);
    public ValueTask<object?> DeserializeAsync(Stream utf8Json, Type returnType);
}

namespace System.Text.Json.Serialization;

public partial class JsonSerializerContext
{
     public JsonSerializer Serializer { get; }
}

Usage Examples

Using the reflection-based serializer

/* composition root */
var options = new JsonSerializerOptions 
{ 
    Converters = new JsonStringEnumConverter(), 
    TypeInfoResolver = new DefaultJsonTypeInfoResolver() 
};

var serializer = new JsonSerializer(options);

/* usage */
serializer.Serialize(value); 

Using the source generator

JsonSerializer serializer = MyContext.Default.Serializer;
serializer.Serialize(new MyPoco()); // Serializes using the source generator 

[JsonSerializable(typeof(MyPoco))]
public partial class MyContext : JsonSerializerContext
{}

Open Questions

• Should we reuse the existing JsonSerializer class or introduce a new type?
• Should we have an obsoletion plan for static APIs accepting JsonSerializerOptions?

Related to #65396, #31094, #64646

cc @eerhardt @davidfowl @ericstj

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

[krwq]

IMO while it could be a good idea when we first created this project I'm not so convinced to do it now and creating second set of the same APIs elsewhere just feels weird. I think it might make more sense to create code analyzer to hint people they're using it wrong. I'm also tempted to say if anything maybe put those methods on the options directly but then it would "weird really read": options.Serialize(...)

[eerhardt]

Should we have an obsoletion plan for static APIs accepting JsonSerializerOptions?

Why would we obsolete this?

[eiriktsarpalis]

Should we have an obsoletion plan for static APIs accepting JsonSerializerOptions?

Why would we obsolete this?

We don't need to, strictly speaking, but it seems to be too much of a pit of failure at the moment. Obsoletion could be one way to guide users to the new APIs.

[davidfowl]

Or an analyzer?

[layomia]

Pervasive RequiresUnreferenceCode/RequiresDynamicCode annotations: all serialization methods accepting JsonSerializerOptions have been annotated as linker/AOT-unsafe even though legitimate scenaria exist where this is not the case

This is pretty compelling, but if we're not going to deprecate the existing static APIs, then it seems moot given that there are existing patterns to avoid the linker warnings. New APIs would add to an increasingly high concept count for using the serializer. New fixers to help users to help users detect and switch bad patterns would perhaps be sufficient to solve these problems.

[gregsdennis]

@eiriktsarpalis can you show how your problem examples would change? This might help explain how exposing these methods will solve the problems those scenarios present.

Also, if we've already documented that people shouldn't do these things, how will these changes alter users' behavior?