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

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

序列化设置

JsonSerializer具有很多属性，可以用它们来自定义如何序列化JSON。通过JsonSerializerSettings重载，这些属性也可以与JsonConvert方法配合使用。

• DateFormatHandling
• MissingMemberHandling
• ReferenceLoopHandling
• NullValueHandling
• DefaultValueHandling
• ObjectCreationHandling
• TypeNameHandling
• TypeNameAssemblyFormat
• SerializationBinder
• MetadataPropertyHandling
• ConstructorHandling
• Converters
• ContractResolver
• TraceWriter
• Error

DateFormatHandling

DateFormatHandling 控制数据如何序列化。

成员	描述
IsoDateFormat	默认情况下，Json.Net用ISO 8601格式写日期，例如“2012-03-21T05:40Z”。
MicrosoftDateFormat	用微软JSON格式写日期，例如“\/Date(1198908717056)\/”。

MissingMemberHandling

MissingMemberHandling 控制在反序列化过程中如何处理流离的成员，例如，JSON包含了一个属性，它不是对象上的成员。

成员	描述
Ignore	默认情况下，Json.NET会忽略JSON，如果在反序列化过程中它的值没有被设置字段或属性。
Error	如果在反序列化过程中存在游离的成员，Json.Net会抛出错误。

ReferenceLoopHandling

ReferenceLoopHandling 控制循环引用对象如何序列化，例如，某个Person对象通过一个Manager属性引用它自身。

Equals(Object)方法用来测试一个对象是否在循环引用中。默认情况下，Object.Equals(Object)将用来测试引用类型的引用是否相等，值类型的私有值和公共值是否相等。类和结构可以重写此方法。

成员	描述
Error	默认情况下，Json.NET如果遭遇了引用循环，就会抛出错误（否则序列化程序将陷入无陷循环）。
Ignore	Json.NET将忽略引用循环中的对象，而不序列化它们。第一次遇到这种对象，会照常序列化它，但是如果该对象是作为其自身的子对象遇到的，则序列化程序将跳过序列化它。
Serialize	此选项会强制Json.NET序列化引用循环中的对象。如果对象是嵌套的，但不是无限的，这个选项就很有用。

在调用serializer时，ReferenceLoopHandling可以作一个参数使用，可以使用ItemReferenceLoopHandling在一个对象的多个属性上或者一个集合的项上设置它，也可以利用ReferenceLoopHandling在一个属性上自定义它，或者利用ItemReferenceLoopHandling在一个属性的对象属性或集合项上自定义它。

NullValueHandling

NullValueHandling 控制了在序列化过程中，.NET对象中的null值如何处理，在反序列化过程中，JSON中的null值如何中处理。

成员	描述
Include	默认情况下，在序列化时，Json.NET把null值写到JSON值中；在反序列化时，Json.NET给字段、属性设置null值。
Ignore	在序列化时，如果.NET值是null，Json.NET将跳过写入JSON属性，在反序列化时，如果JSON属性是null，Json.NET将跳过给字段、属性设置值。

还可以利用JsonPropertyAttribute在单个属性上自定义NullValueHandling。

DefaultValueHandling

DefaultValueHandling控制了Json.NET在序列化和反序列化时，如何使用利用.NET DefaultValueAttribute设置的默认值集合。

成员	描述
Include	默认情况下，如果值与字段、属性的默认值相同，在序列化时，Json.NET将在JSON中写入一个字段属性值。如果JSON值与默认值相同，JSON.NET的反序列化器将继续设置字段、属性。
Ignore	如果值与字段、属性的默认值相同，或者与DefaultValueAttribute中指定的自定义值相同，Json.NET将跳过编写字段、属性值。如果JSON的值与默认值相同，Json.NET的反序列化器将跳过设置一个.NET对象的字段、属性。

还可以利用JsonPropertyAttribute值在单个属性上自定义DefaultValueHandling。

ObjectCreationHandling

ObjectCreationHandling控制了在反序列化过程中，如何创建对象，如何反序列化为对象。

成员	描述
Auto	默认情况下，在反序列化过程中，Json.NET将尝试把JSON值设置到已有的对象上，把JSON值添加到已有的集合中。
Reuse	与auto的行为相同。
Replace	在反序列化过程中，Json.NET将始终重新创建对象和集合，然后对它们设置值。

还可以利用JsonPropertyAttribute在单个属性上自定义ObjectCreationHandling。

TypeNameHandling

Caution
当你的应用程序从外部源反序列化JSON时，必须小心地运用TypeNameHandling。在运用除了TypeNameHandling.None之外的其它值来反序列化时，必须利用自定义的ISerializationBinder来校验输入类型。

TypeNameHandling控制了在序列化过程中，Json.NET是否利用一个$type属性来包含.NET类型的名称；在反序列化过程中，Json.NET是否从属性中读取.NET类型名称来确定创建哪种类型。

像$type这样的元数据属性必须位于JSON对象的开头，从而能在反序列化过程中能被成功地侦测到。如果你不能控制JSON对象中的属性的顺序，则可以使用MetadataPropertyHandling来删除此限制。

