導航頁面

上一步

開始

路由是指 Web API 將URI匹配到一個action。 Web API 2 支援一種新的路由方式，叫做“特性路由”。就像它的名字所示，特性路由使用特性來定義路由規則。特性路由可以讓你更好的控制 Web API 的 URI。 比如，你可以很容易的建立指向層次性資源的URI。

早些時候的路由規則，被稱為基於慣例的路由，現在仍被廣泛支援。事實上，你可以在同一個專案中同時使用這兩種技術。

前提

本教程使用VS2017。
當然，也可以使用 NuGet Package Manager（NyGet程式包管理器）來安裝必要的包。“選單”-> “工具” -> “NuGet Package Manager”（Nuget程式包管理器） -> Package Manager Console（程式包管理器控制檯）.在PM Console裡面輸入以下命令：

Install-Package Microsoft.AspNet.WebApi.WebHost

為什麼使用特性路由

基於慣例的路由規則的一個優點是，路由模板被定義在單一的地方，並且路由規則適用於所有的控制器。不幸運的是，基於慣例的路由規則很難支援某些在RESTful API中很常見的URI. 例如，資源地址經常包含了子資源地址：顧客有訂單、電影有演員，書有作者之類的。我們建立URI經常需要來反應出這些關係。

/customers/1/orders

對於這樣的URI，使用基於慣例的路由規則是很難創建出來的。儘管可以做，但是如果有非常多的controller和資源型別的話，這樣的路由規則往往很難通配。

使用特性路由，為這樣的URI定義一個路由規則是非常簡單的。只需要在這個controller的action上加這樣一條特性即可：

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

這裡有一些其他的路由模式，在這些模式下，使用特性路由可以更簡單的做到。

API版本

在這裡例子中， “/api/v1/products”與”/api/v2/products”將會被路由到不同的控制器。

/api/v1/products
/api/v2/products
 

多引數型

在這裡例子中，“1”是一個訂單號，但是”2013/06/16” 是一個日期。

/orders/1
/orders/2013/06/16

使用特性路由

要使用特性路由，在配置時需要呼叫MapHttpAttributeRoutes 。這個擴充套件方法被定義在System.Web.Http.HttpConfigurationExtensions類裡。

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.
        }
    }
}

特性路由可以與基於慣例的路由一起使用。要想定義基於慣例的路由，需要呼叫MapHttpRoute 方法。

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // Attribute routing.
        config.MapHttpAttributeRoutes();

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

Note: Migrating From Web API 1

在 Web API 2 之前，Web API 專案模板產生的程式碼是這樣的：

protected void Application_Start()
{
    // WARNING - Not compatible with attribute routing.
    WebApiConfig.Register(GlobalConfiguration.Configuration);
}

如果使用了特性路由，這段程式碼將會丟擲一個異常。如果你要在已存在的Web API專案中使用特性路由，要確保將配置程式碼改成下面這個樣子：

protected void Application_Start()
{
    // Pass a delegate to the Configure method.
    GlobalConfiguration.Configure(WebApiConfig.Register);
}

新增路由特性

這裡有一個使用了特性的路由規則的例子：

public class OrdersController : ApiController
{
    [Route("customers/{customerId}/orders")]
    [HttpGet]
    public IEnumerable<Order> FindOrdersByCustomer(int customerId) { ... }
}

字串”customers/{customerId}/orders” 是路由的URI模板。Web API 會嘗試將請求URI匹配到這些模板上。在這個例子中，”customers” 和 “orders”是字面量段，並且”{customerId}”是可變的引數。以下URI可以匹配這個模板：

http://localhost/customers/1/orders
http://localhost/customers/bob/orders
http://localhost/customers/1234-5678/orders

你可以使用 constraints 來限制匹配，接下來會講到。

要注意，這個方法中的路由模板中的”{customerId}”引數 與 方法中的customerId引數匹配。當 Web API 呼叫這個controller的這個action時，它會嘗試繫結路由引數。例如，如果URI是 http://example.com/customers/1/orders， Web API 會嘗試將“1”繫結到action的customerId引數。

一個URI模板可以有好幾個引數：

