码迷，mamicode.com
首页 > Windows程序 > 详细

ASP.NET Web API编程——序列化与内容协商

时间：2018-04-10 15:21:34      阅读：590      评论：0      收藏：0      [点我收藏+]

标签：utc   app   2.3   create   rtm   throw   alice   default   mem   

1 多媒体格式化器

多媒体类型又叫MIME类型，指示了数据的格式。在HTTP协议中多媒体类型描述了消息体的格式。一个多媒体类型包括两个字符串：类型和子类型。

例如：

text/html、image/png、application/json、application/pdf。

 

请求的Content-Type标头指定消息体的格式，指示接收者应如何解析消息体内容。

例如：请求告知服务端请求数据类型为HTML, XHTML, or XML

请求：Accept: text/html,application/xhtml+xml,application/xml

响应：

HTTP/1.1 200 OK

Content-Length: 95267

Content-Type: image/png

 

多媒体类型为Web Api指明了如何序列化与反序列化HTTP消息体。Web API内建对XML, JSON, BSON，form-urlencoded支持，可以创建多媒体格式化器来自定义格式化方式，自定义的格式化器继承自MediaTypeFormatter或BufferedMediaTypeFormatter，其中MediaTypeFormatter使用异步的读写方法，BufferedMediaTypeFormatter使用同步的读写方法。

 

例：创建CSV格式化器

定义实体

    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Category { get; set; }
        public decimal Price { get; set; }
    }

 

定义ProductCsvFormatter，继承自BufferedMediaTypeFormatter

public class ProductCsvFormatter : BufferedMediaTypeFormatter
{
    public ProductCsvFormatter()
    {
        // 添加被支持的多媒体类型
        SupportedMediaTypes.Add(new MediaTypeHeaderValue("text/csv"));
    }
}

 

重写CanWriteType方法，指明格式化器可序列化的类型

public override bool CanWriteType(System.Type type)
{
    //指明可序列化Product
    if (type == typeof(Product))
{
        return true;
}
    //指明可序列化IEnumerable<Product>
    else
    {
        Type enumerableType = typeof(IEnumerable<Product>);
        return enumerableType.IsAssignableFrom(type);
    }
}

 

重写CanReadType方法，指明格式化器可反序列化的类型

public override bool CanReadType(Type type)
{
    //设置为不支持反序列化
    return false;
}

 

重写WriteToStream方法，这个方法将序列化数据写入流，若要支持反序列化可重写ReadFromStream方法。

public override void WriteToStream(Type type, object value, Stream writeStream, HttpContent content)
{
    using (var writer = new StreamWriter(writeStream))
    {
        var products = value as IEnumerable<Product>;
        if (products != null)
        {
            foreach (var product in products)
            {
                WriteItem(product, writer);
            }
        }
        else
        {
            var singleProduct = value as Product;
            if (singleProduct == null)
            {
                throw new InvalidOperationException("Cannot serialize type");
            }
            WriteItem(singleProduct, writer);
        }
    }
}

// 帮助方法
private void WriteItem(Product product, StreamWriter writer)
{
    writer.WriteLine("{0},{1},{2},{3}", Escape(product.Id),
        Escape(product.Name), Escape(product.Category), Escape(product.Price));
}

