ASP.NET Web API 入门大杂烩

【前言】

本文是大杂烩，意思即是：到处Copy再加一点点思考而混在一起的文章，引用来源因为太多太杂故而省略，望原作者原谅。

【概述】

ASP.NET Web API随ASP.NET MVC 4一起发行。它遵循REST架构风格，取WCF Web API与ASP.NET MVC精华，又去除WCF本身较为繁琐的配置问题，专注于提供HTTP Service，只面向Http通信协议，使得可快速开发出自身使用或对外公开的Web API。前端应用只要能发出HTTP的URI请求（例如：http://domain/api/products）向Web API请求服务即可取得如JSON或XML或自定义数据源。

ASP.NET Web APIWeb API 的开发类似于 ASP.NET MVC 中控制器的开发，但是Web API 封装了数据的序列化、反序列化，接口、实现都更加简单。简单地说，如果要向浏览器、移动端等广泛的客户端提供 Json/xml 数据格式，则应首选 ASP.NET Web API。

从 .NET 3.5 开始 WCF 框架已经支持用 WebHttpBinding 构建建立在 WCF Message 栈上的 RESTful Web服务。因为 REST 的工作原理不同，不需要依赖 SOAP 协议，因此 WCF 消息管道对它做了特殊的优化。但 REST 集成在 WCF 消息管道上还是不理想，所以微软提出在 ASP.NET 平台上构建REST，也就有了现在中的 Web Api。

【入门】

1、首先确保开发环境符合微软的要求：

Visual Studio 2012
Visual Studio Express 2012 for Web
Visual Studio 2010 with ASP.NET MVC 4 installed.（安装了ASP.NET MVC 4的VS 2010）
Visual Web Developer 2010 Express with ASP.NET MVC 4 installed.（安装了ASP.NET MVC 4的VS 2010 Web开发者简装版）

2、新建Web API项目

图1、创建项目

图2.选择Web API项目模板

3、添加一个模型

模型是表示应用程序数据的一种对象。ASP.NET Web API可以自动把模型序列化成JSON、XML、或某些其它格式然后写到HTTP响应的消息体中。只要客户端能够读取这种序列化格式，它就可以进行反序列化获取对象信息。另一方面，设置HTTP请求消息中的Accept报头，客户端能够指示它所希望的是哪一种格式。

图3.添加模型

将这个类命名为“Product”，并添加如下属性：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;

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

4、添加控制器

控制器是一种处理HTTP请求的对象。“新项目”向导在创建该项目时为你创建了两个控制器。要看到它们，在“解决方案资源管理器”中展开Controllers文件夹。

HomeController 是传统的ASP.NET MVC控制器。它负责对网站的HTML页面进行服务，且与Web API无直接关系。

ValuesController 是一个例子型的WebAPI控制器。在下一步之前，将此控制器完全删除。

图4.添加一个控制器

图5.创建一个API控制器

修改此控制器的代码如下：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;

using HelloWebAPI.Models;

namespace HelloWebAPI.Controllers
{
    public class ProductsController : ApiController
    {
        Product[] products = new Product[] 
        { 
            new Product { Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1 }, 
            new Product { Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M }, 
            new Product { Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M } 
        };
        public IEnumerable<Product> GetAllProducts()
        {
            return products;
        }
        public Product GetProductById(int id)
        {
            var product = products.FirstOrDefault((p) => p.Id == id);
            if (product == null)
            {
                throw new HttpResponseException(HttpStatusCode.NotFound);
            }
            return product;
        }
        public IEnumerable<Product> GetProductsByCategory(string category)
        {
            return products.Where(
                (p) => string.Equals(p.Category, category,
                    StringComparison.OrdinalIgnoreCase));
        }
    }
}

为了保持示例简单，产品被存储在该控制器类的一个固定数组中。当然，在一个实际应用程序中，你会查询一个数据库，或使用某些其它外部数据源。

该控制器定义了三个方法，它们或者返回一个单一产品，或一个产品列表：

GetAllProducts方法以IEnumerable<Product>类型返回产品的完整列表。

GetProductById方法通过ID查询一个单一产品

GetProductsByCategory方法返回指定类别的全部产品。

好了，你有了一个能工作的Web API了。该控制器上的每个方法都映射到一个URI（如表1所示）：

表1. 控制器方法所映射的URI
Controller Method 控制器方法	URI
GetAllProducts	/api/products
GetProductById	/api/products/id
GetProductsByCategory	/api/products/?category=category

【调试】

在VS中启动调试。ASP.NET开发服务器（ASP.NET Development Server）将启动，屏幕的右下角部将出现一个通知，显示它运行的端口号。默认地，开发服务器选择随机端口号。

Visual Studio然后将自动打开浏览器窗口，其URL指向http//www.localhost:xxxx/，这里，xxxx是端口号。首页看上去应当像这样（如图6所示）：

图6.应用程序首页

