72 lines
3.6 KiB
XML
72 lines
3.6 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>
|
|
</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>
|
|
<title>PreserveReferencesHandling</title>
|
|
<content>
|
|
<para>Settings PreserveReferencesHandling 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 serizlied 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>
|
|
</content>
|
|
</section>
|
|
|
|
<section>
|
|
<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>
|
|
<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>
|
|
</developerConceptualDocument>
|
|
</topic> |