← Back to branch summary

~ubuntu-branches/ubuntu/trusty/monodevelop/trusty-proposed

« back to all changes in this revision

Viewing changes to external/Newtonsoft.Json/Doc/ReducingSerializedJSONSize.aml

  • Committer: Package Import Robot
  • Author(s): Jo Shields
  • Date: 2013-05-12 09:46:03 UTC
  • mto: This revision was merged to the branch mainline in revision 29.
  • Revision ID: package-import@ubuntu.com-20130512094603-mad323bzcxvmcam0
Tags: upstream-4.0.5+dfsg
Import upstream version 4.0.5+dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
external/Newtonsoft.Json/Doc/ReducingSerializedJSONSize.aml
 
1
<?xml version="1.0" encoding="utf-8"?>
 
2
<topic id="ReducingSerializedJSONSize" revisionNumber="1">
 
3
  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
 
4
    <!--
 
5
    <summary>
 
6
      <para>Optional summary abstract</para>
 
7
    </summary>
 
8
    -->
 
9
    <introduction>
 
10
      <!-- Uncomment this to generate an outline of the section and sub-section
 
11
           titles.  Specify a numeric value as the inner text to limit it to
 
12
           a specific number of sub-topics when creating the outline.  Specify
 
13
           zero (0) to limit it to top-level sections only.  -->
 
14
      <!-- <autoOutline /> -->
 
15
      <para>One of the common problems encountered when serializing .NET objects to
 
16
      JSON is that the JSON ends up containing a lot of unwanted properties and values.
 
17
      This can be especially important when returning JSON to the client. More JSON
 
18
      means more bandwidth and a slower website.</para>
 
19
      <para>To solve the issue of unwanted JSON Json.NET has a range of built in
 
20
      options to fine tune what gets written from a serialized object.</para>
 
21
    </introduction>
 
22
    <!-- Add one or more top-level section elements.  These are collapsible.
 
23
         If using <autoOutline />, add an address attribute to identify it
 
24
         and specify a title so that it can be jumped to with a hyperlink. -->
 
25
    <section>
 
26
      <title>JsonIgnoreAttribute and DataMemberAttribute</title>
 
27
      <content>
 
28
        <!-- Uncomment this to create a sub-section outline
 
29
        <autoOutline /> -->
 
30
        <para>By default Json.NET will include all of a classes public properties and fields
 
31
        in the JSON it creates. Adding the
 
32
        <codeEntityReference>T:Newtonsoft.Json.JsonIgnoreAttribute</codeEntityReference>
 
33
        to a property tells the serializer to always skip writing it to the JSON result.</para>
 
34
 
 
35
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeOptOut" title="Opt-out Serialization Example" />
 
36
        
 
37
        <para>If a class has many properties and you only want to serialize a small subset
 
38
        of them then adding JsonIgnore to all the others will be tedious and error prone.
 
39
        The way to tackle this scenario is to add the
 
40
        <codeEntityReference>T:System.Runtime.Serialization.DataContractAttribute</codeEntityReference>
 
41
        to the class and
 
42
        <codeEntityReference>T:System.Runtime.Serialization.DataMemberAttribute</codeEntityReference>
 
43
        to the properties to serialize. This is opt-in
 
44
        serialization, only the properties you mark up with be serialized, compared to
 
45
        opt-out serialization using JsonIgnoreAttribute.</para>
 
46
 
 
47
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeOptIn" title="Opt-in Serialization Example" />
 
48
      </content>
 
49
    </section>
 
50
    <section>
 
51
      <title>Formatting</title>
 
52
      <content>
 
53
        <para>JSON written by the serializer with an option of
 
54
        <codeEntityReference>T:Newtonsoft.Json.Formatting</codeEntityReference>
 
55
        set to Indented produces
 
56
        nicely formatted, easy to read JSON that is great for readability when you are
 
57
        developing. Formatting.None on the other hand keeps the JSON result small, skipping
 