static char[] _specialChars = new char[] { ‘,‘, ‘\n‘, ‘\r‘, ‘"‘ };

private string Escape(object o)
{
    if (o == null)
    {
        return "";
    }
    string field = o.ToString();
    if (field.IndexOfAny(_specialChars) != -1)
    {
        // Delimit the entire field with quotes and replace embedded quotes with "".
        return String.Format("\"{0}\"", field.Replace("\"", "\"\""));
    }
    else return field;
}

 

将多媒体格式化器添加到Web API管道（方法在WebApiConfig类中）

public static void Register(HttpConfiguration config)
{
    config.Formatters.Add(new ProductCsvFormatter()); 
}

 

字符编码

多媒体格式化器支持多种编码，例如UTF-8或ISO 8859-1。

public ProductCsvFormatter()
{
    SupportedMediaTypes.Add(new MediaTypeHeaderValue("text/csv"));

    // 新的编码:
    SupportedEncodings.Add(new UTF8Encoding(encoderShouldEmitUTF8Identifier: false));
    SupportedEncodings.Add(Encoding.GetEncoding("iso-8859-1"));
}

 

在WriteToStream方法中添加选择编码方式的代码。如果支持反序列化，那么在ReadFromStream方法中同样添加选择编码方式的代码。

public override void WriteToStream(Type type, object value, Stream writeStream, HttpContent content)
{
    //调用MediaTypeFormatter.SelectCharacterEncoding选择编码方式，由于ProductCsvFormatter派生自MediaTypeFormatter，所以也就继承了SelectCharacterEncoding这个方法
    Encoding effectiveEncoding = SelectCharacterEncoding(content.Headers);

    using (var writer = new StreamWriter(writeStream, effectiveEncoding))
    {
        // Write the object (code not shown)
    }
}

 

2 JSON和XML的序列化

Web API多媒体类型格式化器可以从HTTP消息体中读取CLR对象或将CLR对象写入消息体。Web API框架提供了JSON格式化器和XML格式化器，默认支持JSON和XML序列化。可以在请求的Accept首部字段指定接收的类型。

例：指定返回JSON字符串

HttpContent content = new StringContent(JsonConvert.SerializeObject(cont));
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
request.Content = content;
HttpResponseMessage response = client.SendAsync(request).Result;

返回结果：

技术分享图片

 

例：指定返回XML字符串

HttpContent content = new StringContent(JsonConvert.SerializeObject(cont));
content.Headers.ContentType = new MediaTypeHeaderValue("application/xml");
request.Content = content;
HttpResponseMessage response = client.SendAsync(request).Result;

返回结果：

技术分享图片

 

2.1 JSON格式化器

类JsonMediaTypeFormatter提供对JSON数据的格式化。默认地JsonMediaTypeFormatter使用Json.NET来格式化数据，也可以指定DataContractJsonSerializer来格式化数据。

var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;

json.UseDataContractJsonSerializer = true;

 

序列化

  • 使用Json.NET时，默认地所有的公有类型的字段和属性都会序列化，除非标记了JsonIgnore特性。
  • 可以使用DataContract特性标记数据模型，标记了DataMember特性的属性都会被序列化，即使是私有类型。
  • 只读属性默认被序列化。
  • 默认地，Json.NET的时间字符串为ISO 8601格式，并保持时区。UTC时间含有“Z”字符后缀，本地时间包括时区偏移量。

 

例：显示本地时间

控制器

        [HttpPost]
        public IHttpActionResult ModelValid([FromBody]DataModel model)
        {
            new TaskCompletionSource<HttpResponseMessage>();

            if (!ModelState.IsValid)
            {
                throw new HttpResponseException(HttpStatusCode.BadRequest);
            }
            return Ok(model);
        }

 

客户端调用：

            HttpClient client = new HttpClient();
            string url = "http://localhost/WebApi_Test/api/account/modelvalid?Field1Name=1name&Field2Name=2name";
            using (HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, url))
            {
                var cont = new { DT=DateTime.Now};
                HttpContent content = new StringContent(JsonConvert.SerializeObject(cont));
                content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                request.Content = content;
                HttpResponseMessage response = client.SendAsync(request).Result;
                Console.WriteLine("状态码：{0}",(int)response.StatusCode);
                var task = response.Content.ReadAsStringAsync();
                task.Wait();
                Console.WriteLine("结果：{0}", task.Result);
            }

结果：

技术分享图片

  • 默认地，Json.NET保留了时区，可以使用DateTimeZoneHandling这一属性改变这种形式。

例：

// 转换所有日期为 UTC
var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.DateTimeZoneHandling = Newtonsoft.Json.DateTimeZoneHandling.Utc;
  • 若想使用Microsoft JSON 日期格式：

例：

var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.DateFormatHandling 
= Newtonsoft.Json.DateFormatHandling.MicrosoftDateFormat;
  • 设置Formatting.Indented来支持缩进格式

例：

var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.Formatting = Newtonsoft.Json.Formatting.Indented;

