File: SerializationGuide.html

package info (click to toggle)
mono 4.6.2.7+dfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 778,148 kB
  • ctags: 914,052
  • sloc: cs: 5,779,509; xml: 2,773,713; ansic: 432,645; sh: 14,749; makefile: 12,361; perl: 2,488; python: 1,434; cpp: 849; asm: 531; sql: 95; sed: 16; php: 1
file content (338 lines) | stat: -rw-r--r-- 12,339 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
<html>
<head>
  <title>Serialization Guide</title>
  <link href="styles.css" rel="stylesheet" type="text/css" />
  <link href="custom.css" rel="stylesheet" type="text/css" />
  <style type="text/css">
    .style1
    {
      width: 100%;
    }
  </style>
</head>
<body>
  <div id="control">
    <span class="productTitle">Json.NET - Quick Starts & API Documentation</span><br />
    <span class="topicTitle">Serialization Guide</span></div>
  <div id="content">
    <span style="color: DarkGray"></span>
    <p>
      The Json.NET serializer can serialize a wide variety of .NET objects. This guide
      looks at how it works at a high level and in more detail.</p>
    <h3>
      Summary</h3>
    <p>
      At a high level, the Json.NET serializer will convert primitive .NET values into
      primitive JSON values, .NET arrays and collections to JSON arrays and everything
      else to JSON objects.</p>
    <p>
      Json.NET will throw an error if it encounters incorrect JSON when deserializing
      a value. For example if the serializer encounters a JSON property with an array
      of values and the type of matching .NET property is not a collection then an error
      will be thrown, and vice-versa.
    </p>
    <h4>
      <strong>Complex Types</strong></h4>
    <table class="members">
      <tbody>
        <tr>
          <th class="nameColumn">
            .NET
          </th>
          <th class="descriptionColumn">
            JSON
          </th>
        </tr>
        <tr>
          <td>
            <b>IList, IEnumerable, IList&lt;T&gt;, Array</b>
          </td>
          <td>
            <div class="summary">
              Array
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>IDictionary, IDictionary&lt;TKey, TValue&gt;</b>
          </td>
          <td>
            <div class="summary">
              Object
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Object (more detail below)</b>
          </td>
          <td>
            <div class="summary">
              Object
            </div>
            <br>
          </td>
        </tr>
      </tbody>
    </table>
    <h4>
      <strong>Primitive Types</strong></h4>
    <table class="members">
      <tbody>
        <tr>
          <th class="nameColumn">
            .NET
          </th>
          <th class="descriptionColumn">
            JSON
          </th>
        </tr>
        <tr>
          <td>
            <b>String</b>
          </td>
          <td>
            <div class="summary">
              String
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Byte<br />
              SByte<br />
              UInt16<br />
              Int16<br />
              UInt32<br />
              Int32<br />
              UInt64<br />
              Int64<br />
              <br />
            </b>
          </td>
          <td>
            <div class="summary">
              Integer
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Float<br />
              Double<br />
              Decimal<br />
              <br />
            </b>
          </td>
          <td>
            <div class="summary">
              Float
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Enum</b>
          </td>
          <td>
            <div class="summary">
              Integer (can be string with <a href="html/T_Newtonsoft_Json_Converters_StringEnumConverter.htm">
                StringEnumConverter</a>)
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>DateTime</b>
          </td>
          <td>
            <div class="summary">
              String (<a href="DatesInJSON.html">Serializing Dates in JSON</a>)
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Byte[]</b>
          </td>
          <td>
            <div class="summary">
              String (base 64 encoded)
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Type</b>
          </td>
          <td>
            <div class="summary">
              String (type name)
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Guid</b>
          </td>
          <td>
            <div class="summary">
              String
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b><a href="http://msdn.microsoft.com/en-us/library/system.componentmodel.typeconverter.aspx"
              target="_blank">TypeConverter</a> (convertible to String)</b>
          </td>
          <td>
            <div class="summary">
              String
            </div>
            <br>
          </td>
        </tr>
      </tbody>
    </table>
    <h3>
      Breakdown of Type Serialization</h3>
    <h4>
      <strong>Objects</strong></h4>
    <p>
      .NET types that don't fall into any other category listed below (i.e. aren't lists,
      dictionaries, dynamic, implement ISerializable, etc) are serialized as JSON objects.</p>
    <p>
      By default types are serialized in opt-out mode. What that means is all public fields
      and properties with getters are automatically serialized to JSON and members that
      shouldn't be serialized are opted-out using the JsonIgnoreAttribute. To serialize
      private members the JsonPropertyAttribute can be placed on private fields and properties
      or the DefaultMembersSearchFlags can be changed on DefaultContractResolver to change
      how members are serialized on all types.</p>
    <p>
      Types can also be serialized using opt-in mode. Only fields that have a JsonPropertyAttribute
      or DataMemberAttribute on them will be serialized. Opt-in mode for an object is
      specified using the JsonObjectAttribute on the class.
    </p>
    <h4>
      <strong>IEnumerable, Lists and Arrays</strong></h4>
    <p>
      .NET lists (types that inherit from IEnumerable) and .NET arrays are converted to
      JSON arrays. Because JSON arrays only support a range of values and not properties,
      any additional properties and fields declared on .NET collections are not serialized.
      In situations where a JSON array is not wanted the JsonObjectAttribute can be placed
      on a .NET type that implements IEnumerable to force the type to be serialized as
      a JSON object instead.</p>
    <p>
      Note that if TypeNameHandling or PreserveReferencesHandling has been enabled for
      JSON arrays on the serializer then JSON arrays are wrapped it a containing object.
      The object will have the type name/reference properties and a $values property which
      will have the collection data.</p>
    <p>
      When deserializing if a member is typed as the interface IList&lt;T&gt; then it
      will be deserialized as a List&lt;T&gt;.</p>
    <p>
      Read more about serializing collections here: <a href="SerializingCollections.html">
        Serializing Collections </a>
    </p>
    <h4>
      <strong>Dictionarys and Hashtables</strong></h4>
    <p>
      .NET dictionaries (types that inherit from IDictionary) are converted to JSON objects.
      Note that only the dictionary name/values will be written to the JSON object when
      serializing and properties on the JSON object will be added to the dictionary's
      name/values when deserializing. Additional members on the .NET dictionary are ignored
      during serialization.</p>
    <p>
      When deserializing if a member is typed as the interface IDictionary&lt;TKey, TValue&gt;
      then it will be deserialized as a Dictionary&lt;TKey, TValue&gt;.</p>
    <p>
      Read more about serializing collections here: <a href="SerializingCollections.html">
        Serializing Collections</a></p>
    <h4>
      <strong>Untyped Objects</strong></h4>
    <p>
      .NET properties on a class that don't specify a type (i.e. they are just object)
      are serialized as usual. When untyped properties are deserialized the serializer
      has no way to know what type to create (unless type name handling is enabled and
      the JSON contains the type names).</p>
    <p>
      For these untyped properties the Json.NET serializer will read the JSON into LINQ
      to JSON objects and set them to the property. JObject will be created for JSON objects,
      JArray will be created for JSON arrays and JValue for primitive JSON values.
    </p>
    <h4>
      <strong>Dynamic</strong></h4>
    <p>
      There are two different usages of dynamic (introduced in .NET 4) in .NET. The first
      are .NET properties with a type of dynamic. Dynamic proeprties behave like properties
      declared as object, any value can be assigned to it, but the difference being that
      properties and methods can be called on a dynamic property without casting. In Json.NET
      dynamic properties are serialized and deserialized exactly the same as untyped objects:
      because dynamic isn't an actual type Json.NET falls back to deserializing the JSON
      as LINQ to JSON objects.
    </p>
    <p>
      The second usage of dynamic in .NET are classes that implement <a href="http://msdn.microsoft.com/en-us/library/system.dynamic.idynamicmetaobjectprovider.aspx"
        target="_blank">IDynamicMetaObjectProvider</a>. This interface lets the implementor
      create dynamic objects that intercept the property and method calls on an object
      and use them. <a href="http://msdn.microsoft.com/en-us/library/system.dynamic.expandoobject.aspx"
        target="_blank">ExpandoObject</a> is a good example of a dynamic object.
    </p>
    <p>
      Dynamic objects are serialized as JSON objects. A property is written for every
      member name returned by <a href="http://msdn.microsoft.com/en-us/library/system.dynamic.dynamicmetaobject.getdynamicmembernames.aspx"
        target="_blank">DynamicMetaObject.GetDynamicMemberNames</a>.</p>
    <p>
      When deserializing dynamic objects the serializer first attempts to set JSON property
      values on a normal .NET member with the matching name. If no .NET member is found
      with the property name then the serializer will call SetMember on the dynamic object.
      Because there is no type information for dynamic members on a dynamic object the
      values assigned to them will be LINQ to JSON objects</p>
    <h4>
      <strong>ISerializable</strong></h4>
    <p>
      Types that implement ISerializable are serialized as JSON objects. When serializing
      only the values returned from ISerializable.GetObjectData are used; members on the
      type are ignored. When deserializing the constructor with a SerializationInfo and
      StreamingContext is called, passing the JSON object's values.</p>
    <p>
      In situations where this behavior is not wanted the JsonObjectAttribute can be placed
      on a .NET type that implements ISerializable to force it to be serialized as a normal
      JSON object.
    </p>
    <h4>
      <strong>LINQ to JSON</strong></h4>
    <p>
      LINQ to JSON types (e.g. JObject, JArray) are automatically serialized and deserialized
      to their equivalent JSON when encountered by the Json.NET serializer.
    </p>
    <h4>
      <strong>JsonConverter</strong></h4>
    <p>
      Serialization of values that are convertible by a JsonConverter (i.e. CanConvert
      returns true for its type) is completely overridden by the JsonConverter. The test
      to see whether a value can be converted by a JsonSerializer takes precedence over
      all other tests.</p>
    <p>
      JsonConverters can be defined and specified in a number of places: in an attribute
      on a member, in an attribute on a class and added to the JsonSerializer's converters
      collection. The priority of which JsonConverter is used is the JsonConverter defined
      by attribute on a member then the JsonConverter defined by an attribute on a class
      and finally any converters passed to the JsonSerializer.</p>
    <div id="footer">
    </div>
  </div>
</body>
</html>