Summary
Document the parameter-binding behavior differences between IFormFileCollection and IReadOnlyList<IFormFile> (and related collection types) in Minimal APIs. This was requested by the framework team in dotnet/aspnetcore#66757 (see this comment from @captainsafia).
Page to update
Parameter binding in Minimal API applications — "Binding to forms with IFormCollection, IFormFile, and IFormFileCollection"
Source file: aspnetcore/fundamentals/minimal-apis/includes/parameter-binding8-10.md (around the section anchored at <a name="bind8">).
What needs to be documented
Minimal API form-file binding has three distinct, undocumented behaviors depending on the parameter type:
-
IFormFileCollection — Always binds to the entire HttpContext.Request.Form.Files collection. The parameter name is ignored; every uploaded file is included regardless of its form field name. This is handled by the Minimal API parameter-binding layer in RequestDelegateFactory and maps directly to HttpContext.Request.Form.Files.
-
IReadOnlyList<IFormFile> — Binds only the files whose form field name matches the parameter (or property) name. This is handled by the shared form-mapping layer used by Minimal APIs and Blazor, which calls IFormFileCollection.GetFiles(name).
-
Other collection shapes are not supported. The following bind to empty / are not populated:
- Interfaces:
IEnumerable<IFormFile>, IReadOnlyCollection<IFormFile>, ICollection<IFormFile>, IList<IFormFile>
- Concrete types:
List<IFormFile>, IFormFile[], Collection<IFormFile>, ReadOnlyCollection<IFormFile>
Users who want a name-scoped collection of files should use IReadOnlyList<IFormFile>; users who want every uploaded file should use IFormFileCollection.
Repro / evidence
Suggested doc change
Add a short subsection (or call-out table) under "Binding to forms with IFormCollection, IFormFile, and IFormFileCollection" that captures the three behaviors above. A table like the following would make the distinction easy to scan:
| Parameter type |
Bound value |
Honors parameter name? |
IFormFileCollection |
All files in HttpContext.Request.Form.Files |
No |
IFormFile |
The single file whose form field name matches the parameter name |
Yes |
IReadOnlyList<IFormFile> |
All files whose form field name matches the parameter name |
Yes |
Other IFormFile collection types (IEnumerable<IFormFile>, List<IFormFile>, IFormFile[], etc.) |
Not supported — parameter is not populated |
n/a |
It would also be worth adding a one-line note that this same behavior applies to properties on [AsParameters] / form-mapped complex types (since the form-mapping layer is shared with Blazor).
Versions affected
The behavior exists in .NET 7+ Minimal APIs. The doc update should target the >= aspnetcore-8.0 content (the parameter-binding8-10.md include), since that is where the form-file binding section lives.
/cc @tdykstra @wadepickett
Summary
Document the parameter-binding behavior differences between
IFormFileCollectionandIReadOnlyList<IFormFile>(and related collection types) in Minimal APIs. This was requested by the framework team in dotnet/aspnetcore#66757 (see this comment from @captainsafia).Page to update
Parameter binding in Minimal API applications — "Binding to forms with IFormCollection, IFormFile, and IFormFileCollection"
Source file:
aspnetcore/fundamentals/minimal-apis/includes/parameter-binding8-10.md(around the section anchored at<a name="bind8">).What needs to be documented
Minimal API form-file binding has three distinct, undocumented behaviors depending on the parameter type:
IFormFileCollection— Always binds to the entireHttpContext.Request.Form.Filescollection. The parameter name is ignored; every uploaded file is included regardless of its form field name. This is handled by the Minimal API parameter-binding layer inRequestDelegateFactoryand maps directly toHttpContext.Request.Form.Files.IReadOnlyList<IFormFile>— Binds only the files whose form field name matches the parameter (or property) name. This is handled by the shared form-mapping layer used by Minimal APIs and Blazor, which callsIFormFileCollection.GetFiles(name).Other collection shapes are not supported. The following bind to empty / are not populated:
IEnumerable<IFormFile>,IReadOnlyCollection<IFormFile>,ICollection<IFormFile>,IList<IFormFile>List<IFormFile>,IFormFile[],Collection<IFormFile>,ReadOnlyCollection<IFormFile>Users who want a name-scoped collection of files should use
IReadOnlyList<IFormFile>; users who want every uploaded file should useIFormFileCollection.Repro / evidence
IFormFileCollection,IReadOnlyList<IFormFile>and other collection types in Minimal APIs aspnetcore#66757 (comment)Suggested doc change
Add a short subsection (or call-out table) under "Binding to forms with IFormCollection, IFormFile, and IFormFileCollection" that captures the three behaviors above. A table like the following would make the distinction easy to scan:
IFormFileCollectionHttpContext.Request.Form.FilesIFormFileIReadOnlyList<IFormFile>IFormFilecollection types (IEnumerable<IFormFile>,List<IFormFile>,IFormFile[], etc.)It would also be worth adding a one-line note that this same behavior applies to properties on
[AsParameters]/ form-mapped complex types (since the form-mapping layer is shared with Blazor).Versions affected
The behavior exists in .NET 7+ Minimal APIs. The doc update should target the
>= aspnetcore-8.0content (theparameter-binding8-10.mdinclude), since that is where the form-file binding section lives./cc @tdykstra @wadepickett