ASP.NET Web API實踐系列04,通過Route等特性設定路由

ASP.NET Web API路由，簡單來說，就是把客戶端請求對映到對應的Action上的過程。在"ASP.NET Web API實踐系列03,路由模版, 路由慣例, 路由設定"一文中，體驗了通過模版、慣例、HTTP方法來設定路由，這種做法的好處是把路由模版統一放在了App_Start資料夾下的WebApiConfig類中，方便管理，但缺點是不夠靈活。

 

REST把一切都看成資源，有時候，一個資源連帶子資源，比如Customer和Orders密切關聯，我們可能希望輸入這樣的請求：customers/1/orders，但僅僅憑藉慣例，很難實現這種路由。而實際上，ASP.NET Web API為我們準備了Route特性，該特性可以直接打到Action上，使用非常靈活、直觀。

 

下面就在ASP.NET MVC4下來體驗Route特性的使用方法。

 

允許Route特性

 

首先需要在WebApiConfig中設定。

using System.Web.Http;
namespace MyRoutingAttributes4
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            //設定特性路由
            config.MapHttpAttributeRoutes();
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );
            // 取消註釋下面的程式碼行可對具有 IQueryable 或 IQueryable<T> 返回型別的操作啟用查詢支援。
            // 若要避免處理意外查詢或惡意查詢，請使用 QueryableAttribute 上的驗證設定來驗證傳入查詢。
            // 有關詳細資訊，請訪問 http://go.microsoft.com/fwlink/?LinkId=279712。
            //config.EnableQuerySupport();
            // 若要在應用程式中禁用跟蹤，請註釋掉或刪除以下程式碼行
            // 有關詳細資訊，請參閱: http://www.asp.net/web-api
            config.EnableSystemDiagnosticsTracing();
        }
    }
}

 

以上的MapHttpAttributeRoutes方法只在ASP.NET Web API較新的版本中才有，如果你的版本比較低，可以通過"NuGet程式包管理器控制檯"解除安裝舊版本，安裝最新版本。

Uninstall-Package microsoft.aspnet.webapi –Force
install-package microsoft.aspnet.webapi

 

接下來，在Global.asax中，需要把原先註冊WebApiConfig的方式註釋掉，採納新的方式，如下：

    public class WebApiApplication : System.Web.HttpApplication
    {
        protected void Application_Start()
        {
            AreaRegistration.RegisterAllAreas();
            //WebApiConfig.Register(GlobalConfiguration.Configuration);
            //Web API,啟動特性路由
            GlobalConfiguration.Configure(WebApiConfig.Register);
            FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
            RouteConfig.RegisterRoutes(RouteTable.Routes);
            BundleConfig.RegisterBundles(BundleTable.Bundles);
        }
    }

 

這時候執行專案可能會報如下錯誤：

 

這是因為在下載使用ASP.NET Web API最新版本的時候，順帶下載了一個最新版本的icrosoft.AspNet.WebApi.HelpPage。可以把最新版的HelpPage解除安裝掉，再下載相對老的版本。

Uninstall-Package Microsoft.AspNet.WebApi.HelpPage –Force
Install-Package Microsoft.AspNet.WebApi.HelpPage -Pre

 

使用Route特性

 

建立一個Cusomter類。

namespace MyRoutingAttributes4.Models
{
    public class Customer
    {
        public int Id { get; set; }
        public string Name { get; set; }
    }
}

 

建立一個Order類。

namespace MyRoutingAttributes4.Models
{
    public class Order
    {
        public int Id { get; set; }
        public decimal Total { get; set; }
        public int CustomerId { get; set; }
        public Customer Customer { get; set; }
    }
}

 

建立一個Database類，用來獲取Order集合。

using System.Collections.Generic;
using System.Linq;
using MyRoutingAttributes4.Models;
namespace MyRoutingAttributes4
{
    public class Database
    {
        public static IEnumerable<Order> GetOrdersByCustomerId(int customerId)
        {
            return GetOrders().Where(o => o.CustomerId == customerId);
        }
        private static IEnumerable<Order> GetOrders()
        {
            Customer cus1 = new Customer() { Id = 1, Name = "張三" };
            Customer cus2 = new Customer() { Id = 2, Name = "李四" };
            List<Order> orders = new List<Order>()
            {
                new Order(){Id = 1, Total = 80M, CustomerId = 1, Customer = cus1},
                new Order(){Id = 2, Total = 100M, CustomerId = 1, Customer = cus1},
                new Order(){Id = 3, Total = 120M, CustomerId = 2, Customer = cus2}
            };
            return orders;
        } 
    }
}

 

建立一個空的API控制器，編寫如下：

using System.Collections.Generic;
using System.Web.Http;
using MyRoutingAttributes4.Models;
namespace MyRoutingAttributes4.Controllers
{
    public class OrdersController : ApiController
    {
        [Route("customers/{customerId}/orders")]
        [HttpGet]
        public IEnumerable<Order> FindOrdersByCustomer(int customerId)
        {
            return Database.GetOrdersByCustomerId(customerId);
        }
    }
}

