NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
NuGet, #226 most downloaded on NuGet
A service API versioning library for Microsoft ASP.NET Core.
Latest stable
5.1.0
Last release 4 years ago
no release in 18 months
Ships unpredictably
gaps range from 1 weeks to 2.3 years
Most releases are documented
notes for 16 of 25 stable releases
3 versions withdrawn
withdrawn after publishing
127 years old
39 releases · first in 1900
Drag across the ruler to compare, or tap a release to open it.
Fix deprecated API version aggregation
This represents the official release for ASP.NET Core with support for .NET 5.0 and .NET 6.0.
:mega: Aside from servicing,
5.1.xmarks the end of the packages and naming under theMicrosoft.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.
No significant new features in this release
LockRecursionException (#703)[FromODataUri] (#693, #729, #737)PostTo navigation properties (#742)all function (#758)IApiVersioningFeature (#704)IApiVersioningFeature on pipeline reentry (#748, #749)Allow for 405 to actions in the same API version (#795)[FromODataUri] (#693, #729, #737)PostTo navigation properties (#742)IEdmModelSelector leverages IApiVersionSelector (#745)all function (#758)IControllerNameConvention (#734)IUrlFactory implementation (#720)No known breaking changes
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.0Big thank you to the community for contributing:
Your coding agent can read these notes before it upgrades. Set up the MCP server →
This represents the official release for ASP.NET Core with support for .NET 5.0.
This represents the official release for ASP.NET Core with support for .NET 5.0.
No new features in this release
No significant fixes in this release
A few enhancements were completed in this release:
No known breaking changes
Big thank you to the community for contributing:
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 ch…
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.
Drop support for .NET Core 2.2
Drop support for .NET Core 2.2
Add support for .NET Core 3.1
Add support for .NET Core 3.1
4.1.0 is a small release with no functional changes. The key change is targeting .NET Core 3.1 for all flavors of ASP.NET Core, specifically OData, and dropping support for ASP.NET Core 2.2.
Refactor conventions API; interfaces are defined end-to-end (see _Breaking Changes_)
This marks the official release of 4.0. All of the prerelease and previous version features, as well as any fixes, roll up into this release.
The following are new features and/or enhancements since 3.1.0:
$ref (#494)$ref (#494)The following are fixes and patches since 3.1.0:
There are no additional breaking changes since the preview release. Review the preview release for additional details.
The following are known issues in this release:
services.AddMvc( options => options.EnableEndpointRouting = false );Special thanks to the support and contributions from the community:
Update Authenticode signature to use SHA256
Update Authenticode signature to use SHA256
Fix resolution of media type parameter name
Fix resolution of media type parameter name (#528)
Ensure implicitly versioned ActionModel has associated ControllerModel
Ensure implicitly versioned ActionModel has associated ControllerModel (#519)
Add API version parameter to Content-Type
Add API version parameter to Content-Type (#484)
Nothing published for this version
Nothing published for this version
The following a behavioral breaking changes.
This is a minor release that primarily supports the Endpoint Routing feature introduced in ASP.NET Core 2.2.
This release will require you to upgrade to ASP.NET Core 2.2 if you haven't already
The following are new features since 3.0.0:
[ApiController]interface IApiControllerSpecification
{
bool IsSatisfiedBy( ControllerModel controller );
}
The following are fixes and patches since 3.0.0:
POST when the controller action is not an EDM actionPOST when the controller action is not an EDM actionThe following a behavioral breaking changes.
ApiVersioningOptions.UseApiBehavior is now true by default
[ApiController] has not been applied[ApiController] cannot be appliedApiVersioningOptions.UseApiBehavior = false[ApiController]services.TryAddEnumerable(ServiceDescriptor.Transient<IApiControllerSpecification, MyApiControllerSpec>());public class MyApiControllerSpec : IApiControllerSpecification
{
// consider all controllers that inherit from Controller to be a UI controller
readonly Type UIControllerType = typeof( Controller ).GetTypeInfo();
public bool IsSatisfiedBy( ControllerModel controller ) =>
!UIControllerType.IsAssignableFrom( controller.ControllerType )
}
Figure 1: Sample custom API specification
The following are known issues in this release:
services.AddMvc( options => options.EnableEndpointRouting = false );Nothing published for this version
This marks the official release of 3.0. All of the Beta features and fixes roll up into this release. The delta from Beta 2 is primarily fixes and enh
This marks the official release of 3.0. All of the Beta features and fixes roll up into this release. The delta from Beta 2 is primarily fixes and enhancements.
The following are new features since 3.0.0 Beta 2:
The following are fixes and patches since 3.0.0 Beta 2:
[ApiExplorerSettings(IgnoreApi = false)] (#405)If you have cloned or forked this repository, the setups in the acceptance test suite have been refactored to maximize test server reuse. You can expect a 5-10x performance improvement in overall test run times.
The future roadmap currently only includes minor updates for ASP.NET Core. The 3.1 release will include support for the new Endpoint Routing feature in ASP.NET Core 2.2. For the first time, API Versioning will require the minimum version of ASP.NET Core to be 2.2 or above. The legacy method of routing will continue to be supported, but Endpoint Routing will be the new default and preferred method of routing.
Breaking changes are always carefully considered. In designing some of the new features, it became clear that a few breaking changes were required. Gi…
The Beta 2 release marks a key milestone, which includes an array of fixes as well as new features you've been asking for. This release is expected to mark 3.0 as feature complete. Any further changes from now to the official release are only expected to include additional bug fixes or performance enhancements.
The following are new features or enhancements since 3.0.0 Beta 1:
The following are fixes and patches since 3.0.0 Beta 1:
IsApiVersionNeutral() convention does not make an API version-neutral (#322)Breaking changes are always carefully considered. In designing some of the new features, it became clear that a few breaking changes were required. Given 3.0 is a major release, now was the appropriate time to introduce these changes. For most users, the changes will be transparent. The differences are most visible to those that are using the customization and extension features.
The following are breaking changes since 2.3.0 and 3.0.0 Beta 1:
The IApiVersionProvider now has the signature:
public interface IApiVersionProvider
{
ApiVersionProviderOptions Options { get; }
IReadOnlyList<ApiVersion> Versions { get; }
}
Where the options are:
[Flags]
public enum ApiVersionProviderOptions
{
None,
Deprecated = 1,
Advertised = 2,
Mapped = 4,
}
The new Mapped option disambiguates a declared API version from an API version mapped to a declaration.
The new MappingTo(ApiVersion) extension method determines whether an API is mapped and if it is explicit or implicit. The IsMappedTo(ApiVersion) extension method is now available on all platforms.
The ApiVersionModel constructors have been reduced to forms that have no dependencies or assumptions on collecting information from attributes.
GetApiVersionModel extension methodSpecial thanks to the support and contributions from the community:
The following are breaking changes since 2.3.0:
This the next major iteration of API versioning for all platforms. NuGet package distribution will begin with a Beta release will provide an opportunity to play with new features, provide feedback, and let things burn in before releasing for general availability.
The most significant new feature is support for the highly anticipated and demanded ASP.NET Core with OData implementation. It will take some time to update all of the documentation on the wiki, but in the meantime there are example projects that illustrate how to configure your application.
The following are new features or enhancements since 2.3.0:
IApiVersionConvention<T> (Issue #278)IControllerConvention (Issue #278)IControllerConventionBuilder (Issue #278)VersionByNamespaceConvention (Issue #278)IApiVersioningFeature (Issue #280)AddVersionedApiExplorer now calls the built-in AddApiExplorer implicitlyUseApiVersioning (advanced scenario to control middleware registration)ApiVersioningOptions.RegisterMiddleware option, which defaults to true
false can be paired with UseApiVersioning for advance middleware scenariosThe following are breaking changes since 2.3.0:
ApiVersionConventionBuilder.ControllerConventions is now ApiVersionConventionBuilder.ControllerConventionBuilders
ApiVersionConventionBuilder.ControllerConventions now refers to a collection of the new IControllerConvention interfaceApiVersionRequestProperties.RawApiVersion was renamed to ApiVersionRequestProperties.RawRequestedApiVersion (for parity with ASP.NET Core feature)ApiVersionRequestProperties.ApiVersion was renamed to ApiVersionRequestProperties.RequestedApiVersion (for parity with ASP.NET Core feature)System.Web.OData namespace were updated to Microsoft.AspNet.OData (also has parity with OData 7.0 and ASP.NET Core)VersionedODataModelBuilder.ModelBuilderFactory now uses new ODataConventionModelBuilder().EnableLowerCamelCase() by defaultAddVersionedApiExplorer is now a IServiceCollection extension method instead of a IMvcCoreBuilder extension methodAddApiVersioning no longer implicitly calls AddMvcCore (it doesn't have an actual dependency on it)IApiVersionRoutePolicy no longer implements IRouter; the old RouteAsync method is now Evaluate(RouteContext, ActionSelectionResult)ApiVersionConvention has been removed and replaced by ApiVersionCollator (Issue #301)The 2.3.0 release is a roll-up release that contains a number of fixes and minor enhancements. This is the official demarcation line before the transi
The 2.3.0 release is a roll-up release that contains a number of fixes and minor enhancements. This is the official demarcation line before the transition to the forthcoming 3.0.0 release.
The following are fixes and patches from 2.0.0 - 2.3.0:
ApiVersion.GetHashCode() (Issue #229)The following are minor features and enhancements from 2.0.0 - 2.3.0:
Nothing published for this version
Nothing published for this version
This is another minor release with respect to changes, but includes the much anticipated and highly demanded support for ASP.NET Core 2.0. There are n
This is another minor release with respect to changes, but includes the much anticipated and highly demanded support for ASP.NET Core 2.0. There are no visible API or behavioral changes in this release.
The following are fixes addressed in the current release:
The following are new or updated features in the current release:
Nothing published for this version
Nothing published for this version
The following are breaking changes in the current release
This is quick, minor release, but with a significant reversion. The 1.1.0 release required ASP.NET Core users to add app.UseApiVersioning(); to their startup configurations. This was really easy to miss and a hung a lot of people up. Unfortunately, that was a required change to fix issues in 1.0.0 for some users and I had yet to find a good way to handle the scenario or fail explicitly when the configuration was missing by the time of release.
I'm happy to report for ASP.NET Core users that I've found a way to inject the behavior required by app.UseApiVersioning(); without actually making you call it. Apologies to early 1.1.x adopters who went through the pain of discovering this was needed, adding it, and now having to remove it. Ultimately, I feel this is the best decision for all users long term. Since current adoption of 1.1.x is only around 1% of 1.0.x, most people who upgrade will never see or deal with the related issues. I have subsequently updated all wiki topics and unlisted the 1.1.x NuGet packages so that users that upgrade will never encounter these issues.
The following are fixes addressed in the current release
The following are breaking changes in the current release
Nothing published for this version
Nothing published for this version
Beyond that, there are no new breaking changes from the previous beta and release candidate releases; however, for ASP.NET Core, do not forget the new…
The wait is over. The official v1.1.0 packages have been released! It has taken a number of months to get all of API Explorer work you asked for, while swatting down bugs and knocking out other little features. Most of the release candidate period involved stabilization and burn-in. Many of you contributed time, blood, and sweat to help test, verify, and reproduce issues. Thank you!
All of the previous release notes apply with the following additional, final changes.
This feature will ultimately enable full Swashbuckle/Swagger integration without using any custom IOperationFilter implementations. Today, the current Swashbuckle implementations do not leverage all of the API explorer information that they could, which is critical for fully documenting the API version parameter information on your behalf. There are open pull requests for all flavors of Swashbuckle to use all of the available metadata. Once that happens, you'll only need to update your Swashbuckle package references, enable Swagger, and the API version parameters will be fully documented for you. In the meantime, you use the simple SwaggerDefaultValues operation filter to bridge the gap. You can see the end-to-end solution in the examples for your flavor of ASP.NET.
Beyond that, there are no new breaking changes from the previous beta and release candidate releases; however, for ASP.NET Core, do not forget the new configuration setup requirement:
public void Configure( IApplicationBuilder app, IHostingEnvironment env )
{
app.UseMvc();
app.UseApiVersioning();
}
Nothing published for this version
Nothing published for this version
> Breaking changes between official releases are carefully considered, but sometimes necessary. After careful
At long last, this is the release candidate for 1.1. I hadn't planned any new features, but based on feedback and bugs, a couple of features made it in. This release is expected to have 100% parity with the official 1.1 release. The purpose of the release candidate is only meant to publish a build that the community can use to verify all of the related bug fixes have indeed been resolved and there are no additional regressions.
Important Release Notes for ASP.NET Core
Breaking changes between official releases are carefully considered, but sometimes necessary. After careful consideration and consultation with the ASP.NET team, a behavioral breaking change is required in API versioning for ASP.NET Core. This is the result of multiple factors in the current routing infrastructure and API versioning implementation. The consequences cause the API versioning extensions to incorrectly return HTTP status code 400 or 404 in some cases. Great care was given to limit the external side effects, but all applications will now be required to add the following to their application configurations:
public void Configure( IApplicationBuilder app, IHostingEnvironment env )
{
app.UseMvc();
app.UseApiVersioning();
}
This is required to make sure that intrinsic features like route constraints continue work once API versioning is enabled. To ensure that attribute-based and convention-based routing work as expected, the call to UseApiVersioning() should always occur after UseMvc().
Sometime in the ASP.NET Core 2.0+ timeline, I'll be working with the ASP.NET team to improve this experience and hopefully remove this requirement in the API versioning 2.0 support.
Beta 2 is here and it includes a few big ticket items that you've been asking for. The direction of the roadmap is to let this iteration burn-in a lit
Beta 2 is here and it includes a few big ticket items that you've been asking for. The direction of the roadmap is to let this iteration burn-in a little (say - a couple of weeks) and then everything will be promoted to the official release. That should provide ample time for any remaining feedback or issues to be reported. No additional feature development is planned for this release.
If you are an author of extensions and/or other low-level customizations, pay special attention the breaking changes that are being introduced.
It's hard to believe that it's been six months since the official 1.0 release, but here we are. I'd like to thank the community for all your contributions, comments, questions, and feedback to help make this project a success. This release will mark the first significant set of roll-up changes since 1.0. This release is primarily made up of fixes, but there are a couple of new features as well; specifically, there is now out-of-the-box support for API versioning using media type negotiation as many have asked for. Keep an eye out for the updated documentation on the wiki soon. If you are an author of extensions and/or other low-level customizations, pay special attention the breaking changes that are being introduced.
There have been a bunch of small, incremental fixes up to this point which did not mark an overall release. The following summarizes all of the fixes since 1.0, including the most recent fixes that have not previously been published in any package.
While I strive to never have breaking changes, at times they are inevitable. Careful consideration is made to limit when break changes are introduced to reduce the amount of impact. The following lists the set of surface area changes that may result in a breaking change. The vast majority of the changes are related to extensions and customizations. If those scenarios do not apply to you, then you'll very likely be unaffected.
bool instead of voidstatic class instead of an abstract classpublic static Combine method to promote IApiVersionReader composition rather than inheritanceApiVersionReader.Combine( new QueryStringApiVersionReader(), new HeaderApiVersionReader( "api-version" ) )ApiVersioningProperties().RawApiVersionApiVersioningProperties().ApiVersionIErrorResponseProvider.BadRequestApiVersioningOptions.CreateBadRequest and replaced it with ApiVersioningOptions.ErrorResponses.BadRequestNothing published for this version
Nothing published for this version
Nothing published for this version
API versions can be expressed using conventions
This release has only minor enhancements and fixes in preparation for the official 1.0 release.
This release has only minor enhancements and fixes in preparation for the official 1.0 release.
Refactored support for the api-supported-versions and api-deprecated-versions HTTP headers to return in the multi-value format using a comma-separated…
This release represents the last anticipated set of features and API changes. This release includes a few minor changes, a couple of bug fixes, and a couple of new examples.
Nothing published for this version
One column per quarter.