路由与动作选择

1、【ASP.NET Web API教程】4.2路由与 动作选择注：本文是【ASP.NET Web API系列教程】的一部分，如果您是第一次看本系列 教程，请先看前面的内容。4.2 Routing and Action Selection4.2路由与动作选择本文引自： HYPERLINK /web-api/overview/web-api-routing-and-actions/routi /web-api/overview/web-api-routing-and-actions/routi ng-and-action-selectionBy Mike Wasson | July 27, 2012

2、作者：Mike Wasson | 日期：2012-7-27This article describes how ASP.NET Web API routes an HTTP request to a particular action on a controller.本文描述ASP.NET Web API如何把一个HTTP请求路由到控制器的一个特定的方 法上。For a high-level overview of routing, see Routing in ASP.NET Web API 关于路由的总体概述，参阅“ASP.NET Web API中的路由”（本系列教程的前一 小节一译者注）

3、。This article looks at the details of the routing process. If you create a Web API project and find that some requests dont qgt routed the way you expect, hopefully this article will help.本文考察路由过程的细节。如果你创建了一个Web AP【项目，并发现有些请求并 未按你期望的方式被路由，希望这篇文章对你会有所帮助。Routing has three main phases:路由有三个主要阶段：Matchin

4、g the URI to a route template.将URI匹配到一个路由模板。Selecting a controller.选择一个控制器Selecting an action.选择一个动作。You can replace some parts of the process with your own custom behaviors.In this article, I describe the default behavior. At the end, I note the places where you can customize the behavior.你可以用自己的自定

5、义行为来替换这一过程的某些部分。在本文中，我会描述默 认行为。最后，我会注明可以在什么地方自定义行为。Route Templates路由模板A route template looks similar to a URI path, but it can have placeholder values, indicated with curly braces:路由模板看上去类似于一个URI路径，但它可以具有占位符，这是用花括号来指 示的：api/controller/public/category/idWhen you create a route, you can provide defaul

