Click or drag to resize
Json.NETSerialization Attributes
 

Attributes can be used to control how Json.NET serializes and deserializes .NET objects.

  • JsonObjectAttribute - Placed on classes to control how they should be serialized as a JSON object.

  • JsonArrayAttribute - Placed on collections to control how they should be serialized as a JSON array.

  • JsonDictionaryAttribute - Placed on dictionaries to control how they should be serialized as a JSON object.

  • JsonPropertyAttribute - Placed on fields and properties to control how they should be serialized as a property in a JSON object.

  • JsonConverterAttribute - Placed on either classes or fields and properties to specify which JsonConverter should be used during serialization.

  • JsonExtensionDataAttribute - Placed on a collection field or property to deserialize properties with no matching class member into the specified collection and write values during serialization.

Standard .NET Serialization Attributes

As well as using the built-in Json.NET attributes, Json.NET also looks for the SerializableAttribute (if IgnoreSerializableAttribute on DefaultContractResolver is set to false) DataContractAttribute, DataMemberAttribute, and NonSerializedAttribute and attributes when determining how JSON is to be serialized and deserialized.

Note Note

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).

Serialization Attributes Example
 1[JsonObject(MemberSerialization.OptIn)]
 2public class Person
 3{
 4    // "John Smith"
 5    [JsonProperty]
 6    public string Name { get; set; }
 7
 8    // "2000-12-15T22:11:03"
 9    [JsonProperty]
10    public DateTime BirthDate { get; set; }
11
12    // new Date(976918263055)
13    [JsonProperty]
14    [JsonConverter(typeof(JavaScriptDateTimeConverter))]
15    public DateTime LastModified { get; set; }
16
17    // not serialized because mode is opt-in
18    public string Department { get; set; }
19}
Json.NET Serialization Attributes
JsonObjectAttribute

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).

Json.NET serializes .NET classes that implement IEnumerable as a JSON array populated with the IEnumerable values. Placing the JsonPropertyAttribute overrides this behavior and forces the serializer to serialize the class's fields and properties.

The DataContractAttribute can be used as substitute for JsonObjectAttribute. The DataContractAttribute will default member serialization to opt-in.

JsonArrayAttribute/JsonDictionaryAttribute

The JsonArrayAttribute and JsonDictionaryAttributes are used to specify whether a class is serialized as that collection type.

The collection attributes have options to customize the JsonConverter, type name handling, and reference handling that are applied to collection items.

JsonPropertyAttribute

JsonPropertyAttribute has a number of uses:

  • By default, the JSON property will have the same name as the .NET property. This attribute allows the name to be customized.

  • JsonPropertyAttribute indicates that a property should be serialized when member serialization is set to opt-in.

  • It includes non-public properties in serialization and deserialization.

  • It can be used to customize type name, reference, null, and default value handling for the property value.

  • It can be used to customize the property's collection items JsonConverter, type name handling, and reference handling.

The DataMemberAttribute can be used as a substitute for JsonPropertyAttribute.

JsonIgnoreAttribute

Excludes a field or property from serialization.

The NonSerializedAttribute can be used as a substitute for JsonIgnoreAttribute.

JsonConverterAttribute

The JsonConverterAttribute specifies which JsonConverter is used to convert an object.

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.

The priority of which JsonConverter is used is member attribute, then class attribute, and finally any converters passed to the JsonSerializer.