58
        all unnecessary spaces and line breaks to produce the most compact and efficient
 
59
        JSON possible.</para>
 
60
      </content>
 
61
    </section>
 
62
    <section>
 
63
      <title>NullValueHandling</title>
 
64
      <content>
 
65
        <para><codeEntityReference>T:Newtonsoft.Json.NullValueHandling</codeEntityReference>
 
66
        is an option on the JsonSerializer and controls how the
 
67
        serializer handles properties with a null value. By setting a value of
 
68
        NullValueHandling.Ignore the JsonSerializer skips writing any properties that have
 
69
        a value of null.</para>
 
70
 
 
71
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeNullValueHandlingObject" title="NullValueHandling Class" />
 
72
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeNullValueHandlingExample" title="NullValueHandling Ignore Example" />
 
73
 
 
74
        <para>NullValueHandling can also be customized on individual properties
 
75
        using the a
 
76
        <codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>.
 
77
        The JsonPropertyAttribute value of
 
78
        NullValueHandling will override the setting on the JsonSerializer for that
 
79
        property.</para>
 
80
      </content>
 
81
    </section>
 
82
    <section>
 
83
      <title>DefaultValueHandling</title>
 
84
      <content>
 
85
        <para><codeEntityReference>T:Newtonsoft.Json.DefaultValueHandling</codeEntityReference>
 
86
        is an option on the JsonSerializer and controls how the serializer handles
 
87
        properties with a default value. Setting a value of DefaultValueHandling.Ignore
 
88
        will make the JsonSerializer skip writing any properties that have a default
 
89
        value to the JSON result. For object references this will be null. For value
 
90
        types like int and DateTime the serializer will skip the default uninitialized
 
91
        value for that value type.</para>
 
92
 
 
93
        <para>Json.NET also allows you to customize what the default value of an individual
 
94
        property is using the
 
95
        <codeEntityReference>T:System.ComponentModel.DefaultValueAttribute</codeEntityReference>.
 
96
        For example if a string property called
 
97
        Department always returns an empty string in its default state and you didn't want
 
98
        that empty string in your JSON then placing the DefaultValueAttribute on Department
 
99
        with that value will mean Department is no longer written to JSON unless it has a
 
100
        value.</para>
 
101
        
 
102
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeDefaultValueHandlingObject" title="DefaultValueHandling Class" />
 
103
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeDefaultValueHandlingExample" title="DefaultValueHandling Ignore Example" />
 
104
        
 
105
        <para>DefaultValueHandling can also be customized on individual properties using
 
106
        the a
 
107
        <codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>.
 
108
        The JsonPropertyAttribute value of DefaultValueHandling
 
109
        will override the setting on the JsonSerializer for that property.</para>
 
110
      </content>
 
111
    </section>
 
112
    <section>
 
113
      <title>IContractResolver</title>
 
114
      <content>
 
115
        <para>For more flexibility the
 
116
        <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>
 
117
        provides an interface to customize
 
118
        almost every aspect of how a .NET object gets serialized to JSON, including changing
 
119
        serialization behavior at runtime.</para>
 
120
 
 
121
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeContractResolverObject" title="IContractResolver Class" />
 
122
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeContractResolverExample" title="IContractResolver Example" />
 
123
        
 
124
      </content>
 
125
    </section>
 
126
    <relatedTopics>
 
127
      <codeEntityReference>T:Newtonsoft.Json.Formatting</codeEntityReference>
 
128
      <codeEntityReference>T:Newtonsoft.Json.JsonIgnoreAttribute</codeEntityReference>
 
129
      <codeEntityReference>T:Newtonsoft.Json.DefaultValueHandling</codeEntityReference>
 
130
      <codeEntityReference>T:Newtonsoft.Json.NullValueHandling</codeEntityReference>
 
131
    </relatedTopics>
 
132
  </developerConceptualDocument>
 
133
</topic>
 
 
b'\\ No newline at end of file'