6.0.0 Preview 3

This iteration contains a few minor enhancements, bug fixes, and a significant refactoring of the Minimal API support.

Enhancements

All Platforms

• ApiVersion now has a protected constructor parameter that accepts a custom status validation function

ASP.NET Core

• Added target for .NET Core 3.1 TFM (#815)
  • Expect this to be dropped in 7.0 per the .NET Core 3.1 End of Support policy

ASP.NET Core with OData

• API Explorer extensions now support OData query options for non-OData controllers
• Added example to demonstrate OData query options for non-OData controllers

ASP.NET Web API with OData

• API Explorer extensions now support OData query options for non-OData controllers
• Added example to demonstrate OData query options for non-OData controllers

Fixes

ASP.NET Core with OData

• Fix mapping of API version metadata to OData endpoints
• Fix/verify OData OpenAPI example (#821 #825)

Breaking Changes

After a lengthy discussion with @davidfowl himself (#751), Minimal API support has been significantly refactored. The end result is less than what I had hoped for the API to look like, but much more inline with you should expect and with far less duplicated code. ASP.NET Core 6.0 has no grouping construct so it doesn't really make sense to shoehorn it in. A grouping concept will be introduced in 7.0 at which time API Versioning will likely provide new extensions that make composing API version sets more succinct.

The current Minimal API design is primarily meant to attach metadata, not extend the builder. API Versioning needs/wants both, which is why it had its own grouping mechanism. That didn't come without consequence. To work within the current design limitations, an API version set is built outside of any Minimal API. This isn't the policy nor complete metadata. This is the version set that you might have otherwise included in a grouping. The WithApiVersionSet extension method will create and return a new IVersionedEndpointConventionBuilder that is a composition between IEndpointConventionBuilder and IMapToApiVersionConventionBuilder. This allows the existing, intrinsic extension methods to continue working as they always have, but allow you to continue building API version related metadata. The ApiVersionMetadata for the configured Endpoint isn't constructed until just before the Endpoint itself is constructed.

For example:

builder.Services.AddApiVersioning();

var app = builder.Build();

// define a 'version set' that applies to an API group
var versionSet = app.NewApiVersionSet()
                    .HasApiVersion(1.0)
                    .HasApiVersion(2.0)
                    .ReportApiVersions()
                    .Build();

app.MapGet("/values/{id}", (string id) => $"Value {id} (V1)")
   .WithApiVersionSet(versionSet)
   .MapToApiVersion(1.0);

app.MapGet("/values/{id}", (int id) => $"Value {id} (V2)")
   .WithApiVersionSet(versionSet)
   .MapToApiVersion(2.0);

This change solves other issues caused by duplicating or reimplementing some of the built-in behaviors such #823 and #824.

Apologies for the change in direction, but I think this is the right way to go given all the feedback. Some level of feedback was necessary to dial things in and I want to thank everyone that has been trying out the previews and/or commenting on the initial design. Save any other bugs or limitations yet to be uncovered, I believe the design for 6.0 is now stable. I don't expect, nor have planned, any other changes for Minimal APIs. I'm still listening to your feedback, so feel free to comment or suggest other changes. A few people have looked that the changes in the last PR branch and are pleased with the changes, despite the shift in direction.