ASP.NET Core模型绑定异常：含参数对象名时无法绑定全部数据

问题描述 #

使用[FromQuery]绑定复杂类型参数时，若请求URL中包含参数对象名称（如示例中的&p），会导致对象内的属性绑定失效（比如P.Time变为null），即便属性对应的查询参数（如time=2025-01-01）已正确传入。

复现代码 #

using Microsoft.AspNetCore.Mvc;

namespace WebApplication1.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class TestController : ControllerBase
    {
        [HttpGet]
        public IActionResult Get([FromQuery] P p)
        {
            return Ok();
        }

        public class P
        {
            [BindProperty]
            public DateTime? Time { get; set; }
        }
    }
}

解决方案 #

方案一：全局配置禁用空值重置绑定 #

在Program.cs中添加配置，阻止绑定器因空参数名重置属性值：

builder.Services.Configure<ApiBehaviorOptions>(options =>
{
    options.SuppressBindingUndefinedValueToNull = true;
});

此配置会让模型绑定器保留已通过属性名绑定的值，不受空参数名的干扰。

方案二：手动提取查询参数赋值 #

绕开自动模型绑定，直接从请求中提取参数并构造对象：

[HttpGet]
public IActionResult Get()
{
    var timeStr = Request.Query["time"];
    DateTime? time = null;
    if (!string.IsNullOrEmpty(timeStr) && DateTime.TryParse(timeStr, out var parsedTime))
    {
        time = parsedTime;
    }
    var p = new P { Time = time };
    return Ok(p);
}

方案三：标记参数对象忽略名称（慎用） #

给参数对象添加[FromQuery(Name = "")]，让绑定器仅处理属性级别的查询参数：

public IActionResult Get([FromQuery(Name = "")] P p)
{
    return Ok();
}

注意：该方法仅适用于单个复杂参数的场景，多复杂参数时可能引发绑定冲突。

问题原因 #

.NET 8的模型绑定逻辑中，当查询字符串存在参数对象的键（如p）但无对应值时，绑定器会默认初始化一个空的P对象，覆盖之前通过属性名（time）绑定的值，最终导致Time属性为null。

内容的提问来源于stack exchange，提问作者Marko