为什么要有属性路由

基于约定路由的一个优点是模板在单个位置中定义，并且路由规则在所有控制器上一致的应用。但是基于约定的路由很难支持RESTFUl 中常见的某些URI模式。例如，资源通常包含子资源，客户有订单，电影有演员，书有作者等等。创建反应这些URI是很自然的，如下图所示：

/customers/1/orders

使用属性路由，为此URI定义路由很简单，只需向控制器中添加一个属性，如下图所示：

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

启用属性路由

要启用属性路由，要在配置期间调用MapHttpAttributeRoutes，此方法在System.Web.Http.HttpConfigurationExtensions类中定义。如下图所示：

using System.Web.Http;namespace WebApplication
{public static class WebApiConfig{public static void Register(HttpConfiguration config){// Web API routesconfig.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 });}
}

添加属性路由

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

请注意：路由模板中的{customerId}参数要和方法中customerId相匹配，当WebAPI调用控制器操作时，它会尝试绑定路由参数。例如 URI为 http://example.com/customers/1/orders ,则Web API会尝试将值“1”绑定到操作的customerId参数中。

URI模板中可以有多个参数，如下图所示：

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

Web API还根据请求的Http方法(Get，Post等)选择操作。默认情况下，Web API会查找与控制器方法名称的开头不区分大小写的匹配项。例如，控制器方法PutCustomer匹配HTTP PUT请求。

以下示例将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() { }

路由前缀

通常，控制器的中的路由都以相同的前缀开头，例如：

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]属性为整个控制器设置公共前缀：

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

在method属性上使用波浪号（〜）来覆盖路由前缀：

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

这时候，只有id是整数时，才匹配第一路径。否则，将选择第二路径。完整的约束列表如下图所示：

约束	描述	例子
alpha	匹配大写或者小写拉丁字母：（a-z , A-Z）	{x:alpha}
bool	匹配布尔类型	{x:bool}
datetime	匹配DataTime类型	{x:datetime}
decimal	匹配小数值	{x:decimal}
double	匹配64位浮点数	{x:double}
float	匹配32位浮点数	{x:float}
guid	匹配Guid值	{x:guid}
int	匹配32位整型	{x:int}
length	匹配具有指定长度或者具有指定长度范围的字符串	{x:length(6)} {x:length(1,20)}
long	匹配64位整数值	{x:long}
max	匹配具有最大值的整数	{x:max(10)}
maxlength	匹配具有最大长度的字符串	{x:maxlength(10)}
min	匹配具有最小值的整数	{x:min(10)}
minlength	匹配具有最小长度的字符串	{x:minlength(10)}
range	匹配值范围内的整数	{x:range(10,50)}
regex	匹配正则表达式	{x:regex(^\d{3}-\d{3}-\d{4}$)}

可以将多个约束应用于参数，以冒号分隔

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

可选的URI参数和默认值

可以通过向路由参数添加问号来使URI参数可选。如果route参数是可选的，则必须为方法参数定义默认值

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

路由名称

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

路由顺序

当框架尝试将URI与路由匹配时，它会按特定的顺序评估路由，要指定顺序，需要在Route属性上设置Order属性，框架首先评估Order值较低的方法，默认Order值为零。

以下是确定总排序的方式：

1、比较Route属性的Order属性。

2、查看路由模板中的每个URI片段，对于细分，约定如下：

a、静态片段。

b、使用约束路由参数。

c、路由参数没有约束。

d、具有约束的通配符参数段

e、没有约束的通配符参数段

[RoutePrefix("orders")]
public class OrdersController : ApiController
{[Route("{id:int}")] // constrained parameterpublic HttpResponseMessage Get(int id) { ... }[Route("details")]  // literalpublic HttpResponseMessage GetDetails() { ... }[Route("pending", RouteOrder = 1)]public HttpResponseMessage GetPending() { ... }[Route("{customerName}")]  // unconstrained parameterpublic HttpResponseMessage GetByCustomer(string customerName) { ... }[Route("{*date:datetime}")]  // wildcardpublic HttpResponseMessage Get(DateTime date) { ... }
}

以上路由将按以下顺序执行：

1、orders/details

2、orders/{id}

3、orders/{customerName}

4、orders/{*date}

5、orders/pending