在瀏覽器中輸入如下：

 

如果你使用的是ASP.NET MVC4進行開發，在程式第一次執行的時候，可能會報如下錯誤：

[A]System.Web.WebPages.Razor.Configuration.HostSection 無法強制轉換為 [B]System.Web.WebPages.Razor.Configuration.HostSection。型別 A 源自“System.Web.WebPages.Razor, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35”(在上下文“Default”中的“C:\Windows\Microsoft.Net\assembly\GAC_MSIL\System.Web.WebPages.Razor\v4.0_2.0.0.0__31bf3856ad364e35\System.Web.WebPages.Razor.dll”位置處)。型別 B 源自“System.Web.WebPages.Razor, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35”(在上下文“Default”中的“C:\Windows\Microsoft.NET\Framework\v4.0.30319\Temporary ASP.NET Files\vs\feb7ce97\a525d58a\asse

 

這是因為，在下載最新版本的ASP.NET Web API的時候，用到了Razor的最新版本。需要在根目錄下的Web.config中作如下配置：

  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      ......
      <dependentAssembly>
        <assemblyIdentity name="System.Web.WebPages.Razor" publicKeyToken="31bf3856ad364e35" />
        <bindingRedirect oldVersion="2.0.0.0" newVersion="3.0.0.0"/>
      </dependentAssembly>
    </assemblyBinding>
  </runtime>

 

使用RoutePrefix特性 

 

如果想給某個API控制器中的所有Action加上一個字首，可把RoutePrefix特性打在API控制器上。

比如我們希望是這樣的格式：http://localhost/api/customers/1/orders

 

這樣來修改OrdersController。

using System.Collections.Generic;
using System.Web.Http;
using MyRoutingAttributes4.Models;
namespace MyRoutingAttributes4.Controllers
{
    [RoutePrefix("api")]
    public class OrdersController : ApiController
    {
        [Route("customers/{customerId}/orders")]
        [HttpGet]
        public IEnumerable<Order> FindOrdersByCustomer(int customerId)
        {
            return Database.GetOrdersByCustomerId(customerId);
        }
    }
}

 

還可以在Route特性中使用~來重寫Action的字首規則。

using System.Collections.Generic;
using System.Web.Http;
using MyRoutingAttributes4.Models;
namespace MyRoutingAttributes4.Controllers
{
    [RoutePrefix("api")]
    public class OrdersController : ApiController
    {
        [Route("~/myapi/customers/{customerId:int}/orders")]
        [HttpGet]
        public IEnumerable<Order> FindOrdersByCustomer(int customerId)
        {
            return Database.GetOrdersByCustomerId(customerId);
        }
    }
}

 

RoutePrefix特性定義的字首還可以帶引數變數：

    [RoutePrefix("api/{customerId}")]
    public class OrdersController : ApiController

 

路由約束

 

可以通過"{引數變數名稱:約束}"來約束路由中的引數變數。

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

以上，如果片段變數id為int型別，就路由到第一個Action，如果不是，路由到第二個Action。

 

ASP.NET Web API內建約束包括：

{x:alpha} 約束大小寫英文字母
{x:bool}
{x:datetime}
{x:decimal}
{x:double}
{x:float}
{x:guid}
{x:int}
{x:length(6)}
{x:length(1,20)} 約束長度範圍
{x:long}
{x:maxlength(10)}
{x:min(10)}
{x:range(10,50)}
{x:regex(正規表示式)}

 

可以為一個引數變數同時設定多個約束：
[Route("api/{id:int:min(1)}")]

 

實現IHttpRouteConstraint介面，可自定義約束規則。實現一個不能為0的約束。

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

 

在App_Start資料夾中的WebApiConfig中註冊自定義約束。

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}")]

 

可選引數及其預設值

 

如果一個路由引數變數是可選的，同時必須給該引數一個預設值。

[Route("api/{id:int?}")]
public IEnumerable<T> Get(int id = 8){}

在約束後面加?，表示可選，在方法引數中給id設定預設值。

 

給路由設定名稱

 

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

 

路由優先順序

 

Route特性設定的路由優先順序是根據慣例和RouteOrder屬性來確定的。

 

慣例是：

1、靜態片段變數
2、帶約束的片段變數
3、不帶約束的片段變數
4、帶約束的萬用字元片段變數
5、不帶約束的萬用字元片段變數

 

RouteOrder屬性的預設值是0，屬性值越小，排在越前面。

 

[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) { ... }
}

以上，路由的優先順序是：

orders/details  靜態片段變數，RouteOrder屬性值為0
orders/{id} 帶約束的片段變數，RouteOrder屬性值為0
orders/{customerName} 不帶約束的片段變數，RouteOrder屬性值為0
orders/{*date} 帶約束的萬用字元片段變數，RouteOrder屬性值為0
orders/pending RouteOrder屬性值為1