← 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/SerializationAttributes.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/SerializationAttributes.aml
 
1
<?xml version="1.0" encoding="utf-8"?>
 
2
<topic id="SerializationAttributes" 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>Attributes can be used to control how Json.NET serializes and deserializes .NET objects.</para>
 
16
      
 
17
<list class="bullet">
 
18
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonObjectAttribute</codeEntityReference> - Placed on classes to control how it should be serialized as a JSON object.</para></listItem>
 
19
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference> - Placed on collections to control how it should be serialized as a JSON array.</para></listItem>
 
20
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference> - Placed on dictionaries to control how it should be serialized as a JSON object.</para></listItem>
 
21
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference> - Placed on fields and properties to control how it should be serialized as a property in a JSON object.</para></listItem>
 
22
  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference> - Placed on either classes or fields and properties to specify which JsonConverter should be used during serialization.</para></listItem>
 
23
</list>
 
24
 
 
25
    </introduction>
 
26
    
 
27
    <section>
 
28
      <title>Standard .NET Serialization Attributes</title>
 
29
      <content>
 
30
        <!-- Uncomment this to create a sub-section outline
 
31
        <autoOutline /> -->
 
32
        <para>As well as using the built-in Json.NET attributes, Json.NET also looks for the <codeEntityReference>T:System.SerializableAttribute</codeEntityReference>
 
33
        (if IgnoreSerializableAttribute on DefaultContractResolver is set to false)
 
34
        <codeEntityReference>T:System.Runtime.Serialization.DataContractAttribute</codeEntityReference>,
 
35
        <codeEntityReference>T:System.Runtime.Serialization.DataMemberAttribute</codeEntityReference>
 
36
        and <codeEntityReference>T:System.NonSerializedAttribute</codeEntityReference> and attributes when determining how JSON is to be serialized and deserialized.
 
37
        </para>
 
38
 
 
39
        
 
40
<alert class="note">
 
41
  <para>Json.NET attributes take presidence over standard .NET serialization attributes, e.g. if both JsonPropertyAttribute
 
42
  and DataMemberAttribute are present on a property and both customize the name,
 
43
  the name from JsonPropertyAttribute will be used.</para>
 
44
</alert>        
 
45
 
 
46
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationAttributes" title="Serialization Attributes Example" />
 
47
        
 
48
      </content>
 
49
    </section>
 
50
    
 
51
    <section>
 
52
      <title>Json.NET Serialization Attributes</title>
 
53
        <sections>
 
54
    <section>
 
55
      <title>JsonObjectAttribute</title>
 
56
      <content>
 
57
        <!-- Uncomment this to create a sub-section outline
 
58
        <autoOutline /> -->
 
59
        <para>The MemberSerialization flag on this attribute specifies whether member serialization is opt-in
 
60
        (a member must have the JsonProperty or DataMember attribute to be serialized), opt-out (everything is
 
61
        serialized by default but can be ignored with the JsonIgnoreAttribute, Json.NET's default behavor) or
 
62
        fields (all public and private fields are serialized, properties are ignored).</para>
 
63
        <para>Json.NET serializes .NET classes that implement IEnumerable as an JSON array populated with the
 
64
        IEnumerable values. Placing the JsonPropertyAttribute overrides this behavor and forces the serializer
 
65
        to serialize the class's fields and properties.</para>
 
66
        <para>The DataContractAttribute can be used as substitute for JsonObjectAttribute. The
 
67
        DataContractAttribute will default member serialization to opt-in.</para>
 
68
      </content>
 
69
    </section>
 
70
        
 
71
    <section>
 
72
      <title>JsonArrayAttribute/JsonDictionaryAttribute</title>
 
73
      <content>
 
74
        <!-- Uncomment this to create a sub-section outline
 
75
        <autoOutline /> -->
 
76
        <para>The JsonArrayAttribute and JsonDictionaryAttributes are used to specified whether a class is serialized as that collection type.</para>
 
77
        <para>The collection attributes have options to customize the JsonConverter, type name handling and reference handling that are applied to collection items.</para>
 
78
      </content>
 
79
    </section>
 
80
        
 
81
    <section>
 
82
      <title>JsonPropertyAttribute</title>
 
83
      <content>
 
84
        <!-- Uncomment this to create a sub-section outline
 
85
        <autoOutline /> -->
 
86
        <para>JsonPropertyAttribute has a number of uses:</para>
 
87
        
 
88
<list class="bullet">
 
89
  <listItem><para>By default the JSON property will have the same name as the .NET property. This attribute allows the name to be customized.</para></listItem>
 
90
  <listItem><para>Indicates that a property should be serialized when member serialization is set to opt-in.</para></listItem>
 
91
  <listItem><para>Includes non-public properties in serialization and deserialization.</para></listItem>
 
92
  <listItem><para>Customize type name, reference, null and default value handling for the property value.</para></listItem>
 
93
  <listItem><para>Customize the property's collection items JsonConverter, type name handing and reference handling.</para></listItem>
 
94
</list>
 
95
        
 
96
        <para> The DataMemberAttribute can be used as substitute for JsonPropertyAttribute.</para>
 
97
        
 
98
      </content>
 
99
    </section>
 
100
        
 
101
    <section>
 
102
      <title>JsonIgnoreAttribute</title>
 
103
      <content>
 
104
        <!-- Uncomment this to create a sub-section outline
 
105
        <autoOutline /> -->
 
106
        <para>Excludes a field or property from serialization.</para>
 
107
        <para>The <codeEntityReference>T:System.NonSerializedAttribute</codeEntityReference> can be used as substitute for JsonIgnoreAttribute.</para>
 
108
      </content>
 
109
    </section>
 
110
        
 
111
    <section>
 
112
      <title>JsonConverterAttribute</title>
 
113
      <content>
 
114
        <!-- Uncomment this to create a sub-section outline
 
115
        <autoOutline /> -->
 
116
        <para>The JsonConverterAttribute specifies which JsonSerializer is used to convert an object.</para>
 
117
        <para>The attribute can be placed on a class or a member. When placed on a class the JsonConverter
 
118
        specified by the attribute will be the default way of serializing that class. When the attribute is
 
119
        on a field or property then the specified JsonConverter will always be used to serialize that value.</para>
 
120
        <para>The priority of which JsonConverter is used is member attribute then class attribute and finally
 
121
        any converters passed to the JsonSerializer.</para>
 
122
        
 
123
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationCallbacksObject" title="JsonConverter Attribute" />
 
124
       
 
125
        <para>This example shows the JsonConverterAttribute being applied to a property.</para>
 
126
        
 
127
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationCallbacksExample" title="JsonConverter Example" />
 
128
                
 
129
        <para>To apply a JsonConverter to the items in a collection use either <codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference>,
 
130
        <codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference> or
 
131
        <codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>
 
132
        and set the ItemConverterType property to the converter type you want to use.</para>
 
133
      </content>
 
134
    </section>
 
135
    </sections>
 
136
    </section>
 
137
    <relatedTopics>
 
138
      <codeEntityReference>T:Newtonsoft.Json.JsonObjectAttribute</codeEntityReference>
 
139
      <codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference>
 
140
      <codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference>
 
141
      <codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>
 
142
      <codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference>
 
143
    </relatedTopics>
 
144
  </developerConceptualDocument>
 
145
</topic>
 
 
b'\\ No newline at end of file'