• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

笔记-ASP.NETWebApi

原作者: [db:作者] 来自: [db:来源] 收藏 邀请

本文是针对ASP.NET WepApi 2 的笔记。

1.void

2.HttpResponseMessage

3.IHttpActionResult

4.其他类型

返回类型 Web API创建响应的方式
void HTTP204(无内容)
HttpResponseMessage 转换为HTTP响应消息
IHttpActionRsult 调用ExecuteAsync来创建HttpResponseMessage,然后转换为HTTP响应消息
其他类型 将序列化的返回值写到响应正文中,返回HTTP200

 

路由

路由表:Web API的默认路由模板"api/{controller}/{id}",此模板中,"api"是文本路径段,{controller}和{id}是占位符变量。

路由变体:可以显示指定Action的HTTP方法,如HttpGet,HttpPost。

public class ProductsController : ApiController
{
    [HttpGet]
    public Product FindProduct(id) {}
}

若要允许多个HTTP方法或GET,POST,PUT,DELETE以外的HTTP方法,可以显示使用AcceptVerbs属性:

public class ProductsController : ApiController
{
    [AcceptVerbs("GET", "HEAD")]
    public Product FindProduct(id) { }

    // WebDAV method
    [AcceptVerbs("MKCOL")]
    public void MakeCollection() { }
}

可以通过ActionName属性重写Action名称:

public class ProductsController : ApiController
{
    [HttpGet]
    [ActionName("Thumbnail")]
    public HttpResponseMessage GetThumbnailImage(int id);

    [HttpPost]
    [ActionName("Thumbnail")]
    public void AddThumbnailImage(int id);
}

也可以使用NonAction属性指定Action不参与路由匹配:

// Not an action method.
[NonAction]  
public string GetPrivateData() { ... }

Web API路由过程的某些部分提供了扩展点:

接口 描述
IHttpControllerSelector 选择控制器
IHttpControllerTypeResolver 获取控制器类型的列表。DefaultHttpControllerSelector从此列表中选择控制器类型
IAssembliesResolver 获取项目的程序集的列表。IHttpControllerTypeResolver接口使用此列表找到控制器的类型
IHttpControllerActivator 创建新的控制器实例
IHttpActionSelector 选择Action
IHttpActionInvoker 调用Action

若要为这些接口提供自己的实现,在HttpConfiguration对象上操作,HttpConfigutation在App_Start文件夹下的WebApiConfig.cs文件下能找到,也可以自己获取:

var config = GlobalConfiguration.Configuration;
config.Services.Replace(typeof(IHttpControllerSelector), new MyControllerSelector(config));

属性路由:Route是API 2支持的一种新类型的路由,顾名思义,它可以使用属性定义路由:

[Route("customers/{customerId}/orders")]
public IEnumerable<Order> GetOrdersByCustomer(int customerId) { ... }

你可能需要先启用,才能使用属性路由:

using System.Web.Http;

namespace WebApplication
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // Web API routes
            config.MapHttpAttributeRoutes();

            // Other Web API configuration not shown.
        }
    }
}

路由名称:

在Web API 中,每个路由都有一个名称。路由名称可用于生成链接,以便可以在HTTP响应中包含一个链接。

Route可以设置名称属性,下面的代码演示如何设置路由名称,以及如何使用根据路由名称生成的链接:

public class BooksController : ApiController
{
    [Route("api/books/{id}", Name="GetBookById")]
    public BookDto GetBook(int id) 
    {
        // Implementation not shown...
    }

    [Route("api/books")]
    public HttpResponseMessage Post(Book book)
    {
        // Validate and add book to database (not shown)

        var response = Request.CreateResponse(HttpStatusCode.Created);

        // Generate a link to the new book and set the Location header in the response.
        string uri = Url.Link("GetBookById", new { id = book.BookId });
        response.Headers.Location = new Uri(uri);
        return response;
    }
}

路由顺序:属性路由还可以指定路由匹配时的顺序,RouteOrder,默认顺序是0,首先计算较低的值。

