.NET API中使用[FromForm]上传列表与文件失效问题

问题场景 #

使用[FromForm]绑定包含IFormFile和复杂类型列表（List<Tax>、List<Approver>）的请求模型时，上传文件后复杂列表无法被正确映射到模型对象，即使Request.Form中存在完整数据；不上传文件时所有列表数据均可正常绑定。Swashbuckle和NSwag均存在此问题。

解决方案 #

方案1：手动从Request.Form绑定复杂列表 #

在控制器方法中直接从Request.Form提取并解析复杂列表数据：

[HttpPost]
[Route("Create")]
public async Task<IActionResult> CreateInvoice(
    [FromForm] CreateInvoiceRequest request,
    CancellationToken cancellationToken)
{
    // 解析Taxes列表（根据实际Tax类属性调整字段名）
    var taxes = new List<Tax>();
    if (int.TryParse(Request.Form["Taxes.Count"], out var taxCount))
    {
        for (var i = 0; i < taxCount; i++)
        {
            taxes.Add(new Tax
            {
                Name = Request.Form[$"Taxes[{i}].Name"],
                Rate = decimal.TryParse(Request.Form[$"Taxes[{i}].Rate"], out var rate) ? rate : 0m
            });
        }
    }
    // 更新request的Taxes字段（record类型使用with表达式）
    request = request with { Taxes = taxes };

    // 解析Approvers列表（根据实际Approver类属性调整字段名）
    var approvers = new List<Approver>();
    if (int.TryParse(Request.Form["Approvers.Count"], out var approverCount))
    {
        for (var i = 0; i < approverCount; i++)
        {
            approvers.Add(new Approver
            {
                Id = Guid.TryParse(Request.Form[$"Approvers[{i}].Id"], out var id) ? id : Guid.Empty,
                Name = Request.Form[$"Approvers[{i}].Name"]
            });
        }
    }
    request = request with { Approvers = approvers };

    // 后续业务逻辑处理
    return Ok();
}

方案2：自定义模型绑定器（更优雅的长期方案） #

创建自定义模型绑定器统一处理请求模型的绑定逻辑：

1. 实现模型绑定器

public class CreateInvoiceRequestModelBinder : IModelBinder
{
    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        if (bindingContext == null)
            throw new ArgumentNullException(nameof(bindingContext));

        var form = bindingContext.HttpContext.Request.Form;

        // 解析Descriptions
        var descriptions = form["Descriptions"]
            .Where(v => !string.IsNullOrWhiteSpace(v))
            .ToList();

        // 解析Attachment
        IFormFile? attachment = form.Files.GetFile("Attachment");

        // 解析Taxes
        var taxes = new List<Tax>();
        if (int.TryParse(form["Taxes.Count"], out var taxCount))
        {
            for (var i = 0; i < taxCount; i++)
            {
                taxes.Add(new Tax
                {
                    Name = form[$"Taxes[{i}].Name"],
                    Rate = decimal.TryParse(form[$"Taxes[{i}].Rate"], out var rate) ? rate : 0m
                });
            }
        }

        // 解析Approvers
        var approvers = new List<Approver>();
        if (int.TryParse(form["Approvers.Count"], out var approverCount))
        {
            for (var i = 0; i < approverCount; i++)
            {
                approvers.Add(new Approver
                {
                    Id = Guid.TryParse(form[$"Approvers[{i}].Id"], out var id) ? id : Guid.Empty,
                    Name = form[$"Approvers[{i}].Name"]
                });
            }
        }

        var request = new CreateInvoiceRequest(descriptions, attachment, taxes, approvers);
        bindingContext.Result = ModelBindingResult.Success(request);
        return Task.CompletedTask;
    }
}

2. 实现模型绑定提供器

public class CreateInvoiceRequestModelBinderProvider : IModelBinderProvider
{
    public IModelBinder? GetBinder(ModelBinderProviderContext context)
    {
        if (context.Metadata.ModelType == typeof(CreateInvoiceRequest))
            return new CreateInvoiceRequestModelBinder();

        return null;
    }
}

3. 注册绑定器到服务
   在Program.cs中添加绑定器注册：

builder.Services.AddControllers(options =>
{
    // 将自定义绑定器放在最前面，优先使用
    options.ModelBinderProviders.Insert(0, new CreateInvoiceRequestModelBinderProvider());
});

4. 修改控制器方法
   此时可以去掉[FromForm]特性（绑定器会自动处理表单绑定）：

[HttpPost]
[Route("Create")]
public async Task<IActionResult> CreateInvoice(
    CreateInvoiceRequest request,
    CancellationToken cancellationToken)
{
    // 业务逻辑处理
    return Ok();
}

问题原因 #

当表单包含IFormFile时，ASP.NET Core默认模型绑定对嵌套复杂类型列表的索引式表单参数（如Taxes[0].Name）解析逻辑存在异常，无法正确映射到列表对象，但这些数据仍完整存在于Request.Form中，因此需要手动解析或通过自定义绑定器处理。

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