File: SerializationSettings.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 (513 lines) | stat: -rw-r--r-- 16,779 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
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
<html>
  
  <head>
    <title>Serialization Settings</title>
    <link href="styles.css" rel="stylesheet" type="text/css" />
    <link href="custom.css" rel="stylesheet" type="text/css" />
  </head>
  
  <body>
    
    <div id="control">
      <span class="productTitle">Json.NET - Quick Starts & API Documentation</span><br />
        <span class="topicTitle">Serialization Settings</span></div>

    <div id="content">
      <span style="color: DarkGray"> </span>
    
          <p>JsonSerializer has a number of properties on it to customize how it serializes 
              JSON. These can also be used with the methods on JsonConvert via the 
              JsonSerializerSettings overloads.</p>

    <h3>DateFormatHandling</h3>
<p>DateFormatHandling controls how dates are serialized.</p>
    <table class="members">
      <tbody>
        <tr>
          <th class="nameColumn">
            Member
          </th>
          <th class="descriptionColumn">
            Description
          </th>
        </tr>
        <tr>
          <td>
            <b>IsoDateFormat</b>
          </td>
          <td>
            <div class="summary">
              By default Json.NET writes dates in the ISO 8601 format, e.g. "2012-03-21T05:40Z".
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>MicrosoftDateFormat</b>
          </td>
          <td>
            <div class="summary">
              Dates are written in the Microsoft JSON format, e.g. "\/Date(1198908717056)\/".
            </div>
            <br>
          </td>
        </tr>
      </tbody>
    </table>
<h3>MissingMemberHandling</h3>
<p>MissingMemberHandling controls how missing members, e.g. JSON contains a property 
    that isn&#39;t a member on the object, are handled during deserialization.</p>
    <table class="members">
      <tbody>
        <tr>
          <th class="nameColumn">
            Member
          </th>
          <th class="descriptionColumn">
            Description
          </th>
        </tr>
        <tr>
          <td>
            <b>Ignore</b>
          </td>
          <td>
            <div class="summary">
              By default Json.NET ignores JSON if there is no field 
                or property for its value to be set to during deserialization.
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Error</b>
          </td>
          <td>
            <div class="summary">
              Json.NET errors when there is a missing member during 
                deserialization.
            </div>
            <br>
          </td>
        </tr>
      </tbody>
    </table>

          <h3>ReferenceLoopHandling</h3>
        <p>ReferenceLoopHandling controls how circular referencing objects, e.g. a Person 
            object referencing itself via a Manager property, are serialized.</p>
    <table class="members">
      <tbody>
        <tr>
          <th class="nameColumn">
            Member
          </th>
          <th class="descriptionColumn">
            Description
          </th>
        </tr>
        <tr>
          <td>
            <b>Error</b>
          </td>
          <td>
            <div class="summary">
             By default Json.NET will error if a reference loop is 
                encountered (otherwise the serializer will get into an infinite loop).
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Ignore</b>
          </td>
          <td>
            <div class="summary">
              Json.NET will ignore objects in reference loops and 
                not serialize them. The first time an object is encountered it will be 
                serialized as usual but if the object is encountered as a child object of itself 
                the serializer will skip serializing it.
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Serialize</b>
          </td>
          <td>
            <div class="summary">
              This option forces Json.NET to serialize objects in 
                reference loops. This is useful if objects are nested but not indefinitely.
            </div>
            <br>
          </td>
        </tr>
      </tbody>
    </table>

        <p>ReferenceLoopHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
    <h3>NullValueHandling</h3>
<p>NullValueHandling controls how null values on .NET objects are handled during 
    serialization and how null values in JSON are handled during deserialization.</p>
    <table class="members">
      <tbody>
        <tr>
          <th class="nameColumn">
            Member
          </th>
          <th class="descriptionColumn">
            Description
          </th>
        </tr>
        <tr>
          <td>
            <b>Include</b>
          </td>
          <td>
            <div class="summary">
             By default Json.NET writes null values to JSON when 
                serializing and sets null values to fields/properties when deserializing.
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Ignore</b>
          </td>
          <td>
            <div class="summary">
              Json.NET will skip writing JSON properties if the .NET 
                value is null when serializing and will skip setting fields/properties if the 
                JSON property is null when deserializing.
            </div>
            <br>
          </td>
        </tr>
      </tbody>
    </table>

        <p>NullValueHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
        <h3>
            DefaultValueHandling</h3>
        <p>
