ReferenceHandler.Preserve Property
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Gets an object that indicates whether metadata properties are honored when JSON objects and arrays are deserialized into reference types, and written when reference types are serialized. This is necessary to create round-trippable JSON from objects that contain cycles or duplicate references.
public:
static property System::Text::Json::Serialization::ReferenceHandler ^ Preserve { System::Text::Json::Serialization::ReferenceHandler ^ get(); };
public static System.Text.Json.Serialization.ReferenceHandler Preserve { get; }
static member Preserve : System.Text.Json.Serialization.ReferenceHandler
Public Shared ReadOnly Property Preserve As ReferenceHandler
Property Value
Remarks
On Serialize:
- When writing complex reference types, the serializer also writes metadata properties (
$id
,$values
, and$ref
) within them. - The output JSON will contain an extra
$id
property for every object, and for every enumerable type the JSON array emitted will be nested within a JSON object containing an$id
and$values
property. - ReferenceEquals(Object, Object) is used to determine whether objects are identical.
- When an object is identical to a previously serialized one, a pointer (
$ref
) to the identifier ($id
) of such object is written instead. - No metadata properties are written for value types.
- When writing complex reference types, the serializer also writes metadata properties (
On Deserialize:
- The metadata properties within the JSON that are used to preserve duplicated references and cycles will be honored as long as they are well-formed.*
- For JSON objects that don't contain any metadata properties, the deserialization behavior is identical to not using
Preserve
. - For value types, the
$id
metadata property is ignored. A JsonException is thrown if a$ref
metadata property is found within the JSON object. - For enumerable value types, the
$values
metadata property is ignored.
For the metadata properties within the JSON to be considered well-formed, they must follow these rules:
- Unless AllowOutOfOrderMetadataProperties is set to
true
, the$id
metadata property must be the first property in the JSON object. - A JSON object that contains a
$ref
metadata property must not contain any other properties. - The value of the
$ref
metadata property must refer to an$id
that has appeared earlier in the JSON. - The value of the
$id
and$ref
metadata properties must be a JSON string. - For enumerable types, such as List<T>, the JSON array must be nested within a JSON object containing an
$id
and$values
metadata property, in that order. (However, the order is not important if AllowOutOfOrderMetadataProperties is set totrue
.) - For enumerable types, the
$values
metadata property must be a JSON array. - The
$values
metadata property is only valid when referring to enumerable types.
- Unless AllowOutOfOrderMetadataProperties is set to
If the JSON is not well-formed, a JsonException is thrown.