87 lines
4.9 KiB
XML
87 lines
4.9 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<topic id="PreserveObjectReferences" revisionNumber="1">
|
|
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<!--
|
|
<summary>
|
|
<para>Optional summary abstract</para>
|
|
</summary>
|
|
-->
|
|
<introduction>
|
|
<para>By default Json.NET will serialize all objects it encounters by value.
|
|
If a list contains two Person references and both references point to the
|
|
same object, then the JsonSerializer will write out all the names and values
|
|
for each reference.</para>
|
|
|
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="PreservingObjectReferencesOff" title="Preserve Object References Off" />
|
|
|
|
<para>In most cases this is the desired result, but in certain scenarios
|
|
writing the second item in the list as a reference to the first is a better
|
|
solution. If the above JSON was deserialized now, then the returned list would
|
|
contain two completely separate Person objects with the same values. Writing
|
|
references by value will also cause problems on objects where a circular
|
|
reference occurs.</para>
|
|
<autoOutline lead="none" excludeRelatedTopics="true" />
|
|
</introduction>
|
|
<!-- Add one or more top-level section elements. These are collapsible.
|
|
If using <autoOutline />, add an address attribute to identify it
|
|
and specify a title so that it can be jumped to with a hyperlink. -->
|
|
<section address="PreserveReferencesHandling">
|
|
<title>PreserveReferencesHandling</title>
|
|
<content>
|
|
<para>Setting <codeEntityReference>T:Newtonsoft.Json.PreserveReferencesHandling</codeEntityReference> will track object references
|
|
when serializing and deserializing JSON.</para>
|
|
|
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="PreservingObjectReferencesOn" title="Preserve Object References On" />
|
|
|
|
<para>The first Person in the list is serialized with the addition of an
|
|
object ID. The second Person in JSON is now only a reference to the first.</para>
|
|
<para>With PreserveReferencesHandling on, now only one Person object is created
|
|
on deserialization and the list contains two references to it, mirroring
|
|
what we started with.</para>
|
|
<para>
|
|
Metadata properties like <codeInline>$id</codeInline> must be located at the beginning of a JSON object to be successfully detected during deserialization. If you can't control
|
|
the order of properties in your JSON object then <codeEntityReference>T:Newtonsoft.Json.MetadataPropertyHandling</codeEntityReference> can be used to remove this restriction.
|
|
</para>
|
|
<alert class="note">
|
|
<para>References cannot be preserved when a value is set via a non-default constructor.
|
|
With a non-default constructor, child values must be created before the parent value so they can be passed into
|
|
the constructor, making tracking reference impossible.
|
|
<codeEntityReference>T:System.Runtime.Serialization.ISerializable</codeEntityReference> types are an example
|
|
of a class whose values are populated with a non-default constructor and won't work with PreserveReferencesHandling.</para>
|
|
</alert>
|
|
</content>
|
|
</section>
|
|
|
|
<section address="IsReference">
|
|
<title>IsReference</title>
|
|
<content>
|
|
<para>The PreserveReferencesHandling setting on the JsonSerializer will
|
|
change how all objects are serialized and deserialized. For fine grain
|
|
control over which objects and members should be serialized as a
|
|
reference there is the IsReference property on the JsonObjectAttribute,
|
|
JsonArrayAttribute and JsonPropertyAttribute.</para>
|
|
|
|
<para>Setting IsReference on JsonObjectAttribute or JsonArrayAttribute to
|
|
true will mean the JsonSerializer will always serialize the type the
|
|
attribute is against as a reference. Setting IsReference on the
|
|
JsonPropertyAttribute to true will serialize only that property as a
|
|
reference.</para>
|
|
|
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="PreservingObjectReferencesAttribute" title="IsReference" />
|
|
</content>
|
|
</section>
|
|
|
|
<section address="IReferenceResolver">
|
|
<title>IReferenceResolver</title>
|
|
<content>
|
|
<para>To customize how references are generated and resolved the
|
|
<codeEntityReference>T:Newtonsoft.Json.Serialization.IReferenceResolver</codeEntityReference>
|
|
interface is available to inherit from and use with
|
|
the JsonSerializer.</para>
|
|
</content>
|
|
</section>
|
|
<relatedTopics>
|
|
<codeEntityReference>T:Newtonsoft.Json.PreserveReferencesHandling</codeEntityReference>
|
|
</relatedTopics>
|
|
</developerConceptualDocument>
|
|
</topic> |