使用ASP.Net WebAPI構建REST服務

2022-06-14 10:01:48

一、建立WebAPI應用程式

1、Web API 1版本

首先建立一個Asp.Net MVC 4 Web應用程式（我這裡用的是Visual Studio 2012）。

在出來的模板中選擇Web API。點選確定後，就建立了一個空的WebAPI服務。

2、Web API 2版本

點選確定後，就建立了一個空的WebAPI服務。此時只有一個空專案，還沒有任何功能

在進行下一步之前，首先我們來看一下REST的基本操作模型，大致可以分為如下四種：

POST — 建立資源
GET — 檢索資源
PUT — 更新資源
DELETE — 刪除資源

非常經典的CRUD模型。

在Web API中實現這樣一個的模型是非常簡單的，直接使用嚮導建一個Controller即可

在Web API中生成預設的ValuesController

預設的模板內容如下：

public class ValuesController : ApiController
{
        // GET api/values
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values/5
        public string Get(int id)
        {
            return "value";
        }

        // POST api/values
        public void Post([FromBody]string value)
        {
        }

        // PUT api/values/5
        public void Put(int id, [FromBody]string value)
        {
        }

        // DELETE api/values/5
        public void Delete(int id)
        {
        }
}

這其實已經幫我們實現了一個最基本的服務了，不過這個服務中只實現了Get，它支援如下兩種中方式的URL存取（其它的方式也能存取，但沒有具體的效果）：

api/values 存取所有的Value列表
api/values/{id} 根據ID存取Value

按Ctrl + F5中執行，在瀏覽器中輸入相應的地址即可看到結果

下面我們要做的就是完善它，實現一個簡單的查詢功能，這裡我參照了微軟官方的一個例子：

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 Get()
        {
            return products;
        }

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

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

此時，我們就可以在瀏覽器中看到結果了（由於Controller改名字了，此時的地址就變成了api/products）

到此為止，一個基於Asp.net Web API的簡單的REST Web服務就構建完成了，由於篇幅所限，這裡就不做更多的介紹了，跟多資訊可以參看微軟官方檔案：Getting Started with ASP.NET Web API 2。

備註：WebAPI升級到 WebAPI 2如下命令更新web Api：

Install-Package Microsoft.AspNet.WebApi

二、路由

REST並沒有像傳統的RPC服務那樣顯式指定了伺服器函數的存取路徑，而是將URL根據一定的規則對映為服務函數入口，這個規則就稱之為路由。Asp.Net WebAPI的路由方式和Asp.Net MVC是相同的，它支援兩種路由方式，傳統的路由對映和特性路由。路由規則WebApiConfig.cs中定義。

它的預設內容如下：

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // Web API configuration and services

        // Web API routes
        config.MapHttpAttributeRoutes();

        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}/{id}",
            defaults: new { id = RouteParameter.Optional }
        );
    }
}

它預設註冊了兩種路由規則，第一行註冊的是特性路由，第二行註冊的則是傳統的對映路由。預設情況下，由於我們沒有編寫特性路由規則，則是按照傳統的Controller方式對映路由。

關於路由規則，MSDN檔案ASP.NET 路由介紹得非常詳細，但由於其介紹得太詳細了，反而不容易得其門而入，這裡我只拿預設的路由規則來簡單但的介紹一下我的理解，它的uri格式是這樣的"api/{controller}/{id}"，其中id是可選的。拿前文的例子來說吧，

當我們對api/products地址進行存取的時候，系統則會首先找到名為ProductsController的控制器。
然後，根據存取方式查詢函數，由於這裡是Get操作，則查詢Get開頭的函數，這裡會找到Get()和Get(int id)兩個過載版本。
最後，根據引數來匹配具體的函數，因為這裡沒有帶引數id。因此匹配到了Get()函數，返回了所有的集合。

另外，這裡也有幾個常用的衍生規則：

根據操作方式找函數的時候，只需要匹配首部即可，因此我們編寫函數的時候寫成Get()和GetProduct()都是可以的。，
根據操作方式找函數的時候查詢的時候不分大小寫，因此寫成Get()或get()都是可以的

當我們使用帶引數的版本時候，也有幾個需要注意的地方：

