Provide fast-path serialization logic in JSON source generator

[layomia]

The JSON source generator (#45448) takes a metadata-based approach where reflection-based type metadata gathering is moved from run-time to compile time. This primarily helps improve start-up time, privates bytes usage, and app size.

For simple JsonSerializerOptions usages, we can also generate serialization logic using Utf8JsonWriter directly. which can help improve serialization throughput.

API Proposal

namespace System.Text.Json.Serialization.Metadata
{
    public abstract partial class JsonTypeInfo<T>
    {
        // Existing:
        // internal JsonTypeInfo() { }

        // A method that can be called to serialize an instance of T, using <see cref="JsonSerializerOptions"/> specified at compile-time.
        public Action<Utf8JsonWriter, T>? Serialize { get; set; }
    }

    // Instructs the System.Text.Json source generator to assume the specified options will be used at run-time via <see cref="JsonSerializerOptions"/>.
    [AttributeUsage(AttributeTargets.Assembly, AllowMultiple = false)]
    public class JsonSerializerOptionsAttribute : JsonAttribute
    {
        // Specifies the default ignore condition.
        public JsonIgnoreCondition DefaultIgnoreCondition { get; set; }

        // Specifies whether to ignore read-only fields.
        public bool IgnoreReadOnlyFields { get; set; }

        // Specifies whether to ignore read-only properties.
        public bool IgnoreReadOnlyProperties { get; set; }

        // Specifies whether to ignore custom converters provided at run-time.
        public bool IgnoreRuntimeCustomConverters { get; set; }

        // Specifies whether to include fields for serialization and deserialization.
        public bool IncludeFields { get; set; }

        // Specifies a built-in naming polices to convert JSON property names with.
        public JsonKnownNamingPolicy NamingPolicy { get; set; }

        // Specifies whether JSON output should be pretty-printed.
        public bool WriteIndented { get; set; }
    }
}

namespace System.Text.Json.Serialization
{
    // Existing: [AttributeUsage(AttributeTargets.Assembly, AllowMultiple = true)]
    [AttributeUsage(AttributeTargets.Assembly | AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Interface, AllowMultiple = true)]
    public sealed class JsonSerializableAttribute : Attribute
    {
        // Existing:
        // public string TypeInfoPropertyName { get; set; }
        // public JsonSerializableAttribute(Type type) { }

        // Constructor to be place directly on types.
        public JsonSerializableAttribute() { }

        // Instructs the generator on what to generate for the type.
        public JsonSourceGenerationMode GenerationMode { get; set; }
    }
  
    public enum JsonKnownNamingPolicy
    {
        Unspecified = 0,
        BuiltInCamelCase = 1
    }

    // The mode for source generation by the System.Text.Json source generator.
    public enum JsonSourceGenerationMode
    {
        // Instructs the JSON source generator to generate serialization logic
       // and type metadata to fallback to when the run-time options don't match.
        MetadataAndSerialization = 0,

        // Instructs the JSON source generator to generate type-metadata initialization logic.
        Metadata = 1,

        // Instructs the JSON source generator to generate serialization logic.
        Serialization = 2,
    }
}

Feature behavior

• Fast-path methods are only overriden when [JsonSerializerOptionsAttribute] is used.
• The generated JsonContext.Default property will generate/use an options populated with the values from the [JsonSerializerOptionsAttribute].

Scenarios

Given a simple type:

[JsonSerializable]
public struct JsonMessage​
{​
    public string Message { get; set; }​
}​

Calling fast-path directly

[assembly: JsonSerializerOptions(NamingPolicy = JsonKnownNamingPolicy.BuiltInCamelCase)]

JsonTypeInfo<JsonMessage> messageInfo = JsonContext.Default.JsonMessage;​

​var ms = new MemoryStream();​
using (var writer = new Utf8JsonWriter(ms))​
{​
    messageInfo.Serialize!(writer, message);​
}​

Using fast-path via JsonSerializer

Some features like reference-loop handling & async (de)serialization are not supported in generated fast-path logic. For those cases, the context or type info should be passed to the serializer directly. The serializer will detect when the fast path can be called or not. For example for reference-handling, the serializer would know that it can call the fast-path logic for primitives and structs.

[assembly: JsonSerializerOptions]

JsonContext context = new JsonContext(new JsonSerializerOptions() { ReferenceHandler = ReferenceHandler.Preserve });
JsonSerializer.Serialize(new JsonMessage(), JsonContext.Default.JsonMessage);

Tagging subscribers to this area: @eiriktsarpalis, @layomia
See info in area-owners.md if you want to be subscribed.

Issue Details

---

The JSON source generator (#45448) takes a metadata-based approach where reflection-based type metadata gathering is moved from run-time to compile time. This primarily helps improve start-up time, privates bytes usage, and app size.

For simple POCOs and simple JsonSerializerOptions usages, we can also generate serialization logic using Utf8JsonWriter directly. which can help improve serialization throughput.

[assembly: JsonSerializable(typeof(JsonMessage))]

public struct JsonMessage​
{​
    public string message { get; set; }​
}​

JsonTypeInfo<JsonMessage> messageInfo = JsonContext.Default.JsonMessage;​

​var ms = new MemoryStream();​
using (var writer = new Utf8JsonWriter(ms))​
{​
    messageInfo.SerializeObject!(writer, message);​
}​

// ​Recall metadata can also be passed to serializer and be used when nested in other object graphs:​

JsonSerializer.SerializeToUtf8Bytes(message, messageInfo);

Author:	layomia
Assignees:	layomia
Labels:	area-System.Text.Json, tenet-performance
Milestone:	6.0.0

[layomia]

"Simple options":

Run-time options (JsonSerializerOptions)

Supported for fast-path​	Fallback to serializer logic​
DefaultIgnoreCondition​	IgnoreNullValues (obsolete)​
IncludeFields​	ReferenceHandler​
PropertyNamingPolicy (Built-in camel)​	NumberHandling​
WriteIndented (writer handles this)​	Async serialization​
IgnoreReadOnlyFields​	Encoder​
IgnoreReadOnlyProperties​	Converters​

Design-time options (Attributes)

Supported for fast-path​	Fallback to serializer logic​
JsonIgnoreAttribute​	JsonConverterAttribute​
JsonIncludeAttribute​	JsonExtensionDataAttribute​
JsonPropertyNameAttribute​	JsonNumberHandlingAttribute​

[Tornhoof]

Are the fallbacks per type or global?, i.e. if I add a converter is fast-path disabled for the type in the converter or for all types?

[layomia]

@Tornhoof the fallbacks would be per type. So if a custom converter is used for the type or one of its members, a fast-path action will not be generated. Other types that fit the characteristics would have fast-path logic generated.

[jkotas]

Other source generators are often adopting a pattern of partial methods that get filled in by the source generator. In this case, it would look like this:

[GeneratedJsonSerializer(JsonSerializerOptions.Default)]
partial static void Serialize(MyType value, Utf8JsonWriter writer);

Would this be a better alternative for the lean fast serializers? What are the pros and cons of this simple static method that just gets the job done vs. what is proposed above?

[layomia]

@jkotas We could absolutely adopt a pattern like this. It is succinct and efficient.

The downside is that it cannot be used within the JsonSerializer. The initial proposal attaches the serialization logic to a JsonTypeInfo<T> so that it can be used within the serializer, as well as called directly by users.

Applications/services that use non-trivial features of JsonSerializer (such as Bing) want to have benefits of source generation highlighted in #45448. The metadata approach enables their most important scenarios (Faster start-up, reduced private set, AOT-friendliness, rich serializer feature set). Layering lean-fast serialization on top of the metadata approach allows them to also benefit from improved throughput, whereas the lean/fast generation based on partial methods alone won't be compatible.

---

For improved usability for really simple scenarios, I think it would be good to add such a pattern alongside the one initially added above. The generator's implementation could be following, depending on configuration:

Assuming the default generation mode (Serialization)

[GeneratedJsonSerializer(JsonSerializerDefaults.General)]
partial static void Serialize(Utf8JsonWriter writer, MyType value)
{
    writer.WriteStartObject();
    ...
    writer.WriteEndObject();
}

Assuming Metadata or SerializationWithMetadataFallback mode

In this case we could the code generated with JsonContext to avoid code duplication.

[assembly: JsonSourceGenerationMode(JsonSourceGenerationMode.Metadata)]

partial static void Serialize(Utf8JsonWriter writer, MyType value)
{
    JsonContext context = JsonContext.GetOrAdd(JsonSerializerDefaults.General); // Lazy create and cache a compatible context
    context.MyType.Serialize(writer, value);
}