Add metadata for IFormFile usage with minimal actions

[martincostello]

Background and Motivation

As suggested in #34303 (comment), to support binding parameters of type IFormFile with minimal actions, some metadata to allow the form field name for the file would be needed to support names that can't be expressed with C# syntax within the parameter name.

Proposed API

namespace Microsoft.AspNetCore.Http.Metadata
{
+    public interface IFromFileMetadata
+    {
+        string? Name { get; }
+    }
}

namespace Microsoft.AspNetCore.Mvc
{
+    [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = false, Inherited = true)]
+    public class FromFileAttribute : Attribute, IBindingSourceMetadata, IModelNameProvider, IFromFileMetadata
+    {
+        public FromFileAttribute();
+        public FromFileAttribute(string name);
+
+        public BindingSource BindingSource => BindingSource.FormFile;
+        public string? Name { get; set; }
+    }
}

Usage Examples

app.MapPost("/upload", async ([FromFile("file-name")] IFormFile file) =>
{
    using var stream = System.IO.File.OpenWrite("upload.txt");
    await file.CopyToAsync(stream);
});

Alternative Designs

A more explicit name, but having from and form next to each other looks a bit yuck.

namespace Microsoft.AspNetCore.Http.Metadata
{
+   public interface IFromFormFileMetadata
+   {
+       string? Name { get; }
+   }
}

Putting FromFileAttribute in a different namespace so it's not coupled to MVC.

namespace Microsoft.AspNetCore.Http.Metadata
{
+    [AttributeUsage(AttributeTargets.Parameter, AllowMultiple = false)]
+    public class FromFileAttribute : Attribute, IFromFileMetadata
+    {
+        public FromFileAttribute();
+        public FromFileAttribute(string name);
+
+        public string? Name { get; set; }
+    }
}

Risks

The other [From...] attributes live in the Microsoft.AspNetCore.Mvc namespace so adding another in the same place would make sense, but adding the concrete implementation for [FromFile(...)] to MVC wouldn't be right without also implementing it within model binding there too as a new feature to supplement the existing IFormFile support. Otherwise users of controllers might try and use it and it then not work as expected.

We've moved this issue to the Backlog milestone. This means that it is not going to be worked on for the coming release. We will reassess the backlog following the current release and consider this item at that time. To learn more about our issue management process and to have better expectation regarding different types of issues you can read our Triage Process.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[pranavkm]

API review: We think we might be able to get away re-using the existing FromFormAttribute and specialize the swagger based on if it's a IFormFile / IFormFileCollection instance.

+ public interface IFromFormMetadata
+ {
+     string? Name { get; }
+ }

- public class FromFormAttribute : Attribute, IBindingSourceMetadata, IModelNameProvider
+ public class FromFormAttribute : Attribute, BindingSourceMetadata, IModelNameProvider, IFromFormMetadata

Usage:

app.MapPost("/upload", async ([FromForm("file-name")] IFormFile file) => { ... });

app.MapPost("/upload", async ([FromForm] IFormFileCollection file) => { ... }); 

app.MapPost("/upload", async (IFormFile myFile) => { ... });

app.MapPost("/upload", async (IFormFileCollection myFiles) => { ... });

// Unsupported. Analyzer error. This can be done in a follow up
app.MapPost("/upload", async ([FromForm("myFiles")] IFormFileCollection file) => { ... }); 

For IFormFileCollection, we do not wanted based on the parameter name or IFromFormAttribute.Name (at least to start with). We can make the latter an error via an analyzer + a runtime check.