ASP.Net Web API 的参数绑定[翻译]

原文地址：Parameter Binding in ASP.NET Web API

译文如下：

当Web API相应Controller的一个方法时，它必定存在一个设置参数的过程，叫作数据绑定。这篇文章描述了Web API如何绑定参数以及如何自定义绑定过程。

一般情况下，Web API绑定参数符合如下规则：

- 如果参数为简单类型，Web API 尝试从URI中获取。简单参数类型包含.Net源生类型(int,bool,double...),加上TimeSpan,DateTime,Guid,decimal和string.加上任何包含string转化器的类型。（More about type converters later.）
- 对复杂类型来说，Web API 试图从message body 中读取，使用media-type 类型。

　　典型Web API Controller方法的例子：

HttpResponseMessage Put(int id, Product item) { ... }

　　参数id是简单类型，所以webapi试图从URI中获取值。参数item为复杂类型，所以web api 使用 media-type 类型从request body中读取。

　　从URI中获取值，Web API会从路由或者URI的查询参数中获取。路由数据例子如下："api/{controller}/public/{category}/{id}"，更多细节可参考：Routing and Action Selection.

　　在余下的文章中，我将给你介绍的是如何自定义参数绑定的过程。对于复杂类型，当然最好尽可能考虑media-type类型转化。一个http的关键原理是：资源是保存在message body 中被传递的,使用内容协商来指定资源如何表示。media-type 类型就是被设计来实现这个目标的。

使用[FromUri]

　　在参数前添加[FromUri]属性可以强制Web API 从URI中读取复杂类型。下面的例子定义了GeoPoint类型，以及一个从URI中获取GeoPoint的controller方法。

public class GeoPoint
{
    public double Latitude { get; set; } 
    public double Longitude { get; set; }
}

public ValuesController : ApiController
{
    public HttpResponseMessage Get([FromUri] GeoPoint location) { ... }
}

　　客户端可以通过查询字符将两个参数传递给Web API。例子如下：

http://localhost/api/values/?Latitude=47.678558&Longitude=-122.130989

使用【FromBody】

　　给参数添加[FromBody]属性可以迫使Web API从request body 中读取简单参数。

public HttpResponseMessage Post([FromBody] string name) { ... }

　　在这个例子中WebAPI将使用一个 media-type 转化器从Request body 中读取name的值。

POST http://localhost:5076/api/values HTTP/1.1
User-Agent: Fiddler
Host: localhost:5076
Content-Type: application/json
Content-Length: 7

"Alice"

　　当一个参数标记[FromBody]后Web API通过Content-Type header选择格式。在这个例子中，content type 是“application/json” 并且request body是原始的Json字符串（不是Json对象)。

　　有而且只有一个参数允许从message body 中读取，下面的例子将不会成功：

// Caution: Will not work!    
public HttpResponseMessage Post([FromBody] int id, [FromBody] string name) { ... }

　　这条规则的原因为：request body 可能存储在一个只能读取一次的非缓冲的数据流中。

Type Converters

　　创建一个TypeConverter并提供一个字符串转化，你就可以使Web API像对待一个简单类型那样对待一个类（所以Web API会尝试从URI中获取绑定的数据）。

　下面的代码展示了一个GeoPoint类代表地理坐标，添加TypeConvert方法将字符串转化为GeoPoint实例。GeoPoint类添加了[TypeConvert]属性，制定类型转化器。（这个例子取自Mike Stall的博客文章How to bind to custom objects in action signatures in MVC/WebAPI)

[TypeConverter(typeof(GeoPointConverter))]
public class GeoPoint
{
    public double Latitude { get; set; } 
    public double Longitude { get; set; }

    public static bool TryParse(string s, out GeoPoint result)
    {
        result = null;

        var parts = s.Split(',');
        if (parts.Length != 2)
        {
            return false;
        }

        double latitude, longitude;
        if (double.TryParse(parts[0], out latitude) &&
            double.TryParse(parts[1], out longitude))
        {
            result = new GeoPoint() { Longitude = longitude, Latitude = latitude };
            return true;
        }
        return false;
    }
}

