张志敏的技术专栏

GitHub PayPal.Me
敏哥
靠谱码农
ASP.NET WebAPI 中的参数绑定

当 WebAPI 调用 Controller 上的方法时， 必须为其参数赋值， 这个过程就是参数绑定。 本文介绍 WebAPI 如何绑定参数， 以及如何进行自定义。

WebAPI 默认使用下面的规则进行参数绑定：

  • 简单类型， WebAPI 尝试从 URL 中获取它的值。 简单类型包括：
    • .NET 原始类型（int、 bool、 float、 double 等）；
    • 以及 TimeSpan 、 DateTime 、 Guid、 decimal 和 string；
    • 提供了类型转换器 (Type Converter)， 能够从字符串转换的类型。
  • 复杂类型则使用 media-type formatter 从 HTTP 请求的正文 (body) 中读取。

比如一个典型的 WebAPI 方法：

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

参数 id 是一个简单类型， 所以从 request URI 中取值， 而参数 item 是复杂类型， 则从 request 正文 (body) 中取值。

使用 [FromUri]

要强制 WebAPI 从 URL 读取一个复杂类型的参数， 则需要在该参数上添加 FromUri 标记。 下面的例子定义了一个 GeoPoint 类型， 以及如何从 URI 中获取 GeoPoint 实例。

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

public class TestController : ApiController {
    public IHttpActionResult Get([FromUri]GeoPoint location) { ... }
}

客户端可以在 QueryString 中传递 Latitude 和 Longitude 来构造 GeoPoint 实例， 示例请求如下：

http://127.0.0.1/api/test?latitude=22.3&longitude=113.2

注： QueryString 中的参数名称是不区分大小写的。

对于数组类型， 也可以使用 [FromUri] 标记， 比如：

public IHttpActionResult Get([FromUri]int[] items) { ... }

客户端这样发送请求：

http://127.0.0.1/api/test?items=1&items=2&items=3

服务端就可以接收到数组参数了。

使用 [FromBody]

要强制 WebAPI 从 request正文 (body) 中读取一个简单类型的参数， 需要在该参数上添加 FromBody 标记:

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

在这个例子中， WebAPI 需要使用 media-type formatter 从 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] 标记时， WebAPI 使用 Content-Type 标头来选择正确的格式， 在上面的例子中， Content-Type 是 application/json ， request正文 (body) 的内容是原始的 JSON 字符串， 而不是一个 JSON 对象。

> 一个函数中， 最多只能有一个 [FromBody] 标记， 因为客户端的请求有可能没有缓冲， 只能被读取一次。

使用 Type Converter

通过创建 Type Converter ， 实现从字符串转换的方法， 可以让 WebAPI 将复杂类型参数视为简单类型参数。

以上面的 GeoPoint 为例， 再提供一个 GeoPointConverter 实现从字符串到 GeoPoint 的转换：

[TypeConverter(typeof(GeoPointConverter))]
public class GeoPoint {

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

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

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

现在， WebAPI 会将 GeoPoint 当作简单类型， 意味着将尝试从 URI 中绑定 GeoPoint 参数的值， 也不再需要 [FromUri] 标记：

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

客户端这样发送 HTTP 请求：

https://127.0.0.1/api/test?location=22.3,113.2

使用 Model Binder

另一个比 type converter 更加灵活的是创建自定义 Model Binder 。 通过 Model Binder ， 可以直接访问 http 请求、 action 描述以及路由的原始值。

要创建 Model Binder ， 需要实现接口 IModelBinder ， 它只定义了一个方法 BindModel :

public interface IModelBinder {
    bool BindModel(
        HttpActionContext actionContext,
        ModelBindingContext bindingContext
    );
}

下面是针对 GeoPoint 的实现：

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;
        }
        // exit if no value from value provider
        var val = bindingContext.ValueProvider.GetValue(
            bindingContext.ModelName
        );
        if (val == null) {
            return false;
        }
        // exit if row value is not a string.
        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 不止局限于简单类型， 也支持复杂类型。 上面的 MobelBinder 支持两种格式的查询：

  • 使用已知的地名： http://127.0.0.1:/rest/api/test?location=redmond ；
  • 使用经纬度： http://127.0.0.1:/rest/api/test?location=47.67856,-122.131 ；

设置 Model Binder

首先， 可以在 action 方法的参数上添加 [ModelBinder] 标记， 例如：

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

其次， 可以在 GeoPoint 类型上添加 [ModelBinder] 标记， 例如：

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

最后， 还可以在 HttpConfiguration 类中添加一个 model-binder provider 来使用， 代码如下：

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
        );
        // ...
    }

}

在 action 方法中仍然需要为参数添加 [ModelBinder] 标记， 来说明该参数需要使用 model-binder 来而不是 media formatter 来进行参数绑定， 不过此时就不需要再指定 ModelBinder 的类型了：

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

使用 ValueProvider

Model Binder 需要从 Value Provider 中取值， 因此也可以创建自定义的 Value Provider 实现获取特殊的值。 要实现自定义的 ValueProvider ， 需要实现接口 IValueProvider ， 下面是一个从 Cookie 中获取值的 CookieValueProvider ：

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 的 CookieValueProviderFactory ， 代码如下：

public class CookieValueProviderFactory : ValueProviderFactory {