6、t values for some or all of the placeholders:当创建一条路由时，可以为某些或所有占位符提供默认值：defaults: new ( category = all You can also provide constraints, which restrict how a URI segment can match a placeholder:也可以提供约束，它限制URI片段如何与占位符匹配：constraints: new ( id = d+ / Only matches if id is one or moredigits./用正则表达式限制片段的取

7、值，上语句表明，id片段的值必须是一个或多个 数字。/因此，URI中id片段必须是数字才能与这条路由匹配The framework tries to match the segments in the URI path to the template. Literals in the template must match exactly. A placeholder matches any value, unless you specify constraints. The framework does not match other parts of the URI, such as th

8、e host name or the query parameters. The framework selects the first route in the route table that matches the URI. 框架会试图把URI路径的片段与该模板进行匹配。模板中的文字必须严格匹配。 占位符可以匹配任意值，除非你指定了约束。框架不会匹配URI的其它部分，如 主机名或查询字符串。框架会选择路由表中与URI匹配的第一条路由。There are two special placeholders: (controller and (action. 有两个特殊的占位符：“contro

9、ller ”和“ action”。(controller provides the name of the controller.“(controller) ”提供控制器名。(action provides the name of the action. In Web API, the usual convention is to omit (action.“(action)”提供动作名。在Web API中，通常的约定是忽略“(action)” 的。Defaults默认值If you provide defaults, the route will match a URI that is mi

10、ssing those segments. For example:如果提供默认值，该路由将能够匹配缺少这些片段的URI。例如：routes.MapHttpRoute(name: DefaultApi,routeTemplate: api/(controller/(category,defaults: new ( category = all )；The URI HYPERLINK http:/localhost/api/products http:/localhost/api/products matches this route. The (category segment is assi

11、gned the default value all.URI“ HYPERLINK http:/localhost/api/products%e2%80%9d http:/localhost/api/products” 与这条路由是匹配的。(category)” 片段被赋成了默认值“ all”。Route Dictionary路由字典If the framework finds a match for a URI, it creates a dictionary that contains the value for each placeholder. The keys are the pla

12、ceholder names, not including the curly braces.The values are taken fromthe URI path or from the defaults. The dictionary is stored in the IHttpRouteData object.如果框架为一个URI找到一个匹配，它会创建一个字典，其中包含了每个占位符 的值。(字典的内容是一些“键-值”对一译者注)。其键是不带花括号的占 位符名称。其值取自URI路径或默认值。该字典被存储在IHttpRouteData对象 中。During this route-matc

13、hing phase, the special (controller and (action placeholders are treated just like the other placeholders. They are simply stored in the dictionary with the other values.在路由匹配阶段，controller ”和“ action ”占位符的处理与其它占位符 的处理是一样的。只是把它们简单地用值存储在字典中。A default can have the special value RouteParameter.Optional.

14、 If a placeholder gets assigned this value, the value is not added to the route dictionary. For example:在默认值中可以使用特殊的RouteParameter.Optional值。如果一个占位符被赋 予了这个值，则该值不会被添加到路由字典。例如：routes.MapHttpRoute(name: DefaultApi,routeTemplate: api/controller/category/id, defaults: new ( category = all, id = RoutePara

15、meter.Optional );For the URI path api/products, the route dictionary will contain: 对于URI路径api/products”，路由字典将含有：controller: productscategory: all由于这条URI路径中不包含id,因此，id的值将采用默认的 RouteParameter.Optional,所以，路由字典中不会包含id片段的键值对一译 者注For api/products/toys/123, however, the route dictionary will contain: 然而，对于

16、“api/products/toys/123”，路由字典将含有：controller: productscategory: toysid: 123The defaults can also include a value that does not appear anywhere in the route template. If the route matches, that value is stored in the dictionary. For example:默认值也可以包含未出现在路由模板中的值。若这条路由匹配，则该值会被存储 在路由字典中。例如：routes.MapHttpRo

17、ute(name: Root,routeTemplate: api/root/id,defaults: new ( controller = customers, id =RouteParameter.Optional );If the URI path is api/root/8, the dictionary will contain two values: 如果URI路径是“api/root/8”，字典将含有两个值： controller: customers. id: 8Selecting a Controller选择控制器Controller selection is handled

18、 by theIHttpControllerSelector.SelectController method. This method takes an HttpRequestMessage instance and returns an HttpControllerDescriptor.The default implementation is provided by the DefaultHttpControllerSelector class. This class uses a straightforward algorithm:控制器选择是由 IHttpControllerSelec

19、tor.SelectController 方法来处理的。 这个方法以HttpRequestMessage实例为参数，并返回 HttpControllerDescriptor。其默认实现是由 DefaultHttpControllerSelector 类提供的。这个类使用了一种很直接的算法：Look in the route dictionary for the key controller. 查找路由字典的“ controller ”键。Take the value for this key and append the string Controller to get the control

20、ler type name.取得这个键的值，并附加字符串 Controller”，以得到控制器的类型名。Look for a Web API controller with this type name.用这个类型名查找Web API控制器。For example, if the route dictionary contains the key-value pair controller = products, then the controller type is ProductsController. If there is no matching type, or multiple m

21、atches, the framework returns an error to the client.例如，如果路由字典的键-值对为“controller”二products”，那么，控制器 类型便为“ProductsController”。如果没有匹配类型，或有多个匹配，框架会 给客户端返回一条错误。For step 3, DefaultHttpControllerSelector uses theIHttpControllerTypeResolver interface to get the list of Web API controller types. The default i

22、mplementation of IHttpControllerTypeResolver returns all public classes that (a) implement IHttpController, (b) are not abstract, and (c) have a name that ends in Controller.对于步骤 3，DefaultHttpControllerSelector 使用IHttpControllerTypeResolver接口以获得Web API控制器类型的列表。 IHttpControllerTypeResolver的默认实现会返回所有符

23、合以下条件的public 类：(a)实现IHttpController的类(b)是非抽象类，且(c)名称以“Controller” 结尾的类。Action Selection动作选择After selecting the controller, the framework selects the action by calling the IHttpActionSelector.SelectAction method. This method takes an HttpControllerContext and returns an HttpActionDescriptor.选择了控制器之后，

24、框架会通过调用IHttpActionSelector.SelectAction方法 来选择动作。这个方法以HttpControllerContext为参数，并返回 HttpActionDescriptor。The default implementation is provided by the ApiControllerActionSelector class. To select an action, it looks at the following:默认实现是由ApiControllerActionSelector类提供的。为了选择一个动作，会 查找以下方面：The HTTP meth

25、od of the request. 请求的HTTP方法。The action placeholder in the route template, if present. 路由模板中的“ action”占位符(如果有)。The parameters of the actions on the controller. 控制器中动作的参数。Before looking at the selection algorithm, we need to understand some things about controller actions.在查找选择算法之前，我们需要理解控制器动作的一些事情。W

26、hich methods on the controller are considered actions? When selecting an action, the framework only looks at public instance methods on the controller. Also, it excludes special name methods (constructors, events, operator overloads, and so forth), and methods inherited from the ApiController class.

27、控制器中的哪些方法被看成为是“动作”？当选择一个动作时，框架只考察控制 器的public实例方法。而且，它会排除“special name特殊名称”的方法(构 造器、事件、操作符重载等等)，以及继承于ApiController类的方法。这里按原文的含义似乎是要排除API控制器中的public方法，但译者认为，框 架会把API控制器中的public方法看成是动作一译者注HTTP Methods. The framework only chooses actions that match the HTTP method of the request, determined as follows:H

28、TTP方法。框架只会选择与请求的HTTP方法匹配的动作，确定如下：You can specify the HTTP method with an attribute: AcceptVerbs, HttpDelete, HttpGet, HttpHead, HttpOptions, HttpPatch, HttpPost or HttpPut.你可以用注解属性 AcceptVerbs、HttpDelete、HttpGet、HttpHead、 HttpOptions、HttpPatch、HttpPost、或 HttpPut 来指定 HTTP 方法（这 段文字说明，你可以在方法上用这些注解属性进行标

29、注，以指定该方法用 于处理哪一种HTTP请求。通过这种标注，方法的命名可以不遵循下一条 的约定一译者注）。Otherwise, if the name of the controller method starts with Get, Post”, Put, Delete, Head, Options, or Patch, then by convention the action supports that HTTP method.否则，如果控制器方法名称以“Get”、“Post”、“Put”、“Delete”、 “Head”、“Options”、或“Patch”开头，那么，按照约定，该动作

30、支持相应的HTTP方法。If none of the above, the method supports POST.如果以上都不是（即，既未用第一条的办法进行标注，又未用第二条的方 法命名约定一译者注），则该方法支持POST。Parameter Bindings. A parameter binding is how Web API creates a value for a parameter. Here is the default rule for parameter binding: 参数绑定。参数绑定是指Web API如何创建参数值。以下是参数绑定的默认规则：Simple type

31、s are taken from the URI.简单类型取自URI。Complex types are taken from the request body.复合类型取自请求体。Simple types include all of the .NET Framework primitive types, plus DateTime, Decimal, Guid, String, and TimeSpan. For each action, at most one parameter can read the request body.简单类型包括所有“ .NET框架简单类型”，另外还有，D

32、ateTime、Decimal、Guid、 String和TimeSpan。对于每一个动作，最多只有一个参数可以读取请求体。It is possible to override the default binding rules. See WebAPI Parameter binding under the hood也可以重写这种默认的绑定规则。参见WebAPI Parameter binding under the hood（作者的一篇博客文章一译者注）。With that background, here is the action selection algorithm. 在这种背景下，

33、动作选择算法如下：Create a list of all actions onthe controller that match the HTTP request method.创建该控制器中与HTTP请求方法匹配的所有动作的列表（这一步属于 HTTP请求方法匹配，即，从已选定的控制器中挑出了与请求类型匹配的 动作方法，例如，对于GET请求，于是只挑出处理GET请求的那些方法一 译者注）。If the route dictionary has an action entry, remove actions whose name does not match this value.如果路由字典

34、有“action”条目，（从该列表）除去与该条目值不匹配的 动作（这一步属于方法名称匹配，即，在上一步基础上进一步挑出其中与 路由字典的action键值匹配的动作方法一译者注）。Try to match action parameters to the URI, as follows:试图将动作参数与该URI匹配，办法如下（这一步属于参数匹配一译者 注）：For each action, get a list of the parameters that are a simple type, where the binding gets the parameter from the URI.

35、Exclude optional parameters.针对每个动作，获得简单类型的参数列表，这是绑定得到URI参数 的地方。该列表不包括可选参数（提取方法的参数名称一译者注）。From this list, try to find a match for each parameter name, either in the route dictionary or in the URI query string. Matches are case insensitive and do not depend on the parameter order.根据这个列表，在路由字典或是在URI查询字

36、符串中，试着为每个 参数名找到一个匹配。匹配是大小写不敏感的，且与参数顺序无关 （为各个方法参数匹配一个值一译者注）。Select an action where every parameter in the list has a match in the URI.选择一个动作，其列表中的每个参数都在这个URI中获得一个匹配 （选出满足条件的动作一译者注）。If more than one action meets these criteria, pick the one with the most parameter matches.如果满足这些条件的动作不止一个，选用参数匹配最多的一个（进

37、 一步筛选动作一译者注）。Ignore actions with the NonAction attribute. 忽略用NonAction注解属性标注的动作。Step #3 is probably the most confusing. The basic idea is that a parameter can get its value either from the URI, from the request body, or from a custom binding. For parametersthat come from the URI, we want to ensure t

38、hat the URI actuallycontains a value for that parameter, either in the path （via the route dictionary） or in the query string.第3步可能会让人困扰。其基本思想是，可以从URI、或请求体、或一个自定义 绑定来获取参数值（这里指出了方法参数的来源一译者注）。对于来自URI的参数，我们希望确保URI在其路径(通过路由字典)或查询字符串中实际包含 了一个用于此参数的值。For example, consider the following action: 例如，考虑以下动作：p

39、ublic void Get(int id)The id parameter binds to the URI. Therefore, this action can only match a URI that contains a value for id”, either in the route dictionary or in the query string.其id参数绑定到URI。因此，这个动作只能匹配在路由字典或查询字符串中包 含了“id”值的URI。Optional parameters are an exception, because they are optional.

40、For an optional parameter, its OK if the binding cant get the value from the URI.可选参数是一个例外，因为它们是可选的。对于可选参数，如果绑定不能通过 URI获取它的值，是没关系的。Complex types are an exception for a different reason. A complex type can only bind to the URI through a custom binding. But in that case, the framework cannot know in a

41、dvance whether the parameter would bind to a particular URI. To find out, it would need to invoke the binding. The goal of the selection algorithm is to select an action from the static description, before invoking any bindings. Therefore, complex types are excluded from the matching algorithm.复合类型是

42、另一种原因的例外。复合类型只能通过自定义绑定来绑定到URI。但 在这种情况下，框架不能预知该参数是否会绑定到一个特定的URI。为了找出来， 框架需要调用绑定。选择算法的目的是在调用绑定之前根据静态描述来选择一个 动作。因此，复合类型是属于匹配算法之外的。After the action is selected, all parameter bindings are invoked. 动作选择之后，会调用所有参数绑定。Summary:小结：The action must match the HTTP method of the request. 动作必须匹配请求的HTTP方法。The actio

43、n name must match the action entry in the route dictionary, if present.动作名必须匹配路由字典中的“action”条目，如果有。For every parameter of the action, if the parameter is taken from the URI, then the parameter name must be found eitherin the route dictionary or in the URI query string. (Optional parameters and param

44、eters with complex types are excluded.)对于动作的各个参数，如果参数取自URI,那么该参数名必须在路由字典 或URI查询字符串中能够被找到。(可选参数和复合类型的参数不包括在 内。)Try to match the most number of parameters. The best match might be a method with no parameters.试图匹配最多数目的参数。最佳匹配可能是一个无参数方法(意即，框架 按最多参数匹配来选择动作，而不是按最佳匹配来选择一译者注)。Extended Example扩展示例Routes:路由ro

45、utes.MapHttpRoute(name: ApiRoot”,routeTemplate: api/root/id”,defaults: new ( controller = products, id =RouteParameter.Optional )；routes.MapHttpRoute(name: DefaultApi,routeTemplate: api/controller/id”,defaults: new ( id = RouteParameter.Optional )；Controller:控制器：public class ProductsController : Api

46、Controller(public IEnumerable GetAll() (public Product GetById(int id, double version = 1.0) (HttpGetpublic void FindProductsByName(string name) (public void Post(Product value) (public void Put(int id, Product value) (HTTP request:HTTP请求：GET HYPERLINK http:/localhost:34701/api/products/1?version=1.

47、5&details=1 http:/localhost:34701/api/products/1?version=1.5&details=1Route Matching路由匹配The URI matches the route named DefaultApi”. The route dictionary contains the following entries:该URI与名为“DefaultApi”路由匹配。路由字典包含以下条目： controller: products. id: 1The route dictionary does not contain the query stri

48、ng parameters, version and details, but these will still be considered during action selection.该路由字典并未包含查询字符串参数 version”和“ details”，但这些将在动 作选择期间考虑。Controller Selection控制器选择From the controller entry in the route dictionary, the controller type is ProductsController.根据路由字典中的“controller”条目，控制器类型是Produc

49、tsControlleroAction Selection选择动作The HTTP request is a GET request. The controller actions that support GET are GetAll, GetByld, and FindProductsByName. The route dictionary does not contain an entry for action, so we dont need to match the action name.该HTTP请求是一个GET请求。支持GET的控制器动作是GetAll、GetByld和 Fin

50、dProductsByName。路由字典不包含action”条目，因此不需要匹配动作名。Next, we try to match parameter names for the actions, looking only at the GET actions.下一步，会试图匹配这些动作的参数名，只考查GET动作。ActionParameters to Match动作要匹配的参数GetAllNone （无）GetByIdidFindProductsByName nameNotice that the version parameter of GetById is not considered, because it is an optional parameter.注意，不会考虑GetById的version参数，因为它是一个可选参数。The GetAll method matches trivially. The GetById method also matches, because the route di