控制器与客户端调用与前例基本一致，缩进的效果为：

技术分享图片

  • 为了使JSON字符串属性名称具有驼峰式的风格，设置为CamelCasePropertyNamesContractResolver

例：

var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
  • 匿名类型自动序列化为JSON

例：控制器操作为Get

public object Get()
{
    return new { 
        Name = "Alice", 
        Age = 23, 
        Pets = new List<string> { "Fido", "Polly", "Spot" } 
    };
}

调用控制器获得响应中包含：{"Name":"Alice","Age":23,"Pets":["Fido","Polly","Spot"]}

 

2.2 XML格式化器

类XmlMediaTypeFormatter 提供对XML数据的格式化。默认地，使用DataContractSerializer执行序列化。

可设置使用XmlSerializer来执行序列化。XmlSerializer支持的类型比DataContractSerializer少，但可以对XML结果做更多地控制。

var xml = GlobalConfiguration.Configuration.Formatters.XmlFormatter;

xml.UseXmlSerializer = true;

 

默认地DataContractSerializer行为如下：

1）所有的公有类型属性或字段都会被序列化（set和get不加修饰），可使用IgnoreDataMember特性将其排除在外。

2）Private和protected成员不会序列化。

3）只读属性不会序列化，但只读的集合属性会被序列化。

4）类及其成员名称如其定义时所显示的那样，不加改变地被写入XML中。

5）使用默认的XML名称空间。

 

若想要施加更多的控制那么使用DataContract修饰类，使用DataMember修饰其属性。序列化规则如下：

1）使用DataMember特性修饰成员使其可序列化，即使类属性为私有属性也可将其序列化。

2）对于使用DataContract特性修饰的类，若不对其属性成员使用DataMember特性，那么就不能序列化。

3）只读属性不会被序列化。

4）在DataContract中设置Name属性来指定类在XML中的名称。

5）在DataContract中设置NameSpace属性来指定XML名称空间。

6）在DataMember中设置Name属性来指定类属性在XML中的名称。

 

时间类型会序列化为ISO 8601格式的字符串。

使用Indent属性设置缩进格式

var xml = GlobalConfiguration.Configuration.Formatters.XmlFormatter;

xml.Indent = true;

 

为不同的CLR类型设置不同的格式化器

var xml = GlobalConfiguration.Configuration.Formatters.XmlFormatter;

// 将XmlSerializer 应用于Product类

xml.SetSerializer<Product>(new XmlSerializer(typeof(Product)));

 

移除JSON或XML格式化器，在Register中添加以下代码。

// Remove the JSON formatter

config.Formatters.Remove(config.Formatters.JsonFormatter);

// Remove the XML formatter

config.Formatters.Remove(config.Formatters.XmlFormatter);

 

2.3控制类的循环引用（应避免循环引用）

例：

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;
    }
}

 

文件Global.asax中的Application_Start方法中添加如下代码，如果不添加下述代码运行时会报500错误。

var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.PreserveReferencesHandling = 
    Newtonsoft.Json.PreserveReferencesHandling.All;

结果为：{"$id":"1","Name":"Sales","Manager":{"$id":"2","Name":"Alice","Department":{"$ref":"1"}}}

 

对于XML循环引用的问题，有两种解决办法。一是在模型上应用[DataContract(IsReference=true)]特性，二是为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);

 

3 ASP.NET Web API 2.1支持BSON

BSON是二进制序列化格式，与JSON大小相近，对于二进制的文件序列化后比JSON小。BSON数据易扩展，因为元素带有长度字段前缀。解析器能够跳过元素而不对数据解码。编码和解码是高效的，因为数值数据类型被存储为数字，而不是字符串。

例：不支持BOSN的调用

var cont = new { Field1Name = "1name", Field2Name = "2name", DT=DateTime.Now};
HttpContent content = new StringContent(JsonConvert.SerializeObject(cont));
content.Headers.ContentType = new MediaTypeHeaderValue("application/bson");
request.Content = content;
HttpResponseMessage response = client.SendAsync(request).Result;

结果：

技术分享图片

 

启用BSON格式化器

