-Fixed missing XML documentation
-Updated custom documentation pages to use MAML
This commit is contained in:
James Newton-King
@@ -0,0 +1,127 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<topic id="ReducingSerializedJSONSize" revisionNumber="1">
|
||||
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<!--
|
||||
<summary>
|
||||
<para>Optional summary abstract</para>
|
||||
</summary>
|
||||
-->
|
||||
<introduction>
|
||||
<!-- Uncomment this to generate an outline of the section and sub-section
|
||||
titles. Specify a numeric value as the inner text to limit it to
|
||||
a specific number of sub-topics when creating the outline. Specify
|
||||
zero (0) to limit it to top-level sections only. -->
|
||||
<!-- <autoOutline /> -->
|
||||
<para>One of the common problems encountered when serializing .NET objects to
|
||||
JSON is that the JSON ends up containing a lot of unwanted properties and values.
|
||||
This can be especially important when returning JSON to the client. More JSON
|
||||
means more bandwidth and a slower website.</para>
|
||||
<para>To solve the issue of unwanted JSON Json.NET has a range of built in
|
||||
options to fine tune what gets written from a serialized object.</para>
|
||||
</introduction>
|
||||
<!-- Add one or more top-level section elements. These are collapsible.
|
||||
If using <autoOutline />, add an address attribute to identify it
|
||||
and specify a title so that it can be jumped to with a hyperlink. -->
|
||||
<section>
|
||||
<title>JsonIgnoreAttribute and DataMemberAttribute</title>
|
||||
<content>
|
||||
<!-- Uncomment this to create a sub-section outline
|
||||
<autoOutline /> -->
|
||||
<para>By default Json.NET will include all of a classes public properties and fields
|
||||
in the JSON it creates. Adding the
|
||||
<codeEntityReference>T:Newtonsoft.Json.JsonIgnoreAttribute</codeEntityReference>
|
||||
to a property tells the serializer to always skip writing it to the JSON result.</para>
|
||||
|
||||
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeOptOut" title="Opt-out Serialization Example" />
|
||||
|
||||
<para>If a class has many properties and you only want to serialize a small subset
|
||||
of them then adding JsonIgnore to all the others will be tedious and error prone.
|
||||
The way to tackle this scenario is to add the
|
||||
<codeEntityReference>T:System.Runtime.Serialization.DataContractAttribute</codeEntityReference>
|
||||
to the class and
|
||||
<codeEntityReference>T:System.Runtime.Serialization.DataMemberAttributes</codeEntityReference>
|
||||
to the properties to serialize. This is opt-in
|
||||
serialization, only the properties you mark up with be serialized, compared to
|
||||
opt-out serialization using JsonIgnoreAttribute.</para>
|
||||
|
||||
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeOptIn" title="Opt-in Serialization Example" />
|
||||
</content>
|
||||
</section>
|
||||
<section>
|
||||
<title>Formatting</title>
|
||||
<content>
|
||||
<para>JSON written by the serializer with an option of
|
||||
<codeEntityReference>T:Newtonsoft.Json.Formatting</codeEntityReference>
|
||||
set to Indented produces
|
||||
nicely formatted, easy to read JSON that is great for readability when you are
|
||||
developing. Formatting.None on the other hand keeps the JSON result small, skipping
|
||||
all unnecessary spaces and line breaks to produce the most compact and efficient
|
||||
JSON possible.</para>
|
||||
</content>
|
||||
</section>
|
||||
<section>
|
||||
<title>NullValueHandling</title>
|
||||
<content>
|
||||
<para><codeEntityReference>T:Newtonsoft.Json.NullValueHandling</codeEntityReference>
|
||||
is an option on the JsonSerializer and controls how the
|
||||
serializer handles properties with a null value. By setting a value of
|
||||
NullValueHandling.Ignore the JsonSerializer skips writing any properties that have
|
||||
a value of null.</para>
|
||||
|
||||
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeNullValueHandlingObject" title="NullValueHandling Class" />
|
||||
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeNullValueHandlingExample" title="NullValueHandling Ignore Example" />
|
||||
|
||||
<para>NullValueHandling can also be customized on individual properties
|
||||
using the a
|
||||
<codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>.
|
||||
The JsonPropertyAttribute value of
|
||||
NullValueHandling will override the setting on the JsonSerializer for that
|
||||
property.</para>
|
||||
</content>
|
||||
</section>
|
||||
<section>
|
||||
<title>DefaultValueHandling</title>
|
||||
<content>
|
||||
<para><codeEntityReference>T:Newtonsoft.Json.DefaultValueHandling</codeEntityReference>
|
||||
is an option on the JsonSerializer and controls how the serializer handles
|
||||
properties with a default value. Setting a value of DefaultValueHandling.Ignore
|
||||
will make the JsonSerializer skip writing any properties that have a default
|
||||
value to the JSON result. For object references this will be null. For value
|
||||
types like int and DateTime the serializer will skip the default unitialized
|
||||
value for that value type.</para>
|
||||
|
||||
<para>Json.NET also allows you to customize what the default value of an individual
|
||||
property is using the
|
||||
<codeEntityReference>T:System.ComponentModel.DefaultValueAttribute</codeEntityReference>.
|
||||
For example if a string property called
|
||||
Department always returns an empty string in its default state and you didn't want
|
||||
that empty string in your JSON then placing the DefaultValueAttribute on Department
|
||||
with that value will mean Department is no longer written to JSON unless it has a
|
||||
value.</para>
|
||||
|
||||
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeDefaultValueHandlingObject" title="DefaultValueHandling Class" />
|
||||
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeDefaultValueHandlingExample" title="DefaultValueHandling Ignore Example" />
|
||||
|
||||
<para>DefaultValueHandling can also be customized on individual properties using
|
||||
the a
|
||||
<codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>.
|
||||
The JsonPropertyAttribute value of DefaultValueHandling
|
||||
will override the setting on the JsonSerializer for that property.</para>
|
||||
</content>
|
||||
</section>
|
||||
<section>
|
||||
<title>IContractResolver</title>
|
||||
<content>
|
||||
<para>For more flexibility the
|
||||
<codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>
|
||||
provides an interface to customize
|
||||
almost every aspect of how a .NET object gets serialized to JSON, including changing
|
||||
serialization behavior at runtime.</para>
|
||||
|
||||
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeContractResolverObject" title="IContractResolver Class" />
|
||||
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeContractResolverExample" title="IContractResolver Example" />
|
||||
|
||||
</content>
|
||||
</section>
|
||||
</developerConceptualDocument>
|
||||
</topic>
|
||||
Reference in New Issue
Block a user