引數名不分大小寫，我們寫成id或ID都是可以的
引數名要求嚴格匹配的，我們寫成ID2是不行的，此時則會匹配到錯誤的結果Get()

預設的規則雖然大多數的時候還是比較方便的，但是很多時候我們需要手動指定個性化的路由規則。例如，我們可以自定義一個按名稱來查詢的url：api/products/name=xxx。這個時候則可以用特性路由快速的實現了：

[Route("api/{controller}/name={name}")]
public IHttpActionResult GetByName(string name)

關於特性路由，MSDN原文Attribute Routing in ASP.NET MVC 5介紹得非常詳細。

三、返回值

Asp.Net WebAPI服務函數的返回值主要可以分為void、普通物件、HttpResponseMessag、IHttpActionResult e四種，本文這裡簡單的介紹一下它們的區別。

1、返回void

返回void一般常用於Put和Delete函數。

public void Delete(int id)
{
}

當服務函數執行完成後，伺服器端並不是啥都不幹直接把使用者端給斷掉，而是傳送一個標準的204 (No Content)的Http應答給使用者端。

HTTP/1.1 204 No Content
    Cache-Control: no-cache
    Pragma: no-cache
    Expires: -1
    Server: Microsoft-IIS/8.0
    X-AspNet-Version: 4.0.30319
    X-SourceFiles: =?UTF-8?B?Zjpc5paH5qGjXHZpc3VhbCBzdHVkaW8gMjAxM1xQcm9qZWN0c1xXZWJBcHBsaWNhdGlvbjFcV2ViQXBwbGljYXRpb24xXGFwaVx2YWx1ZXNcMQ==?=
    X-Powered-By: ASP.NET
    Date: Fri, 02 May 2014 13:32:07 GMT

2、返回普通物件

返回普通物件時，伺服器將返回的物件序列化後（預設是json），通過Http應答返回給使用者端。例如，

public class ValuesController : ApiController
{
        public string Get()
        {
            return "hello";
        }
}

此時的返回結果是：

HTTP/1.1 200 OK
    Cache-Control: no-cache
    Pragma: no-cache
    Content-Type: application/json; charset=utf-8
    Expires: -1
    Server: Microsoft-IIS/8.0
    X-AspNet-Version: 4.0.30319
    X-SourceFiles: =?UTF-8?B?Zjpc5paH5qGjXHZpc3VhbCBzdHVkaW8gMjAxM1xQcm9qZWN0c1xXZWJBcHBsaWNhdGlvbjFcV2ViQXBwbGljYXRpb24xXGFwaVx2YWx1ZXM=?=
    X-Powered-By: ASP.NET
    Date: Fri, 02 May 2014 12:54:18 GMT
    Content-Length: 7
"hello"

非同步返回普通物件：

WebAPI也是支援非同步返回物件的：

    public async Task<string> Get()
    {
        await Task.Delay(100);
        return "hello";
    }

非同步返回的時候，伺服器非同步等待函數執行完成後再將返回值返回給物件。由於這個過程對於使用者端來說是透明的，這裡就不列舉報文了。

3、返回HttpResponseMessage

HttpResponseMessage是標準Http應答了，此時伺服器並不做任何處理，直接將HttpResponseMessage傳送給使用者端。

public HttpResponseMessage Get()
{
        var response = Request.CreateResponse(HttpStatusCode.OK);
        response.Content = new StringContent("hello", Encoding.UTF8);
            
        return response;
}

此時的返回結果如下：

HTTP/1.1 200 OK
    Cache-Control: no-cache
    Pragma: no-cache
    Content-Length: 5
    Content-Type: text/plain; charset=utf-8
    Expires: -1
    Server: Microsoft-IIS/8.0
    X-AspNet-Version: 4.0.30319
    X-SourceFiles: =?UTF-8?B?Zjpc5paH5qGjXHZpc3VhbCBzdHVkaW8gMjAxM1xQcm9qZWN0c1xXZWJBcHBsaWNhdGlvbjFcV2ViQXBwbGljYXRpb24xXGFwaVx2YWx1ZXM=?=
    X-Powered-By: ASP.NET
    Date: Fri, 02 May 2014 13:09:57 GMT
hello

可以看到，這裡返回的content-type仍然是原始定義的text型別，而不是json。要實現想上面的例子所示的結果，則需要將Get函數改寫為如下形式