class GeoPointConverter : TypeConverter
{
    public override bool CanConvertFrom(ITypeDescriptorContext context, Type sourceType)
    {
        if (sourceType == typeof(string))
        {
            return true;
        }
        return base.CanConvertFrom(context, sourceType);
    }

    public override object ConvertFrom(ITypeDescriptorContext context, 
        CultureInfo culture, object value)
    {
        if (value is string)
        {
            GeoPoint point;
            if (GeoPoint.TryParse((string)value, out point))
            {
                return point;
            }
        }
        return base.ConvertFrom(context, culture, value);
    }
}

　　现在Web API将GeoPoint视为简单类型，也就是说他会试图从URL中获取GeoPoint参数，而不用在参数前添加[FromUri]。

public HttpResponseMessage Get(GeoPoint location) { ... }

　　客户端请求的URI就像这样：

http://localhost/api/values/?location=47.678558,-122.130989

Model Binders

　　操控类型转化更强的是创建自定义对象绑定Model Binder。使用Model Binder，你可以接收一个Http请求，一个Action和一个路由数据的原始值。

　　创建一个Model Binder，需要继承IModelBinder接口，这个接口只定义了一个方法BindModel：

bool BindModel(HttpActionContext actionContext, ModelBindingContext bindingContext);

　　下面是GeoPoint对象的Model Binder

public class GeoPointModelBinder : IModelBinder
{
    // List of known locations.
    private static ConcurrentDictionary<string, GeoPoint> _locations
        = new ConcurrentDictionary<string, GeoPoint>(StringComparer.OrdinalIgnoreCase);

    static GeoPointModelBinder()
    {
        _locations["redmond"] = new GeoPoint() { Latitude = 47.67856, Longitude = -122.131 };
        _locations["paris"] = new GeoPoint() { Latitude = 48.856930, Longitude = 2.3412 };
        _locations["tokyo"] = new GeoPoint() { Latitude = 35.683208, Longitude = 139.80894 };
    }

    public bool BindModel(HttpActionContext actionContext, ModelBindingContext bindingContext)
    {
        if (bindingContext.ModelType != typeof(GeoPoint))
        {
            return false;
        }

        ValueProviderResult val = bindingContext.ValueProvider.GetValue(
            bindingContext.ModelName);
        if (val == null)
        {
            return false;
        }

        string key = val.RawValue as string;
        if (key == null)
        {
            bindingContext.ModelState.AddModelError(
                bindingContext.ModelName, "Wrong value type");
            return false;
        }

        GeoPoint result;
        if (_locations.TryGetValue(key, out result) || GeoPoint.TryParse(key, out result))
        {
            bindingContext.Model = result;
            return true;
        }

        bindingContext.ModelState.AddModelError(
            bindingContext.ModelName, "Cannot convert value to Location");
        return false;
    }
}

　　Model Binder 从Value Provider获取原始输入,这个设计中区分了两个单独的功能:

Value Provider提供了一个Http请求并填充到一个键值字典中。
Model Binder使用这个字典填充Model。

　　WebAPI默认的Value Provider通过路由数据和URI的查询参数获取数据。如果URI是http://localhost/api/values/1?location=48,-122，Value Provider创建一个键值对：

id="1"
location="48,122"

　　(我假设默认的路由模板是"api/{controller}/{id}")

　　绑定参数的名称存储在ModelBindingContext.ModelName属性中，Model Binder在字典中查找Key和它的值。如果值存在而且可以被转化成GeoPoint,Model Binder将绑定的值分配给ModelBindingContext.Model属性。

　　注意：Model Binder并不只限定于简单类型。在这个例子中，Model Binder首先寻找location类型的列表，如果失败了才使用type Conversion。

设置 Model Binder

　　有多种路径可以设置Model Binder。首先，你可以给参数添加[ModelBinder]属性。

public HttpResponseMessage Get([ModelBinder(typeof(GeoPointModelBinder))] GeoPoint location)

　　你也可以在类型上添加[ModelBinder]属性。Web API会对所有此类型的参数指派Model Binder。

[ModelBinder(typeof(GeoPointModelBinder))]
public class GeoPoint
{
    // ....
}