JsonConverter Attribute
 1public class SerializationEventTestObject
 2{
 3    // 2222
 4    // This member is serialized and deserialized with no change.
 5    public int Member1 { get; set; }
 6
 7    // The value of this field is set and reset during and 
 8    // after serialization.
 9    public string Member2 { get; set; }
10
11    // This field is not serialized. The OnDeserializedAttribute 
12    // is used to set the member value after serialization.
13    [JsonIgnore]
14    public string Member3 { get; set; }
15
16    // This field is set to null, but populated after deserialization.
17    public string Member4 { get; set; }
18
19    public SerializationEventTestObject()
20    {
21        Member1 = 11;
22        Member2 = "Hello World!";
23        Member3 = "This is a nonserialized value";
24        Member4 = null;
25    }
26
27    [OnSerializing]
28    internal void OnSerializingMethod(StreamingContext context)
29    {
30        Member2 = "This value went into the data file during serialization.";
31    }
32
33    [OnSerialized]
34    internal void OnSerializedMethod(StreamingContext context)
35    {
36        Member2 = "This value was reset after serialization.";
37    }
38
39    [OnDeserializing]
40    internal void OnDeserializingMethod(StreamingContext context)
41    {
42        Member3 = "This value was set during deserialization";
43    }
44
45    [OnDeserialized]
46    internal void OnDeserializedMethod(StreamingContext context)
47    {
48        Member4 = "This value was set after deserialization.";
49    }
50}

This example shows the JsonConverterAttribute being applied to a property.

JsonConverter Example
 1SerializationEventTestObject obj = new SerializationEventTestObject();
 2
 3Console.WriteLine(obj.Member1);
 4// 11
 5Console.WriteLine(obj.Member2);
 6// Hello World!
 7Console.WriteLine(obj.Member3);
 8// This is a nonserialized value
 9Console.WriteLine(obj.Member4);
10// null
11
12string json = JsonConvert.SerializeObject(obj, Formatting.Indented);
13// {
14//   "Member1": 11,
15//   "Member2": "This value went into the data file during serialization.",
16//   "Member4": null
17// }
18
19Console.WriteLine(obj.Member1);
20// 11
21Console.WriteLine(obj.Member2);
22// This value was reset after serialization.
23Console.WriteLine(obj.Member3);
24// This is a nonserialized value
25Console.WriteLine(obj.Member4);
26// null
27
28obj = JsonConvert.DeserializeObject<SerializationEventTestObject>(json);
29
30Console.WriteLine(obj.Member1);
31// 11
32Console.WriteLine(obj.Member2);
33// This value went into the data file during serialization.
34Console.WriteLine(obj.Member3);
35// This value was set during deserialization
36Console.WriteLine(obj.Member4);
37// This value was set after deserialization.

To apply a JsonConverter to the items in a collection, use either JsonArrayAttribute, JsonDictionaryAttribute or JsonPropertyAttribute and set the ItemConverterType property to the converter type you want to use.

JsonExtensionDataAttribute

The JsonExtensionDataAttribute instructs the JsonSerializer 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.

This example shows the JsonExtensionDataAttribute being applied to a field, unmatched JSON properties being added to the field's collection during deserialization.

Types
 1public class DirectoryAccount
 2{
 3    // normal deserialization
 4    public string DisplayName { get; set; }
 5
 6    // these properties are set in OnDeserialized
 7    public string UserName { get; set; }
 8    public string Domain { get; set; }
 9
10    [JsonExtensionData]
11    private IDictionary<string, JToken> _additionalData;
12
13    [OnDeserialized]
14    private void OnDeserialized(StreamingContext context)
15    {
16        // SAMAccountName is not deserialized to any property
17        // and so it is added to the extension data dictionary
18        string samAccountName = (string)_additionalData["SAMAccountName"];
19
20        Domain = samAccountName.Split('\\')[0];
21        UserName = samAccountName.Split('\\')[1];
22    }
23
24    public DirectoryAccount()
25    {
26        _additionalData = new Dictionary<string, JToken>();
27    }
28}
Usage
 1string json = @"{
 2  'DisplayName': 'John Smith',
 3  'SAMAccountName': 'contoso\\johns'
 4}";
 5
 6DirectoryAccount account = JsonConvert.DeserializeObject<DirectoryAccount>(json);
 7
 8Console.WriteLine(account.DisplayName);
 9// John Smith
10
11Console.WriteLine(account.Domain);
12// contoso
13
14Console.WriteLine(account.UserName);
15// johns
See Also