Attributes can be used to control how Json.NET serializes and deserializes .NET objects.
- JsonObjectAttribute - Placed on classes to control how it should be serialized as a JSON object.
- JsonArrayAttribute - Placed on collections to control how it should be serialized as a JSON array.
- JsonDictionaryAttribute - Placed on dictionaries to control how it should be serialized as a JSON object.
- JsonPropertyAttribute - Placed on fields and properties to control how it 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.
As well as using the built-in Json.NET attributes, Json.NET also looks for the Serializable (if IgnoreSerializableAttribute on DefaultContractResolver is set to false) DataContract, DataMember and NotSerialized and attributes when determining how JSON is to be serialized and deserialized. If both are present the Json.NET serialization attributes take precedence.
[JsonObject(MemberSerialization.OptIn)]
public class Person
{
// "John Smith"
[JsonProperty]
public string Name { get; set; }
// "2000-12-15T22:11:03"
[JsonProperty]
public DateTime BirthDate { get; set; }
// new Date(976918263055)
[JsonProperty]
[JsonConverter(typeof(JavaScriptDateTimeConverter))]
public DateTime LastModified { get; set; }
// not serialized because mode is opt-in
public string Department { get; set; }
}
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 behavor) or fields (all public and private fields are serialized, properties are ignored).
Json.NET serializes .NET classes that implement IEnumerable as an JSON array populated with the IEnumerable values. Placing the JsonPropertyAttribute overrides this behavor 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 specified 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.
- Indicates that a property should be serialized when member serialization is set to opt-in.
- Includes non-public properties in serialization and deserialization.
- Customize type name, reference, null and default value handling for the property value.
- Customize the property's collection items JsonConverter, type name handing and reference handling.
The DataMemberAttribute can be used as substitute for JsonPropertyAttribute.
JsonIgnoreAttribute
Excludes a field or property from serialization.
The NotSerializedAttribute can be used as substitute for JsonIgnoreAttribute.
JsonConverterAttribute
The JsonConverterAttribute specifies which JsonSerializer 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.
public class MemberConverterClass
{
public DateTime DefaultConverter { get; set; }
[JsonConverter(typeof(IsoDateTimeConverter))]
public DateTime MemberConverter { get; set; }
}
This example shows the JsonConverterAttribute being applied to a property.
DateTime date = Convert.ToDateTime("1970-01-01T00:00:00Z").ToUniversalTime();
MemberConverterClass c = new MemberConverterClass
{
DefaultConverter = date,
MemberConverter = date
};
string json = JsonConvert.SerializeObject(c, Formatting.Indented);
Console.WriteLine(json);
//{
// "DefaultConverter": "\/Date(0)\/",
// "MemberConverter": "1970-01-01T00:00:00Z"
//}
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.