　　最后，你也可以在HttpConfiguration中添加Model-binder Provider。model-binder provider是一个创建Model binder的简单的工厂类。你可以通过继承 ModelBinderProvider类来创建一个Provider.然而，如果你的model binder只处理一个类型，简单的方法是嵌入SimpleModelBinderProvider，这也是SimpleModelBinderProvider的设计目的。下面的代码展示了如何做到：

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        var provider = new SimpleModelBinderProvider(
            typeof(GeoPoint), new GeoPointModelBinder());
        config.Services.Insert(typeof(ModelBinderProvider), 0, provider);

        // ...
    }
}

　　使用model-binding provider，你仍然需要给参数添加[ModelBinder]属性，去告诉WebAPI它应该使用model binder并且不是一个media-type类型。但是现在你不用在属性中指定model binder的类型:

public HttpResponseMessage Get([ModelBinder] GeoPoint location) { ... }

Value Providers

　　我提到了model binder从Value provider中获取值。通过实现IValueProvider接口创建自定义value provider。下面的列子展示了如何从一个Request请求的Cookie中拉取值:

public class CookieValueProvider : IValueProvider
{
    private Dictionary<string, string> _values;

    public CookieValueProvider(HttpActionContext actionContext)
    {
        if (actionContext == null)
        {
            throw new ArgumentNullException("actionContext");
        }

        _values = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
        foreach (var cookie in actionContext.Request.Headers.GetCookies())
        {
            foreach (CookieState state in cookie.Cookies)
            {
                _values[state.Name] = state.Value;
            }
        }
    }

    public bool ContainsPrefix(string prefix)
    {
        return _values.Keys.Contains(prefix);
    }

    public ValueProviderResult GetValue(string key)
    {
        string value;
        if (_values.TryGetValue(key, out value))
        {
            return new ValueProviderResult(value, value, CultureInfo.InvariantCulture);
        }
        return null;
    }
}

　　你还必须创建一个继承于ValueProviderFactory类的Value Provider工厂。

public class CookieValueProviderFactory : ValueProviderFactory
{
    public override IValueProvider GetValueProvider(HttpActionContext actionContext)
    {
        return new CookieValueProvider(actionContext);
    }
}

　　把Value Provider添加到HttpConfiguration

public static void Register(HttpConfiguration config)
{
    config.Services.Add(typeof(ValueProviderFactory), new CookieValueProviderFactory());

    // ...
}

　　Web API中包含所有的Value Provider,当我们调用ValueProvider.GetValue方法时，model binder接收到的是第一个可以产生它的Provider。

　　另外一种方法是，你可以使用ValueProvider属性，在参数级下设置ValueProvider 工厂，就像下面所示：

public HttpResponseMessage Get(
    [ValueProvider(typeof(CookieValueProviderFactory))] GeoPoint location)

　　这就会告诉Web API使用指定的value provider factory工厂，而不是其他注册的value provider。

HttpParameterBinding

　　模型绑定是一个普通机制中更常用的一个具体实例。如果你查看[ModelBinder]属性，你就会发现他继承于一个静态类ParameterBindingAttribute。这个静态类只定义了一个方法：GetBinding。这个方法返回一个HttpParameterBinding对象。

public abstract class ParameterBindingAttribute : Attribute
{
    public abstract HttpParameterBinding GetBinding(HttpParameterDescriptor parameter);
}

　　HttpParameterBinding 负责将绑定参数转化为值。如果设置了 [ModelBinder]，属性会返回一个实现了IModelBinder 接口的HttpParameterBinding 去实现实际的绑定。你也可以实现你自己的HttpParameterBinding。

　　举例来说：假设你想从一个请求的headers中的if-match和if-none-match中获取ETags.首先我们需要定义ETag类。

public class ETag
{
    public string Tag { get; set; }
}

　　再次我们需要定义一个枚举来确定是从header中的if-match还是if-none-match中取得ETag。

public enum ETagMatch
{
    IfMatch,
    IfNoneMatch
}

　　下面是一个从我们需要的header中获取ETag并且把它绑定到ETag类型参数的HttpParameterBinding类的例子：

public class ETagParameterBinding : HttpParameterBinding
{
    ETagMatch _match;

    public ETagParameterBinding(HttpParameterDescriptor parameter, ETagMatch match) 
        : base(parameter)
    {
        _match = match;
    }