媒体格式化

媒体类型,也称MIME类型。在HTTP中,媒体类型描述消息正文的格式。例如:

  • text/html
  • image/png
  • application/json

当HTTP消息包含实体正文时,Content-type标头指定消息正文的格式。

例如,如果HTTP响应包含PNG图像,响应可能包含以下标头:

HTTP/1.1 200 OK
Content-Length: 95267
Content-Type: image/png

当客户端发送请求时,它可以包含Accept标头。Accept标头指示客服端想要从服务器获取的响应媒体类型。例如:

Accept: text/html,application/xhtml+xml,application/xml

此标头指示客户端希望获得HTML、XHTML或XML。

媒体类型可以确定Web API 如何序列化和反序列化HTTP消息正文。可以通过编写自己的媒体类型达到扩展Web API序列化和反序列化的目的。

若要创建媒体格式化程序,需要实现以下类:

  • MediaTypeFormatter。 此类使用异步的方式读取和写入。
  • BufferedMediaTypeFormatter。此类派生自MediaTypeFormatter,但是使用同步的方式读取和写入。

下面的实例演示的媒体类型可以序列化以逗号分割值(CSV)格式的产品对象。下面是Product对象的定义:

namespace ProductStore.Models
{
    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Category { get; set; }
        public decimal Price { get; set; }
    }
}

若要实现CSV格式化程序,定义一个类,派生自BufferedMediaTypeFormatter:

namespace ProductStore.Formatters
using System;
using System.Collections.Generic;
using System.IO;
using System.Net.Http;
using System.Net.Http.Formatting;
using System.Net.Http.Headers;
using ProductStore.Models;

namespace ProductStore.Formatters
{
    public class ProductCsvFormatter : BufferedMediaTypeFormatter
    {
    }
}

在构造函数中,添加格式化程序支持的媒体类型。在此示例中,支持类型"text/csv":

public ProductCsvFormatter()
{
    // Add the supported media type.
    SupportedMediaTypes.Add(new MediaTypeHeaderValue("text/csv"));
}

重写CanWriteType方法,以指示该类型格式化程序可以序列化:

public override bool CanWriteType(System.Type type)
{
    if (type == typeof(Product))
    {
        return true;
    }
    else
    {
        Type enumerableType = typeof(IEnumerable<Product>);
        return enumerableType.IsAssignableFrom(type);
    }
}

在此示例中,格式化程序可以序列化单个Product对象的集合、Product对象。

同样,重写CanReadType方法,以指示该类型格式化程序可以反序列化。在此示例中,格式化程序不支持反序列化,因此,此方法返回false:

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

// Helper methods for serializing Products to CSV format. 
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管道

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

WebAPI 提供了对JSON和XML的媒体类型格式化程序。

JSON格式由JsonMediaTypeFormatter类处理,默认情况下JsonMediaTypeFormatter使用Json.NET库以执行序列化。

如果您愿意,可以配置JsonMediaTypeFormatter,以使用DataContractJsonSerializer而不是Json.NET。若要执行此操作,设置UseDataContractJsonSerializer属性true:

var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.UseDataContractJsonSerializer = true;

默认情况下,所有公共属性和字段会参与序列化JSON。若要忽略属性或字段,给它装饰JsonIgnore属性。

public class Product
{
    public string Name { get; set; }
    public decimal Price { get; set; }
    [JsonIgnore]
    public int ProductCode { get; set; } // omitted
}

你也可以使用DataContract属性装饰你的类,存在此属性,则将忽略所有成员,除非它们具有DataMember(JsonProperty)属性。此外,可以使用DataMember序列化私有成员。

[DataContract]
public class Product
{
    [DataMember]
    public string Name { get; set; }
    [DataMember]
    public decimal Price { get; set; }
    public int ProductCode { get; set; }  // omitted by default
}

默认情况下,只读属性参与序列化。

