6.1.0

This is a minor release which contains mostly fixes and a few minor enhancements. The next phase in the roadmap will be supporting .NET 7.0.

.NET Core 3.1 will be End of Life in December of 2022; therefore, support for that target framework will be dropped in the next major release.

Features

All Platforms

• ApiVersion now has a protected copy constructor
• Support custom reporting HTTP headers (#875)

ASP.NET Web API with OData

• Update OData query option exploration (#702, #853)

ASP.NET Core

• ApiVersion can be bound in Minimal APIs using the new EnableApiVersionBinding() extension method for IApiVersioningBuilder
• Fix matching precedence of overlapping endpoint templates (#884)

ASP.NET Core with OData

• Support batching (#720, #847)
• Update OData query option exploration (#702, #853)

Client Extensions

• Support reading custom HTTP headers (#875)

Breaking Changes

No known breaking changes

6.0.0

This is the official 6.0.0 release with support for .NET 6.0 and OData 8.0.

📣 Note that the new package names are Asp.Versioning.*. For more background, see the announcement and roadmap.

Features

No significant new features from the previous pre-releases.

Fixes

ASP.NET Web API with OData

• Support cast routing convention (#738)
• Use assembly-qualified type names for EDM type resolution (#854)

ASP.NET Core

• Clone IsDefaultResponse for API Explorer (#823)
• Provide workaround for ASP.NET Core bug dotnet/aspnetcore#41773 (#830)
• Avoid NullReferenceException when reporting API version for non 2xx (#837)
• Skip collation of actions without versioning metadata (#839)

ASP.NET Core with OData

• Support cast routing convention (#738)
• Revert to 8.0.2 as baseline OData version (#836)
• Fix normalization of OData endpoint metadata (#850)
• Use assembly-qualified type names for EDM type resolution (#854)

Breaking Changes

No known breaking changes

Contributors

Big thank you to the community for helping burn-in the pre-releases, sharing your thoughts, and reporting issues, but especially:

• @icnocop - fixed #738
• @ChrisSfanos - whiteglove service onboarding to .NET Foundation
• @clairernovotny - removing roadblocks in packaging and publishing

5.1.0

This represents the official release for ASP.NET Core with support for .NET 5.0 and .NET 6.0.

📣 Aside from servicing, 5.1.x marks the end of the packages and naming under the Microsoft.AspNet* prefixes. For more background, see the announcement and roadmap. Despite months of communicate with Microsoft and the .NET Foundation to re-enable publishing permissions for the NuGet packages, I'm still unable to. At this point, I suspect it may never happen and this release contains the official, signed packages which you can integrate into your own NuGet feeds.

This release has been a long time coming, but has been stymied due to administrative changes in moving the project under the .NET Foundation. Now that the process is complete, you can expect fluid releases once more. The following highlights high-level changes since 5.0.0. For the complete list, please review the change log.

Features

No significant new features in this release

Fixes

All Platforms

• Fix deprecated API version aggregation (#719)
• Fix API version parsing from namespace (#805)

ASP.NET Web API

• Avoid LockRecursionException (#703)

ASP.NET Web API with OData

• Fix route template building optimizations (#689, #710)
• Correct binding source for [FromODataUri] (#693, #729, #737)
• Disambiguate OData actions by parameters (#697)
• Support cast routing convention (#738)
• Handle PostTo navigation properties (#742)
• Fix all functions versus all function (#758)
• Use assembly-qualified type names for EDM type resolution (#854)

ASP.NET Core

• Handle on-demand initialization of IApiVersioningFeature (#704)
• Clear IApiVersioningFeature on pipeline reentry (#748, #749)
• Limit Allow for 405 to actions in the same API version (#795)
• Handle candidates that differ by route constraint only (#797)

ASP.NET Core with OData

• Fix route template building optimizations (#689, #710)
• Correct binding source for [FromODataUri] (#693, #729, #737)
• Handle DI service registration order (#694)
• Copy endpoint metadata (#695)
• Disambiguate OData actions by parameters (#697)
• Support cast routing convention (#738)
• Handle PostTo navigation properties (#742)
• IEdmModelSelector leverages IApiVersionSelector (#745)
• Fix all functions versus all function (#758)
• Use assembly-qualified type names for EDM type resolution (#854)

Enhancements

All Platforms

• Added IControllerNameConvention (#734)
• Do not discover API versions which are only mapped (#735)
• Update build status badge (#775)

ASP.NET Web API

• Minor optimization to IUrlFactory implementation (#720)

ASP.NET Core

• Report API versions for ambiguous request in legacy routing
• Add support for .NET 6.0

Breaking Changes

No known breaking changes

Additional Release Notes

ASP.NET Core with OData

• The official OData release is now 8.x, but due to the required changes this release targets 7.x with .NET Core 3.1
• The 6.0 support for OData has been rebuilt from the ground up and supports 8.x along with .NET Core 3.1 and .NET 6.0

Contributors

Big thank you to the community for contributing:

• @xavierjohn - new examples
• @aleks-ivanov - fix/improve build and code analysis
• @GrayPockets - Allow ICollectionModelBinder as registered parameters
• @icnocop - fixed #738

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.

6.0.0 Preview 2

This is a quick iteration to Preview 2 with a few key fixes and enhancements.

Enhancements

All Platforms

• Added ApiExplorerOptions.RouteConstraintName (useful for resolving API parameters by constraint)

ASP.NET Core

• Added DescribeApiVersions extension method which can be used by WebApplication
  • This is functionally equivalent to IApiVersionDescriptionProvider
  • The implementation uses the DefaultApiVersionDescriptionProvider
• DefaultApiVersionDescriptionProvider now uses EndpointDataSource instead of IActionDescriptorCollectionProvider
• ApiVersionMetadata.Name will be used for controller token in ActionDescriptor for Minimal APIs, if specified
  • For Minimal APIs, this is typically provided via app.DefineApi(name: "My API")
• Added feature parity with OpenApiRouteHandlerExtensions such as Accepts, Produces, etc
  • Note: This might change in the future. See dotnet/aspnetcore#39604
• Added OpenAPI example with API Versioning, Minimal APIs, and Swashbuckle

Fixes

ASP.NET Core

• Support API Explorer extensions for Minimal APIs (#812)

6.0.0 Preview 1

This is the first preview release, which includes support for .NET 6.0. Be sure to follow the announcement for more background and the roadmap for in-depth review of the release.

The wiki has not been updated, but it's a work in progress. While the wiki has been useful and informative, it is reaching the limits of what is possible. Consideration is being made to lift the current wiki into a fully-fledged documentation website. All of the examples have been updated and include new examples such as Minimal APIs. This is currently the best place to start and review how things have changed.

Features

• Sunset Policies (RFC 8594)
• Web Linking (RFC 8288)
• API version-aware HTTP clients
  • ex: services.AddHttpClient("test").AddApiVersion(1.0)
  • If the server reports API versions, the use of deprecated API versions and their sunset polices are passed to ILogger

ASP.NET Core

• Support .NET 6.0 (LTS)
• Support Minimal APIs
• Support OData 8.0 (finally! 🎉)

Enhancements

All Platforms

• Performance (ex: more Span<T>, no Regex, fewer allocations, etc)
• ApiVersion and related attributes now allows double (ex: new ApiVersion(1.0), [ApiVersion(1.0)])
• ApiVersion.Status now allows . (ex: 2.0-beta.1, 2022-04-01-preview.1)
• ApiVersion.Parse is supplanted by IApiVersionParser via ApiVersionParser.Default
  • This now makes end-to-end customization of ApiVersion possible (ex: you can add, parse, and format a patch or revision version component if you really want it)
• All errors now use Problem Details (RFC 7807)
• 404, 405, and 415 are now properly returned in accordance with configured versioning methods without requiring additional configuration or customization
• Namespace-to-API Version parsing has been lifted out into NamespaceParser
  • You can extend/customize the behavior or simply use NamespaceParser.Default for the same old out-of-the-box implementation

.NET 6.0

• ApiVersion supports ISpanFormattable

ASP.NET Web API

• .NET Framework 4.5 is still supported, but .NET Framework 4.7.2 is added as a target for performance benefits when supported
• UrlHelper.WithoutApiVersion() extension (useful when generating links from versioned to version-neutral routes)

ASP.NET Core

• IUrlHelper.WithoutApiVersion() extension (useful when generating links from versioned to version-neutral endpoints)

Fixes

All of the open issues that could be fixed, have been fixed in this release. These will listed in the forthcoming 5.1 release, but it includes 65+ issues. I will accept reported issues and backport them to 5.1 if they are applicable.

Breaking Changes

This release is essentially a reset and rewrite so many things will be broken from 5.x. The most obvious issues will be new packages. Here is the mapping of old packages to new packages:

Old Package ID	New Package ID
	Asp.Versioning.Abstractions
Microsoft.AspNet.OData.Versioning	Asp.Versioning.WebApi.OData
Microsoft.AspNet.OData.Versioning.ApiExplorer	Asp.Versioning.WebApi.OData.ApiExplorer
Microsoft.AspNet.WebApi.Versioning	Asp.Versioning.WebApi
Microsoft.AspNet.WebApi.Versioning.ApiExplorer	Asp.Versioning.WebApi.ApiExplorer
	Asp.Versioning.Http
	Asp.Versioning.Http.Client
Microsoft.AspNetCore.Mvc.Versioning	Asp.Versioning.Mvc
Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer	Asp.Versioning.Mvc.ApiExplorer
Microsoft.AspNetCore.OData.Versioning	Asp.Versioning.OData
Microsoft.AspNetCore.OData.Versioning.ApiExplorer	Asp.Versioning.OData.ApiExplorer

The second obvious big change will be different namespaces. All previous Microsoft.* namespaces are now Asp.Versioning.*. If you are a library author that targets multiple platforms, this should make things easier going forward; it certainly made it easier in the project itself. Extension methods continue to use the same namespace as the type they correspond to.

Significant individual changes:

• IApiVersionReader.Read now returns IReadOnlyList<string> instead of string?
  • Solves the problem of multiple values for a single key (ex: query string or header)
  • Simplifies reader composition (which naturally may have multiple values)
  • Makes reading duplicate values non-exceptional, which is also valuable in error reporting
• IReportApiVersions.Report now accepts the entire response instead of just headers
• IErrorResponseProvider no longer exists; it is supplanted by IProblemDetailsFactory and Problem Details (RFC 7807)
• The following old extension methods were moved to the new ApiVersionMetadata type:
  • GetApiVersionModel(ApiVersionMapping) → GetApiVersionMetadata()
  • GetApiVersionModel() → ApiVersionMetadata.Map(ApiVersionMapping.Explicit)
  • MappingTo(ApiVersion) → ApiVersionMetadata.MappingTo(ApiVersion)
  • IsMappedTo(ApiVersion) → ApiVersionMetadata.IsMappedTo(ApiVersion)

Routing behavior has changed to more accurately return 404, 405, or 415 when appropriate. 400 is still returned in known, invalid requests such as an unspecified API version when required.

For ASP.NET Core, the setup is now a fluent interface of chained configuration options:

services.AddApiVersioning()     // Core API Versioning services with support for Minimal APIs
        .AddMvc()               // API versioning extensions for MVC Core
        .AddApiExplorer()       // API version-aware API Explorer extensions
        .AddOData()             // API versioning extensions for OData
        .AddODataApiExplorer(); // API version-aware API Explorer extensions for OData

Future Release

The following are features and enhancements still under consideration before the final release:

• Support OData query options for non-OData controllers
• Alignment to Improve Minimal API Routing with Grouping, which will matter for .NET 7.0

Feedback

I want to hear your feedback. What do you like? What do you not like? I want to give the community a chance to play with the latest bits and provide any final thoughts before committing to the final release. Now would be the time for any other name changes or other significant refactoring that could cause additional disruption going forward.

Administrative

TL;DR

• This project is now officially part of the .NET Foundation (🎉)
• Code signing still isn't setup, which will hold up the official release, including the 5.x patches

5.0.0

This represents the official release for ASP.NET Core with support for .NET 5.0.

Features

No new features in this release

Fixes

No significant fixes in this release

Enhancements

A few enhancements were completed in this release:

All Platforms

• Performance enhancements to IApiVersionReader implementations

ASP.NET Core

• Updated examples with the latest version of Swashbuckle and OpenAPI

Breaking Changes

No known breaking changes

Additional Release Notes

ASP.NET Core with OData

• The official OData release is still 7.x, which only supports .NET Core 3.1
  • This release can be used with it, but doesn't include anything new
• OData 8.x supports .NET 5.0, but is yet another massive overall, which requires additional work
• There are a number of open OData issues which will be address in future patches

Contributors

Big thank you to the community for contributing:

• @paulomorgado suggested and drove a number of performance improvements
• @icnocop fixed some documentation and updated the Swashbuckle examples

4.2.0

This marks the official release of 4.2.0 across the board. Each package version has drifted over time and this release was unable to align all the version numbers again.

For clarity, these are the package version numbers in this release:

Package ID	Package Version
Microsoft.AspNet.OData.Versioning	5.0.0
Microsoft.AspNet.OData.Versioning.ApiExplorer	5.0.0
Microsoft.AspNet.WebApi.Versioning	4.1.0
Microsoft.AspNet.WebApi.Versioning.ApiExplorer	4.1.0
Microsoft.AspNetCore.Mvc.Versioning	4.2.0
Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer	4.2.0
Microsoft.AspNetCore.OData.Versioning	5.0.0
Microsoft.AspNetCore.OData.Versioning.ApiExplorer	5.0.0

There are no additional changes, fixes, or features from the OData 5.0.0 RC 2 release. The release notes from OData 5.0.0 RC 1 and 2 contain the full rollup of release notes to this point.

Additional Release Notes

• The .NET 5.0 preview will be a separate package and release (e.g. the real 5.0.0 release)
• OData 8.0 is not supported and will not be supported 5.0.0; there are breaking changes introduced by OData which will require another major version change

OData 5.0.0 RC 2

Minor fixes to wrap up 5.0.0-RC.2.

Fixes

The following are fixes and patches since 5.0.0-RC.1:

ASP.NET Web API

• Handle model bound API version in route template (#671)

ASP.NET Web API with OData

• Fix lookup of EDM model (#675)

ASP.NET Core

• Handled unregistered IUrlHelperFactory (#673)
• Support API Version in LinkGenerator
• Remove check for dynamic endpoints (#678)

ASP.NET Core with OData

• Map OData-specific route name property (#670)
• Fix lookup of EDM model (#675)
• Support API Version in LinkGenerator

OData 5.0.0 RC 1

This marks the initial release of 5.0. The versioning scheme across library versions has drifted over time. The major version bump is required for OData support, but all other libraries and their versions are expected to realign in the .NET 5.0 time frame.

While there is a myriad of fixes and feature changes, this release is heavily focused on OData support. The long-requested Endpoint Routing support is now available. That work led to a complete overhaul of the versioning infrastructure used for OData, resulting in a simpler
implementation and removes several internal workarounds.

Due to the amount of changes, this release will start with a pre-release to afford some burn-in time. Once there has been a chance to exercise things with real workloads, it will be promoted to an official release. Expect this release to have the same level of quality as official releases.

Features

The following are new features and/or enhancements since 4.1:

All Platforms

• Support API Version in URL Generation (#663)

ASP.NET Web API

• HttpControllerDescriptorExtensions.AsEnumerable is now public

ASP.NET Web API with OData

• Add IEdmModelSelector interface
• Overhaul route registration
• Add RoutePrefix extension method for ApiDescription

ASP.NET Core

• Default error response provider should return errors in ProblemDetails format (#612)

ASP.NET Core with OData

• Add IEdmModelSelector interface
• Overhaul route registration
• Add RoutePrefix extension method for ApiDescription
• Support Endpoint Routing (#608, #616, #647)
• Update all examples to use Endpoint Routing
• Add new examples on par with ASP.NET Web API examples

Fixes

The following are fixes and patches since 4.1.0:

All Platforms

• Unable to add versioning NuGet package (#587, #637)

ASP.NET Web API

• CORS preflight request with URL Path versioning results in ArgumentNullException (#619)

ASP.NET Web API with OData

• CreateRef and DeleteRef Issue (#573)
• Support OData $select for PUT/PATCH/POST (#594)
• Issue with OData Singleton entity controller actions (#610)
• Multiple Route Prefixes for a single API Version (#628)
• NullReferenceException exploring API by URL segment

ASP.NET Core

• ApiVersionMatcherPolicy doesn't check candidate validity (#600, #658)

ASP.NET Core with OData

• Net core odata with versioning and template in url prefix (#529)
• Startup.cs in another assembly causes OData to return 404 (#551)
• Error: "Cannot find the services container for route" when using MapVersionedODataRoute (#553)
• Action parameter gets defined twice when using multiple odata routes (#555)
• CreateRef and DeleteRef Issue (#573)
• Support OData $select for PUT/PATCH/POST (#594)
• ODataQueryOptions parameter on method generates over 1600 parameters in Swagger UI (#599)
• Issue with OData Singleton entity controller actions (#610)
• Multiple Route Prefixes for a single API Version (#628)
• Using MapDynamicControllerRoute("{**path}") throws NullReferenceException (#658)
• NullReferenceException exploring API by URL segment

Breaking Changes

The following outlines the breaking changes.

ASP.NET Core

• IRouter legacy routing returns 405 versus 400 for unmatched candidate, filtered by route constraint

  • This was previously undetected in the test suite
  • The last implementation produced the correct response for this scenario, but with the wrong response for others
  • Only the status code is different; the payload is the same
  • Endpoint Routing is not affected

  Workaround: This scenario is only expected to occur when routes differ by route constraint alone. For example, api/values/{id}?api-version=1.0 versus api/values/{id:int}?api-version=2.0. To retain
  the previous and expected functionality, remove the :int route constraint and perform the validation in the controller action instead.

ASP.NET Web API with OData

• VersionedAttributeRoutingConvention.ApiVersion has been removed
• Removed MapVersionedODataRoutes; only MapVersionedODataRoute is now required
• Removed ODataApiVersionRequestProperties
• Removed VersionedODataPathRouteConstraint
• IModelConfiguration.Apply has new routePrefix parameter

ASP.NET Core with OData

• VersionedAttributeRoutingConvention.ApiVersion has been removed
• Removed MapVersionedODataRoutes; only MapVersionedODataRoute is now required
• Removed IODataVersioningFeature
• Removed VersionedODataPathRouteConstraint
• IModelConfiguration.Apply has new routePrefix parameter