| | | 1 | | // Licensed to the .NET Foundation under one or more agreements. |
| | | 2 | | // The .NET Foundation licenses this file to you under the MIT license. |
| | | 3 | | |
| | | 4 | | using System.Collections.Generic; |
| | | 5 | | |
| | | 6 | | namespace System.Text.Json.Serialization |
| | | 7 | | { |
| | | 8 | | /// <summary> |
| | | 9 | | /// This class defines how the <see cref="JsonSerializer"/> deals with references on serialization and deserializati |
| | | 10 | | /// </summary> |
| | | 11 | | public abstract class ReferenceHandler |
| | | 12 | | { |
| | | 13 | | /// <summary> |
| | | 14 | | /// Indicates whether this ReferenceHandler implementation should use <see cref="JsonKnownReferenceHandler.Prese |
| | | 15 | | /// The defualt is Preserve. |
| | | 16 | | /// </summary> |
| | 0 | 17 | | internal JsonKnownReferenceHandler HandlingStrategy = JsonKnownReferenceHandler.Preserve; |
| | | 18 | | |
| | | 19 | | /// <summary> |
| | | 20 | | /// Metadata properties will be honored when deserializing JSON objects and arrays into reference types and writ |
| | | 21 | | /// </summary> |
| | | 22 | | /// <remarks> |
| | | 23 | | /// * On Serialize: |
| | | 24 | | /// When writing complex reference types, the serializer also writes metadata properties (`$id`, `$values`, and |
| | | 25 | | /// The output JSON will contain an extra `$id` property for every object, and for every enumerable type the JSO |
| | | 26 | | /// <see cref="object.ReferenceEquals(object?, object?)"/> is used to determine whether objects are identical. |
| | | 27 | | /// When an object is identical to a previously serialized one, a pointer (`$ref`) to the identifier (`$id`) of |
| | | 28 | | /// No metadata properties are written for value types. |
| | | 29 | | /// * On Deserialize: |
| | | 30 | | /// The metadata properties within the JSON that are used to preserve duplicated references and cycles will be h |
| | | 31 | | /// For JSON objects that don't contain any metadata properties, the deserialization behavior is identical to <s |
| | | 32 | | /// For value types: |
| | | 33 | | /// * The `$id` metadata property is ignored. |
| | | 34 | | /// * A <see cref="JsonException"/> is thrown if a `$ref` metadata property is found within the JSON object. |
| | | 35 | | /// * For enumerable value types, the `$values` metadata property is ignored. |
| | | 36 | | /// ** For the metadata properties within the JSON to be considered well-formed, they must follow these rules: |
| | | 37 | | /// 1) The `$id` metadata property must be the first property in the JSON object. |
| | | 38 | | /// 2) A JSON object that contains a `$ref` metadata property must not contain any other properties. |
| | | 39 | | /// 3) The value of the `$ref` metadata property must refer to an `$id` that has appeared earlier in the JSON. |
| | | 40 | | /// 4) The value of the `$id` and `$ref` metadata properties must be a JSON string. |
| | | 41 | | /// 5) For enumerable types, such as <see cref="List{T}"/>, the JSON array must be nested within a JSON object |
| | | 42 | | /// 6) For enumerable types, the `$values` metadata property must be a JSON array. |
| | | 43 | | /// 7) The `$values` metadata property is only valid when referring to enumerable types. |
| | | 44 | | /// If the JSON is not well-formed, a <see cref="JsonException"/> is thrown. |
| | | 45 | | /// </remarks> |
| | 0 | 46 | | public static ReferenceHandler Preserve { get; } = new PreserveReferenceHandler(); |
| | | 47 | | |
| | | 48 | | /// <summary> |
| | | 49 | | /// Ignores an object when a reference cycle is detected during serialization. |
| | | 50 | | /// </summary> |
| | 0 | 51 | | public static ReferenceHandler IgnoreCycles { get; } = new IgnoreReferenceHandler(); |
| | | 52 | | |
| | | 53 | | /// <summary> |
| | | 54 | | /// Returns the <see cref="ReferenceResolver "/> used for each serialization call. |
| | | 55 | | /// </summary> |
| | | 56 | | /// <returns>The resolver to use for serialization and deserialization.</returns> |
| | | 57 | | public abstract ReferenceResolver CreateResolver(); |
| | | 58 | | |
| | | 59 | | /// <summary> |
| | | 60 | | /// Optimization for the resolver used when <see cref="Preserve"/> is set in <see cref="JsonSerializerOptions.Re |
| | | 61 | | /// we pass a flag signaling whether this is called from serialization or deserialization to save one dictionary |
| | | 62 | | /// </summary> |
| | 0 | 63 | | internal virtual ReferenceResolver CreateResolver(bool writing) => CreateResolver(); |
| | | 64 | | } |
| | | 65 | | } |