默认情况下,Json.NET将日期将采用ISO 8601格式。例如:

2012-07-27T18:51:45.53403Z         // UTC
2012-07-27T11:51:45.53403-07:00    // Local

您可以通过设置 DateTimeZoneHandling 属性覆盖此:

var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.DateTimeZoneHandling = Newtonsoft.Json.DateTimeZoneHandling.Utc;

如果想要使用Microsoft JSON 日期格式("\/Date(ticks)\/") 设置而不是 ISO 8601 DateFormatHandling上序列化程序设置属性:

var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.DateFormatHandling 
= Newtonsoft.Json.DateFormatHandling.MicrosoftDateFormat;

编写缩进的JSON,可以如下设置:

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();

可以返回一个匿名对象。

XML媒体类型格式化程序

默认XmlMediaTypeFormatter类。默认使用DataContractSerializer来执行序列化。

若要执行此操作,设置UseXmlSerializer属性设置为true:

var xml = GlobalConfiguration.Configuration.Formatters.XmlFormatter;
xml.UseXmlSerializer = true;

请考虑使用XmlSerializer如果你需要匹配现有 XML 架构。

介绍下DataContractSerializer的序列化行为:

  • 所有公共的属性和字段进行序列化。若要忽略,使用IgnoreDataMember属性。
  • 不序列私有和受保护成员。
  • 只读属性不会序列化(但是,只读集合属性的内容进行序列化)。
  • 类和成员名称是用XML类声明中显示完成相同的。
  • 使用默认XML命名空间。

当存在此属性时,类被序列,如下所示:

  • 要序列化的属性或字段,给它装饰DataMember属性。
  • 要序列化的私有或受保护成员,给它装饰DataMember属性。
  • 只读属性不会序列化。
  • 若要更改类名称在 XML 中的显示方式,请设置名称中的参数DataContract属性。
  • 若要更改成员名称在 XML 中的显示方式,请设置名称中的参数DataMember属性。
  • 若要更改的 XML 命名空间,请设置Namespace中的参数DataContract类。

删除JSON或XML格式化程序

若要执行此操作的主要原因是:

 

  • 例如,你可能决定以支持仅将 JSON 响应,并删除 XML 格式化程序。
  • 例如,可以使用您自己的 JSON 格式化程序的自定义实现来替换 JSON 格式化程序。

调用此成员,从你应用程序_启动Global.asax 中定义的方法。

void ConfigureApi(HttpConfiguration config)
{
    // Remove the JSON formatter
    config.Formatters.Remove(config.Formatters.JsonFormatter);

    // or

    // Remove the XML formatter
    config.Formatters.Remove(config.Formatters.XmlFormatter);
}

ASP.NET Web API 中的模型验证

当客户端将数据发送到 web API 时,通常要执行任何处理之前验证数据。

数据注释

请考虑以下模型:

 

using System.ComponentModel.DataAnnotations;

namespace MyApi.Models
{
    public class Product
    {
        public int Id { get; set; }
        [Required]
        public string Name { get; set; }
        public decimal Price { get; set; }
        [Range(0, 999)]
        public double Weight { get; set; }
    }
}

Range属性指出Weight必须是介于 0 和 999 之间。

假设客户端发送 POST 请求,其中以下 JSON 表示形式:

{ "Id":4, "Price":2.99, "Weight":5 }

在你的控制器操作,可以检查模型是否有效:

using MyApi.Models;
using System.Net;
using System.Net.Http;
using System.Web.Http;

namespace MyApi.Controllers
{
    public class ProductsController : ApiController
    {
        public HttpResponseMessage Post(Product product)
        {
            if (ModelState.IsValid)
            {
                // Do something with the product (not shown).

                return new HttpResponseMessage(HttpStatusCode.OK);
            }
            else
            {
                return Request.CreateErrorResponse(HttpStatusCode.BadRequest, ModelState);
            }
        }
    }
}

可以创建一个Action筛选器来调用控制器操作前的模型检查:

