7.0.0
The official release for .NET 7.0 is finally here. There have been numerous changes between the previews and fixes that occurred in 6.0 so they will all be collated here for your convenience.
Features
The primary feature and enhancement areas include:
- Support for .NET 7.0
- Enhanced support for Minimal APIs with grouping
- Expanded support for exploring OData query options in non-OData APIs
Minimal APIs
var builder = WebApplication.CreateBuilder( args );
builder.Services.AddApiVersioning();
var app = builder.Build();
var orders = app.NewVersionedApi(); // ← group for an api with an optional name
var v1 = orders.MapGroup( "/api/order" ).HasApiVersion( 1.0 ); // ← all endpoints in this group have 1.0
var v2 = orders.MapGroup( "/api/order" ).HasApiVersion( 2.0 ); // ← all endpoints in this group have 2.0
v1.MapGet( "/{id:int}", ( int id ) => new V1.Order() { Id = id, Customer = "John Doe" } );
v2.MapGet( "/{id:int}", ( int id ) => new V2.Order() { Id = id, Customer = "John Doe", Phone = "555-555-5555" } );
v2.MapDelete( "/{id:int}", ( int id ) => Results.NoContent() );
Non-OData Model Bound Settings
Several OData query settings, such as the allowed properties, can only be configured using Model Bound settings. This information is annotated in the Entity Data Model (EDM). How do you configure this information if you're only using some of OData and don't have an EDM?
The OData API Explorer extensions already support using conventions, but it does not allow you to specify a convention which cannot be mapped to some combination of ODataQueryOptionSettings
or ODataValidationSettings
. ModelBoundSettings
is supported, but mapping custom conventions over it would largely be a duplication of what ODataModelBuilder
already does.
The new API Explorer support bridges this gap by creating ad hoc EDM instances on your behalf for the sole purpose of configuring Model Bound settings. This allows you to define configurations you couldn't otherwise without having to use an EDM. You have the choice to use attributes or the ODataModelBuilder
fluent API for conventions.
Consider the following:
[Filter( "author", "published" )] // ← model bound settings with attributes
public class Book
{
public string Id { get; set; }
public string Title { get; set; }
public string Author { get; set; }
public int Published { get; set; }
}
For ASP.NET Core, that's it; there is nothing else you need to do. ASP.NET Web API doesn't support DI out-of-the-box, so you'll need the following basic setup:
configuration.AddODataApiExplorer(
options => options.AdHocModelBuilder
.ModelConfigurations
.Add( new ImplicitModelBoundSettingsConvention() ) );
Both platforms support adding, removing, or using conventions. The result of this configuration will show the $filter
query option and indicate only the author
and published
properties can be used. If you prefer not to use attributes, the convention-based API can be used as well:
AddODataApiExplorer(
options =>
options.AdHocModelBuilder.DefaultConfiguration = (builder, version, prefix) =>
builder.ComplexType<Book>().Filter( "author", "published" ) ) ;
The ad hoc EDM is only available during API exploration and is then discarded. It does not opt into any OData features.
ASP.NET Web API
ApiVersioningOptions.UnsupportedApiVersionStatusCode
allows specifying a custom HTTP status code- The default value is
400
- This property is ignored when versioning by URL segment and
404
will always be used
- The default value is
- A Sunset Policy will always attempt be written when reporting API versions
ASP.NET Web API with OData
- Added support for ad hoc Model Bound Settings
- Add
ODataApiExplorerOptions.AdHocModelBuilder
to add or configure conventions - Examples:
- Add
ASP.NET Core
- Migration from
IProblemDetailsFactory
toIProblemDetails
- Minimal APIs:
- Add group support
- Support adding metadata to groups (e.g.
RouteGroupBuilder
) - Add
ApiVersionSetBuilderFactory
as an injectable delegate - Add
VersionedEndpointRouteBuilderFactory
as an injectable delegate - Examples:
ApiVersioningOptions.UnsupportedApiVersionStatusCode
allows specifying a custom HTTP status code- The default value is
400
- This property is ignored when versioning by URL segment and
404
will always be used
- The default value is
- A Sunset Policy will always attempt be written when reporting API versions
- Added the
IApiVersionMetadataCollationProvider
service
ASP.NET Core with OData
- Added support for ad hoc Model Bound Settings
- Add
ODataApiExplorerOptions.AdHocModelBuilder
which is used in the same way asODataApiVersioningOptions.ModelBuilder
- Examples:
- Add
Fixes
All Platforms
- Fix
StackOverflowException
inAdvertiseApiVersionsAttribute
(#932)
ASP.NET Core
- Use
404
over400
when versioning only by URL segment (#911) - Do not explore unversioned endpoint more than once (#917)
IApiVersioningBuilder.AddMvc
ensures dependent services are registeredIApiVersioningBuilder.AddApiExplorer
ensures dependent services are registered- The
Code
extension inProblemDetails
is correctly written in JSON ascode
- API versions are reported when an endpoint is unmatched (#876, #918)
- This is best effort, but restore behavior for unmatched endpoints prior to 6.0
- Honor the name provided in
NewVersionedApi
when usedWithOpenApi
(#920) - Refactor API version metadata collation (#922)
- Fix regression from custom group names (#923)
ASP.NET Core with OData
- Provide workaround for OData/AspNetCoreOData/#753
Breaking Changes
This is a summary of all breaking changes from the first previews to the final release.
ASP.NET Web API
DefaultApiVersionReporter
constructor addedISunsetPolicyManager
ASP.NET Core
- As previously announced, .NET Core 3.1 has been dropped and is end of life
ProblemDetails
implementationIProblemDetailsFactory
has been removed and is supplanted by the built-inIProblemDetailsService
AddProblemDetails()
must be called to addProblemDetails
, which may result in a behavioral change
- Minimal APIs:
- Since RC 1:
MapApiGroup
is nowNewVersionedApi
(ASP.NET team recommendation)
- Since 6.0:
IVersionedEndpointConventionBuilder
has been removedVersionedEndpointConventionBuilder
has been removedDefaultApiVersionSetBuilderFactory
has been replaced by theApiVersionSetBuilderFactory
delegateIVersionedEndpointConventionBuilder.WithApiVersionSet
now has the signatureTBuilder WithApiVersionSet<TBuilder>(TBuilder, ApiVersionSet) where TBuilder : notnull, IEndpointConventionBuilder
- Since RC 1:
- The following constructors were updated with
IEnumerable<IApiVersionMetadataCollationProvider>
:ApiVersionMatcherPolicy
DefaultApiVersionDescriptionProvider
GroupedApiVersionDescriptionProvider
DefaultApiVersionReporter
constructor addedISunsetPolicyManager
ApiExplorerOptionsFactory<T>
was changed to:- Inherit from
OptionsFactory<T>
- Remove
Setups
property - Remove
PostConfigures
property
- Inherit from
Contributors
Thanks you to all that contributed directly with code, filing issues, and in-depth discussions. In particular, special thanks to:
- @captainsafia, @halter73, @davidfowl for collaborating on Minimal API grouping
- @SamGuoMsft (#928)
- @marmoso (#932, #936)
- @gimlichael (#887)
- @bordecal (#876)