161 lines
11 KiB
XML
161 lines
11 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<topic id="SerializationAttributes" revisionNumber="1">
|
|
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
|
|
<introduction>
|
|
<para>Attributes can be used to control how Json.NET serializes and deserializes .NET objects.</para>
|
|
|
|
<list class="bullet">
|
|
<listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonObjectAttribute</codeEntityReference> - Placed on classes to control how they should be serialized as a JSON object.</para></listItem>
|
|
<listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference> - Placed on collections to control how they should be serialized as a JSON array.</para></listItem>
|
|
<listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference> - Placed on dictionaries to control how they should be serialized as a JSON object.</para></listItem>
|
|
<listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference> - Placed on fields and properties to control how they should be serialized as a property in a JSON object.</para></listItem>
|
|
<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>
|
|
<listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonExtensionDataAttribute</codeEntityReference> - Placed on a collection field or property to deserialize properties with no matching class member into the specified collection and write values during serialization.</para></listItem>
|
|
<listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonConstructorAttribute</codeEntityReference> - Placed on a constructor to specify that it should be used to create the class during deserialization.</para></listItem>
|
|
</list>
|
|
|
|
</introduction>
|
|
|
|
<section>
|
|
<title>Standard .NET Serialization Attributes</title>
|
|
<content>
|
|
<para>As well as using the built-in Json.NET attributes, Json.NET also looks for the <codeEntityReference>T:System.SerializableAttribute</codeEntityReference>
|
|
(if IgnoreSerializableAttribute on DefaultContractResolver is set to false)
|
|
<codeEntityReference>T:System.Runtime.Serialization.DataContractAttribute</codeEntityReference>,
|
|
<codeEntityReference>T:System.Runtime.Serialization.DataMemberAttribute</codeEntityReference>,
|
|
and <codeEntityReference>T:System.NonSerializedAttribute</codeEntityReference> and attributes when determining how JSON is to be serialized and deserialized.
|
|
</para>
|
|
|
|
<alert class="note">
|
|
<para>Json.NET attributes take precedence over standard .NET serialization attributes (e.g. if both JsonPropertyAttribute
|
|
and DataMemberAttribute are present on a property and both customize the name,
|
|
the name from JsonPropertyAttribute will be used).</para>
|
|
</alert>
|
|
|
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationAttributes" title="Serialization Attributes Example" />
|
|
|
|
</content>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Json.NET Serialization Attributes</title>
|
|
<content>
|
|
<autoOutline />
|
|
</content>
|
|
<sections>
|
|
<section address="JsonObjectAttribute">
|
|
<title>JsonObjectAttribute</title>
|
|
<content>
|
|
<para>The MemberSerialization flag on this attribute specifies whether member serialization is opt-in
|
|
(a member must have the JsonProperty or DataMember attribute to be serialized), opt-out (everything is
|
|
serialized by default but can be ignored with the JsonIgnoreAttribute, Json.NET's default behavior) or
|
|
fields (all public and private fields are serialized and properties are ignored).</para>
|
|
<para>Placing the the <codeEntityReference>T:System.Runtime.Serialization.DataContractAttribute</codeEntityReference>
|
|
on a type is another way to default member serialization to opt-in.</para>
|
|
<para>The NamingStrategy setting on this attributes can be set to a <codeEntityReference>T:Newtonsoft.Json.Serialization.NamingStrategy</codeEntityReference>
|
|
type that specifies how property names are serialized.</para>
|
|
<para>Json.NET serializes .NET classes that implement IEnumerable as a JSON array populated with the
|
|
IEnumerable values. Placing the <codeEntityReference>T:Newtonsoft.Json.JsonObjectAttribute</codeEntityReference>
|
|
overrides this behavior and forces the serializer to serialize the class's fields and properties.</para>
|
|
</content>
|
|
</section>
|
|
|
|
<section address="JsonArrayAttributeJsonDictionaryAttribute">
|
|
<title>JsonArrayAttribute/JsonDictionaryAttribute</title>
|
|
<content>
|
|
<para>The <codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference> and
|
|
<codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference> are used to specify
|
|
whether a class is serialized as that collection type.</para>
|
|
<para>The collection attributes have options to customize the JsonConverter, type name handling, and reference handling that are applied to collection items.</para>
|
|
</content>
|
|
</section>
|
|
|
|
<section address="JsonPropertyAttribute">
|
|
<title>JsonPropertyAttribute</title>
|
|
<content>
|
|
<para>JsonPropertyAttribute has a number of uses:</para>
|
|
|
|
<list class="bullet">
|
|
<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>
|
|
<listItem><para>JsonPropertyAttribute indicates that a property should be serialized when member serialization is set to opt-in.</para></listItem>
|
|
<listItem><para>It includes non-public properties in serialization and deserialization.</para></listItem>
|
|
<listItem><para>It can be used to customize type name, reference, null, and default value handling for the property value.</para></listItem>
|
|
<listItem><para>It can be used to customize the <codeEntityReference>T:Newtonsoft.Json.Serialization.NamingStrategy</codeEntityReference> of the serialized property name.</para></listItem>
|
|
<listItem><para>It can be used to customize the property's collection items JsonConverter, type name handling, and reference handling.</para></listItem>
|
|
</list>
|
|
|
|
<para> The DataMemberAttribute can be used as a substitute for JsonPropertyAttribute.</para>
|
|
|
|
</content>
|
|
</section>
|
|
|
|
<section address="JsonIgnoreAttribute">
|
|
<title>JsonIgnoreAttribute</title>
|
|
<content>
|
|
<para>Excludes a field or property from serialization.</para>
|
|
<para>The <codeEntityReference>T:System.NonSerializedAttribute</codeEntityReference> can be used as a substitute for JsonIgnoreAttribute.</para>
|
|
</content>
|
|
</section>
|
|
|
|
<section address="JsonConverterAttribute">
|
|
<title>JsonConverterAttribute</title>
|
|
<content>
|
|
<para>The <codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference> specifies which
|
|
<codeEntityReference>T:Newtonsoft.Json.JsonConverter</codeEntityReference> is used to convert an object.</para>
|
|
<para>The attribute can be placed on a class or a member. When placed on a class, the JsonConverter
|
|
specified by the attribute will be the default way of serializing that class. When the attribute is
|
|
on a field or property, then the specified JsonConverter will always be used to serialize that value.</para>
|
|
<para>The priority of which JsonConverter is used is member attribute, then class attribute, and finally
|
|
any converters passed to the JsonSerializer.</para>
|
|
|
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConverterAttributeProperty.cs" region="Types" title="JsonConverterAttribute Property Example" />
|
|
|
|
<para>This example shows the JsonConverterAttribute being applied to a property.</para>
|
|
|
|
<para>To apply a JsonConverter to the items in a collection, use either <codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference>,
|
|
<codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference> or
|
|
<codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>
|
|
and set the ItemConverterType property to the converter type you want to use.</para>
|
|
</content>
|
|
</section>
|
|
|
|
<section address="JsonExtensionDataAttribute">
|
|
<title>JsonExtensionDataAttribute</title>
|
|
<content>
|
|
<para>The <codeEntityReference>T:Newtonsoft.Json.JsonExtensionDataAttribute</codeEntityReference> instructs the
|
|
<codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference> to deserialize properties with no matching field or property
|
|
on the type into the specified collection. During serialization the values in this collection are written back to the instance's JSON object.</para>
|
|
|
|
<alert class="note">
|
|
<para>All extension data values will be written during serialization, even if a property the same name has already been written.</para>
|
|
</alert>
|
|
<para>This example shows the JsonExtensionDataAttribute being applied to a field, unmatched JSON properties being added to the field's collection during deserialization.</para>
|
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\DeserializeExtensionData.cs" region="Types" title="Types" />
|
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\DeserializeExtensionData.cs" region="Usage" title="Usage" />
|
|
</content>
|
|
</section>
|
|
|
|
<section address="JsonConstructorAttribute">
|
|
<title>JsonConstructorAttribute</title>
|
|
<content>
|
|
<para>The <codeEntityReference>T:Newtonsoft.Json.JsonConstructorAttribute</codeEntityReference> instructs the
|
|
<codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference> to use a specific constructor when deserializing a class. It can be used to create a class using a parameterized constructor instead of the default constructor, or to pick which specific parameterized constructor to use if there are multiple.</para>
|
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConstructorAttribute.cs" region="Types" title="Types" />
|
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Serializer\JsonConstructorAttribute.cs" region="Usage" title="Usage" />
|
|
</content>
|
|
</section>
|
|
|
|
</sections>
|
|
</section>
|
|
<relatedTopics>
|
|
<codeEntityReference>T:Newtonsoft.Json.JsonObjectAttribute</codeEntityReference>
|
|
<codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference>
|
|
<codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference>
|
|
<codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>
|
|
<codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference>
|
|
<codeEntityReference>T:Newtonsoft.Json.JsonExtensionDataAttribute</codeEntityReference>
|
|
<codeEntityReference>T:Newtonsoft.Json.JsonConstructorAttribute</codeEntityReference>
|
|
</relatedTopics>
|
|
</developerConceptualDocument>
|
|
</topic> |