Add support for argument list surrogates in minimal APIs

[davidfowl]

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

The idea here is to support using a type that can act like a surrogate for the argument list in a minimal API. The motivation is about refactoring a minimal API that takes a large set of parameters into one that takes a single object with top level properties that represent what were once arguments. This is a common pattern seen with CQRS frameworks where a request object is made to bind all inputs.

Describe the solution you'd like

app.MapGet("/products/{id}", (int id, int pageSize, int page, ILogger<Program> logger, MyDb db) =>
{
    logger.LogInformation("Getting products for page {Page}, page);
    
    return db.Products.Skip((page - 1) * pageSize).Take(pageSize);
});

The user wishes to refactor this to:

app.MapGet("/products/{id}", ([Parameters]ProductRequest req) =>
{
     req.Logger.LogInformation("Getting products for page {Page}, req.Page);
    
     return req.Db.Products.Skip((req.Page - 1) * req.PageSize).Take(req.PageSize);
});

public record ProductRequest(int Id, int PageSize, int Page, ILogger<Program> Logger, MyDb Db);

The parameter or type needs to be marked explicitly to identify that this is not from the body or elsewhere (query etc). These properties should also support binding attributes:

public class ProductRequest
{
  [FromRoute]
  public int Id { get; set; } 

  [FromQuery]
  public int PageSize { get; set; }

  [FromQuery]
  public int Page { get; set; } 

  [FromServices]
  public ILogger<Program> Logger { get; set; } 

  [FromServices]
  public MyDb Db {get; set; }
}

This would only work for top level properties in this object.

Additional context

Open questions:

• Do we want to support multiple of these? No 😄

[ghost]

Thanks for contacting us.

We're moving this issue to the .NET 7 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[Acerby]

I suspect its fairly common for a number of API method to support a common set/subset of options/properties. Being able to do something akin to:
app.MapGet("/chairs/{cid}", (int cid, [Parameters]CommonProps) => {...}
app.MapGet("/seats/{sid}", (int sid, [Parameters]CommonProps) => {...}
would seem to provide a nice way to allow these to be declared/managed/used in a consistent way.
Additionally common pre-processing operations could be encapsulated by methods/extension-methods on the above CommonProps class.

[Acerby]

It feels like there is an overlap between this functionality and that supported by the IModelBinder interface. The primary difference being the class is based declarative automatic generation of the fields based as opposed to being generated via bespoke code. I guess one potential approach to implementation would be to use the [Properties] attribute on the class as a trigger to the complier to auto generate the code to add a default implementation of the IModelBinder interface on the given class. Provision for this might also result in simpler/cleaner code for cases where IModelBinder may currently be required/used.

[brunolins16]

Proposed API

Add new attribute that users can decorate their classes or delegates parameters to allow refactoring a minimal API that takes a large set of parameters into one that takes a single object with top level properties that represent what were once arguments.

namespace Microsoft.AspNetCore.Http;

+[AttributeUsage(AttributeTargets.Parameter, Inherited = false, AllowMultiple = false)]
+public sealed class ParametersAttribute : Attribute
+{ }

The idea is supporting the attribute in multiples parameters and also mixed with parameters without the atrribute.

Usage Examples

Attribute specified in the delegate parameter

app.MapGet("/products/{id}", ([Parameters]ProductRequest req, [Parameters]Paging pageInfo) =>
{    
     return req.Db.Products.Skip((req.Page - 1) * req.PageSize).Take(req.PageSize);
});

public record ProductRequest(int Id, ILogger<Program> Logger, MyDb Db);
public record Paging(int PageSize, int Page);

or

app.MapGet("/products/{id}", (int id, ILogger<Program> logger, MyDb db, [Parameters]Paging pageInfo) =>
{    
     return req.Db.Products.Skip((req.Page - 1) * req.PageSize).Take(req.PageSize);
});
public record Paging(int PageSize, int Page);

Alternative Designs

As an alternative design, we could also create a public interface (marker).

namespace Microsoft.AspNetCore.Http.Metadata;

+public interface IFromParametersMetadata
+{}

namespace Microsoft.AspNetCore.Http;

+[AttributeUsage(AttributeTargets.Parameter, Inherited = false, AllowMultiple = false)]
+public sealed class ParametersAttribute : Attribute, IFromParametersMetadata
+{ }

That will allow users to create their own attribute implementation, as we have for IFromServiceMetadata, IFromRouteMetadata, etc.

[ghost]

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.

[halter73]

I'm not sure that I like how generic [Parameters] is for a parameter attribute. I don't think many people would guess what the attribute does without already knowing. It almost seems redundant. Of course, a parameter is a parameter 😆

This is going to be in a global using by default as part of the Microsoft.AspNetCore.Http namespace, so it could show up in a lot of contexts. This is different than all the other attributes we currently use in route handlers like [FromBody] that lives in Microsoft.AspNetCore.Mvc.

I know what we're really trying to indicate is that the properties of the parameter are treated as a top-level parameter and that it's hard to communicate this in a reasonably short attribute name though. Maybe [Flatten] would work? That's less seemingly redundant but just as ambiguous. [PropertiesAsParameters]? Would we ever put this in another namespace? We cannot reasonably put it in Microsoft.AspNetCore.Mvc unless MVC also supports it which seems unlikely.

[davidfowl]

I was waiting for this ugly name discussion 😄. I agree parameters is too generic. I can't wait to 🚲 shed on this.

[brunolins16]

Some additional name ideas:

[AsParameters]
[Flatten]
[PropertiesAsParameters]
[ParameterList]
[Surrogate]

[halter73]

API review notes:

• What should we target?
  • Parameters? For sure.
  • Types? Not for now. It might make it appear that nesting should work. It's not supported by other parameter attributes in MVC.
  • Properties? No nesting! 😞
• Name?
  • Between keeping [Parameters] and [AsParameters]. The [AsParameters] feels more like the [From...] attributes.
  • [AsParameters] wins.
• Should the attribute be inheritable?
  • What does this even mean for parameters? Are parameter attributes inherited from the overridden method on the base type?
  • This seems pretty niche for minimal route handlers which are normally delegates or local methods. I don't think I've even seen someone use an overridden method as a route handler yet.
  • Starting out with Inherited = false seems simpler and safer. If we change our mind, I doubt it'd break many apps if we switch the attribute to be inheritable.
• Should [FromServices] be updated to support properties?
  • Yes, but be careful that this doesn't have weird MVC side effects.
• Are we happy with the Microsoft.AspNetCore.Http namespace? It's globally included by default.
  • Yes we're happy especially now that the attribute is [AsParameters] instead of [Parameters].

API Approved!

namespace Microsoft.AspNetCore.Http;

+[AttributeUsage(AttributeTargets.Parameter, Inherited = false, AllowMultiple = false)]
+public sealed class AsParametersAttribute : Attribute
+{ }

namespace Microsoft.AspNetCore.Mvc;

-[AttributeUsage(AttributeTargets.Parameter, AllowMultiple = false, Inherited = true)]
+[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = false, Inherited = true)]
public class FromServicesAttribute : Attribute, IBindingSourceMetadata, IFromServiceMetadata

[JamesNK]

Does this feature work in MVC? If not, are there any plans to add it? It seems like the idea can be applied to both frameworks.

[JamesNK]

Issue for adding support to MVC: #42271