public HttpResponseMessage Get()
{
        return Request.CreateResponse(HttpStatusCode.OK, "hello");
}

4、返回IHttpActionResult

IHttpActionResult是Web API 2 中引入的一個介面，它的定義如下：

public interface IHttpActionResult
{
        Task ExecuteAsync(CancellationToken cancellationToken);
}

從它的定義可以看出，IHttpActionResult是HttpResponseMessage的一個工廠類，最終還是用於構建HttpResponseMessage返回，由於它可以取消，因而可以實現更為強大的返回功能（如流傳輸）。當服務函數返回IHttpActionResult物件時，伺服器執行該物件的ExecuteAsync函數，並非同步等待至函數完成後，獲取其返回值HttpResponseMessage輸出給使用者端。

IHttpActionResult是WebAPI中推薦的標準返回值，ApiController類中也提供了不少標準的工廠函數方便我們快速構建它們，如BadRequest，Conflict，Ok，NotFound等，一個簡單的範例如下：

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

四、引數繫結

1、預設繫結方式

WebAPI把引數分成了簡單型別和複雜型別：

簡單型別主要包括CLR的primitive types，（int、double、bool等），系統內建的幾個struct型別（TimeSpan、Guid等）以及string。對於簡單型別的引數，預設從URI中獲取。
複雜型別的資料也可以直接作為引數傳入進來，系統使用media-type formatter進行解析後傳給服務函數。對於複雜型別，預設從正文中獲取。

例如，對於如下函數

HttpResponseMessage Put(int id, Product item)

其id預設從url中獲取，其item預設從正文中獲取。

2、使用 [FromUri] 標記從URI中繫結引數

我們可以使用 [FromUri] 標記強制從URI中繫結引數，例如

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

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

這樣，Get引數就是從URI中獲取了讀取GeoPoint物件。需要注意的是，此時我們必須將GeoPoint物件的屬性在URI中傳入： http://localhost/api/values/?Latitude=47.678558&Longitude=-122.130989 。

這種預設的序列化方式比較冗長，我們也可以自定義反序列化格式為類似這樣的形式：http://localhost/api/values/?location=47.678558,-122.130989，具體方法請參看參考檔案 Type Converters 的一節。

3、使用 [FromBody] 標記從正文中繫結引數

同樣，我們可以使用 [FromBody] 標記強制從正文中繫結引數，例如

public HttpResponseMessage Post( [FromBody] string name)

將強制從FormData等非URL引數中讀取資料

4、繫結多個引數

前面介紹的方式中，只能從URI中繫結一個引數，雖然可以通過傳入複雜型別解決多引數的問題，但很多時候不如在URI中來得直接。此時，我們則可以使用前面介紹的特性路由來實現多參的繫結，例如：

[Route("api/{controller}/{year}/{month}/{day}")]
public string Get(int year, int month, int day)
{
        return string.Join(",", year, month, day);
}

參考檔案： http://www.asp.net/web-api/overview/formats-and-model-binding

五、使用者端

WebAPI是標準的Http協定，支援Http協定的使用者端（如瀏覽器）都可以存取。但是，有的時候我們如果想在自己的程式中使用WebAPI時，此時就要實現自己的使用者端了。

1、使用HttpClient庫

我之前介紹過在.Net 4.5中新增的HttpClient庫，它對Http操作實現了非常好的封裝。我們可以通過它實現Http存取，例如，我們對前文所示的API進行一次Post操作：

// POST: api/Values
public void Post(Product value)
{
}

首先對HttpClient進行一些初始化操作：

var client = new HttpClient();
client.BaseAddress = new Uri("http://localhost:1282/");
client.DefaultRequestHeaders.Accept.Clear();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

這裡主要進行了兩部操作：1. 定義了預設的基地址，減少後續的URL長度，2. 定義了預設的接受的資料型別為Json。

下一步就要開始對Product物件的內容編碼，預設是xml或json，這裡我選擇相對簡單的json：

var product = new Product() { Id = 1, Name = "food" };
var content = Newtonsoft.Json.JsonConvert.SerializeObject(product);
var httpContent = new StringContent(content, Encoding.UTF8);
httpContent.Headers.ContentType = new MediaTypeHeaderValue("application/json") { CharSet = "utf-8" };
await httpContent.LoadIntoBufferAsync();
var rsp = await client.PostAsync("api/values", httpContent);

