WebApi2官网学习记录---Attribute Routing

从WebApi 1迁移到WebAPI 2要改变配置代码如下：

WebApi 1：

protected void Application_Start()
{
    // WARNING - Not compatible with attribute routing.
    WebApiConfig.Register(GlobalConfiguration.Configuration);
}

WebAPI 2：

protected void Application_Start()
{
    // Pass a delegate to the Configure method.
    GlobalConfiguration.Configure(WebApiConfig.Register);
}

添加一个Route Attributes

public class OrdersController : ApiController
{
    [Route("customers/{customerId}/orders")]
    [HttpGet]
    public IEnumerable<Order> FindOrdersByCustomer(int customerId) { ... }
}

可以匹配一下URL：

• http://localhost/customers/1/orders
• http://localhost/customers/bob/orders
• http://localhost/customers/1234-5678/orders

匹配http post请求的CreateBook

[Route("api/books")]
[HttpPost]
public HttpResponseMessage CreateBook(Book book) { ... }

[Route("api/books")]
[AcceptVerbs("MKCOL")]
public void MakeCollection() { 

Route Prefixes

对于同一个controller路由有相同的前缀， 此时可以使用 [RoutePrefix] attribute

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

可以在方法的attribute中使用（~）重写路由前缀

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

 自定义路由约束

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

修改WebAPIConfig.cs
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参数和默认值

第一种方式，默认值直接分配给了方法参数，因此参数获得的是精确的值

第二种方式，默认值通过model-binding进行处理，默认的model-binder将字符串类型的默认值"1033"转为int形的1033，对于model-binder可能有所不同。

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

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

Route Names

web api中每个路由有一个name，Route names可以用来生成links

 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

通过设置RouteOrder属性在route attribute上，可以指定Route的顺序，值越小先被计算，默认顺序对应的值是0

路由顺序的选择：

• 比较RouteOrder属性
• 对于URI部分按如下进行排序

1. URI的固定部分（literal segments）　　
2. 带约束的路由参数
3. 不带约束的路由参数
4. 带约束的通配符
5. 不带约束的通配符

• route的排序不区分大小写的

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

路由排序如下：

1. orders/{details}
2. orders/{id}
3. orders/{customreName}
4. orders/{*date}
5. orders/pending

Route Attribute的使用完整例子：

 using BooksAPI.DTOs;
 using BooksAPI.Models;
 using System;
 using System.Data.Entity;
 using System.Linq;
 using System.Linq.Expressions;
 using System.Threading.Tasks;
 using System.Web.Http;
 using System.Web.Http.Description;

 namespace BooksAPI.Controllers
 {
     [RoutePrefix("api/books")]
     public class BooksController : ApiController
     {
         private BooksAPIContext db = new BooksAPIContext();

         // Typed lambda expression for Select() method.
         private static readonly Expression<Func<Book, BookDto>> AsBookDto =
             x => new BookDto
             {
                 Title = x.Title,
                 Author = x.Author.Name,
                 Genre = x.Genre
             };

         // GET api/Books
         [Route("")]
         public IQueryable<BookDto> GetBooks()
         {
             return db.Books.Include(b => b.Author).Select(AsBookDto);
         }

         // GET api/Books/5
         [Route("{id:int}")]
         [ResponseType(typeof(BookDto))]
         public async Task<IHttpActionResult> GetBook(int id)
         {
             BookDto book = await db.Books.Include(b => b.Author)
                 .Where(b => b.BookId == id)
                 .Select(AsBookDto)
                 .FirstOrDefaultAsync();
             if (book == null)
             {
                 return NotFound();
             }

             return Ok(book);
         }

         [Route("{id:int}/details")]
         [ResponseType(typeof(BookDetailDto))]
         public async Task<IHttpActionResult> GetBookDetail(int id)
         {
             var book = await (from b in db.Books.Include(b => b.Author)
                               where b.AuthorId == id
                               select new BookDetailDto
                               {
                                   Title = b.Title,
                                   Genre = b.Genre,
                                   PublishDate = b.PublishDate,
                                   Price = b.Price,
                                   Description = b.Description,
                                   Author = b.Author.Name
                               }).FirstOrDefaultAsync();

             if (book == null)
             {
                 return NotFound();
             }
             return Ok(book);
         }

         [Route("{genre}")]
         public IQueryable<BookDto> GetBooksByGenre(string genre)
         {
             return db.Books.Include(b => b.Author)
                 .Where(b => b.Genre.Equals(genre, StringComparison.OrdinalIgnoreCase))
                 .Select(AsBookDto);
         }

         [Route("~api/authors/{authorId}/books")]
         public IQueryable<BookDto> GetBooksByAuthor(int authorId)
         {
             return db.Books.Include(b => b.Author)
                 .Where(b => b.AuthorId == authorId)
                 .Select(AsBookDto);
         }

         [Route("date/{pubdate:datetime:regex(\\d{4}-\\d{2}-\\d{2})}")]
         [Route("date/{*pubdate:datetime:regex(\\d{4}/\\d{2}/\\d{2})}")]
         public IQueryable<BookDto> GetBooks(DateTime pubdate)
         {
             return db.Books.Include(b => b.Author)
                 .Where(b => DbFunctions.TruncateTime(b.PublishDate)
                     == DbFunctions.TruncateTime(pubdate))
                 .Select(AsBookDto);
         }

         protected override void Dispose(bool disposing)
         {
             db.Dispose();
             base.Dispose(disposing);
         }
     }
 }

其中以下路由中的匹配符*的作用：

  [Route("date/{pubdate:datetime:regex(\\d{4}-\\d{2}-\\d{2})}")]
        [Route("date/{pubdate:datetime:regex(\\d{4}/\\d{2}/\\d{2})}")]  // new
        public IQueryable<BookDto> GetBooks2(DateTime pubdate)
        {
            /*
             * 路由中的*匹配符的作用，是为了告诉route engine占位符{pubdate}应该匹配剩余的URI，
             * 默认情况下，一个模板参数仅仅匹配一个URI。
             * This tells the routing engine that {pubdate} should match the rest of the URI. By default,
             * a template parameter matches a single URI segment. In this case, we want {pubdate} to
             * span several URI segments:
             */

        }