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。

【入门】

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

• 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开发者简装版）

二、新建Web API项目

图一、建立项目

图2.选择Web API项目模板

 

三、添加一个模型

模型是表示应用程序数据的一种对象。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; }
    }
}

四、添加控制器

控制器是一种处理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的最后部分；

 

【进阶】

 一、实现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访问的动做名字。

 

 二、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系列教程目录【对微软官方主页教程的良心翻译】

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