Document IFormFileCollection vs IReadOnlyList<IFormFile> binding behavior in Minimal APIs

[Copilot]

Internal review link directly to new section

Fixes #37173

Minimal API form-file binding has undocumented behavioral differences depending on parameter type — IFormFileCollection ignores the parameter name and binds all files, IReadOnlyList<IFormFile> binds only name-matched files, and other collection types silently don't bind at all. Requested by framework team in dotnet/aspnetcore#66757.

Changes:

• Added #### IFormFile collection binding behavior subsection to parameter-binding8-10.md after the existing form-file binding content
• Added comparison table covering IFormFileCollection, IFormFile, IReadOnlyList<IFormFile>, and unsupported collection types
• Added note that the same behavior applies to [AsParameters] and form-mapped complex types (shared form-mapping layer with Blazor)

Parameter type	Bound value	Honors parameter name?
IFormFileCollection	All files in HttpContext.Request.Form.Files	No
IFormFile	Single file matching parameter name	Yes
IReadOnlyList<IFormFile>	All files matching parameter name	Yes
Other collection types	Not supported	n/a

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/fundamentals/minimal-apis/parameter-binding.md	aspnetcore/fundamentals/minimal-apis/parameter-binding

[Copilot]

Pull request overview

Documents the (previously undocumented) differences in Minimal API form-file binding behavior across IFormFile-related parameter types, helping readers choose the correct type for “all files” vs “name-matched files” scenarios.

Changes:

• Added an “IFormFile collection binding behavior” subsection under the existing form binding section.
• Added a comparison table describing binding results for IFormFileCollection, IFormFile, IReadOnlyList<IFormFile>, and unsupported collection shapes.
• Added a note that the same behavior applies for [AsParameters] and form-mapped complex types.

[wadepickett]

Approved after a few fixes have now been addressed.

[wadepickett]

@danroth27, Internal review link directly to the new section for your review on this binding behaviour update.

[wadepickett]

@copilot, also update the file that uses this include to have the latest ms.date value in the metadata:
dotnet/AspNetCore.Docs/refs/heads/main/aspnetcore/fundamentals/minimal-apis/parameter-binding.md

update this:
ms.date: 10/22/2025

to this:
ms.date: 05/22/2026

[Copilot]

@copilot, also update the file that uses this include to have the latest ms.date value in the metadata:
dotnet/AspNetCore.Docs/refs/heads/main/aspnetcore/fundamentals/minimal-apis/parameter-binding.m...

Updated ms.date to 05/22/2026 in aspnetcore/fundamentals/minimal-apis/parameter-binding.md.

[wadepickett]

Approved, after a few updates were applied.

[tdykstra]

Looks good; I left a couple take it or leave it suggestions.

[wadepickett]

@copilot.
In the new "IFormFile collection binding behavior" section in aspnetcore/fundamentals/minimal-apis/includes/parameter-binding8-10.md::
Replace all backtick-only API type references with xref: links.

For example, IFormFileCollection should become xref:Microsoft.AspNetCore.Http.IFormFileCollection, IFormFile should become xref:Microsoft.AspNetCore.Http.IFormFile, and IReadOnlyList<IFormFile> should link at least IFormFile. Follow the same xref conventions already used elsewhere in this file. Verify al xref links, if you can't, indicate so.

[Copilot]

@copilot.
In the new "IFormFile collection binding behavior" section in aspnetcore/fundamentals/minimal-apis/includes/parameter-binding8-10.md::
Replace all backtick-only API type references with ...

Replaced all backtick-only API type references with xref links in commit 867e9c6. Used <xref:Microsoft.AspNetCore.Http.IFormFile>, <xref:Microsoft.AspNetCore.Http.IFormFileCollection>, <xref:System.Collections.Generic.IReadOnlyList%601>, <xref:Microsoft.AspNetCore.Http.IFormCollection.Files>, and <xref:Microsoft.AspNetCore.Http.AsParametersAttribute>. Table cells use the [DisplayName](xref:Full.Name) pattern for readability.