using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http.Controllers;
using System.Web.Http.Filters;
using System.Web.Http.ModelBinding;

namespace MyApi.Filters
{
    public class ValidateModelAttribute : ActionFilterAttribute
    {
        public override void OnActionExecuting(HttpActionContext actionContext)
        {
            if (actionContext.ModelState.IsValid == false)
            {
                actionContext.Response = actionContext.Request.CreateErrorResponse(
                    HttpStatusCode.BadRequest, actionContext.ModelState);
            }
        }
    }
}

在这种情况下,不会调用控制器操作。

若要将此筛选器应用于所有的 Web API 控制器,将添加到筛选器的实例HttpConfiguration.Filters在配置期间的集合:

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        config.Filters.Add(new ValidateModelAttribute());

        // ...
    }
}

另一个选项是设置筛选器作为特性上各个控制器或控制器操作:

public class ProductsController : ApiController
{
    [ValidateModel]
    public HttpResponseMessage Post(Product product)
    {
        // ...
    }
}

ASP.NET Web API 中的参数绑定

Web API 在控制器上调用方法时,必须设置参数的值,此过程称为“绑定”。

默认情况下,Web API 使用以下规则进行参数绑定:

  • (稍后介绍有关类型转换器的详细信息。)
  • 媒体类型格式化程序从消息正文中读取值。

例如,下面是典型的 Web API 控制器方法:

HttpResponseMessage Put(int id, Product item) { ... }

item 参数是复杂类型,因此 Web API 使用媒体类型格式化程序从请求正文中读取值。

使用 [FromUri]

下面的示例定义 GeoPoint 类型,以及从 URI 获取 GeoPoint 的控制器方法。

public class GeoPoint
{
    public double Latitude { get; set; } 
    public double Longitude { get; set; }
}

public ValuesController : ApiController
{
    public HttpResponseMessage Get([FromUri] GeoPoint location) { ... }
}

使用 [FromBody]

若要强制 Web API 从请求正文读取简单类型,请向参数添加 [FromBody] 特性:

public HttpResponseMessage Post([FromBody] string name) { ... }

 

ASP.NET Web API 中的异常处理

HttpResponseException

默认情况下,大多数异常将转换为状态代码 500 内部服务器错误的 HTTP 响应。

例如,以下方法将返回 404,找不到,如果id参数无效。

public Product GetProduct(int id)
{
    Product item = repository.Get(id);
    if (item == null)
    {
        throw new HttpResponseException(HttpStatusCode.NotFound);
    }
    return item;
}

更好地响应的控制,还可以构造的整个响应消息,并将其与包含HttpResponseException:

public Product GetProduct(int id)
{
    Product item = repository.Get(id);
    if (item == null)
    {
        var resp = new HttpResponseMessage(HttpStatusCode.NotFound)
        {
            Content = new StringContent(string.Format("No product with ID = {0}", id)),
            ReasonPhrase = "Product ID Not Found"
        };
        throw new HttpResponseException(resp);
    }
    return item;
}

异常筛选器

HttpResponseException类型是一种特殊情况,因为它专为返回的 HTTP 响应。

 

编写异常筛选器的最简单方法是从派生System.Web.Http.Filters.ExceptionFilterAttribute类并重写OnException方法。

下面是将转换的筛选器NotImplementedException异常转化为 HTTP 状态代码 501,未实现:

namespace ProductStore.Filters
{
    using System;
    using System.Net;
    using System.Net.Http;
    using System.Web.Http.Filters;

    public class NotImplExceptionFilterAttribute : ExceptionFilterAttribute 
    {
        public override void OnException(HttpActionExecutedContext context)
        {
            if (context.Exception is NotImplementedException)
            {
                context.Response = new HttpResponseMessage(HttpStatusCode.NotImplemented);
            }
        }
    }
}

响应的属性HttpActionExecutedContext对象包含将发送到客户端的 HTTP 响应消息。

注册异常筛选器

