ASP.NET Web API 2中的属性路由(Attribute Routing)

提示：扫一扫查出行
【扫一扫了解最新限行尾号】
复制提示

如何启用属性路由并描述属性路由的各种选项?

Why Attribute Routing?

Web API的第一个版本使用基于约定的路由。在这种类型的路由中，您可以定义一个或多个路由模板，这些模板基本上是参数化字符串。当框架收到请求时，它会将URI与路由模板进行匹配。

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

/customers/1/orders

使用基于约定的路由很难创建这种类型的URI。尽管可以这样做，但如果您有许多控制器或资源类型，结果将无法很好地扩展。

使用属性路由，为此URI定义路由很简单。您只需向控制器操作添加一个属性：

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

启用属性路由：Enabling Attribute Routing

要启用属性路由，请在WebApiConfig配置文件调用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 }
);
}
}

注意：从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);
}

添加路由属性：Adding Route Attributes

以下是使用属性定义的路径示例：

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参数的名称相匹配。

当Web API调用控制器操作时，它会尝试绑定路由参数。例如，如果URI为http://example.com/customers/1/orders，则Web API会尝试将值“1”绑定到操作中的customerId参数。

任何没有路由属性的控制器方法都使用基于约定的路由。这样，您可以在同一个项目中组合两种类型的路由。

HTTP方法

Web API还根据请求的HTTP方法（GET，POST等）选择操作。默认情况下，Web API会查找与控制器方法名称的开头不区分大小写的匹配项。例如，控制器方法名：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() { }

路由前缀：Route Prefixes

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

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

路由约束：Route Constraints

路由约束允许您限制路径模板中的参数匹配方式。一般语法是“{parameter：constraint}”。例如：

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

下表列出了支持的约束：

Constraint	Description	Example
alpha	Matches uppercase or lowercase Latin alphabet characters (a-z, A-Z)	{x:alpha}
bool	Matches a Boolean value.	{x:bool}
datetime	Matches a DateTime value.	{x:datetime}
decimal	Matches a decimal value.	{x:decimal}
double	Matches a 64-bit floating-point value.	{x:double}
float	Matches a 32-bit floating-point value.	{x:float}
guid	Matches a GUID value.	{x:guid}
int	Matches a 32-bit integer value.	{x:int}
length	Matches a string with the specified length or within a specified range of lengths.	{x:length(6)} {x:length(1,20)}
long	Matches a 64-bit integer value.	{x:long}
max	Matches an integer with a maximum value.	{x:max(10)}
maxlength	Matches a string with a maximum length.	{x:maxlength(10)}
min	Matches an integer with a minimum value.	{x:min(10)}
minlength	Matches a string with a minimum length.	{x:minlength(10)}
range	Matches an integer within a range of values.	{x:range(10,50)}
regex	Matches a regular expression.	{x:regex(^\d{3}-\d{3}-\d{4}$)}

请注意，某些约束（例如“min”）在括号中包含参数。您可以将多个约束应用于参数，以冒号分隔。

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

自定义路由约束：Custom Route Constraints

您可以通过实现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 != ;
} string valueString = Convert.ToString(value, CultureInfo.InvariantCulture);
if (Int64.TryParse(valueString, NumberStyles.Integer,
CultureInfo.InvariantCulture, out longValue))
{
return longValue != ;
}
}
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参数和默认值

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

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

在这个例子中，/api/books/locale/1033并/api/books/locale返回相同的资源。

或者，您可以在路径模板中指定默认值，如下所示：

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

路由名称：Route Names

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

路由顺序：Route Order

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

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

比较route属性的RouteOrder属性。
查看路由模板中的每个URI段。对于每个细分，顺序如下：
1. 文字片段。
2. 使用约束路由参数。
3. 路由参数没有约束。
4. 具有约束的通配符参数段。
5. 没有约束的通配符参数段。
In the case of a tie,，路由按路由模板的不区分大小写的序列比较（OrdinalIgnoreCase）排序。

[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 = )]
public HttpResponseMessage GetPending() { ... } [Route("{customerName}")] // unconstrained parameter
public HttpResponseMessage GetByCustomer(string customerName) { ... } [Route("{*date:datetime}")] // wildcard
public HttpResponseMessage Get(DateTime date) { ... }
}

这些路由按如下顺序排列.

orders/details
orders/{id}
orders/{customerName}
orders/{*date}
orders/pending

正文

Why Attribute Routing?

启用属性路由：Enabling Attribute Routing

注意：从Web API 1迁移

添加路由属性：Adding Route Attributes

HTTP方法

路由前缀：Route Prefixes

路由约束：Route Constraints

自定义路由约束：Custom Route Constraints

可选的URI参数和默认值

路由名称：Route Names

路由顺序：Route Order

相关阅读

系统架构设计师Web架构的简单介绍

html5移动Web开发指南唐俊开，h5移动端开发

HTML5移动Web开发期末测试题，基于html5技术的移动web前端设计与开发

iis服务器，IIS服务器使用____协议为客户提供Web浏览服务

python爬虫数据显示到Web，python爬取数据保存到数据库

微信小程序属于Web应用开发，小程序属于web应用吗

Python爬虫实战爬取Web页面图片，python爬取网页数据步骤图解

web游戏开发，web 游戏开发

目录[+]