ReferenceHandler.Preserve プロパティ

定義

メタデータ プロパティは、JSON オブジェクトと配列を参照型に逆シリアル化するときに使用され、参照型をシリアル化するときに書き込まれます。Metadata properties will be honored when deserializing JSON objects and arrays into reference types and written when serializing reference types. これは、サイクルまたは重複する参照が含まれるオブジェクトからラウンドトリップ可能な JSON を作成するために必要です。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; }
member this.Preserve : System.Text.Json.Serialization.ReferenceHandler
Public Shared ReadOnly Property Preserve As ReferenceHandler

プロパティ値

ReferenceHandler

注釈

  • シリアル化時:On Serialize:

    • 複雑な参照型を記述する場合、シリアライザーはメタデータプロパティ ( $id$values 、および $ref ) をその中にも書き込みます。When writing complex reference types, the serializer also writes metadata properties ($id, $values, and $ref) within them.
    • 出力 JSON には、 $id オブジェクトごとに追加のプロパティが含まれます。すべての列挙可能な型に対して、出力される json 配列は、プロパティとプロパティを含む json オブジェクト内に入れ子にされ $id $values ます。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) は、オブジェクトが同一かどうかを判断するために使用されます。ReferenceEquals(Object, Object) is used to determine whether objects are identical.
    • オブジェクトが以前にシリアル化されたオブジェクトと同一である場合、 $ref そのオブジェクトの識別子 () へのポインター () $id が代わりに書き込まれます。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.
  • 逆シリアル化時:On Deserialize:

    • 重複する参照と循環を保持するために使用される JSON 内のメタデータプロパティは、適切な形式である限り、有効になります。*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.*
    • メタデータプロパティが含まれていない JSON オブジェクトの場合、逆シリアル化動作は、を使用しないことと同じです PreserveFor JSON objects that don't contain any metadata properties, the deserialization behavior is identical to not using Preserve.
    • 値型の場合、 $id metadata プロパティは無視されます。For value types, the $id metadata property is ignored. JsonException $ref JSON オブジェクト内でメタデータプロパティが見つかった場合は、がスローされます。A JsonException is thrown if a $ref metadata property is found within the JSON object.
    • 列挙可能な値型の場合、 $values メタデータプロパティは無視されます。For enumerable value types, the $values metadata property is ignored.

* JSON 内のメタデータプロパティが適切な形式と見なされるためには、次の規則に従う必要があります。* For the metadata properties within the JSON to be considered well-formed, they must follow these rules:

  • $idメタデータプロパティは、JSON オブジェクトの最初のプロパティである必要があります。The $id metadata property must be the first property in the JSON object.
  • メタデータプロパティを含む JSON オブジェクトには、 $ref 他のプロパティを含めることはできません。A JSON object that contains a $ref metadata property must not contain any other properties.
  • メタデータプロパティの値は、 $ref JSON で既に登場したを参照する必要があり $id ます。The value of the $ref metadata property must refer to an $id that has appeared earlier in the JSON.
  • $idプロパティとメタデータプロパティの値は、 $ref JSON 文字列である必要があります。The value of the $id and $ref metadata properties must be a JSON string.
  • などの列挙型の場合、 List<T> json 配列は、 $id およびメタデータプロパティを含む json オブジェクト内で、この順序で入れ子にする必要があり $values ます。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.
  • 列挙可能な型の場合、 $values メタデータプロパティは JSON 配列である必要があります。For enumerable types, the $values metadata property must be a JSON array.
  • $valuesメタデータプロパティは、列挙可能な型を参照する場合にのみ有効です。The $values metadata property is only valid when referring to enumerable types.

JSON が整形式でない場合は、 JsonException がスローされます。If the JSON is not well-formed, a JsonException is thrown.

適用対象