设置支持BSON，当客户端请求的Content-Type为application/bson时，Web API会使用BSON格式化器。

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        config.Formatters.Add(new BsonMediaTypeFormatter());

        // 其他配置
    }
}

 

为了关联其他多媒体类型与BOSN，应如下设置，例如多媒体类型为“application/vnd.contoso”

var bson = new BsonMediaTypeFormatter();
bson.SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/vnd.contoso"));
config.Formatters.Add(bson);

 

例：.NET客户端应用HttpClient使用BSON格式化器。

static async Task RunAsync()
{
    using (HttpClient client = new HttpClient())
    {
        client.BaseAddress = new Uri("http://localhost");

        // 设置Accept头.
        client.DefaultRequestHeaders.Accept.Clear();
        client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/bson"));

        // 发送请求
        result = await client.GetAsync("api/books/1");
        result.EnsureSuccessStatusCode();

        // 使用BSON格式化器反序列化结果
        MediaTypeFormatter[] formatters = new MediaTypeFormatter[] {
            new BsonMediaTypeFormatter()
        };

        var book = await result.Content.ReadAsAsync<Book>(formatters);
    }
}

 

发送post请求：

static async Task RunAsync()
{
    using (HttpClient client = new HttpClient())
    {
        client.BaseAddress = new Uri("http://localhost:15192");

        // 设置请求头Content-Type为application/bson
        client.DefaultRequestHeaders.Accept.Clear();
        client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/bson"));

        var book = new Book()
        {
            Author = "Jane Austen",
            Title = "Emma",
            Price = 9.95M,
            PublicationDate = new DateTime(1815, 1, 1)
        };

        // 使用BSON格式化器
        MediaTypeFormatter bsonFormatter = new BsonMediaTypeFormatter();
        var result = await client.PostAsync("api/books", book, bsonFormatter);
        result.EnsureSuccessStatusCode();
    }
}

 

例：未反序列化BSON结果

客户端调用

            using(HttpClient client = new HttpClient())
            {
                client.DefaultRequestHeaders.Accept.Clear();
                client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/bson"));

                string url = "http://localhost/WebApi_Test/api/account/modelvalid?Field1Name=1name&Field2Name=2name";
                using (HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, url))
                {
                    var cont = new { Field1Name = "1name", Field2Name = "2name", DT = DateTime.Now };
                    HttpContent content = new StringContent(JsonConvert.SerializeObject(cont));
                    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                    request.Content = content;
                    HttpResponseMessage response = client.SendAsync(request).Result;
                    Console.WriteLine("状态码：{0}", (int)response.StatusCode);
                    var task = response.Content.ReadAsStringAsync();
                    task.Wait();
                    Console.WriteLine("结果：{0}", task.Result);
                }

                Console.Read();
            }

结果：

技术分享图片

 

客户端序列化，只要改变处理HTTP响应方式即可：

MediaTypeFormatter[] formatters = new MediaTypeFormatter[] 
{
     new BsonMediaTypeFormatter()
};

var task = response.Content.ReadAsAsync<DataModel>(formatters);
task.Wait();
var model =  task.Result;

再次运行获得结果：

技术分享图片

 

序列化顶级原始类型

BOSN语法中并没有规定如何序列化顶级原始类型，比如int类型，为了突破这一限制，BsonMediaTypeFormatter将顶级原始类型视为一种特殊的情况。在序列化之前将值转换为键值对，键为“Value”。

例：

public class ValuesController : ApiController
{
    public IHttpActionResult Get()
    {
        return Ok(42);
    }
}

序列化后的值为：{ "Value": 42 }

 

4 内容协商

在HTTP中主要的内容协商机制包括如下的请求头：

Accept：应答中可接受的多媒体类型，如"application/json," "application/xml,"

Accept-Charset：可接受的字符，如UTF-8或ISO 8859-1。

Accept-Encoding：可接受的编码方式，如gzip。

Accept-Language：首先的自然语言，如en-us。

X-Requested-With：服务器据此判断请求是否来自于AJAX。

 

序列化

如果Web API的控制器操作（Action）返回CLR类型，管道序列化返回值并将其写入HTTP响应消息体。

