Asp.Net Web API 2第十三课——ASP.NET Web API中的JSON和XML序列化
前言
阅读本文之前，您也可以到Asp.Net Web API 2 系列导航进行查看 http://www.cnblogs.com/aehyok/p/3446289.html
本文描述ASP.NET Web API中的JSON和XML格式化器。
在ASP.NET Web API中，媒体类型格式化器（Media-type Formatter）是一种能够做以下工作的对象：
- 从HTTP消息体读取CLR（公共语言运行时）对象
- 将CLR对象写入HTTP消息体
Web API提供了用于JSON和XML的媒体类型格式化器。框架已默认将这些格式化器插入到消息处理管线之中。客户端在HTTP请求的Accept报头中可以请求JSON或XML。
JSON媒体类型格式化器
JSON格式化是由JsonMediaTypeFormatter类提供的。默认情况下，JsonMediaTypeFormatter使用Json.NET库执行序列化工作。Json.NET是一个第三方开源项目。
如果喜欢，你可以将JsonMediaTypeFormatter配置成使用DataContractJsonSerializer来代替Json.NET。要想这么做，只需UseDataContractJsonSerializer将属性设置为true即可：
var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter; json.UseDataContractJsonSerializer = true;
JSON序列化
本小节描述，在使用默认的Json.NET序列化器时，JSON格式化器的一些特定行为。这并不意味着要包含Json.NET库的整个文档。更多信息参阅Json.NET Documentation。
什么会被序列化？
默认情况下，所有public属性和字段都会被包含在序列化的JSON中。为了忽略一个属性或字段，需要用JsonIgnore注解属性修饰它。
public class Product
{
public string Name { get; set; }
public decimal Price { get; set; }
[JsonIgnore]
public int ProductCode { get; set; } // omitted
}
如果你更喜欢“opt-in（选入）”方法，可以用DataContract注解属性来修饰类。如果有注解属性，则成员均被忽略，除非有DataMember。DataMember也可以序列化private成员。
[DataContract]
public class Product
{
[DataMember]
public string Name { get; set; }
[DataMember]
public decimal Price { get; set; }
public int ProductCode { get; set; } // omitted by default
}
只读属性
只读属性默认是序列化的。
Dates（日期）
默认情况下，Json.NET会将日期写成ISO 8601格式。UTC（Coordinated Universal Time — 世界标准时间）格式的日期书写时带有后缀“Z”。本地时间格式的日期包括了一个时区偏移量。例如：
2012-07-27T18:51:45.53403Z // UTC（标准时间） 2012-07-27T11:51:45.53403-07:00 // Local（本地时间）
默认情况下，Json.NET保留时区。通过设置DateTimeZoneHandling属性，可以重写这一行为：
// Convert all dates to UTC
// 将所有日期转换成UTC格式
var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.DateTimeZoneHandling =
Newtonsoft.Json.DateTimeZoneHandling.Utc;
如果你喜欢使用微软的JSON日期格式（"\/Date(ticks)\/ "）而不是ISO 8601，可以在SerializerSettings上设置DateFormatHandling属性：
var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.DateFormatHandling =
Newtonsoft.Json.DateFormatHandling.MicrosoftDateFormat;
Indenting（缩进）
为了书写有缩进的JSON，可以将Formatting设置为Formatting.Indented：
var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.Formatting =
Newtonsoft.Json.Formatting.Indented;
Camel Casing（驼峰式大小写转换）
为了在不修改数据模型的情况下，用驼峰式大小写转换JSON的属性名，可以设置序列化器上的CamelCasePropertyNamesContractResolver：
var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.ContractResolver =
new CamelCasePropertyNamesContractResolver();
匿名类型与弱类型对象
动作方法或以返回一个匿名对象，并将其序列化成JSON。例如：
public object Get()
{
return new {
Name = "Alice",
Age = 23,
Pets = new List<string> { "Fido", "Polly", "Spot" }
};
}
响应消息体将含有以下JSON：
{"Name":"Alice","Age":23,"Pets":["Fido","Polly","Spot"]}
如果Web API从客户端接收了松散结构的JSON，你可以将该请求体解序列化成Newtonsoft.Json.Linq.JObject类型。
public void Post(JObject person)
{
string name = person["Name"].ToString();
int age = person["Age"].ToObject<int>();
}
然而，通常更好的是使用强类型数据对象。那么，便不需要自行对数据进行解析，并且能得到模型验证的好处。
XML序列化器不支持匿名类型或JObject实例。如果将这些特性用于JSON数据，应该去掉管线中的XML格式化器，如本文稍后描述的那样。
XML媒体类型格式化器
XML格式化是由XmlMediaTypeFormatter类提供的。默认情况下，XmlMediaTypeFormatter使用DataContractSerializer类来执行序列化。如果喜欢，你可以将XmlMediaTypeFormatter配置成使用XmlSerializer而不是DataContractSerializer。要想这么做，可将UseXmlSerializer属性设置为true：
var xml = GlobalConfiguration.Configuration.Formatters.XmlFormatter; xml.UseXmlSerializer = true;
XmlSerializer类支持的类型集要比DataContractSerializer更窄一些，但对结果XML有更多的控制。如果需要与已有的XML方案匹配，可考虑使用XmlSerializer。
XML Serialization——XML序列化
本小节描述使用默认DataContractSerializer的时，XML格式化器的一些特殊行为。默认情况下，DataContractSerializer行为如下：
- 序列化所有public读/写属性和字段。为了忽略一个属性或字段，请用IgnoreDataMember注解属性修饰它。
- private和protected成员不作序列。
- 只读属性不作序列化
- 类名和成员名按类声明中的确切呈现写入XML
- 使用XML的默认命名空间
如果需要在序列化上的更多控制，可以用DataContract注解属性修饰类。当这个注解属性出现时，该类按以策略序列化：
- “Opt in（选入）”方法：属性与字段默认不被序列化。为了序列化一个属性或字段，请用DataMember注解属性修饰它。
- 要序列化private或protected成员，请用DataMember注解属性修饰它。
- 只读属性不被序列化。
- 要改变类名在XML中的呈现，请在DataContract注解属性中设置Name参数。
- 要改变成员名在XML中的呈现，请设置DataMember注解属性中的Nmae参数。
- 要改变XML命名空间，请设置DataContract类中的Namespace参数。
Read-Only Properties——只读属性
只读属性是不被序列化的。如果只读属性有一个支撑private字段，可以用DataMember注解属性对这个private字段进行标记。这种办法需要在类上使用DataContract注解属性。
[DataContract]
public class Product
{
[DataMember]
private int pcode; // serialized（序列化的）
// Not serialized (read-only)
// 不作序列化（只读）
public int ProductCode { get { return pcode; } }
}
Dates——日期
日期被写成ISO 8601格式。例如，“2012-05-23T20:21:37.9116538Z”。
Indenting——缩进
要书写缩进的XML，请将Indent属性设置为true：
var xml = GlobalConfiguration.Configuration.Formatters.XmlFormatter; xml.Indent = true;
设置每一类型（Per-Type）的XML序列化器
你可以为不同的CLR类型设置不同的XML序列化器。例如，你可能有一个特殊的数据对象，它出于向后兼容而需要XmlSerializer。你可以为此对象使用XmlSerializer，而对其它类型继续使用DataContractSerializer。
为了设置用于特殊类型的XML序列化器，要调用SetSerializer。
var xml = GlobalConfiguration.Configuration.Formatters.XmlFormatter; // Use XmlSerializer for instances of type "Product": // 对“Product”类型的实例使用XmlSerializer： xml.SetSerializer<Product>(new XmlSerializer(typeof(Product)));
你可以指定一个XmlSerializer，或任何派生于XmlObjectSerializer的对象。
Removing the JSON or XML Formatter——去除JSON或XML格式化器
你可以从格式化器列表中删除JSON格式化器，或XML格式化器，只要你不想使用它们。这么做的主要原因是：
- 将你的Web API响应限制到特定的媒体类型。例如，你可能决定只支持JSON响应，而删除XML格式化器。
- 用一个自定义格式化器代替默认的格式化器。例如，你可能要用自己的自定义JSON格式化器实现来代替（默认的）JSON格式化器。
以下代码演示了如何删除默认的格式化器。在Global.asax中定义的Application_Start方法中调用它。
void ConfigureApi(HttpConfiguration config)
{
// Remove the JSON formatter
// 删除JSON格式化器
config.Formatters.Remove(config.Formatters.JsonFormatter);
// or（或者）
// Remove the XML formatter
// 删除XML格式化器
config.Formatters.Remove(config.Formatters.XmlFormatter);
}
Handling Circular Object References——处理循环对象引用
在默认情况下，JSON和XML格式化器将所有对象都写成值。如果两个属性引用了同一个对象，或者，如果在一个集合同一个对象出现了两次，格式化器将对此对象做两次序列化。这是在对象图含有循环的情况下会出现的特有问题，因为，序列化器在检测到对象图中的循环时，会抛出异常。
考虑以下对象模型和控制器。
public class Employee
{
public string Name { get; set; }
public Department Department { get; set; }
}
public class Department
{
public string Name { get; set; }
public Employee Manager { get; set; }
}
public class DepartmentsController : ApiController
{
public Department Get(int id)
{
Department sales = new Department() { Name = "Sales" };
Employee alice = new Employee() { Name = "Alice", Department = sales };
sales.Manager = alice;
return sales;
}
}
调用此动作会触发格式化器抛出异常，该异常将转换成发送给客户端的状态代码500（内部服务器错误）响应。
为了保留JSON中的对象引用，对Global.asax文件的Application_Start方法添加以下代码：
var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.PreserveReferencesHandling =
Newtonsoft.Json.PreserveReferencesHandling.All;
现在，此控制器动作将返回类似于如下形式的JSON：
{"$id":"1","Name":"Sales","Manager":{"$id":"2","Name":"Alice","Department":{"$ref":"1"}}}
注意，序列化器对两个对象都添加了一个“$id”。而且，它检测到Employee.Department属性产生了一个循环，因此，它用一个对象引用{"$ref":"1"}代替这个值。
对象引用是不标准的JSON。在使用此特性之前，要考虑你的客户端是否能够解析这种结果。简单地去除对象图中的循环，可能是更好的办法。例如，此例中Employee链接回Department并不是真正的需要。
为了保留XML中的对象引用，可以使用两个选项。较简单的选项是对模型类添加[DataContract(IsReference=true)]。IsReference参数启用了对象引用。记住，DataContract构成了序列化的“选入（Opt-in）”，因此，你还需要对属性添加DataMember注解属性：
[DataContract(IsReference=true)]
public class Department
{
[DataMember]
public string Name { get; set; }
[DataMember]
public Employee Manager { get; set; }
}
现在，该格式化器将产生类似于如下形式的XML：
<Department xmlns:i="http://www.w3.org/2001/XMLSchema-instance" z:Id="i1"
xmlns:z="http://schemas.microsoft.com/2003/10/Serialization/"
xmlns="http://schemas.datacontract.org/2004/07/Models">
<Manager>
<Department z:Ref="i1" />
<Name>Alice</Name>
</Manager>
<Name>Sales</Name>
</Department>
如果想避免在模型类上使用注解属性，还有另一个选项：创建新的类型专用的DataContractSerializer实例，并在构造器中将preserveObjectReferences设置为true：
var xml = GlobalConfiguration.Configuration.Formatters.XmlFormatter;
var dcs = new DataContractSerializer(typeof(Department), null, int.MaxValue,
false, /* preserveObjectReferences: */ true, null);
xml.SetSerializer<Department>(dcs);
Testing Object Serialization——测试对象序列化
在设计Web API时，对如何序列化对象进行测试是有用的。不必创建控制器或调用控制器动作，便可做这种事。
string Serialize<T>(MediaTypeFormatter formatter, T value)
{
// Create a dummy HTTP Content.
// 创建一个HTTP内容的哑元
Stream stream = new MemoryStream();
var content = new StreamContent(stream);
// Serialize the object.
// 序列化对象
formatter.WriteToStreamAsync(typeof(T), value, stream, content.Headers, null).Wait();
// Read the serialized string.
// 读取序列化的字符串
stream.Position = 0;
return content.ReadAsStringAsync().Result;
}
T Deserialize<T>(MediaTypeFormatter formatter, string str) where T : class
{
// Write the serialized string to a memory stream.
// 将序列化的字符器写入内在流
Stream stream = new MemoryStream();
StreamWriter writer = new StreamWriter(stream);
writer.Write(str);
writer.Flush();
stream.Position = 0;
// Deserialize to an object of type T
// 解序列化成类型为T的对象
return formatter.ReadFromStreamAsync(typeof(T), stream, null, null).Result as T;
}
// Example of use
// 使用示例（用例）
void TestSerialization()
{
var value = new Person() { Name = "Alice", Age = 23 };
var xml = new XmlMediaTypeFormatter();
string str = Serialize(xml, value);
var json = new JsonMediaTypeFormatter();
str = Serialize(json, value);
// Round trip
// 反向操作（解序列化）
Person person2 = Deserialize<Person>(json, str);
}
总结
本课主要简单的了解一下JSON和XML的序列化和反序列的使用。
本文的参考链接为 http://www.asp.net/web-api/overview/formats-and-model-binding/json-and-xml-serialization
同时本文已更新至 Web API导航系列 http://www.cnblogs.com/aehyok/p/3446289.html