DefaultValueHandling controls how Json.NET uses default values set using the .NET 
            DefaultValueAttribute when serializing and deserializing.</p>
    <table class="members">
      <tbody>
        <tr>
          <th class="nameColumn">
            Member
          </th>
          <th class="descriptionColumn">
            Description
          </th>
        </tr>
        <tr>
          <td>
            <b>Include</b>
          </td>
          <td>
            <div class="summary">
             By default Json.NET will write a field/property value 
                to JSON when serializing if the value is the same as the field/property's 
                default value. The Json.NET deserializer will continue setting a field/property 
                if the JSON value is the same as the default value.
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Ignore</b>
          </td>
          <td>
            <div class="summary">
             Json.NET will skip writing a field/property value to 
                JSON if the value is the same as the field/property's default value. The 
                Json.NET deserializer will skip setting a .NET object's field/property if the 
                JSON value is the same as the default value.
            </div>
            <br>
          </td>
        </tr>
      </tbody>
    </table>

        <p>DefaultValueHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
<h3>ObjectCreationHandling</h3>
        <p>ObjectCreationHandling controls how objects are created and deserialized to 
            during deserialization.</p>
    <table class="members">
      <tbody>
        <tr>
          <th class="nameColumn">
            Member
          </th>
          <th class="descriptionColumn">
            Description
          </th>
        </tr>
        <tr>
          <td>
            <b>Auto</b>
          </td>
          <td>
            <div class="summary">
             By default Json.NET will attempt to set JSON values onto 
                existing objects and add JSON values to existing collections during 
                deserialization.
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Reuse</b>
          </td>
          <td>
            <div class="summary">
             Same behaviour as auto.
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Replace</b>
          </td>
          <td>
            <div class="summary">
             Json.NET will always recreate objects and collections 
                before setting values to them during deserialization.
            </div>
            <br>
          </td>
        </tr>
      </tbody>
    </table>

        <p>ObjectCreationHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