例如：

public Product GetProduct(int id)
{
    var item = _products.FirstOrDefault(p => p.ID == id);
    if (item == null)
    {
        throw new HttpResponseException(HttpStatusCode.NotFound);
    }
    return item; 
}

 

发送的请求如下，其中请求接收JSON字符串，即通过Accept: application/json来指定的。

GET http://localhost.:21069/api/products/1 HTTP/1.1

Host: localhost.:21069

Accept: application/json, text/javascript, */*; q=0.01

响应为：

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8

Content-Length: 57

Connection: Close

 

{"Id":1,"Name":"Gizmo","Category":"Widgets","Price":1.99}

 

也可返回HttpResponseMessage类型：

public HttpResponseMessage GetProduct(int id)
{
    var item = _products.FirstOrDefault(p => p.ID == id);
    if (item == null)
    {
        throw new HttpResponseException(HttpStatusCode.NotFound);
    }
    return Request.CreateResponse(HttpStatusCode.OK, product);
}

 

内容协商工作原理

首选，管道从HttpConfiguration对象中获得IContentNegotiator，并从HttpConfiguration.Formatters集合中获得多媒体格式化器列表。

然后，管道调用IContentNegotiatior.Negotiate，传入待序列化类型、格式化器集合、HTTP请求。Negotiate方法返回两条信息，一是使用了哪个格式化器，二是响应需要的多媒体类型。如果所需的格式化器没有找到，那么Negotiate方法返回NULL，客户端会接受到406（不接受，请求资源不可访问）错误。

 

默认的内容协商机制

DefaultContentNegotiator是IContentNegotiator默认的实现，其选择格式化器的准则为：

首先，使用MediaTypeFormatter.CanWriteType来验证格式化器是否能够序列化待处理的类型。

其次，内容协商者会查看每个格式化器，并评估其与HTTP请求的匹配程度。为了评估匹配程度，内容协商会做两件事。

  • 集合SupportedMediaTypes包含了被支持的多媒体类型，内容协商者依据请求头的Accept标头来匹配这个集合。Accept标头可能包含一个范围，例如"text/plain" 可以匹配 text/* 或*/*。
  • MediaTypeMapping类提供了匹配HTTP请求的多媒体类型的一般方法。例如它可以匹配自定的HTTP请求头到特定的多媒体类型。

如果有多个匹配，那么选取质量因数最高的一个匹配。

例如：

Accept: application/json, application/xml; q=0.9, */*; q=0.1

选取质量因数为0.9的，即application/json。

如果没有匹配，内容协商者试图匹配请求消息体的多媒体类型。

如果请求包含JSON格式的数据，内容协商者会查找JSON格式化器。

如果通过以上规则还是无法匹配，内容协商者会选择第一个可以序列化待处理类型的格式化器。

 

字符编码方式

选好格式化器以后，内容协商者会选取最好的字符编码方式，通过查看格式化器的SupportedEncodings属性，并与请求的Accept-Charset标头值进行匹配。

 

参考：

https://docs.microsoft.com/en-us/aspnet/web-api/

部分示例来自于该网站

 

---------------------------------------------------------------------

转载与引用请注明出处。

时间仓促，水平有限，如有不当之处，欢迎指正。

ASP.NET Web API编程——序列化与内容协商

标签：utc   app   2.3   create   rtm   throw   alice   default   mem   

原文地址：https://www.cnblogs.com/hdwgxz/p/8778344.html
踩
(0)
赞
(0)
   
举报
评论 一句话评论（0）
登录后才能评论！
分享档案
更多>
2021年07月29日 (22)
2021年07月28日 (40)
2021年07月27日 (32)
2021年07月26日 (79)
2021年07月23日 (29)
2021年07月22日 (30)
2021年07月21日 (42)
2021年07月20日 (16)
2021年07月19日 (90)
2021年07月16日 (35)
周排行
mamicode.com排行更多图片
更多
友情链接
兰亭集智   国之画   百度统计   站长统计   阿里云   chrome插件   新版天听网
关于我们 - 联系我们 - 留言反馈
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码！