WebApi初探之路由配置

本文介绍了ASP.NET Web API路由HTTP请求控制器。

如果你熟悉ASP.NET MVC，Web API路由是和MVC路由非常相似的。主要差别是Web API使用HTTP方法而不是URI路径来选择Action的。你也可以使用MVC的路由配置风格来配置Web API路由，当然本文不是来介绍ASP.NET MVC的。

路由表

在ASP.NET Web API，控制器是一种处理HTTP请求的类。控制器的公共方法被称为动作方法或简单的动作。当Web API框架接收请求时，它将请求发送到一个动作。

要确定调用哪个动作，该框架使用路由表。Visual Studio项目模板为Web API创建了一个默认的路由:                 

routes.MapHttpRoute(
    name: "API Default",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

这个路由在位于App_Start文件夹中的WebApiConfig.cs文件中定义:

如果想要知道更多相关的配置，你可以访问Configuring ASP.NET Web API .

如果是自主机Web API，你必须设置路由表直接在HttpSelfHostConfiguration对象.想知道更多相关信息，请访问Self-Host a Web API.

路由表中的每一个条目包含一个路由模板。Web API默认的路由模板是"api/{controller}/{id}". 在这个模板中, "api"是固定路径量, {controller} 和 {id} 都是预置位变量.

当Web API框架接收到一个HTTP请求，它将尝试匹配URI对路由表中的路由模板。如果没有匹配到，客户端将收到一个404错误。例如，可以用下列地址来匹配默认的路由规则：

• /api/contacts
• /api/contacts/1
• /api/products/gizmo1

但是，下面这个路径将匹配不到，因为它缺少了"api"这个固定路径量：

• /contacts/1

注: 之所以在路由中使用"api"是为了避免和ASP.NET MVC中的路由冲突。这样，你就可以使用"/contacts"来访问MVC控制器，使用"/api/contacts"来访问API控制器了。当然，如果你不喜欢这么做的话，你可以改变默认路由表。

一旦一条路由被匹配到，Web API将按照以下步骤来选择控制器和Action方法来执行：

• 定位控制器，Web API把 {controller}变量替换成相应"Controller"的值
• 定位Action方法，Web API先要获得HTTP方法，然后查找以HTTP方法名开头的Action方法。比如有一个GET请求，Web API首先去寻找以"Get..."开头的Actin方法，比如"GetContact"或者"GetAllContacts"。但这仅仅适用于GET, POST, PUT和DELETE这几个方法。如果你想要在你的控制器使用其他的HTTP方法，你就得使用属性了，我们将会在后面的例子中看到.
• 路由模板中的其他占位符变量，比如 {id}，将会映射到Action参数中。

让我们来看一个例子。假设定义有如下控制器：

public class ProductsController : ApiController
{
    public void GetAllProducts() { }
    public IEnumerable<Product> GetProductById(int id) { }
    public HttpResponseMessage DeleteProduct(int id){ }
}

下面列出了可能会访问到的HTTP请求，同时可能会执行到的Action方法：

HTTP Method	URI Path	Action	Parameter
GET	api/products	GetAllProducts	(none)
GET	api/products/4	GetProductById	4
DELETE	api/products/4	DeleteProduct	4
POST	api/products	(no match)

请注意URI中的{id}这个字段，如果有这个变量，它会映射到包含有id变量的Action方法。在这个例子中，控制器定义了两个GET方法，一个有id这个变量，一个没有。并且，POST请求将会失败，因为控制器没有定义"Post..."方法。 

路由变化

上一节介绍了ASP.NET Web API的基本路由机制。下面来讲一下路由变化。

HTTP方法

与其使用命名约定为HTTP方法，你可以显式地用HttpGet，HttpPut，HttpPost，或HttpDelete属性来指定HTTP方法。

在下面的例子中，FindProduct这个方法将会处理GET请求：

public class ProductsController : ApiController
{
    [HttpGet]
    public Product FindProduct(id) {}
}

为了使一个Action支持多种HTTP方法，或者说允许HTTP方法更多的支持GET, PUT, POST和DELETE, 你需要用到AcceptVerbs这个属性，它允许配置一个HTTP方法列表。

public class ProductsController : ApiController
{
    [AcceptVerbs("GET", "HEAD")]
    public Product FindProduct(id) { }

    // WebDAV method
    [AcceptVerbs("MKCOL")]
    public void MakeCollection() { }
}

根据Action名字来路由

有了默认的路由配置模板，Web API使用HTTP方法来选择Action。不过你仍然可以创建一个路由并且用Action方法名字来显示在URI中：

routes.MapHttpRoute(
    name: "ActionApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

在这条路由模板中，控制器使用{action}这个变量名来定义Action方法。按照这种方式来定义的路由，我们需要使用属性来指定可以接受的HTTP方法。例如，你的控制器中包含如下的方法：

public class ProductsController : ApiController
{
    [HttpGet]
    public string Details(int id);
}

在这个例子中，一个GET请求”api/products/details/1”将会映射到详细方法。这种风格的路由类似于ASP.NET MVC，并可适当的RPC风格的API。

你可以使用ActionName属性来重新定义Action方法名。在下面的例子中，包含两个Acton方法，他们都映射到"api/products/thumbnail/id“，但一个支持Get，一个支持POST:

public class ProductsController : ApiController
{
    [HttpGet]
    [ActionName("Thumbnail")]
    public HttpResponseMessage GetThumbnailImage(int id);

    [HttpPost]
    [ActionName("Thumbnail")]
    public void AddThumbnailImage(int id);
}

Non-Actions

为了防止某个方法被误认做一个Action, 我们可以使用NonAction这个属性。标注为NonAction的方法即表示该方法不是一个可执行的Action，即使它被路由规则给匹配到。

// Not an action method.
[NonAction]  
public string GetPrivateData() { ... }

延伸阅读

本文只是简单的介绍了一下，如果想要了解更多关于更精确的框架如何用路由来匹配URI并选择控制器和Action来执行的详细内容，可以访问Routing and Action Selection。

原文地址：http://www.asp.net/web-api/overview/web-api-routing-and-actions/routing-in-aspnet-web-api

注：首次翻译，肯定有很多地方有错误，请大家批评指教。