<h3>TypeNameHandling</h3>
        <p>TypeNameHandling controls whether Json.NET includes .NET type names during 
            serialization with a $type property and reads .NET type names from that property 
            to determine what type to create during deserialization.</p>
    <table class="members">
      <tbody>
        <tr>
          <th class="nameColumn">
            Member
          </th>
          <th class="descriptionColumn">
            Description
          </th>
        </tr>
        <tr>
          <td>
            <b>None</b>
          </td>
          <td>
            <div class="summary">
             By default Json.NET does not read or write type names 
                during deserialization.
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Objects</b>
          </td>
          <td>
            <div class="summary">
             Json.NET will write and use type names for objects 
                but not collections.
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Arrays</b>
          </td>
          <td>
            <div class="summary">
             Json.NET will write and use type names for collections 
                but not objects.
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Auto</b>
          </td>
          <td>
            <div class="summary">
             Json.NET will check whether an object/collection matches 
                its declared property and writes the type name if they do not match, e.g. a 
                property with a type of Mammal has a derived instance of Dog assigned. Auto will 
                ensure that type information isn't lost when serializing/deserializing 
                automatically without having to write type names for every object.
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>All</b>
          </td>
          <td>
            <div class="summary">
             Json.NET will write and use type names for objects and 
                collections.
            </div>
            <br>
          </td>
        </tr>
      </tbody>
    </table>

        <p>TypeNameHandling can also be customized on individual properties with JsonPropertyAttribute.</p>
        <h3>TypeNameAssemblyFormat</h3>
        <p>TypeNameAssemblyFormat controls how type names are written during serialization.</p>
    <table class="members">
      <tbody>
        <tr>
          <th class="nameColumn">
            Member
          </th>
          <th class="descriptionColumn">
            Description
          </th>
        </tr>
        <tr>
          <td>
            <b>Simple</b>
          </td>
          <td>
            <div class="summary">
             By default Json.NET writes the partial assembly name 
                with the type, e.g. System.Data.DataSet, System.Data. Note that Silverlight and 
                Windows Phone are not able to use this format.
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>Full</b>
          </td>
          <td>
            <div class="summary">
             Json.NET will write the full assembly name, including 
                version number, culture and public key token.
            </div>
            <br>
          </td>
        </tr>
      </tbody>
    </table>

        <p>Read more about the valid values at
            <a href="http://msdn.microsoft.com/en-us/library/tt9xha1h" target="_blank">
            FormatterAssemblyStyle</a>. </p>
        <h3>Binder</h3>
        <p>The serialization binder is used to resolve type names to a .NET type.</p>
        <p>Read more about the serialization binder here:
            <a href="http://msdn.microsoft.com/en-us/library/ffas09b2" target="_blank">SerializationBinder</a></p>
        <h3>ConstructorHandling</h3>
        <p>ConstructorHandling controls how constructors are used when initializing objects 
            during deserialization.</p>
    <table class="members">
      <tbody>
        <tr>
          <th class="nameColumn">
            Member
          </th>
          <th class="descriptionColumn">
            Description
          </th>
        </tr>
        <tr>
          <td>
            <b>Default</b>
          </td>
          <td>
            <div class="summary">
             By default Json.NET will first look for a constructor 
                marked with the JsonConstructorAttribute, then look for a public default 
                constructor (a constructor that doesn't take any arguments), then check if 
                the class has a single public constructor with arguments and finally check
                for a non-public default constructor. If the class has multiple public
                constructors with arguments an error will be thrown. This can be fixed by
                marking one of the constructors with the JsonConstructorAttribute.
            </div>
            <br>
          </td>
        </tr>
        <tr>
          <td>
            <b>AllowNonPublicDefaultConstructor</b>
          </td>
          <td>
            <div class="summary">
             Json.NET will use a classes private default constructor before constructors
             with arguments if available.
            </div>
            <br>
          </td>
        </tr>
      </tbody>
    </table>

        <h3>Converters</h3>
        <p>This is the collection of JsonConverters that will be used during serialization 
            and deserialization. </p>
        <p>JsonConverters allows JSON to be manually written during serialization and read 
            during deserialization. This is useful for particularly complex JSON structures 
            or for when you want to change how a type is serialized.</p>
        <p>When a JsonConverter has been added to a JsonSerializer it will be checked for 
            every value that is being serialized/deserialized using its CanConvert to see if 
            it should be used. If CanConvert returns true then the JsonConverter will be 
            used to read or write the JSON for that value. Note that while a JsonConverter 
            gives you complete control over that values JSON, many Json.NET serialization 
            features are no longer available like type name and reference handling.</p>
        <p>To create your own custom converter inherit from the JsonConverter class. Read 
            more about the built-in JsonConverters below:</p>
        <ul>
            <li><a href="DatesInJSON.html">Serializing Dates in JSON</a></li>
            <li><a href="ConvertingJSONandXML.html">Converting between JSON and XML</a></li>
            <li><a href="CustomCreationConverter.html">CustomCreationConverter</a></li>
            <li><a href="html/T_Newtonsoft_Json_Converters_StringEnumConverter.htm">
                StringEnumConverter</a></li>
        </ul>
        <h3>ContractResolver</h3>
        <p>Internally for every .NET type the JsonSerializer will create a contract of how 
            the type should be serialized and deserialized, based on type metadata and 
            attributes applied to the class. Specifying a custom IContractResolver allows 
            the creation of contracts to be customized.</p>
        <p>Read more about Contract Resolvers here: <a href="ContractResolver.html">Contract 
            Resolvers</a></p>
        <h3>Error</h3>
        <p>The Error event can catch errors during serialization and either handle the event 
            and continue with serialization or let the error bubble up and be thrown to the 
            application.</p>
        <p>Read more about error handling here: <a href="SerializationErrorHandling.html">
            Serialization Error Handling</a></p>


      <div id="footer">


    
        </div>      
    </div>

  </body>

</html>