7.0.0

[commonsensesoftware]

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.EntitySet<Book>( "Books" ).EntityType.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
• 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:
    • Partial OData Example

ASP.NET Core

• Migration from IProblemDetailsFactory to IProblemDetails
• 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:
    • Minimal API Example
    • Minimal OpenAPI Example
• 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
• 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 as ODataApiVersioningOptions.ModelBuilder
  • Examples:
    • Partial OData Example

Fixes

All Platforms

• Fix StackOverflowException in AdvertiseApiVersionsAttribute (AdvertiseApiVersionsAttribute causes stackoverflow when enumarated #932)

ASP.NET Core

• Use 404 over 400 when versioning only by URL segment ([OData] /odata/v1/orders() gives 400 Bad Request "Unspecified API version" #911)
• Do not explore unversioned endpoint more than once (Migration from Microsoft.AspNetCore.Mvc.Versioning to Asp.Versioning.Mvc causes versioning to no longer work #917)
• IApiVersioningBuilder.AddMvc ensures dependent services are registered
• IApiVersioningBuilder.AddApiExplorer ensures dependent services are registered
• The Code extension in ProblemDetails is correctly written in JSON as code
• API versions are reported when an endpoint is unmatched (Incomplete response when incorrect version requested #876, Requests with unsupported version don't return 4xx error code #918)
  • This is best effort, but restore behavior for unmatched endpoints prior to 6.0
• Honor the name provided in NewVersionedApi when used WithOpenApi (New WithOpenApi() methods breaks ASP.NET API Versioning #920)
• Refactor API version metadata collation (Injecting ApiVersion as a parameter in a controller action method. #922)
• Fix regression from custom group names (Invalid ApiDescription GroupName in DocInclusionPredicate since 6.2.0 #923)

ASP.NET Core with OData

• Provide workaround for OData/AspNetCoreOData/ApiVersionLinkGenerator methods that don't take HttpContext argument don't generate links #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 added ISunsetPolicyManager

ASP.NET Core

• As previously announced, .NET Core 3.1 has been dropped and is end of life
• ProblemDetails implementation
  • IProblemDetailsFactory has been removed and is supplanted by the built-in IProblemDetailsService
  • AddProblemDetails() must be called to add ProblemDetails, which may result in a behavioral change
• Minimal APIs:
  • Since RC 1:
    • MapApiGroup is now NewVersionedApi (ASP.NET team recommendation)
  • Since 6.0:
    • IVersionedEndpointConventionBuilder has been removed
    • VersionedEndpointConventionBuilder has been removed
    • DefaultApiVersionSetBuilderFactory has been replaced by the ApiVersionSetBuilderFactory delegate
    • IVersionedEndpointConventionBuilder.WithApiVersionSet now has the signature TBuilder WithApiVersionSet<TBuilder>(TBuilder, ApiVersionSet) where TBuilder : notnull, IEndpointConventionBuilder
• The following constructors were updated with IEnumerable<IApiVersionMetadataCollationProvider>:
  • ApiVersionMatcherPolicy
  • DefaultApiVersionDescriptionProvider
  • GroupedApiVersionDescriptionProvider
• DefaultApiVersionReporter constructor added ISunsetPolicyManager
• ApiExplorerOptionsFactory<T> was changed to:
  • Inherit from OptionsFactory<T>
  • Remove Setups property
  • Remove PostConfigures property

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 (How to use AllowedFilterProperties and AllowedExpandProperties under ODataQueryOptionDescriptionContext #928)
• @marmoso (AdvertiseApiVersionsAttribute causes stackoverflow when enumarated #932, AssumeCulture en-us for month formatting test #932 #936)
• @gimlichael (MediaTypeApiVersionReader to skip application/signed-exchange #887)
• @bordecal (Incomplete response when incorrect version requested #876)

---

This discussion was created from the release 7.0.0.