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

Asp.Net Web API 2第十三课——ASP.NET Web API中的JSON和XML序列化

JSON序列化

什么会被序列化？

只读属性

Dates（日期）

Indenting（缩进）

Camel Casing（驼峰式大小写转换）

匿名类型与弱类型对象

XML Serialization——XML序列化

Read-Only Properties——只读属性

Dates——日期

Indenting——缩进

设置每一类型（Per-Type）的XML序列化器

热门文章

最新文章

相关课程

相关电子书

相关实验场景

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

开发者评测

高校计划

乘风者计划

训练营

直播

下载

镜像站

技术资料

Asp.Net Web API 2第十三课——ASP.NET Web API中的JSON和XML序列化

JSON序列化

什么会被序列化？

只读属性

Dates（日期）

Indenting（缩进）

Camel Casing（驼峰式大小写转换）

匿名类型与弱类型对象

XML Serialization——XML序列化

Read-Only Properties——只读属性

Dates——日期

Indenting——缩进

设置每一类型（Per-Type）的XML序列化器

热门文章

最新文章

相关课程

相关电子书

相关实验场景