Document ReferenceResolver limitations with custom converters in System.Text.Json

[Copilot]

The System.Text.Json documentation was missing critical information about a limitation when using custom converters with ReferenceHandler.Preserve. Users were confused why their custom converters didn't work properly when reference preservation was enabled.

Problem

When using ReferenceHandler.Preserve with custom converters, the reference handling state is not preserved when the serializer calls into custom converters. This means:

• Custom converters cannot access the current ReferenceResolver instance
• Converters are called for each object instance separately, without knowledge of whether the object has already been serialized elsewhere in the graph
• Calling ReferenceHandler.CreateResolver() throws an exception because the resolver has already been created

Solution

Added a new subsection "ReferenceResolver limitations with custom converters" under the "Preserve references" section that:

• Clearly explains the limitation with a concrete code example showing Parent and Child classes
• Documents that this is a known runtime limitation
• Provides three practical workaround approaches for developers who need both custom conversion logic and reference preservation
• Links to the relevant runtime issues (#51715 and #42163) for tracking future improvements

This documentation change helps users understand why their converters don't work as expected with reference preservation and provides guidance on current limitations and potential approaches.

Fixes #44491.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

---

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