可以通过创建自己的ISerializationBinder来自定义并校验$type属性的值。

成员	描述
None	默认情况下，在反序列化过程中，Json.NET并不读或写类型的名称。
Objects	Json.NET将为对象写入并使用类型名称，但是对集合不采取同样措施。
Arrays	Json.NET将为集合写入并使用类型名称，但不对对象不采取同样的措施。
Auto	Json.NET将检查某个对象、集合是否匹配它的声明属性，如果不匹配，就写入类型名称，例如，其类型为Mammal的属性被赋值了一个派生的实例Dog。Auto将确保在序列化、反序列化过程中，类型信息自动不会丢失，而不需要为每个对象写入类型名称。
All	Json.NET将为对象和集合写入并使用类型名称。

在调用序列化器时，可以将TypeNameHandling用作参数，可以利用ItemTypeNameHandling在一个对象的属性或一个集合的项上设置它，可以利用TypeNameHandling在某个属性上自定义它，可以利用ItemTypeNameHandling在一个属性的对象属性或集合项上设置它。

TypeNameAssemblyFormat

FormatterAssemblyStyle控制了在序列化过程中如何编写类型名称。

成员	描述
Simple	默认情况下，Json.NET利用类型来写入部分程序集名称，例如System.Data.DataSet、System.Data。请注意，Silverlight和Windows Phone不能使用这种格式。
Full	Json.NET将写入完整的程序集名称，包括版本数、语言版本和公钥标记。

请在FormatterAssemblyStyle读取有效的值。

SerializationBinder

在序列化过程中，ISerializationBinder用来把.NET类型换算为类型名称，在反序列化过程中，它用来把类型名称换算成.NET类型。

如果启用了TypeNameHandling，则强烈建议使用某个自定义的ISerializationBinder来校验输入类型名称，为安全起见。

MetadataPropertyHandling

MetadataPropertyHandling控制了在反序列化过程中，如何读取像$type和$id这样的元数据属性。

出于性能原因，默认情况下，JsonSerializer假定任何元数据属性都位于JSON对象的开头。如果你不能够保证JSON中属性的序列，你可以先反序列化，然后使用MetadataPropertyHandling.ReadAhead来删除此限制，它需要付出一定的性能成本。

成员	描述
Default	默认情况下，Json.NET将只能读取JSON对象开头的元数据属性。
ReadAhead	Json.NET将查找遍位于JSON对象的任意位置的元数据属性。
Ignore	Json.NET将忽略元数据属性。

ConstructorHandling

ConstructorHandling控制了在反序列化过程中如何使用构造器来初始化对象。

成员	描述
Default	默认情况下，Json.NET将首先查找利用JsonConstructorAttrubite标记的构造器，然后查找公共构造器（一个构造器，不取用任何参数），然后检查类是否有单个公共构造器，带有参数，最后检查非公共的默认构造器。如果类有多个公共构造器带有参数，则将抛出一个错误。可以通过对其中一个构造器标记JsonConstructorAttrubite来修复这种问题。
AllowNonPublicDefaultConstructor	在使用带参数的构造器之前，如果可以的话，Json.NET将使用一个类私有默认构造器。

Converters

这是JsonConverters的集合，将在序列化和反序列化过程中使用它们。

JsonConverter允许在序列化过程中手动编写JSON、在反序列化中手动读取JSON。对于比较复杂的JSON结构，这很有用；此外，如果你想要改变一个类型如何被序列化，它也很有用。

如果某个JsonSerializer添加了一个JsonConverter，它会利用它的ConConvert来检查要被序列化、反序列化的每一个值，看是否应该用到它。如果CanConvert返回true，则JsonConverter将用来从JSON中读取那个值，或把那个值写入JSON。请注意，虽然JsonConverter给了你对JSON值的完全的控制，但这也意味着很多Json.NET序列化功能也不再可用了，譬如类型名称和引用处理。

在调用序列化器时，JsonConverters可被用作一个参数，可以利用JsonConverterAttribute在一个对象或属性上设置它，可以利用ItemConverterType在一个对象的属性或一个集合的项上设置它，可以利用ItemConverterType在一个属性的对象属性或集合项上设置它。

若要创建你的自定义转换器，继承自JsonConverter类，请阅读下面的关于内建JsonConverters的文章：

• 在JSON中序列化Dates
• 在JSON和XML之间转换
• CustomCreationConverter
• StringEnumConverter

ContractResolver

在内部，JsonSerializer将根据类型元数据和应用于类的特性，为每个.NET类型创建一个类型应如何序列化和反序列化的协定。指定一个自定义的IContractResolver允许创建自定义的协定。

此处可以进一步了解协定换算器：利用ContractResolver序列化

TraceWriter

利用ITraceWriter接口，Json.NET序列化器支持日志和调试。通过分配一个跟踪编写器，在序列化JSON和反序列化JSON时，你可以调试在Json.NET序列化器内部发生的事情。

在此处阅进一步了解TraceWriter：利用序列化跟踪来调试

Error

Error事件可以捕获序列化过程中的错误，既可以处理错误，也可以继续序列化，或让错误冒泡，从而抛出给应用程序。