有几种方法来注册 Web API 异常筛选器:

  • 由Action
  • 由控制器
  • 全局

筛选器应用到特定的Action,请将作为属性的筛选器添加到操作:

public class ProductsController : ApiController
{
    [NotImplExceptionFilter]
    public Contact GetContact(int id)
    {
        throw new NotImplementedException("This method is not implemented");
    }
}

筛选器应用到所有控制器上的操作,将筛选器作为属性添加到控制器类:

[NotImplExceptionFilter]
public class ProductsController : ApiController
{
    // ...
}

在此集合中的异常筛选器适用于任何 Web API 控制器操作。

GlobalConfiguration.Configuration.Filters.Add(
    new ProductStore.NotImplExceptionFilterAttribute());

如果使用"ASP.NET MVC 4 Web 应用程序"项目模板来创建你的项目,将 Web API 配置代码内的放WebApiConfig类,该类在应用程序位于_开始文件夹:

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        config.Filters.Add(new ProductStore.NotImplExceptionFilterAttribute());

        // Other configuration code...
    }
}

HttpError

下面的示例演示如何返回 HTTP 状态代码 404 (找不到) 与HttpError响应正文中。

public HttpResponseMessage GetProduct(int id)
{
    Product item = repository.Get(id);
    if (item == null)
    {
        var message = string.Format("Product with id = {0} not found", id);
        return Request.CreateErrorResponse(HttpStatusCode.NotFound, message);
    }
    else
    {
        return Request.CreateResponse(HttpStatusCode.OK, item);
    }
}

在内部, CreateErrorResponse创建HttpError实例,然后创建HttpResponseMessage ,其中包含HttpError.

 

HttpError 和模型验证

public HttpResponseMessage PostProduct(Product item)
{
    if (!ModelState.IsValid)
    {
        return Request.CreateErrorResponse(HttpStatusCode.BadRequest, ModelState);
    }

    // Implementation not shown...
}

此示例中可能会返回以下响应:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 320

{
  "Message": "The request is invalid.",
  "ModelState": {
    "item": [
      "Required property 'Name' not found in JSON. Path '', line 1, position 14."
    ],
    "item.Name": [
      "The Name field is required."
    ],
    "item.Price": [
      "The field Price must be between 0 and 999."
    ]
  }
}

使用 HttpResponseException HttpError

这样就可以返回强类型化模型中正常成功的情况下,同时仍返回HttpError如果出现错误:

public Product GetProduct(int id)
{
    Product item = repository.Get(id);
    if (item == null)
    {
        var message = string.Format("Product with id = {0} not found", id);
        throw new HttpResponseException(
            Request.CreateErrorResponse(HttpStatusCode.NotFound, message));
    }
    else
    {
        return item;
    }
}

全局错误处理 ASP.NET Web API 2 中

如今,在Web API中没有简单的方式记录或处理全局错误。可以通过异常筛选器过滤某些未经处理的异常,但也有一部分异常筛选器不能处理。例如:

  1. 从控制器的构造函数引发的异常。
  2. 从消息处理程序引发的异常。
  3. 在路由期间引发的异常。
  4. 响应内容序列化期间引发的异常。

我们可以使用异常筛选器,消息处理程序(后面会提到),但是它们都很难处理上面的问题,所以微软提供了两个类:IExceptionLogger和IExceptionHandler。

我们该怎么使用:

  • IExceptionLogger用于查看WebAPI捕获到的所有未经过处理的异常。
  • IExceptionHandler用于自定义所有可能的响应未经处理WebAPI捕获的异常。
  • IExceptionFilter是Controller或者Action下捕捉未经处理的异常的最简单的解决方案。
public interface IExceptionLogger
{
   Task LogAsync(ExceptionLoggerContext context, 
                 CancellationToken cancellationToken);
}

public interface IExceptionHandler
{
   Task HandleAsync(ExceptionHandlerContext context, 
                    CancellationToken cancellationToken);
}

 

 


鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
热门推荐
热门话题
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap