1、入门--ASP.NET Web API 2 (C#)

杨孟易翻译于2015年1月15日星期四

HTTP不只是服务了网页。这也是一个强大的平台，构建公开服务和数据的API。 HTTP是简单，灵活，并且无处不在的。几乎你能想到的任何平台上都有一个HTTP库，所以HTTP服务可以达到广泛的客户，包括浏览器，移动设备和传统的桌面应用程序。

ASP.NET Web API是在.NET Framework上构建的Web API的框架。在本教程中，你将使用ASP.NET Web API来创建一个产品清单的Web API。

教程使用的软件版本

Visual Studio 2013 update 4
Web API 2

创建Web API项目

在本教程中，你将使用ASP.NET Web API来创建一个产品清单的Web API。前端网页使用jQuery来显示结果。

启动Visual Studio，并从起始页中选择新建项目，或者从文件菜单，选择新建，然后选择项目。

在模板窗口中，选择已安装的模板，并展开Visual C＃节点。在Visual C＃中，选择Web。在项目模板列表中，选择ASP.NET Web应用程序。将项目命名为“ProductsApp”，然后单击确定。

在新建ASP.NET项目对话框中，选择Empty。在“为以下对象添加文件夹和核心引用”，勾选Web API。点击确定。

你也可以使用“Web API”模板创建Web API项目。在Web API模板中使用ASP.NET MVC提供API帮助页面。因为我想证明没有MVC的Web API，所以本教程使用的是空模板。一般情况下，你不需要知道ASP.NET MVC后才使用Web API。

添加Model（模型）

model（模型）是一个对象，它代表了应用程序中的数据。 ASP.NET Web API可以自动将model（模型）序列化为JSON、XML或者其他格式，然后将序列化的数据写入到HTTP响应消息的正文。只要客户端可以读取序列化格式，它就可以反序列化对象。大多数客户端可以解析XML或者JSON。此外，客户端可以通过设置HTTP请求消息的Accept报头来获取想要的消息格式。

让我们先创建一个代表产品的简单model（模型）。

如果解决方案资源管理器看不见，单击视图菜单，然后选择解决方案资源管理器。在解决方案资源管理器中，右键单击Models文件夹。从上下文菜单中，选择添加，然后选择类。

命名类为“Product”。将以下属性添加到产品类。

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

添加Controller（控制器）

在Web API中, 一个controller（控制器） 是一个处理HTTP请求的对象。我们将添加一个controller控制器，可以返回的产品列表或通过ID指定一个产品。

注意：如果你已经使用ASP.NET MVC，已经熟悉了控制器。Web API控制器类似于MVC控制器，但继承ApiController类，而不是Controller类。

在解决方案资源管理器中，右键单击Controllers（控制器）文件夹。选择添加，然后选择控制器。

在添加基架对话框中，选择Web API控制器 - 空。单击添加。

在添加控制器对话框，命名controller（控制器）为“ProductsController”，点击添加。

在Controllers文件夹下面，基架创建了一个名为ProductsController.cs的文件。

你不需要把contollers（所有控制器）都放到一个文件夹命名为Controllers。该文件夹的名字仅仅是方便你组织源文件的一种方式。

如果此文件尚未打开，双击打开该文件。替换在此文件中使用以下的代码：

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

namespace ProductsApp.Controllers
{
    public class ProductsController : ApiController
    {
        Product[] products = new Product[] 
        { 
            new Product { Id = 1, Name = "番茄蛋汤", Category = "汤类", Price = 10 },
            new Product { Id = 2, Name = "土豆丝", Category = "中餐", Price = 3.75M },
            new Product { Id = 3, Name = "汉堡包", Category = "快餐", Price = 16.99M }
        };

        public IEnumerable<Product> GetAllProducts()
        {
            return products;
        }

        public IHttpActionResult GetProduct(int id)
        {
            var product = products.FirstOrDefault((p) => p.Id == id);
            if (product == null)
            {
                return NotFound();
            }
            return Ok(product);
        }
    }
}

为了令例子简单，产品存储在控制器类中的固定数组。当然，在实际应用中，你会查询数据库，或使用一些其他的外部数据源。

该控制器定义了返回产品两种方法：

GetAllProducts 方法返回产品IEnumerable<Product>类型的整个列表。
GetProduct 方法通过其ID查找单个产品。

就是这样！你有一个运行中的Web API。控制器上的每个方法对应于一个或多个URI：

控制器方法	URI
GetAllProducts	/api/products
GetProduct	/api/products/id

针对GetProduct方法，在URI中的id是一个占位符。例如，为了得到编号为5的产品，该URI就为api/products/5。

有关如何使Web API将HTTP请求路由到控制器方法的详细信息，请参阅Routing in ASP.NET Web API（未翻译，导航到官网）.

通过JavaScript和jQuery调用Web API

在本节中，我们将添加使用AJAX调用Web API的HTML页面。我们将使用jQuery做AJAX调用，也会根据返回结果更新页面。

在解决方案资源管理器中，右键单击该项目并选择添加，然后选择新建项。

在添加新项对话框中，在Visual C＃下面选择Web节点，然后选择HTML页的项目。命名页“index.html”。

以下内容替换这个文件中的所有内容：

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>Product App</title>
</head>
<body>

  <div>
    <h2>所有产品</h2>
    <ul id="products" />
  </div>
  <div>
    <h2>通过ID搜索</h2>
    <input type="text" id="prodId" size="5" />
    <input type="button" value="Search" onclick="find();" />
    <p id="product" />
  </div>

  <script src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.3.min.js"></script>
  <script>
    var uri = 'api/products';

    $(document).ready(function () {
      // 发送AJAX请求
      $.getJSON(uri)
          .done(function (data) {
            // 如果成功，‘data’包含产品列表。
            $.each(data, function (key, item) {
              // 将列表添加到product节点。
              $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
          });
    });

    function formatItem(item) {
      return item.Name + ': ￥' + item.Price;
    }

    function find() {
      var id = $('#prodId').val();
      $.getJSON(uri + '/' + id)
          .done(function (data) {
            $('#product').text(formatItem(data));
          })
          .fail(function (jqXHR, textStatus, err) {
            $('#product').text('错误: ' + err);
          });
    }
  </script>
</body>
</html>

有几种方法得到的jQuery。在这个例子中，我使用了百度的Ajax CDN。您也可以从http://jquery.com/下载，并且ASP.NET的“Web API”项目模板已经包括了jQuery。

获得产品列表

为了获得产品列表，发送HTTP GET请求到“/api/products”。
jQuery的getJSON方法发送了AJAX请求。响应包含JSON对象的数组。如果请求成功，将回调done方法，更新产品信息的DOM节点。

$(document).ready(function () {
    // 发送AJAX请求 
    $.getJSON(apiUrl)
        .done(function (data) {
            // 如果成功，‘data’包含产品列表。
            $.each(data, function (key, item) {
                // 将列表添加到product节点。
                $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
        });
});

通过ID获得一个产品

为了通过ID获得产品，发送一个HTTP的GET请求到“/api/products/id”，其中id就是产品ID。

function find() {
    var id = $('#prodId').val();
    $.getJSON(apiUrl + '/' + id)
        .done(function (data) {
            $('#product').text(formatItem(data));
        })
        .fail(function (jqXHR, textStatus, err) {
            $('#product').text('错误: ' + err);
        });
}

我们仍然调用的getJSON发送Ajax请求，但这次我们把ID加在请求的URI上。从这个请求的响应是一个单一产品的JSON格式。

运行应用程序

按F5开始调试应用程序。该网页应该像下面这样：

要通过ID获得产品，输入ID，然后点击搜索：

如果输入一个无效的ID，服务器返回一个HTTP错误：

下一章，将介绍Web API 2 的Action Results，或者参考原文Action Results in Web API 2