Which package should be used for versioning API controllers in .NET 7: Microsoft.AspNetCore.Mvc.Versioning or Asp.Versioning.Http?

Question

I am using NET 7 in a project and I have a question about which package to use for versioning API controllers. There are two packages Microsoft.AspNetCore.Mvc.Versioning and Asp.Versioning.Http which one is preferable for ASP.NET Core 7?

The "Microsoft.AspNetCore.Mvc.Versioning" package has version 5.1.0, I believe it is intended for .NET 5, and the "Asp.Versioning.Http" package has version 7.0.0 and it seems that using the second package is more preferable. But the documentation shows that the second package is also used for ASP.NET which confuses me very much, it seems that this package was required for the transition from .NET Framework to .NET Core

Zygote

Answer 1

The package for controller support that you want is:

Asp.Versioning.Mvc

Don't let the name fool you. There is no package that intentionally supports API versioning for the UI stack.

Keep in mind that ASP.NET Web API is a platform, but sometimes people refer to creating web APIs in ASP.NET Core. These are two different things. The platforms are mostly incompatible and, therefore, have separate implementations. ASP.NET Web API is always referring to the legacy platform and ASP.NET Core always refers to the new platform. They are both different iterations of ASP.NET. If there is some specific documentation that you can link to that is confusing, please point it out so that it can be updated.

The following original packages are now deprecated and will only undergo servicing:

Platform	Package	Version	TFM
ASP.NET Web API	Microsoft.AspNet.WebApi.Versioning	<= 5.x.x	net45
ASP.NET Web API	Microsoft.AspNet.WebApi.Versioning.ApiExplorer	<= 5.x.x	net45
ASP.NET Web API	Microsoft.AspNet.OData.Versioning	<= 5.x.x	net45
ASP.NET Web API	Microsoft.AspNet.OData.Versioning.ApiExplorer	<= 5.x.x	net45
ASP.NET Core	Microsoft.AspNetCore.Mvc.Versioning	<= 5.x.x	netcoreapp3.1, net5.0
ASP.NET Core	Microsoft.AspNetCore.Mvc.ApiExplorer	<= 5.x.x	netcoreapp3.1, net5.0
ASP.NET Core	Microsoft.AspNetCore.OData	<= 5.x.x	netcoreapp3.1, net5.0
ASP.NET Core	Microsoft.AspNetCore.OData.ApiExplorer	<= 5.x.x	netcoreapp3.1, net5.0

All new features and platform support will be:

Platform	Package	Version	TFM
All	Asp.Versioning.Abstractions	6.0.0+	net6.0+, netstandard1.0, netstandard2.0
ASP.NET Web API	Asp.Versioning.WebApi	6.0.0+	net45, net472
ASP.NET Web API	Asp.Versioning.WebApi.ApiExplorer	6.0.0+	net45, net472
ASP.NET Web API	Asp.Versioning.WebApi.OData	6.0.0+	net45, net472
ASP.NET Web API	Asp.Versioning.WebApi.OData.ApiExplorer	6.0.0+	net45, net472
ASP.NET Core	Asp.Versioning.Http1	6.0.0+	net6.0+
ASP.NET Core	Asp.Versioning.Mvc2	6.0.0+	net6.0+
ASP.NET Core	Asp.Versioning.Mvc.ApiExplorer3	6.0.0+	net6.0+
ASP.NET Core	Asp.Versioning.OData	6.0.0+	net6.0+
ASP.NET Core	Asp.Versioning.OData.ApiExplorer	6.0.0+	net6.0+
All	Asp.Versioning.Http.Client	6.0.0+	net6.0+, netstandard1.1, netstandard2.0

_[1] Base library that supports Minimal APIs
_[2] MVC Core with controller support
_[3] Supports exploration of Minimal APIs and controllers

Activator

This answer is really, really useful! So much so, it should be in the readme.md here: github.com/dotnet/aspnet-api-versioning – Forensic

Fair. Many people will never come to the repo nor ever read the documentation, but it's not unreasonable to add some of this to the wiki and expand the banner just a bit. I suppose it's about time there is more comprehensive migration/transition wiki page. Thanks for the suggestion. – Activator

The wiki now includes this information in the migration guide: github.com/dotnet/aspnet-api-versioning/wiki/… – Activator