即将推出本人原译的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事件可以捕获序列化过程中的错误,既可以处理错误,也可以继续序列化,或让错误冒泡,从而抛出给应用程序。