ASP.NET Web API 2 中的属性路由

WEB前端开发社区 昨天路由是 Web API 将 URI 与操作匹配的方式。 Web API 2 支持一种称为属性路由的新型路由。 顾名思义，属性路由使用属性来定义路由。 属性路由使您能够对 Web API 中的 URI 进行更多控制。 例如，您可以轻松地创建描述资源层次结构的 URI。早期路由样式（称为基于约定的路由）仍完全支持。 事实上，您可以将这两种技术合并到同一项目中。本主题演示如何启用属性路由，并介绍属性路由的各种选项。 有关使用属性路由的端到端教程，请学习在 Web API 2 中使用属性路由创建 REST API。先决条件Visual Studio 2017社区版、专业版或企业版或者，使用 NuGet 包管理器安装必要的包。 从 Visual Studio 中的 "工具"菜单中，选择NuGet 包管理器，然后选择 "包管理器控制台"。 在包管理器控制台窗口中输入以下命令：Install-Package Microsoft.AspNet.WebApi.WebHost为什么选择属性路由？Web API 的第一个版本使用了基于约定的路由。 在这种类型的路由中，定义一个或多个路由模板，这些模板基本上是参数化字符串。 当框架收到请求时，它将 URI 与路由模板匹配。 有关基于约定的路由的详细信息，请参阅ASP.NET Web API 中的路由。基于约定的路由的一个优点是模板在一个位置定义，并且路由规则在所有控制器之间一致应用。 遗憾的是，基于约定的路由很难支持 RESTful API 中常见的某些 URI 模式。 例如，资源通常包含子资源：客户有订单，电影有演员，书籍有作者，等等。 创建反映这些关系的 URI 是很自然的：/customers/1/orders这种类型的 URI 很难使用基于约定的路由创建。 尽管可以做到这一点，但如果您有许多控制器或资源类型，则结果不会很好地扩展。使用属性路由，为此 URI 定义路由非常简单。 只需向控制器操作添加属性：[Route("customers/{customerId}/orders")]public IEnumerable<Order> GetOrdersByCustomer(int customerId) { ... }下面是一些其他模式，属性路由使容易。API 版本控制在此示例中，"/api/v1/产品"将路由到与"/api/v2/产品"不同的控制器。/api/v1/products /api/v2/products重载 URI 段在此示例中，"1"是订单号，但"挂起"映射到集合。/orders/1 /orders/pending多种参数类型在此示例中，"1"是订单号，但"2013/06/16"指定日期。/orders/1 /orders/2013/06/16启用属性路由要启用属性路由，请在配置期间调用MapHttpAttributeRoutes。 此扩展方法在System.Web.http.Http 配置扩展类中定义。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 的详细信息，请参阅配置ASP.NET Web API 2。注意：从 Web API 1 迁移在 Web API 2 之前，Web API 项目模板生成了如下所示的代码：protected void Application_Start(){ // WARNING - Not compatible with attribute routing. WebApiConfig.Register(GlobalConfiguration.Configuration);}如果启用了属性路由，则此代码将引发异常。 如果将现有 Web API 项目升级为使用属性路由，请确保将此配置代码更新为以下内容：C#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) { ... }}字符串"客户/[客户 Id]/订单"是路由的 URI 模板。 Web API 尝试将请求 URI 与模板匹配。 在此示例中，"客户"和"订单"是文本段，"[客户 Id]"是一个变量参数。 以下 URI 将匹配此模板：http://localhost/customers/1/ordershttp://localhost/customers/bob/ordershttp://localhost/customers/1234-5678/orders您可以使用约束来限制匹配，本主题稍后将介绍。请注意，"工艺路线模板中的"{customerId} 参数与 方法中的customerId参数的名称匹配。 当 Web API 调用控制器操作时，它尝试绑定路由参数。 例如，如果 URI 是http://example.com/customers/1/orders，Web API 会尝试在操作中将值"1"绑定到customerId参数。URI 模板可以具有多个参数：[Route("customers/{customerId}/orders/{orderId}")]public Order GetOrderByCustomer(int customerId, int orderId) { ... }没有任何路由属性的控制器方法都使用基于约定的路由。 这样，可以将两种类型的路由合并到同一项目中。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() { }路由前缀通常，控制器中的路由都以相同的前缀开头。 例如：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) { ... }}在方法属性上使用波浪线 （*） 来覆盖路由前缀：[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) { ... }}路由约束通过路由约束，您可以限制路由模板中的参数的匹配方式。 一般语法是"[参数：约束"] 。 例如：C#[Route("users/{id:int}")]public User GetUserById(int id) { ... }[Route("users/{name}")]public User GetUserByName(string name) { ... }此处，仅当 URI 的 ID""段是整数时，才会选择第一个路由。 否则，将选择第二个路由。请注意，某些约束（如"最小"值）在括号中采用参数。 您可以将多个约束应用于参数，由冒号分隔。[Route("users/{id:int:min(1)}")]public User GetUserById(int id) { ... }自定义路由约束您可以通过实现IHttpRoute 约束接口来创建自定义路由约束。 例如，以下约束将参数限制为非零整数值。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) { ... }您还可以通过实现IInline 约束解析器接口来替换整个默认内联约束解析器类。 这样做将替换所有内置约束，除非您的IInline 约束解析器的实现专门添加它们。可选 URI 参数和默认值您可以通过向路由参数添加问号来使 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) { ... }}这几乎与前一个示例相同，但在应用默认值时，行为有细微差异。在第一个示例（"{lcid：int？}"）中，默认值 1033 直接分配给方法参数，因此参数将具有此精确值。在第二个示例（"{lcid：int=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; }}路线订单当框架尝试将 URI 与路由匹配时，它会按特定顺序评估路由。 要指定订单，请在工艺路线属性上设置Order属性。 首先计算较低的值。 默认订单值为零。以下是确定总排序的方式：比较工艺路线属性的Order属性。查看工艺路线模板中的每个 URI 段。 对于每个段，顺序如下：字段。具有约束的路由参数。路由参数没有约束。具有约束的通配符参数段。通配符参数段没有约束。在连接的情况下，路由由路由模板的区分大小写序字符串比较（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 = 1)] public HttpResponseMessage GetPending() { ... }[Route("{customerName}")] // unconstrained parameter public HttpResponseMessage GetByCustomer(string customerName) { ... }[Route("{*date:datetime}")] // wildcard public HttpResponseMessage Get(DateTime date) { ... }}这些路线按如下方式排序。订单/详细信息订单/{id}订单/[客户名称]订单/*日期订单/待定请注意，"详细信息"是文本段，出现在"{id}"之前，但"挂起"显示最后，因为Order属性为 1。 （此示例假定没有名为"详细信息"或"挂起"的客户。 通常，尽量避免不明确的路线。 在此示例中，更好的GetByCustomer路由模板是"客户/[客户名称]"来源：https://docs.microsoft.com/zh-cn/喜欢此内容的人还喜欢Lua制作flappy bird（2）Lua制作flappy bird（2）...游戏制作不喜欢确定Javascript每日一题Javascript每日一题...Javascript每日一题不喜欢确定【回溯篇】在Python中从另一个序列派生出该序列【回溯篇】在Python中从另一个序列派生出该序列...Python之刃不喜欢确定