practical-aspnetcore 实战:在 Minimal API 中使用 IFormFileCollection 实现多文件上传
practical-aspnetcore 实战:在 Minimal API 中使用 IFormFileCollection 实现多文件上传
在 ASP.NET Core Minimal API 中上传单个文件时可以直接注入 IFormFile,而上传多个文件则要使用 IFormFileCollection。本项目仓库的 iform-file-collection 示例 提供了一个完整的、可直接运行的多文件上传实现:一个 GET 接口渲染 HTML 表单,一个 POST 接口接收并落盘所有上传文件。读完本文,你将掌握 Minimal API 中多文件上传的表单构造、参数绑定、文件保存的完整写法,以及相关的安全注意事项与仓库内的延伸示例。
一、示例定位:Minimal API 文件上传系列
在仓库的 minimal-api 目录 中,文件上传被归入 "Minimal API Improvements" 分组,包含两个递进示例:
- iform-file:演示使用
IFormFile在 Minimal API 中上传单个文件; - iform-file-collection:演示使用
IFormFileCollection在 Minimal API 中上传多个文件。
本示例的项目文件 i-form-file-collection.csproj 目标框架为 net10.0,启用了 ImplicitUsings 与 LangVersion=preview,整个示例不依赖任何第三方包,开箱即用。目录下还附带了一个 pdf-test.pdf 测试文件,方便直接用于上传验证。
二、源码全解:多文件上传的完整实现
示例的完整逻辑都写在 Program.cs 中,仅包含两个端点。
2.1 GET /:渲染多文件上传表单
app.MapGet("/", (HttpContext context) => Results.Content($$"""
<html>
<head>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css" rel="stylesheet" ...>
</head>
<body>
<div class="container">
<h1>Upload Files</h1>
<div class="alert alert-info mb-3">You can find the uploaded file in 'uploaded' directory</div>
<form action="upload" method="post" enctype="multipart/form-data">
<input type="file" name="files" multiple/>
<br/>
<button type="submit" class="btn btn-primary mt-3">Upload</button>
</form>
</div>
</body>
</html>
""", "text/html"));
这段代码有几点值得注意:
Results.Content直接输出 HTML:Minimal API 没有视图引擎,这里用Results.Content(html, "text/html")将内联字符串按 HTML 类型返回,页面样式通过源码中引用的 Bootstrap 5 CDN 渲染(源码第 4-21 行)。- 字符串插值语法
$$""":Results.Content的原始字符串使用了$$前缀(源码第 4 行),表示内部{{不会触发插值,HTML 大括号因此可以原样输出。 - 多文件表单的三要素(源码第 13-15 行):
method="post":使用 POST 提交;enctype="multipart/form-data":关键,只有 multipart 编码才能携带二进制文件内容;<input type="file" name="files" multiple/>:multiple属性允许一次选择多个文件,字段名files与端点参数名保持一致。
2.2 POST /upload:接收并保存所有文件
app.MapPost("/upload", async (IFormFileCollection files, IWebHostEnvironment env) =>
{
var folder = Path.Combine(env.ContentRootPath, "uploaded");
if (Directory.Exists(folder) is false)
Directory.CreateDirectory(folder);
foreach(var file in files)
{
if (file is not null && file.Length > 0)
{
var path = Path.Combine(folder, file.FileName);
Console.WriteLine(path);
using var stream = System.IO.File.OpenWrite(path);
await file.CopyToAsync(stream);
}
}
return Results.LocalRedirect("/");
});
处理流程(源码第 23-42 行)可以拆解为四个步骤:
- 参数自动绑定:端点签名
(IFormFileCollection files, IWebHostEnvironment env)中,IFormFileCollection由 Minimal API 的内建绑定机制负责——当请求为multipart/form-data时,表单中携带的所有文件会被自动收集进该集合,无需手动解析;IWebHostEnvironment则由依赖注入容器提供。 - 准备目标目录:用
Path.Combine(env.ContentRootPath, "uploaded")在应用内容根目录下拼接uploaded子目录,若不存在则通过Directory.CreateDirectory(folder)创建(源码第 25-27 行)。 - 逐文件落盘:遍历集合,对每个非空文件用
System.IO.File.OpenWrite(path)打开写入流,再通过await file.CopyToAsync(stream)将上传内容流式拷贝到磁盘(源码第 29-38 行)。CopyToAsync是异步流式写入,不会把整个文件读入内存。 - 返回跳转:
Results.LocalRedirect("/")将浏览器重定向回上传页(源码第 41 行),形成"上传 → 回到表单 → 可再次上传"的闭环。LocalRedirect只允许本地相对路径跳转,可避免开放重定向风险。
运行 dotnet run 后访问 http://localhost:5000(或启动日志中显示的实际端口),在页面中一次选择多个文件并点击 Upload,控制台会打印每个文件的落盘路径,文件即被保存到项目目录下的 uploaded 文件夹。
三、核心机制:IFormFileCollection 到底是什么
IFormFileCollection 位于 Microsoft.AspNetCore.Http 命名空间,继承自 IEnumerable<IFormFile>,本质上是 IFormFile 的集合视图。在 Minimal API 中,它的绑定行为可以从两个维度理解:
- 集合维度:所有上传文件被统一收集,适合"一次上传多张图片/多个附件"的场景;
- 接口维度:
IFormFile成员(如FileName、Length、OpenReadStream()、CopyToAsync())对集合中的每个文件同样可用,因此遍历后可以复用与单文件完全相同的保存逻辑。
为了看清它在绑定体系中的位置,仓库提供了两个可对照的示例:
对照一:单文件 IFormFile(iform-file)
iform-file 示例 的端点签名是 (IFormFile file, IWebHostEnvironment env),配合 name="file" 的单选文件框,表单中只绑定一个文件。多文件版把参数类型换成 IFormFileCollection、文件框加上 multiple,其余保存逻辑几乎不变——这正是两个示例成对设计的原因:从单文件到多文件,只需替换参数类型与表单属性。
对照二:手动解析 ReadFormAsync(form-upload-file)
form-upload-file 示例 展示了不依赖 IFormFile 绑定的底层写法:先判断 context.Request.HasFormContentType,再 await context.Request.ReadFormAsync() 得到表单,通过 form.Files 遍历文件并 OpenReadStream() 读取。相比之下,Minimal API 的 IFormFileCollection 参数绑定是更简洁的声明式写法,把"判断内容类型 + 读取表单"的样板代码交给了框架。
四、工程细节:文件保存路径与异常边界
示例中的保存逻辑虽然简短,但包含几个值得在生产中留意的行为:
| 代码片段 | 行为说明 |
|---|---|
Path.Combine(env.ContentRootPath, "uploaded") |
文件统一落在内容根目录的 uploaded 子目录,便于集中管理 |
Directory.Exists(folder) is false 时 CreateDirectory |
幂等创建目录,避免首次上传时因目录不存在而抛异常 |
File.OpenWrite(path) |
以覆盖方式打开文件(若同名文件已存在会被截断),示例直接以原始文件名落盘 |
file.Length > 0 过滤 |
跳过空文件,避免写入零字节内容 |
Console.WriteLine(path) |
输出每个文件的最终保存路径,方便本地调试观察 |
需要说明的是:示例为了保持精简,直接使用了用户提供的 file.FileName 作为落盘文件名。从源码结构看,这存在两点生产化隐患:
- 路径穿越风险:
FileName由客户端控制,理论上可包含../等路径片段,与folder拼接后可能把文件写到uploaded目录之外。生产代码应使用Path.GetFileName(file.FileName)提取纯文件名,或使用 GUID/随机名重命名; - 同名覆盖:多个用户上传同名文件会互相覆盖,建议按时间戳或唯一 ID 生成存储名。
五、配套知识点:请求体大小与防伪令牌
多文件上传绕不开两个配套主题,仓库中恰好都有对应示例:
请求体大小上限:Kestrel 默认的请求体大小限制会作用于上传场景。仓库的 features-max-request-body-size 示例 演示了两种调整方式:在 builder.WebHost.ConfigureKestrel(k => k.Limits.MaxRequestBodySize = 5000) 中全局设置,或通过 IHttpMaxRequestBodySizeFeature 按请求动态设置(MaxRequestBodySize 属性)。文件较多、较大时,应根据实际场景调高该限制,并配合 MultipartBodyLengthLimit 约束单个文件大小。
防伪令牌:multipart/form-data 表单同样存在 CSRF 风险。仓库的 anti-forgery-1 与 anti-forgery-2 示例分别演示了在 HTML 表单与 AJAX 调用中通过 IAntiforgery 接口生成并校验防伪令牌的做法,可作为上传表单安全加固的参考。
六、延伸阅读:仓库内的相关示例
| 示例 | 路径 | 说明 |
|---|---|---|
单文件上传(IFormFile) |
projects/minimal-api/iform-file | 与本文示例对照,理解单文件与多文件的写法差异 |
| 手动解析上传表单 | projects/request/form-upload-file | 不依赖 IFormFile 绑定、直接 ReadFormAsync 的底层实现 |
| 请求体大小限制 | projects/features/features-max-request-body-size | Kestrel 与 IHttpMaxRequestBodySizeFeature 的配置方式 |
| 表单值读取 | projects/request/form-values | Request.Form 中非文件字段的读取方式,适合与文件混合的表单 |
| Minimal API 总览 | projects/minimal-api/README.md | 全部 Minimal API 示例索引(路由、参数绑定、防伪、OpenAPI 等) |
小结
IFormFileCollection 让 Minimal API 的多文件上传回归到最简形态:表单侧一个 multiple 文件框,端点侧一个集合参数,框架自动完成 multipart 解析与文件收集,开发者的核心工作只剩"遍历 + 落盘"。通过 iform-file-collection 示例 及其姊妹示例的对照,你可以快速在自己的项目里落地多文件上传,并在生产化时补上文件名净化、大小限制与防伪校验这几道安全工序。