    public override Task ExecuteBindingAsync(ModelMetadataProvider metadataProvider, 
        HttpActionContext actionContext, CancellationToken cancellationToken)
    {
        EntityTagHeaderValue etagHeader = null;
        switch (_match)
        {
            case ETagMatch.IfNoneMatch:
                etagHeader = actionContext.Request.Headers.IfNoneMatch.FirstOrDefault();
                break;

            case ETagMatch.IfMatch:
                etagHeader = actionContext.Request.Headers.IfMatch.FirstOrDefault();
                break;
        }

        ETag etag = null;
        if (etagHeader != null)
        {
            etag = new ETag { Tag = etagHeader.Tag };
        }
        actionContext.ActionArguments[Descriptor.ParameterName] = etag;

        var tsc = new TaskCompletionSource<object>();
        tsc.SetResult(null);
        return tsc.Task;
    }
}

　　ExecuteBindingAsync 方法执行绑定。通过这个方法可以将已绑定的参数值添加到HttpActionContext中的ActionArgument 字典中。

　　NOTE:如果你的ExecuteBindingAsync方法从请求连接中的Body读取值。需要重写WillReadBody 属性并让他返回true。因为请求的Body可能是只能读一次的无缓冲数据流。所以Web API定义了强制执行的规则：只有一个绑定可以读取请求的body。

　　为了实现一个自定义HttpParameterBinding。你可以定义一个继承自ParameterBindingAttribute的属性。在ETagParameterBinding中定义了两个属性，一个是为if-match headers 另一个是为if-not-match headers。两个都继承自静态基类。

public abstract class ETagMatchAttribute : ParameterBindingAttribute
{
    private ETagMatch _match;

    public ETagMatchAttribute(ETagMatch match)
    {
        _match = match;
    }

    public override HttpParameterBinding GetBinding(HttpParameterDescriptor parameter)
    {
        if (parameter.ParameterType == typeof(ETag))
        {
            return new ETagParameterBinding(parameter, _match);
        }
        return parameter.BindAsError("Wrong parameter type");
    }
}

public class IfMatchAttribute : ETagMatchAttribute
{
    public IfMatchAttribute()
        : base(ETagMatch.IfMatch)
    {
    }
}

public class IfNoneMatchAttribute : ETagMatchAttribute
{
    public IfNoneMatchAttribute()
        : base(ETagMatch.IfNoneMatch)
    {
    }
}

　　下例说明了在controller的方法中如何使用[IfNoneMatch]属性：

public HttpResponseMessage Get([IfNoneMatch] ETag etag) { ... }

　　除了ParameterBindingAttribute，这里还有另外一种关联自定义HttpParameterBinding的方法。在HttpConfiguration 对象中，ParameterBindingRules 属性是一个(HttpParameterDescriptor -> HttpParameterBinding)类型的匿名函数的集合。举例来说，你可以添加一个规则，所有的包含ETag参数的Get方法使用if-none-match的ETagParameterBinding：

config.ParameterBindingRules.Add(p =>
{
    if (p.ParameterType == typeof(ETag) && 
        p.ActionDescriptor.SupportedHttpMethods.Contains(HttpMethod.Get))
    {
        return new ETagParameterBinding(p, ETagMatch.IfNoneMatch);
    }
    else
    {
        return null;
    }
});

　　如果绑定的参数不合适会返回null。

IActionValueBinder

　　整个参数绑定的过程被一个名为IActionValueBinder的可插拔的服务控制。IActionValueBinder的默认实现方式遵循以下步骤：

1. 在参数中寻找ParameterBindingAttribute 。包含[FromBody], [FromUri], 和[ModelBinder]或自定义的属性。
2. 否则，从HttpConfiguration.ParameterBindingRules中寻找一个返回非空的HttpParameterBinding的函数。
3. 否则，使用上面所描述的默认规则。
  - 如果参数简单或者有类型转化器，绑定在URI上。这就相当于给参数添加了 [FromUri]属性。
  - 否则，尝试从消息体中读取参数。相当于给参数添加了[FromBody] 属性。

　　如果你想，你可以使用自定义的实现代替整个IActionValueBinder 服务。