Document open generic converters with JsonConverterAttribute (.NET 11+)

[eiriktsarpalis]

Summary

Documents the new .NET 11 feature from dotnet/runtime#123209 that allows JsonConverterAttribute to support open generic converter types on generic types when the type parameter arity matches.

Previously, open generic converters required implementing a JsonConverterFactory. Starting in .NET 11, you can apply [JsonConverter(typeof(OptionConverter<>))] directly to a generic type like Option<T>, and the serializer automatically constructs the closed generic converter at runtime.

Changes

Article (converters-how-to.md)

• Added forward-reference in the Custom converter patterns section noting .NET 11+ open generic support
• Added new Use open generic converters with [JsonConverter] section covering:
  • Feature overview and when it applies
  • How to define the generic type with [JsonConverter]
  • How to implement the generic converter
  • Serialization/deserialization usage
  • How the automatic construction works
  • Decision guide: factory pattern vs. open generic converters
  • Error handling note for arity mismatches
• Updated ms.date

Snippet (OpenGenericConverter.cs)

• Option<T> struct annotated with [JsonConverter(typeof(OptionConverter<>))]
• OptionConverter<T> with null handling support
• UserProfile class showing property-level usage

Project file

• Updated TFM from net8.0 to net11.0

Content source breakdown

Section	Source
Feature behavior description	Adapted from PR description in dotnet/runtime#123209
Option<T> / OptionConverter<T> code	Adapted from PR example code
UserProfile usage example	AI-generated
Decision guide (factory vs open generic)	AI-generated based on PR semantics

Note

AI-generated sections (usage example, decision guide) should be reviewed for accuracy.

Validation

• Code snippet verified to compile and run on .NET 10 (syntax is TFM-agnostic; the runtime behavior is .NET 11+)

---

Internal previews

📄 File	🔗 Preview link
docs/standard/serialization/system-text-json/converters-how-to.md	How to write custom converters for JSON serialization (marshalling) in .NET