[Route("customers/{customerId}/orders/{orderId}")]
public Order GetOrderByCustomer(int customerId, int orderId) { ... }

任何沒有特性路由的控制器方法都會使用基於慣例的路由規則。也就是說，你可以在同一個專案中結合使用這兩種路由規則。

HTTP方法

Web API 也通過請求的HTTP方法來選擇action。預設情況下，Web API 會通過大小寫不敏感的匹配方式來選擇一個以對應的HTTP方法開頭的action。比如，一個controller的方法名為PutCustomers，則它匹配HTTP PUT 請求。

你可以通過使用以下特性來使這樣的慣例規則不再適用。

[HttpDelete]
[HttpGet]
[HttpHead]
[HttpOptions]
[HttpPatch]
[HttpPost]
[HttpPut]

下面的例子中，CreateBook方法匹配HTTP Post 請求

[Route("api/books")]
[HttpPost]
public HttpResponseMessage CreateBook(Book book) { ... }

對於其他的HTTP方法，包括非標準的方法，使用AcceptVerbs特性來包含多個HTTP方法。

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

路由字首

通常情況下，同一個controller中的路由路徑是有相同字首的，例如：

public class BooksController : ApiController
{
    [Route("api/books")]
    public IEnumerable<Book> GetBooks() { ... }

    [Route("api/books/{id:int}")]
    public Book GetBook(int id) { ... }

    [Route("api/books")]
    [HttpPost]
    public HttpResponseMessage CreateBook(Book book) { ... }
}

你可以使用RoutePrefix特性來修飾一個controller來為它的路由新增公共字首：

[RoutePrefix("api/books")]
public class BooksController : ApiController
{
    // GET api/books
    [Route("")]
    public IEnumerable<Book> Get() { ... }

    // GET api/books/5
    [Route("{id:int}")]
    public Book Get(int id) { ... }

    // POST api/books
    [Route("")]
    public HttpResponseMessage Post(Book book) { ... }
}

在方法特性中使用波浪線（~）來重寫路由字首：

[RoutePrefix("api/books")]
public class BooksController : ApiController
{
    // GET /api/authors/1/books
    [Route("~/api/authors/{authorId:int}/books")]
    public IEnumerable<Book> GetByAuthor(int authorId) { ... }

    // ...
}

路由字首可以包含引數:

[RoutePrefix("customers/{customerId}")]
public class OrdersController : ApiController
{
    // GET customers/1/orders
    [Route("orders")]
    public IEnumerable<Order> Get(int customerId) { ... }
}

路由約束

路有約束可以讓你對路由模板中的引數的匹配新增限制。大體語法是”{parameter:constraint}”，例如：

[Route("users/{id:int}"]
public User GetUserById(int id) { ... }

[Route("users/{name}"]
public User GetUserByName(string name) { ... }

這裡，第一個路由僅當URI的id段是整形時才會被選擇。否則，第二個路由將會被選擇。
下面這個表列出了被支援的約束：

主要到有些約束，比如min，是包含括號值的。你可以在一個引數上使用多個約束，使用冒號隔開。

[Route("users/{id:int:min(1)}")]
public User GetUserById(int id) { ... }

定製的路由約束

你可以通過實現IHttpRouteConstraint介面來自己定製路由約束。例如，下面的約束限制了引數必須為非零整數。

public class NonZeroConstraint : IHttpRouteConstraint
{
    public bool Match(HttpRequestMessage request, IHttpRoute route, string parameterName, 
        IDictionary<string, object> values, HttpRouteDirection routeDirection)
    {
        object value;
        if (values.TryGetValue(parameterName, out value) && value != null)
        {
            long longValue;
            if (value is long)
            {
                longValue = (long)value;
                return longValue != 0;
            }

            string valueString = Convert.ToString(value, CultureInfo.InvariantCulture);
            if (Int64.TryParse(valueString, NumberStyles.Integer, 
                CultureInfo.InvariantCulture, out longValue))
            {
                return longValue != 0;
            }
        }
        return false;
    }
}

下面的程式碼演示瞭如何註冊這個約束：

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        var constraintResolver = new DefaultInlineConstraintResolver();
        constraintResolver.ConstraintMap.Add("nonzero", typeof(NonZeroConstraint));

        config.MapHttpAttributeRoutes(constraintResolver);
    }
}