该首页是一个ASP.NET MVC视图，它是由HomeControllers类返回的。为了调用Web API，我们必须使用前面列出的URI之一。例如，要得到全部产品列表，浏览http://localhost:xxxx/api/products/。

结果取决于你所使用的浏览器。Internet Explorer（IE浏览器）将提示你是否打开或保存一个名称为products的“文件”（如图7所示）。

图7.IE的提示

用记事本打开：

如果用Firefox或者Chrome访问，则会在浏览器中用xml形式显示：

出现这种差别的原因是IE和Firefox发送了不同的Accept报头，因此，Web API在响应中发送了不同的内容类型。

现在，试着浏览这些URI：

http://localhost:xxxx/api/products/1
http://localhost:xxxx/api/products?category=hardware

第一个应当返回ID等于1的词条。第二个应当返回Category等于“hardware”的所有产品的列表（这里，只有一个词条）。

目前为止就实现了一个最简单的Web API应用。

有两个改进的方向：

在IE上按“F12”启动开发人员工具，可以看见详细的请求以及响应信息；

在页面增加按钮、输入框等实现查询等功能；

以上两步详见：调用与 Javascript 和 jQuery 的 Web API的最后部分；

【进阶】

1、实现CURD

CURD 是指对资源的增删查改，对应了Create 、 Update 、 Read 、 Delete 四个简单的数据库操作。

在Web API中，Create 、 Update 、 Read 、 Delete 分别可以通过Post，Put，Delete，Get四种HTTP方法来实现。当然，在实际应用中，更多的是使用了Get/Post方法。

在Web API中，默认在每个方法名字之前加上Create 、 Update 、 Read 、 Delete字眼就可以识别方法对应的HTTP方法，当让，也可以手动在每个方法之前增加属性标注，强制指明所使用的HTTP方法。如下所示：

[HttpGet]
        [ActionName("GetUser")]
        public IEnumerable<User> GetUsersByName(string userName)
        {
            return users.Where(
                (p) => string.Equals(p.UserName, userName,
                    StringComparison.OrdinalIgnoreCase));
        }

        [HttpPost]
        [ActionName("AddUser")]
        public User AddUser([FromBody]User user)
        {
            if (user == null)
            {
                throw new HttpRequestException();
            }
            users.Add(user);
            return user;
        }

至于ActionName标注，是方便在更改路由规则之后，可以指定一个URL访问的动作名字。

2、API路由规则

Web API会App_Start目录的WebApiConfig.cs文件创建一个默认的路由模板是“api/{controller}/{id}”：

routes.MapHttpRoute( 
    name: "API Default", 
    routeTemplate: "api/{controller}/{id}", 
    defaults: new { id = RouteParameter.Optional } 
);

在这个模板中，“api”是一个标记式的文字路径，而{controller}和{id}是占位符变量。

当Web API接收到一个HTTP请求，它会试图根据路由表中的一个路由模板来匹配其URI。如果无路由匹配，客户端会接收到404（NotFound）错误。例如，以下URI与默认路由匹配：

/api/contacts
/api/contacts/1
/api/products/gizmo1

然而，以下URI不匹配，因为它缺少“api”片段：

/contacts/1

注：使用“api”的原因是为了避免与ASP.NET MVC的路由冲突。通过这种方式，可以用“/contacts”进入一个MVC控制器，而“/api/contacts”进入一个Web API控制器。

一旦匹配路由，Web API便会选择相应的控制和动作：

1，根据URI中的“控制器”作为{controller}变量的值找到Web API中的Controller。

2，为了找到动作，Web API寻找一个名称以HTTP方法名开头的动作。例如，对于一个GET请求，Web API会查找一个以“Get…”开头的动作，如“GetContact”或“GetAllContacts”等。这种约定仅运用于GET、POST、PUT和DELETE方法。通过把注解属性运用于控制器，你可以启用其它HTTP方法。也可以使用上述所说在每个方法前增加属性标注强制指明HTTP方法类型。

3，路由模板中的其它占位变量，如{id}，被映射成动作参数。

正如前文说，较多的HTTP请求使用Get/POST方法，这样的话，就不排除在一个Controller里面有好几个POST方法并且参数格式也差不多的。由于默认路由只会匹配第一个匹配的方法，所以仅仅是使用默认路由是满足不了要求的。

这种情况下我们可以改变路由规则：

routes.MapHttpRoute( 
    name: "ActionApi", 
    routeTemplate: "api/{controller}/{action}/{id}", 
    defaults: new { id = RouteParameter.Optional } 
);

配合ActionName,NonAction标注，可以更改更精准地匹配到方法。

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

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

    // Not an action method.
    // 不是一个动作方法
    [NonAction] 
    public string GetPrivateData() { ... }
}

【发布】

【推荐网站】

ASP.NET Web API官方主页

ASP.NET Web API系列教程目录【对微软官方主页教程的良心翻译】

ASP.NET Web API 入门大杂烩

我最喜爱的功能：Entity Framework Code First和 ASP.NET Web API