PageRenderTime 56ms CodeModel.GetById 28ms RepoModel.GetById 0ms app.codeStats 0ms

/lib/Json45r7/Source/Doc/PreserveObjectReferences.html

https://bitbucket.org/wantstudios/bitbucketclient
HTML | 138 lines | 116 code | 22 blank | 0 comment | 0 complexity | a4ea1731b8530682ef772bf37e75a7bb MD5 | raw file
    

  1. <html>
    2. 

  2.   
    3. 

  3.   <head>
    4. 

  4.     <title>Serialization and Preserving Object References</title>
    5. 

  5.     <link href="styles.css" rel="stylesheet" type="text/css" />
    6. 

  6.     <link href="custom.css" rel="stylesheet" type="text/css" />
    7. 

  7.   </head>
    8. 

  8.   
    9. 

  9.   <body>
    10. 

  10.     
    11. 

  11.     <div id="control">
    12. 

  12.       <span class="productTitle">Json.NET - Quick Starts & API Documentation</span><br />
    13. 

  13.         <span class="topicTitle">Serialization and Preserving Object References</span></div>
    14. 

  14. 

  15.     <div id="content">
    16. 

  16.       <span style="color: DarkGray"> </span>
    17. 

  17.     
    18. 

  18. 	<p>By default Json.NET will serialize all objects it encounters by value. If a list 
    19. 

  19.         contains two Person references, and both references point to the same object 
    20. 

  20.         then the JsonSerializer will write out all the names and values for each 
    21. 

  21.         reference.</p>
    22. 

  22. 

  23. <div class="overflowpanel"> <div class="code">
    24. 

  24. 

  25. <div style="font-family: Courier New; font-size: 10pt; color: black;">
    26. 

  26. <pre style="margin: 0px;"><span style="color: #2b91af;">Person</span> p = <span style="color: blue;">new</span> <span style="color: #2b91af;">Person</span></pre>
    27. 

  27. <pre style="margin: 0px;">&nbsp; {</pre>
    28. 

  28. <pre style="margin: 0px;">&nbsp; &nbsp; BirthDate = <span style="color: blue;">new</span> <span style="color: #2b91af;">DateTime</span>(1980, 12, 23, 0, 0, 0, <span style="color: #2b91af;">DateTimeKind</span>.Utc),</pre>
    29. 

  29. <pre style="margin: 0px;">&nbsp; &nbsp; LastModified = <span style="color: blue;">new</span> <span style="color: #2b91af;">DateTime</span>(2009, 2, 20, 12, 59, 21, <span style="color: #2b91af;">DateTimeKind</span>.Utc),</pre>
    30. 

  30. <pre style="margin: 0px;">&nbsp; &nbsp; Name = <span style="color: #a31515;">"James"</span></pre>
    31. 

  31. <pre style="margin: 0px;">&nbsp; };</pre>
    32. 

  32. <pre style="margin: 0px;">&nbsp;</pre>
    33. 

  33. <pre style="margin: 0px;"><span style="color: #2b91af;">List</span>&lt;<span style="color: #2b91af;">Person</span>&gt; people = <span style="color: blue;">new</span> <span style="color: #2b91af;">List</span>&lt;<span style="color: #2b91af;">Person</span>&gt;();</pre>
    34. 

  34. <pre style="margin: 0px;">people.Add(p);</pre>
    35. 

  35. <pre style="margin: 0px;">people.Add(p);</pre>
    36. 

  36. <pre style="margin: 0px;">&nbsp;</pre>
    37. 

  37. <pre style="margin: 0px;"><span style="color: blue;">string</span> json = <span style="color: #2b91af;">JsonConvert</span>.SerializeObject(people, <span style="color: #2b91af;">Formatting</span>.Indented);</pre>
    38. 

  38. <pre style="margin: 0px;"><span style="color: green;">//[</span></pre>
    39. 

  39. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; {</span></pre>
    40. 

  40. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; &nbsp; "Name": "James",</span></pre>
    41. 

  41. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; &nbsp; "BirthDate": "\/Date(346377600000)\/",</span></pre>
    42. 

  42. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; &nbsp; "LastModified": "\/Date(1235134761000)\/"</span></pre>
    43. 

  43. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; },</span></pre>
    44. 

  44. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; {</span></pre>
    45. 

  45. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; &nbsp; "Name": "James",</span></pre>
    46. 

  46. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; &nbsp; "BirthDate": "\/Date(346377600000)\/",</span></pre>
    47. 

  47. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; &nbsp; "LastModified": "\/Date(1235134761000)\/"</span></pre>
    48. 

  48. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; }</span></pre>
    49. 

  49. <pre style="margin: 0px;"><span style="color: green;">//]</span></pre>
    50. 

  50. </div>
    51. 

  51. </div></div>
    52. 

  52. <p>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. 
    53. 

  53.     If the above JSON was deserialized now then the returned list would contain two 
    54. 

  54.     completely separate Person objects with the same values. Writing references by value will also cause problems on objects where a 
    55. 

  55.     circular reference occurs.</p>
    56. 

  56.     
    57. 

  57.     <h3>PreserveReferencesHandling</h3>
    58. 

  58.         <p>Settings PreserveReferencesHandling will track object references when serializing 
    59. 

  59.             and deserializing JSON.</p>
    60. 

  60. 

  61. <div class="overflowpanel"> <div class="code">
    62. 

  62. <div style="font-family: Courier New; font-size: 10pt; color: black;">
    63. 

  63. <pre style="margin: 0px;"><span style="color: blue;">string</span> json = <span style="color: #2b91af;">JsonConvert</span>.SerializeObject(people, <span style="color: #2b91af;">Formatting</span>.Indented,</pre>
    64. 

  64. <pre style="margin: 0px;">&nbsp; <span style="color: blue;">new</span> <span style="color: #2b91af;">JsonSerializerSettings</span> { PreserveReferencesHandling = <span style="color: #2b91af;">PreserveReferencesHandling</span>.Objects });</pre>
    65. 

  65. <pre style="margin: 0px;"><span style="color: green;">//[</span></pre>
    66. 

  66. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; {</span></pre>
    67. 

  67. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; &nbsp; "$id": "1",</span></pre>
    68. 

  68. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; &nbsp; "Name": "James",</span></pre>
    69. 

  69. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; &nbsp; "BirthDate": "\/Date(346377600000)\/",</span></pre>
    70. 

  70. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; &nbsp; "LastModified": "\/Date(1235134761000)\/"</span></pre>
    71. 

  71. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; },</span></pre>
    72. 

  72. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; {</span></pre>
    73. 

  73. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; &nbsp; "$ref": "1"</span></pre>
    74. 

  74. <pre style="margin: 0px;"><span style="color: green;">//&nbsp; }</span></pre>
    75. 

  75. <pre style="margin: 0px;"><span style="color: green;">//]</span></pre>
    76. 

  76. <pre style="margin: 0px;">&nbsp;</pre>
    77. 

  77. <pre style="margin: 0px;"><span style="color: #2b91af;">List</span>&lt;<span style="color: #2b91af;">Person</span>&gt; deserializedPeople = <span style="color: #2b91af;">JsonConvert</span>.DeserializeObject&lt;<span style="color: #2b91af;">List</span>&lt;<span style="color: #2b91af;">Person</span>&gt;&gt;(json,</pre>
    78. 

  78. <pre style="margin: 0px;">&nbsp; <span style="color: blue;">new</span> <span style="color: #2b91af;">JsonSerializerSettings</span> { PreserveReferencesHandling = <span style="color: #2b91af;">PreserveReferencesHandling</span>.Objects });</pre>
    79. 

  79. <pre style="margin: 0px;">&nbsp;</pre>
    80. 

  80. <pre style="margin: 0px;"><span style="color: #2b91af;">Console</span>.WriteLine(deserializedPeople.Count);</pre>
    81. 

  81. <pre style="margin: 0px;"><span style="color: green;">// 2</span></pre>
    82. 

  82. <pre style="margin: 0px;">&nbsp;</pre>
    83. 

  83. <pre style="margin: 0px;"><span style="color: #2b91af;">Person</span> p1 = deserializedPeople[0];</pre>
    84. 

  84. <pre style="margin: 0px;"><span style="color: #2b91af;">Person</span> p2 = deserializedPeople[1];</pre>
    85. 

  85. <pre style="margin: 0px;">&nbsp;</pre>
    86. 

  86. <pre style="margin: 0px;"><span style="color: #2b91af;">Console</span>.WriteLine(p1.Name);</pre>
    87. 

  87. <pre style="margin: 0px;"><span style="color: green;">// James</span></pre>
    88. 

  88. <pre style="margin: 0px;"><span style="color: #2b91af;">Console</span>.WriteLine(p2.Name);</pre>
    89. 

  89. <pre style="margin: 0px;"><span style="color: green;">// James</span></pre>
    90. 

  90. <pre style="margin: 0px;">&nbsp;</pre>
    91. 

  91. <pre style="margin: 0px;"><span style="color: blue;">bool</span> equal = <span style="color: #2b91af;">Object</span>.ReferenceEquals(p1, p2);</pre>
    92. 

  92. <pre style="margin: 0px;"><span style="color: green;">// true</span></pre>
    93. 

  93. </div>
    94. 

  94. </div></div>
    95. 

  95. 

  96. <p>The first Person in the list is serizlied with the addition of an object Id. The 
    97. 

  97.     second Person in JSON is now only a reference to the first.</p>
    98. 

  98.         <p>With PreserveReferencesHandling on now only one Person object is created on 
    99. 

  99.             deserialization and the list contains two references to it, mirroring what we 
    100. 

  100.             started with.</p>
    101. 

  101. 

  102. 	<h3>IsReference on JsonObjectAttribute, JsonArrayAttribute and JsonPropertyAttribute</h3>
    103. 

  103. 

  104. 

  105. 	<p>The PreserveReferencesHandling setting on the JsonSerializer will change
    106. 

  106. 	how all objects are serialized and deserialized. For fine grain control over which 
    107. 

  107.         objects and members should be serialized as a reference there is the IsReference property on 
    108. 

  108.         the JsonObjectAttribute, JsonArrayAttribute and JsonPropertyAttribute.</p>
    109. 

  109.         <p>Setting IsReference on JsonObjectAttribute or JsonArrayAttribute to true will 
    110. 

  110.             mean the JsonSerializer will always serialize the type the attribute is against 
    111. 

  111.             as a reference. Setting IsReference on the JsonPropertyAttribute to true will 
    112. 

  112.             serialize only that property as a reference.</p>
    113. 

  113. 

  114. <div class="overflowpanel"> <div class="code">
    115. 

  115. 

  116. <div style="font-family: Courier New; font-size: 10pt; color: black;">
    117. 

  117. <pre style="margin: 0px;">[<span style="color: #2b91af;">JsonObject</span>(IsReference = <span style="color: blue;">true</span>)]</pre>
    118. 

  118. <pre style="margin: 0px;"><span style="color: blue;">public</span> <span style="color: blue;">class</span> <span style="color: #2b91af;">EmployeeReference</span></pre>
    119. 

  119. <pre style="margin: 0px;">{</pre>
    120. 

  120. <pre style="margin: 0px;">&nbsp; <span style="color: blue;">public</span> <span style="color: blue;">string</span> Name { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
    121. 

  121. <pre style="margin: 0px;">&nbsp; <span style="color: blue;">public</span> <span style="color: #2b91af;">EmployeeReference</span> Manager { <span style="color: blue;">get</span>; <span style="color: blue;">set</span>; }</pre>
    122. 

  122. <pre style="margin: 0px;">}</pre>
    123. 

  123. </div>
    124. 

  124. 

  125. </div></div>
    126. 

  126.     <h3>IReferenceResolver</h3>
    127. 

  127.         <p>To customize how references are generated and resolved the <a href="./html/T_Newtonsoft_Json_Serialization_IReferenceResolver.htm">IReferenceResolver</a> interface is available to inherit from and use with the JsonSerializer.</p>
    128. 

  128. 

  129.       <div id="footer">
    130. 

  130. 

  131. 

  132.     
    133. 

  133.         </div>      
    134. 

  134.     </div>
    135. 

  135. 

  136.   </body>
    137. 

  137. 

  138. </html>
    139.