從上面的程式碼可以看出，由於WebAPI不像WCF那樣能自動生成使用者端程式碼，需要我們自己封裝物件，上面光封裝物件就用了四行程式碼，對於不熟悉HttpClient朋友來說還是比較容易出錯的。因此微軟提供了一系列擴充套件函數方便我們簡化這一過程。

2、使用WebApi.Client庫

在Nuget中安裝WebApi.Client庫

這個庫安裝後會在參照中增加一個System.Net.Http.Formatting的程式集，它主要提供了一系列擴充套件函數（其實裝這個庫順帶也會把HttpClient和Json.Net一併安上），現在上面的程式碼就可以簡化如下了：

var product = new Product() { Id = 1, Name = "food" };
var rsp = await client.PostAsJsonAsync("api/values", product);

除了PostAsJsonAsync這個擴充套件函數外，還提供了PostAsXmlAsync這種以XML傳輸的方式。同樣，Put也有PutAsJsonAsync和PutAsXmlAsync的擴充套件版本。對於Get，雖然也提供了擴充套件函數，但是使用的方式稍有不同：

var rsp = await client.GetAsync("api/values/1");
rsp.EnsureSuccessStatusCode();
var product = await rsp.Content.ReadAsAsync();

對於Delete，卻沒有提供擴充套件函數，可能是官方認為Delete直接在URL中就傳ID就夠用了，沒必要在Request中封裝訊息了吧。

限於篇幅，今天就介紹到這裡了，更多內容的可以參看官方檔案：http://www.asp.net/web-api/overview/web-api-clients/calling-a-web-api-from-a-net-client

六、Self-Host

Asp.Net WebAPI生成的是一個程式集，並不是獨立的程序，因此，要執行的時候必須將其承載在相應的宿主上，一般比較常見的是IIS承載。

很多時候，我們為了簡化部署或者功能整合，需要將其承載到獨立的程序上，這種方式一般稱之為Self-Host，本文就簡單的介紹一下WebAPI的SefHost方法。

首先在Nuget上安裝Microsoft.AspNet.WebApi.SelfHost庫。

附上我們的WebAPI控制器

public class ValuesController : ApiController
{
    public IEnumerable<string> Get()
    {
        return new string[] { "111", "222" };
    }
}

接下來的工作就是啟動我們的伺服器了。

    class Program
    {
        static void Main(string[] args)
        {
            //Assembly.Load("WebApplication1, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null");    //載入外部程式集
            var config = new HttpSelfHostConfiguration("http://localhost:8080");

            config.Routes.MapHttpRoute(
                "API Default", "api/{controller}/{id}",
                new { id = RouteParameter.Optional });

            using (var server = new HttpSelfHostServer(config))
            {
                server.OpenAsync().Wait();
                Console.WriteLine("Press Enter to quit.");
                Console.ReadLine();
            }
        }
    }

從上面的程式碼可以看出，組態檔和Asp.Net程式中基本上是一樣的，如果是直接用Asp.Net專案中生成的DLL的話，我們也可以直接用其WebApiConfig.Register的方法來進行設定的（需要像第一行注掉的那樣使用Assembly.Load載入程式集）。下面一段就是啟動伺服器了，更多內容可以參看MSDN檔案：http://www.asp.net/web-api/overview/hosting-aspnet-web-api/self-host-a-web-api

值得一提的是，SelfHost是在一個獨立程序中啟動了Http服務，也可以是說，它是一個mini版的Http伺服器，我之前介紹過通過HttpListener實現簡單的Http服務，到了現在，用WebAPI的SelfHost方式是可以更加快捷的實現擴充套件性更好的Mini Http伺服器的，當我們需要一個簡單的Http服務的時候，可以使用這種方式。

除了這種方式外，微軟更加推薦用功能更加強大的OWIN來承載WebAPI服務。

另外，除了IIS、SelfHost等方式外，雲時代釋出到Windows Azure也是非常便捷的，這裡就不做多少介紹了，詳細內容請參看MSDN檔案：http://www.asp.net/web-api/overview/hosting-aspnet-web-api 。