From 95f70ce3a74dbd7c932fb7084e13213087e12258 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 22 May 2026 17:01:33 -0700 Subject: [PATCH] Document IFormFileCollection vs IReadOnlyList binding behavior in Minimal APIs (#37180) * Initial plan * Add IFormFile collection binding behavior documentation table Agent-Logs-Url: https://github.com/dotnet/AspNetCore.Docs/sessions/31eabf0b-7df6-4426-8954-70d277d62994 Co-authored-by: wadepickett <10985336+wadepickett@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Apply suggestion from @wadepickett * Apply suggestion from @wadepickett * Update ms.date to 05/22/2026 in parameter-binding.md * Apply suggestion from @wadepickett name to id link fix per feedback from tdykstra * Replace backtick API references with xref links in IFormFile collection binding section Agent-Logs-Url: https://github.com/dotnet/AspNetCore.Docs/sessions/560fca58-5c8b-4fe3-8d5b-eaec8740cd24 Co-authored-by: wadepickett <10985336+wadepickett@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: wadepickett <10985336+wadepickett@users.noreply.github.com> Co-authored-by: Wade Pickett Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../includes/parameter-binding8-10.md | 18 +++++++++++++++++- .../minimal-apis/parameter-binding.md | 2 +- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/aspnetcore/fundamentals/minimal-apis/includes/parameter-binding8-10.md b/aspnetcore/fundamentals/minimal-apis/includes/parameter-binding8-10.md index fe887ae9335c..74fe11354353 100644 --- a/aspnetcore/fundamentals/minimal-apis/includes/parameter-binding8-10.md +++ b/aspnetcore/fundamentals/minimal-apis/includes/parameter-binding8-10.md @@ -217,7 +217,23 @@ For more information on XSRF attacks, see [Antiforgery with Minimal APIs](xref:s For more information, see [Form binding in Minimal APIs](https://andrewlock.net/exploring-the-dotnet-8-preview-form-binding-in-minimal-apis/); - +#### IFormFile collection binding behavior + +The following table summarizes how different collection parameter types are bound in Minimal APIs. The general guidance that the parameter name in the route handler must match the form field name applies to and supported named file collections such as , but not to , which binds all uploaded files. + +| Parameter type | Bound value | Honors parameter name? | +| --- | --- | --- | +| [`IFormFileCollection`](xref:Microsoft.AspNetCore.Http.IFormFileCollection) | All files in [`HttpContext.Request.Form.Files`](xref:Microsoft.AspNetCore.Http.IFormCollection.Files) | No | +| [`IFormFile`](xref:Microsoft.AspNetCore.Http.IFormFile) | The single file whose form field name matches the parameter name | Yes | +| [`IReadOnlyList`](xref:System.Collections.Generic.IReadOnlyList%601) | All files whose form field name matches the parameter name | Yes | +| Other [`IFormFile`](xref:Microsoft.AspNetCore.Http.IFormFile) collection types (`IEnumerable`, `List`, `IFormFile[]`, etc.) | Not supported — parameter is not populated | N/A | + +Use when you need all uploaded files regardless of form field name. Use when you need only the files whose form field name matches the parameter name. + +> [!NOTE] +> The collection binding rules in the preceding table also apply to properties on [`[AsParameters]`](xref:Microsoft.AspNetCore.Http.AsParametersAttribute) types and form-mapped complex types, since the form-mapping layer is shared with Blazor. + + ## Bind to collections and complex types from forms diff --git a/aspnetcore/fundamentals/minimal-apis/parameter-binding.md b/aspnetcore/fundamentals/minimal-apis/parameter-binding.md index 7cbcabc173bc..9ebf052eecd2 100644 --- a/aspnetcore/fundamentals/minimal-apis/parameter-binding.md +++ b/aspnetcore/fundamentals/minimal-apis/parameter-binding.md @@ -4,7 +4,7 @@ author: wadepickett description: Learn how parameters are populated before invoking minimal route handlers. ms.author: wpickett monikerRange: '>= aspnetcore-7.0' -ms.date: 10/22/2025 +ms.date: 05/22/2026 uid: fundamentals/minimal-apis/parameter-binding ai-usage: ai-assisted ---