原文地址：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的默认实现方式遵循以下步骤：

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

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

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

使用[FromUri]

使用【FromBody】

Type Converters

Model Binders

设置 Model Binder

Value Providers

HttpParameterBinding

IActionValueBinder

相关资源：

ASP.Net Web API 的参数绑定[翻译]相关推荐

最新文章

热门文章