現在你就可以在你的路由上使用這個約束了：

[Route("{id:nonzero}")]
public HttpResponseMessage GetNonZero(int id) { ... }

你可以通過實現IInlineConstraintResolver 介面來替換整個DefaultInlineConstraintResolver 類。這樣做將會替換掉所有內建的約束，除非你對IInlineConstraintResolver的實現中特地的加上了它們。

可選URI引數以及預設值

你可以通過在路由模板中的引數後面加一個問號來使該引數成為一個可選引數。如果一個路由引數是可選引數，你必須為它指定一個預設值。

public class BooksController : ApiController
{
    [Route("api/books/locale/{lcid:int?}")]
    public IEnumerable<Book> GetBooksByLocale(int lcid = 1033) { ... }
}

在這個例子中，“/api/books/locale/1033” 和 “/api/books/locale” 將會得到相同的響應。

或者，你也可以在路由模板的引數後面直接宣告預設值，就像下面這樣：

public class BooksController : ApiController
{
    [Route("api/books/locale/{lcid:int=1033}")]
    public IEnumerable<Book> GetBooksByLocale(int lcid) { ... }
}

這跟之前的例子幾乎一樣，但是當預設值被使用時，兩者表現還是會有輕微差別：

1. 對於第一個例子 (“{lcid?}”)，預設值1033直接被指定在方法的引數中，所以該引數將會獲取到1033這個準確值。
2. 對於第二個例子 (“{lcid=1033}”), 預設值1033將會經過一個模型繫結過程。預設的模型繫結器將會將“1033”轉化為數字型1033.然而，你可以在定製的模型繫結器中做一些其他的事情。
   （大多數情況下，除非你在你的管道中寫了自己的模型繫結器之外，這兩種方式是相同的。）

路由名稱

在 Web API 中， 每個路由規則都有一個名稱。路由名稱在產生連結的過程中非常有用處，所以你在HTTP響應中可以包含一個連結。

為了指明路由名稱，要在特性路由中使用Name屬性。下面的例子展示瞭如何設定路由名稱以及如何在產生連結時使用路由名稱。

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

路由順序

當framework嘗試將URI匹配到路由規則時，它會使用特定的順序來評價路由。為了指定順序，要在特性路由中設定RouteOrder屬性，該屬性值越小的路由將會越先被評價。該屬性預設值為0。

以下是定義全部順序的步驟：

1. 在特性路由中比較RouteOrder 的值。
2. 檢視每個路由模板的URI段。對於每個URI段，按以下規則排序
   a. 字面量
   b. 帶有約束的路由引數
   c. 不帶有約束的路由引數
   d. 帶有約束的萬用字元引數
   e. 不帶有約束的萬用字元引數
3. 如果有評價結果相等的情況，將會按照路由模板的大小寫不敏感的字串比較來排序。

下面是一個例子。假設你定義了以下controller：

[RoutePrefix("orders")]
public class OrdersController : ApiController
{
    [Route("{id:int}")] // constrained parameter
    public HttpResponseMessage Get(int id) { ... }

    [Route("details")]  // literal
    public HttpResponseMessage GetDetails() { ... }

    [Route("pending", RouteOrder = 1)]
    public HttpResponseMessage GetPending() { ... }

    [Route("{customerName}")]  // unconstrained parameter
    public HttpResponseMessage GetByCustomer(string customerName) { ... }

    [Route("{*date:datetime}")]  // wildcard
    public HttpResponseMessage Get(DateTime date) { ... }
}

這些路由將按照以下排序：

1. orders/details
2. orders/{id}
3. orders/{customerName}
4. orders/{*date}
5. orders/pending

注意到“details”是一個出現在”{id}”之前的字面量段，但是”pending” 是在最後的，因為它的RouteOrder 值為1。（這個例子假設沒有客戶名字是”details” 或 “pending”。一般情況下，要避免定義有歧義的路由規則。在這個例子中，對於 GetByCustomer 來說更好的路由模板是”customers/{customerName}” ）

下一步

結束