    public override IValueProvider GetValueProvider(HttpActionContext actionContext) {
        return new CookieValueProvider(actionContext);
    }

}

然后将 CookieValueProviderFactory 注册到 HttpConfiguration 实例：

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

Web API 将组合所有的 ValueProviderFactory ， 当一个 model binder 调用 ValueProvider.GetValue 方法时， 将会收到第一个能够提供对应值的 ValueProviderFactory 提供的值。

或者， 也可以直接在在参数上使用 ValueProviderAttribute 标记：

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

这样， Web API 在处理这个参数时， 就会直接使用 CookieValueProviderFactory ， 不再使用其它的 CookieValueProviderFactory 。

HttpParameterBinding

Model binder 只是参数绑定中的一个特定的实例， 如果查看 ModelBinderAttribute 类的定义， 会发现它继承自抽象类 ParameterBindingAttribute ， 这个类只定义了一个方法 GetBinding ， 返回一个 HttpParameterBinding 实例。

public abstract class ParameterBindingAttribute : Attribute {

    public abstract HttpParameterBinding GetBinding(
        HttpParameterDescriptor parameter
    );

}

HttpParameterBinding 负责将参数绑定到值， 以 [ModelBinder] 为例， 这个标记返回一个 HttpParameterBinding 实现， 使用 IModelBinder 进行具体的绑定。 当然， 也可以实现自定义的 HttpParameterBinding 。

假设要获取 HTTP 请求 Header 中的 if-match 和 if-none-match 标签 (ETag) ， 先定义一个类来表示 ETag ：

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

同时再定义一个枚举来指定是从 if-match 还是 if-none-match 标头中获取 ETag：

public enum ETagMatch {
    IfMatch,
    IfNoneMatch
}

接下来是从 HTTP 请求头中获取 ETag 的 ETagParameterBinding ，

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 字典中。

注意， 如果自定义的 HttpParameterBinding 需要从 HTTP 请求的正文 (body) 中读取信息， 则需要重写 WillReadBody 并返回 true 。 由于 HTTP 请求正文可能是个没有缓冲的流， 只能读取一次， 所以 Web API 加强了一个规则， 那就是每个方法只有一个绑定能够从 HTTP 请求正文读取数据。

要使用自定义的 HttpParameterBinding ， 则需要创建一个自定义的标记， 继承自 ParameterBindingAttribute 。 针对上面的 ETagParameterBinding ， 我们来定义两个自定义标记， 分别表示从 if-match 和 if-none-match 标头中获取， 代码如下：

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

}

下面是一个使用 IfNoneMatch 的例子：

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

除了直接使用这个标记， 也可以在 HttpConfiguration 中进行配置， 代码如下：

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 的可插拔的服务控制，默认的按照下面的规则进行参数绑定：

  1. 在参数上查找 ` ParameterBindingAttribute ， 包括 [FromBody] 、 [FromUri] 、 [ModelBinder]` 或者其它自定义标记；
  2. 然后在 HttpConfiguration.ParameterBindingRules 中查找一个返回 HttpParameterBinding 实例的函数；
  3. 最后， 使用上面提到的默认规则：
    • 如果参数是一个简单类型或者指定了类型转换器， 从 URI 绑定， 相当于在参数上添加 [FromUri] 标记；
    • 否则， 尝试从 HTTP 请求正文中读取， 相当于在参数上添加 [FromBody] 标记。

如果默认的绑定不能满足需求， 也可以实现自定义的 IActionValueBinder 来替换掉 Web API 默认的实现。

标签
llama(1) React(3) GeoServer(1) 前端(2) Rollup(1) ANTLR(1) Spring(1) MapBox(1) JavaScript(2) SSH(1) NGINX(1) PostgreSQL(6) .NET Core(8) .NET Standard(1) Docker(9) TypeScript(4) Angular(9) Nginx(1) Gulp(1) Windsor(1) OAuth2(3) WebAPI(7) AngularJS(7) OWIN(10) ExtJS(1) MvvmCross(5) 算法(5) 设计模式(25) Linux(15) ArcGIS(7) MVC(4) ASP.NET(12) Xamarin(16) NuGet(2) Git(5) C(3) macOS(4) Android(13) Unity3D(1) Silverlight(5) .NET(14) NHibernate(9) 转载(14) iOS(16) Mono(15) 参考(29) 教程(15)
最近发表
在 Macbook M1 上运行 AI 大模型 LLAMA 2024-04-11 GNU Screen 命令简介 2024-04-08 React 入门 03 - Callback 和 Memo 2023-05-28 React 入门 02 - Effect 2023-03-28 在微信的 Webview 中运行 ES 模块化的 Web 应用 2023-03-14 React 入门 01 - 函数组件和状态 2023-02-18 修复 Ubuntu 2204 Wi-Fi 热点无法连接问题 2023-02-11 Switch 模拟器 Ryujinx 在 Mac M1 上的体验 2023-01-08 2022年技术总结 2023-01-03 感染新冠奥密克戎病毒以及广州琶洲方仓医院见闻 2022-12-10
访问信息
Flag Counter

本博客基于 Tabler CSS 框架， 采用 Jekyll 模板引擎， 使用 Markdown 语法编写。

博客源代码及文章内容采用 AS-IS 协议发布，转载时请 AS-IS 。

Copyright © 2024 张志敏 版权所有