JsonSerializerOptions.ReferenceHandler Property


Configures how object references are handled when reading and writing JSON.

 property System::Text::Json::Serialization::ReferenceHandler ^ ReferenceHandler { System::Text::Json::Serialization::ReferenceHandler ^ get(); void set(System::Text::Json::Serialization::ReferenceHandler ^ value); };
public System.Text.Json.Serialization.ReferenceHandler ReferenceHandler { get; set; }
member this.ReferenceHandler : System.Text.Json.Serialization.ReferenceHandler with get, set
Public Property ReferenceHandler As ReferenceHandler

Property Value



By default, serialization does not support objects with cycles and does not preserve duplicate references. Metadata properties will not be written when serializing reference types and will be treated as regular properties on deserialize.

  • On Serialize:

    • Treats duplicate object references as if they were unique and writes all their properties.
    • The serializer throws a JsonException if an object contains a cycle.
  • On Deserialize:

    • Metadata properties ($id, $values, and $ref) will not be consumed and therefore will be treated as regular JSON properties.
    • The metadata properties can map to a real property on the returned object if the property names match, or will be added to the JsonExtensionDataAttribute overflow dictionary, if one exists; otherwise, they are ignored.

Use Preserve to enable unique object reference preservation on serialization and metadata consumption to read preserved references on deserialization.

Applies to