NewtonSoft.JSON官方手册中文版【连载5】

即将推出本人原译的NewtonSoft.JSON官方手册中文版完整文档（.chm格式），敬请期待！

序列化特性

可以用来控制Json.NET如何序列化和反序列化.NET对象的特性。

• JsonObjectAttribute - 放置在一个类上，以控制如何把类序列化为JSON对象。
• JsonArrayAttribute - 放置在一个集合上，以控制如何把集合序列化为JSON数组。
• JsonDictionaryAttribute - 放置在字典上，以控制如何把字典序列化为JSON对象。
• JsonPropertyAttribute - 放置在字段和属性主，以控制如何把字段和属性序列化为JSON对象中的一个属性。
• JsonConverterAttribute - 要么放置在类上，要么放置在字段和属性上，以指定在序列化过程中要使用哪种JsonConverter。
• JsonExtensionDataAttribute - 放置在集合字段或属性上，以将没有匹配类成员的属性反序列化到指定的集合中，并在序列化期间写入值。
• JsonConstructorAttribute - 放置在一个构造器上，指定在反序列化过程中，需要用它来创建类。

标准.NET序列化特性

除了使用内建的Json.NET特性，Json.NET还会查找SerializableAttribute（如果DefaultContractResolver上的IgnoreSerializableAttribute被设置为false）、DataContractAttribute、DataMemberAttribute和NonSerializedAttribute，以及用来确定如何序列化和反序列化JSON的一些特性。

Note
Json.NET特性优先于标准的.NET序列化特性（例如，如果一个属性上同时出现了JsonPropertyAttribute和DataMemberAttribute，两者都自定义了其名称，则来将使用来自JsonPropertyAttribute的名称）

序列化特性示例

[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]
  public DateTime LastModified { get; set; }
  // not serialized because mode is opt-in
  public string Department { get; set; }
}

Json.NET序列化特性

此节内容包含了以下小节：

• JsonObjectAttribute
• JsonArrayAttribute/JsonDictionaryAttribute
• JsonPropertyAttribute
• JsonIgnoreAttribute
• JsonConverterAttribute
• JsonExtensionDataAttribute
• JsonConstructorAttribute

JsonObjectAttribute

此特性上的MemberSerialization标志指定了成员序列化到底是opt-in的（必须是具有JsonPropery或DataMember特性的成员才会被序列化），还是opt-out的（默认每个成员都会被序列化，但是带有JsonIgnoreAttribute的成员会被忽略，这是Json.NET的默认行为），还是字段（所有公开的和私有的字段会被序列化，但是属性会被忽略）。

在类型上放 DataContractAttribute是默认成员序列化为opt-in的另一种方式。

此特性上的NamingStrategy设置，可被设置为某个NamingStrategy类型，指定了如何序列化属性名称。

Json.NET将实现IEnumerable的.NET类序列化为JSON数据，用IEnumerable的值来填充。放置JsonObjectAttribute会覆盖此行为，并强迫序列化器序列化类的字段和属性。

JsonArrayAttribute/JsonDictionaryAttribute

JsonArrayAttribute和JsonDictionaryAttribute用来指定类是否被序列化为集合类型。

集合特性具有选项来自定义JsonConverter，类型名称处理，以及应用到集合项的引用的处理。

JsonPropertyAttribute

JsonPropertyAttribute具有很多用法：

• 默认情况下，JSON属性具有与.NET属性相同的名称。此特性允许自定义名称。
• JsonPropertyAttribute表明，当成员被序列化为opt-in时，属性应该被序列化。
• 它包含了在序列化和反序列化处理中的非公开的属性。
• 它可被用来自定义类型名称、引用、空，以及处理属性值的默认值。
• 它可以用来自定义序列化属性名称的NamingStrategy。
• 它可以用来自定义属性集合项JsonConverter，类型名称处理，以及引用处理。

DataMemberAttribute可用作JsonPropertyAttribute的替代品。

JsonIgnoreAttribute

从序列化中排除了一个字段或属性。

NonSerializedAttribute可用作JsonIgnoreAttribute的替代品。

JsonConverterAttribute

JsonConverterAttribute指定了用哪种JsonConverter来转换对象。

此属性既可以放在一个类上，也可以放在一个成员上。当放置在一个类上时，由此属性指定的JsonConverter将是序列化类的默认方式。此特性放在一个字段或属性上时，则指定的JsonConverter将始终有来指定那个值。

使用哪种JsonConverter的优先级顺序，首先是成员特性，然后是类特性，最后是任何传给JsonSerializer的转换器。

JsonConverterAttribute属性示例

public enum UserStatus
{
  NotConfirmed,
  Active,
  Deleted
}
public class User
{
  public string UserName { get; set; }
  [JsonConverter(typeof(StringEnumConverter))]
  public UserStatus Status { get; set; }
}

此示例演示了JsonConverterAttribute可以应用到一个属性上。

要将一个JsonConverter应用到某个集合上的项，既可以使用JsonArrayAttribute、JsonDictionaryAttribute，又可以使用JsonPropertyAttribute，并把ItemConverterType属性设置为你想要使用的转换器类型。

JsonExtensionDataAttribute

JsonExtensionDataAttribute指示JsonSerializer将类型上没有匹配字段或属性的属性反序列化到指定的集合中。在序列化过程中，此集合中的值被写回实例的JSON对象。

Note
序列化过程中将写入所有的扩展数据，哪怕已经写入了同名的属性。

此示例显示了一个字段上应用了JsonExtensionDataAttribute，在反序列化过程中，不匹配的JSON属性被添加到字段的集合。

类型

public class DirectoryAccount
{
  // normal deserialization
  public string DisplayName { get; set; }
  // these properties are set in OnDeserialized
  public string UserName { get; set; }
  public string Domain { get; set; }
  [JsonExtensionData]
  private IDictionary<string, JToken> _additionalData;
  [OnDeserialized]
  private void OnDeserialized(StreamingContext context)
  {
      // SAMAccountName is not deserialized to any property
      // and so it is added to the extension data dictionary
      string samAccountName = (string)_additionalData["SAMAccountName"];
      Domain = samAccountName.Split('\\')[0];
      UserName = samAccountName.Split('\\')[1];
  }
  public DirectoryAccount()
  {
      _additionalData = new Dictionary<string, JToken>();
  }
}

用法

string json = @"{
  'DisplayName': 'John Smith',
  'SAMAccountName': 'contoso\\johns'
}";
DirectoryAccount account = JsonConvert.DeserializeObject<DirectoryAccount>(json);
Console.WriteLine(account.DisplayName);
// John Smith
Console.WriteLine(account.Domain);
// contoso
Console.WriteLine(account.UserName);
// johns

JsonConstructorAttribute

JsonConstructorAttribute指示JsonSerializer在反序列化一个类时使用指定的构造器。可以用它来创建一个类，使用一个参数化的构造器，而不是默认构造器，或者如果存在多个构造器，则挑选使用哪个特定参数化的构造器。

类型

public class User
{
  public string UserName { get; private set; }
  public bool Enabled { get; private set; }
  public User()
  {
  }
  [JsonConstructor]
  public User(string userName, bool enabled)
  {
      UserName = userName;
      Enabled = enabled;
  }
}

用法

string json = @"{
  ""UserName"": ""domain\\username"",
  ""Enabled"": true
}";
User user = JsonConvert.DeserializeObject<User>(json);
Console.WriteLine(user.UserName);
// domain\username