ASP.NET Core 模型绑定

原文:Model Binding
作者:Rachel Appel
翻译:娄宇(Lyrics)
校对:许登洋(Seay)何镇汐

模型绑定介绍

ASP.NET Core MVC 中的模型绑定从 HTTP 请求参数中将数据映射到 Action 方法里。这些参数可以是 string、interger、float 这样的简单类型,也可以是复杂类型。这是 MVC 一个非常棒的功能,因为无论传入数据的大小或复杂性如何,映射传入数据到对应项是一个经常重复的情况。 MVC 通过抽象绑定解决了这个问题,所以开发者们不必继续在每一个应用中反复编写同样的代码。自己编写文本到类型转换的代码是冗长并且容易出错的。

模型绑定如何工作

当 MVC 收到一个 HTTP 请求,它将其路由到一个 Controller 特定的一个 Action 方法。它基于路由数据来决定运行哪个 Action 方法,然后将值从 HTTP 请求绑定到 Action 方法的参数中。例如,考虑下面的 URL:

http://contoso.com/movies/edit/2

因为路由模板看起来像这样,{controller=Home}/{action=Index}/{id?} movies/edit/2 路由到Movies Controller ,和它的 Edit Action 方法。同时接受到一个可选参数 id 。 Action 方法代码应该看起来像这样:

public IActionResult Edit(int? id)

提示
URL 中的字符串不区分大小写。

MVC 尝试通过参数名将请求数据绑定到 Action 的参数上。 MVC 将使用参数名以及它的公开可设置的属性名称查询所有的值。在上面的例子中,只有一个参数命名为 id ,MVC 将路由值中名称相同的值绑定过去。除了路由值之外, MVC 会以一种固定的顺序从 HTTP 请求中的其他部分绑定数据。下面是模型绑定的数据源列表的绑定顺序:

  • Form values :这是通过 HTTP POST 请求发送的表单数据(包括 jQuery POST 请求)。

  • Route values :由 routing 提供的路由数据集。

  • Query strings :URI 的查询字符串的一部分。

提示
表单值,路由数据,以及查询字符串都以键值对的形式存储。

因为模型绑定要找一个命名为 id 的键,但是在表单值里没有命名为 id 的键,所以接下来将在路由数据中找寻这个键。在我们的例子中,它是匹配的。绑定发生时,该值转换为 integer 类型的 2。相同的请求使用 Edit(string id) 将转换成 string 类型的值 “2” 。

到目前为止的例子使用的都是简单类型。在 MVC 中简单类型是任何 .NET 原始类型或者带字符串的类型的转换器。如果 Action 方法的参数是一个类,比如说 Movie 类型,这个类包含简单类型和复杂类型的属性,MVC 的模型绑定仍然可以很好的处理它。它使用反射和递归遍历复杂类型寻找匹配的属性。模型绑定寻找 parameter_name.parameter_name 的模式去绑定值到属性上。如果没有从表单中找到匹配的值,将尝试只通过 property_name 进行绑定。对于那些 集合(Collection) 类型,模型绑定会去匹配 parameter_name[index] 或者只是 [index] 。模型绑定对待 字典(Dictionary) 类型也是一样,寻找 parameter_name[key] 或只是 [key] ,前提是 Key 是简单类型。 Key 支持匹配 HTML 和 Tag Helpers 为相同的模型类型生成的字段名。当创建或者编辑的绑定数据未通过验证的时候,回传值使得用户输入的表单字段仍然保留,方便了用户(不必重新输入全部数据)。

为了绑定发生,这个类必须有一个公开的默认构造函数,并且被绑定的成员必须是公开的,并且可写的属性。当模型绑定发生的时候只会通过默认的构造函数去实例化类型,然后设置属性的值。

当一个参数被绑定,模型绑定停止继续查找这个参数名并开始绑定下一个参数。如果绑定失败, MVC 不会抛出异常。你可以查询模型状态异常通过检查 ModelState.IsValid 属性。

提示
Controller 的 ModelState 属性中的每个 Entry 都是一个包含了 Errors 属性 的 ModelStateEntry。 你基本不需要去查询这个集合。使用 ModelState.IsValid 来替代它。

此外,还有一些特殊的数据类型在 MVC 执行模型绑定的时候需要考虑:

  • IFormFileIEnumerable<IFormFile>: 一个或多个通过 HTTP 请求上传的文件。

  • CancelationToken:用于在异步 Controller 中取消活动。

这些类型可以被绑定到 Action 参数或者一个类的属性中。

一旦模型绑定完成,就会进行 验证 。默认的模型绑定适合绝大多数开发场景。它也是可扩展的,所以如果你有独特的需求,你可以自定义内置的行为。

通过 Attributes 自定义模型绑定行为

MVC 包含几种让你可以指定与默认绑定源不同行为的 Attribute 。比如,你可以通过使用 [BindRequired] 或者 [BindNever] Attribute 指定一个属性是否需要绑定,或者它是否应该不发生。另外你可以替换默认的数据源,指定模型绑定器(Model Binder)的数据源。下面的是模型绑定 Attribute 的列表:

  • [BindRequired]:这个 Attribute 表示如果这个绑定不能发生,将添加一个模型状态错误(Model State Error)。

  • [BindNever]:告诉模型绑定器(Model Binder)这个参数不进行绑定。

  • [FromHeader][FromQuery][FromRoute][FromForm]:通过这些来指定期望的绑定源。

  • [FromServices]:这个 Attribute 使用 dependency injection 通过服务来绑定参数。

  • [FromBody]:使用配置好的格式化器来 从 HTTP 请求 Body 中绑定数据。格式化器的选择基于 HTTP 请求的 Content-Type
    [ModelBinder]:用来替换默认的模型绑定器(Model Binder),绑定源和名字。

当你需要替换模型绑定的默认行为时,Attribute 是非常有用的工具。

从 Http Request 的 body 中绑定格式化数据

HTTP 请求数据能够支持各种各样的格式,包括 JSON 、XML 以及许多其它的格式。当你使用 [FromBody] 特性的时候表示你想要从 HTTP 请求的 Body 中绑定参数, MVC 使用一个格式化器的配置集来处理与 HTTP 请求的 Content-Type 对应的请求数据。默认情况下 MVC 包含一个 JsonInputFormatter 类用来处理 JSON 数据,但是你可以添加额外的格式化器来处理 XML 或者其它自定义格式。

提示
JsonInputFormatter 是默认的格式化器,它是基于 Json.NET

ASP.NET 选择输入格式化器基于 Content-Type Header 以及参数的类型,除非这里有一个 Attribute 去指定其它的。如果你更喜欢使用 XML 或者其他格式,你必须在 Startup.cs 文件中进行配置,但是首先你必须使用 NuGet 引用 Microsoft.AspNetCore.Mvc.Formatters.Xml 。你的启动代码看起来应该像这样:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
       .AddXmlSerializerFormatters();
}

Startup.cs 文件中的代码包含了一个带有 services 参数的 ConfigureServices 方法,你可以使用它来为你的 ASP.NET 应用构建服务。在示例中,我们添加一个 XML 格式化器作为一个在此应用中 MVC 能够提供的的服务。 options 参数传入 AddMvc 方法允许你去添加和管理过滤器(Filter),格式化器(Formatter),以及其它 MVC 的系统选项从应用中启动。然后应用 各种各样的 Attribute 到 Controller 类或者 Action 方法上去实现你预期的效果。