Announcement: Hello Project "Asp"

[commonsensesoftware]

This project started as a thought experiment about how take the ideas behind versioning a service, specifically RESTful
services, and implement them in a practical way. The API versioning principles and concepts weren't really anything new, but
applying them in a generic way had yet to be done. It took about 2 years of development and feedback with several projects at
Microsoft, but eventually a generic pattern and foundling framework emerged. 6 years ago I took that foundation to the
open source community in order to evolve the framework and, honestly, for my own selfish use for service projects outside
of Microsoft. It was beyond my wildest imagination that the project would be noticed or become as popular as it has.

The decision to release the project under the Microsoft organization on GitHub was primarily to follow company open source
policy. Despite the common misconception, I am not, nor have ever been, a part of the ASP.NET team. I have established a
report with various team members over the years which I continue to maintain, but nothing more ever came of it. This project
has never had any type of official company sponsorship or funding. Although there been a few external contributions and
design collaborations, I've mostly run this project as a one-man army.

2021 came with a bunch of changes and after 14 years, I decided to leave Microsoft. As the solitary steward of the project,
that left the state of affairs a in predicament. While I attempted to usher a smooth transition of the project and keep it
afloat, there were a number of challenges in doing so. It took several months, but it was ultimately decided that the best
course of action was to move the project out of the Microsoft organization and into the .NET Foundation. Look for this
formal announcement in the .NET Foundation news soon.

This is all well and good. You may have noticed that the repo is already under the .NET Foundation organization, even
though it isn't listed as a project. A couple of other issues have arisen. First and foremost, the project name
and NuGet packages all indicate that they are owned or managed by Microsoft. Since I was the team and there is no longer
any official Microsoft oversight, that has to change. I thought about just forking the repo and starting anew, but I came
to the conclusion that it would be too confusing for the community that has been built. Hence forth, the project will be known
as "Asp", but still retain the ASP.NET API Versioning nomenclature.

The second issue is the NuGet package identifiers. It was suggested that I just send out an advisory that the identifiers
would change and leave them behind. After 100 million downloads, I found that to be an unacceptable answer. It took many months
to track down the appropriate NuGet stakeholders to begin the process, but the package identifiers have now been transferred
to the api-versioning-team with dotnetfoundation as a co-owner. If you've wondered why you haven't seen any packages
published in a long time, that's why. Now that I have some level of control over the packages again, updates can resume
once more. There are some limitations though. Any expansion of features in new packages would not be able to continue to
be published under the Microsoft.* prefix. Given this restriction and the previous possibility I might not have ever regained control
of the packages, I have already begun work in the next major release that will start using the Asp.Versioning.* prefix without
any reference to Microsoft. The README.md and repo will provide information indicating this transition. The existing packages
for v5.x will continue limited servicing for existing issues before the long-term switch to the new packages.

I have no doubt that this transition will result in some level of confusion and disruption. I hope that this announcement will
provide some level of clarity as to the how and why it is happening. I'm really proud and honored to be a part of the
community that has been built around API Versioning, which is a big part of why I'm invested in continuing to actively support
it. It has also been many years since the project started and if there is to be a big disturbance now is the time to rip off
the proverbial band aid. The details of all these changes will be outlined in the v6.0 roadmap discussion.

Thank you to all that have supported and advocated for the project over the years.

Chris (@commonsensesoftware)

The API Versioning Team

[ikemtz]

As a long-time consumer of this project, I thank you for all your great work. Best of luck on your new endeavor.

[lchilson]

Thank you for all your work you rock!

[auvansangit]

Thank you so much!

[julealgon]

The API Versioning Team

aka "the one-man army" 🤣

Thank you @commonsensesoftware for your support and determination to continue heading this project.

[greg-lomax]

made my month! :)

[jtTorres]

Thanks for doing this!

[SalehAhmadi]

Thank you @commonsensesoftware for your great work!🙏

[iSeiryu]

Does anyone know what we are supposed to use for dotnet 7 now?
Looks like this package was abandoned https://www.nuget.org/packages/Microsoft.AspNetCore.Mvc.Versioning/
https://github.com/dotnet/aspnet-api-versioning has examples for old Framework 4.8, Aspnetcore MVC, and minimal APIs. But there are no examples for Aspnetcore Web API when we just add services.AddControllers(); without MVC.

[iSeiryu]

Looks like what you wanted finally happened?

[commonsensesoftware]

It finally did. Honestly, about a month ago, but I've been up to my eyeballs and hadn't had time to test it would work. This is the exact same packages as what was published in the official 5.1 release, only uploaded to NuGet. It's kind of crazy that it already has that many downloads. This version and all others going forward will have a banner at the top of the README. I just hope people notice. I'm not sure how else to communicate it. It's been over two years, I know there are still people using the 5.x with .NET 5+. No additional work will happen on these versions, save for critical servicing. Since two fundamental areas have been split up into new packages, I can't really resume these package identifiers even if I wanted to.

[JuanZamudioGBM]

I updated my .net6 Web API to 5.1.0 but my unit tests started to take a long time (for some reason there is a stack overflow exception that takes a lot of time and then the test host restarts and finishes the tests).

Because of that I started googling and found out about all of this, I had no idea about what happened to the project.

About people noticing in my case it's easier when the package is marked as deprecated, that and the README would make it easier to change to the appropriate version.

Thanks a lot for your work, time, dedication and for keeping this project alive.

Edit: I upgraded to 6.4.0 and I'm getting the same behavior, I'm staying with 5.0.0 until I figure out what's going on.

[commonsensesoftware]

@JuanZamudioGBM unfortunately I haven't been able to even publish updates until about a month ago. It's taken over 2 years to get to this point. Without the ability to publish, there was no way to update the README to help let people know. I knew that would be problem and fell on many grenades trying to sort it out for the community to no avail. Fortunately, it is finally fixed and people are starting to notice. I hadn't considered formally marking the packages a deprecated, but that's a good idea. I'll look into making sure that I even have the ability to do that. 5.x is the last of the MS packages, but I will consider servicing it.

Since the behavior repros on 5.x and 6.x+, there might be an issue there. If you have the world's simplest repro, open an issue and I can help dive deeper into what's happening.

[commonsensesoftware]

@JuanZamudioGBM It's also worth mentioning that 7.x is the latest version. 😉

[AshurovRustam]

Hello mates, firstly lemme say thanks for your work. MS once again overusing their community without any effort from their side 😒

But regarding the API we have here. I have few questions more even after whole evening of reading about the topic:

1. Microsoft.AspNetCore.Mvc.Versioning - won't work with .NET 7 at all? Or only new minimal API endpoints?
2. What is the difference between Asp.Versioning.WebApi and Asp.Versioning.Mvc? One for projects that have REST API controllers and another for MVC (with views and web UI)?
3. Having three packages Asp.Versioning.WebApi , Asp.Versioning.Mvc , and Asp.Versioning.Http how it's expected to be used in a project that has MinimalAPIs and REST API controllers? Two packages could be added and versioning should be configured two times separately? Does Asp.Versioning.Http contain all the API from Asp.Versioning.WebApi?

[commonsensesoftware]

Well, it's just lonely old me here as a mate of one #army-of-one. Thanks for the kudos. It's appreciated and what keeps me going on the project.

1. As you've noted, I have not gotten necessary support from those at MS that can enable me to push or update the old Microsoft.* packages. As a result, I can't even notify people about the changes. I've fought for close to 2 years to make this happen to no avail. Lots of promises have been made, but they all come up short. If enough people in the community complain, maybe it will change. Microsoft.AspNetCore.Mvc.Versioning should be considered dead. Even if I could push to the old packages, I was unlikely to ever be able to push new ones under the same branding. When I thought I would never regain any control, I started the process of breaking things into to new packages. I was close to forking the entire project, but decided it was better for the community to stay in the same repo. I manually published a 5.1 version with some patches, but the 5.x release is only ever intended to support .NET 5. Moving forward (e.g. 6.0+), all packages will be branded as Asp.Versioning.*.
2. I tried to make it clear on the landing page, but there is still some confusion. Here's the breakdown:
   • ASP.NET Web API (.NET 4.5 - 4.8.x)
     • Asp.Versioning.WebApi
     • Asp.Versioning.WebApi.OData
     • Asp.Versioning.WebApi.ApiExplorer
     • Asp.Versioning.WebApi.OData.ApiExplorer
   • ASP.NET Core (.NET 6.0+)
     • Asp.Versioning.Http (core - supports Minimal APIs)
     • Asp.Versioning.Mvc (brings in MVC Core for controllers)
     • Asp.Versioning.Mvc.ApiExplorer (API Explorer support)
     • Asp.Versioning.OData (OData 8.0+)
     • Asp.Versioning.OData.ApiExplorer
3. Asp.Versioning.Mvc depends on Asp.Versioning.Http so if you bring in MVC Core support for controllers, you'll have Minimal API support too
   • It appears you are using ASP.NET Core so you do not want any of the Asp.Versioning.WebApi* packages
   • ASP.NET Web API was a product, whereas you can build a "web API" with ASP.NET Core (thanks MS Marketing >_<)

If you have both Minimal APIs and controllers, that is a supported scenario. If the APIs are across the implementation styles, there's a bit of work to do. If they are separate APIs, implemented in different styles, then there's nothing to do.

For example:

[ApiVersion(1.0)]
[AdvertisesApiVersions(2.0)]
[Route("[controller]")]
public class HelloController : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok("Hello world!");
}

var app = builder.Build();
var hello = app.NewVersionedApi();

hello.MapGet( "/hello", () => "Hello world v2!")
     .HasApiVersion(2.0)
     .AdvertisesApiVersion(1.0);

The reason this is necessary is because collation is performed differently between controllers and Minimal APIs. Routing would not be affected, but reporting API versions would. In order have api-supported-versions: 1.0, 2.0 for both styles of endpoints, you can advertise (a long-time existing feature) version from the other implementation style. If your APIs don't overlap this way, then you're good to go.

[AshurovRustam]

Thank you very much for clarification, now it's clear for me. Once again it's shame Microsoft ignores this topic. Actually, I was unable even to find any official MS guidelines for versioning usage (even via old libraries), only some 3rd party articles. What a mess I must say.

[commonsensesoftware]

There's a broad and long misconception that this project was run or otherwise funded by Microsoft and/or the ASP.NET team. It's not nor was it ever. It was under Microsoft OSS when I was still an employee. I was never even part of the ASP.NET team. That all cast a big shadow. Most posts, videos, and interviews all talk about how some Microsoft team brought it all to light. There's no i in team. Since I've left the company, it has become - sometimes painfully even - that this project is not part Microsoft or ASP.NET. This is why there is no official Microsoft documentation and you won't find anything on the documentation sites. I'm no longer allowed to use Microsoft naming or branding and no one from Microsoft wanted to help carry the torch. All that was really required was to have someone review and approve my releases. 🤷🏽

That being the case, the bandage had to come off at some point. The level of confusion that it has caused is unfortunate, I fought long and hard to transition things the right way. I feared this might happen. Sadly, those fears came to fruition. Nevertheless, people have started to notice the change, make the transition, and spread the word along the way. Thanks for your continued support.

Running, documenting, and supporting this entire project takes quite a bit of time. Things have simmered down a bit. I have some goals to get some articles and videos published in 2023. Stay tuned.

[dozer75]

After wondering why the Microsoft.AspNetCore.Mvc.* packages wasn't updated to .NET 6/.NET 7 (or actually done anything since february 2021) I discovered this announcement..

It would be really nice if the old packages was marked as Depracated on NuGet with a link to the new packages as alternative (and as well to some transition documents). It is quite standard way to notify users of NuGet packages about deprecations.

I have missed the .NET 6 version totally because of this (can't keep a track of 200+ packages in detail on GitHub) and when looking at the number of downloads of the Api.Versioning.* packages I strongly suspect that I'm not the only one that has missed this important evolution step of the versioning APIs.

[commonsensesoftware]

A quick note because I noticed that someone posted a question/comment about AddVersionedApiExplorer, but now seems to have deleted their comment. It also relates to @dozer75's comment about the breaking changes.

The breaking changes between 5.x and 6.x are outlined in significant detail (IMO) in #808. The section Breaking Changes → Configuration specifically calls out the differences in setup and the new IApiVersioningBuilder. If additional information is required or people want to see this information repeated somewhere else (the wiki?), I'm happy to oblige. I'd probably have to reword it a bit as it was written in the context of a roadmap, but now that is simply how it is.

[trlevvis]

NuGet package manager in VS now shows that Microsoft.AspNetCore.Mvc.Versioning is deprecated and links Asp.Versioning.Mvc as the recommended replacement.

[commonsensesoftware]

@trlevvis Indeed. I'm not if that is a question or statement. I finally put a migration page based on this discussion. I discovered do have what's necessary to mark the package as deprecated with additional information so I have done so. The README.md in the old packages already said as much, but people have not been reading it. There is still a ton of people using the 5.x.x versions, so hopefully this will help highlight the change and get people to migrate. 😄

[trlevvis]

Sadly, you can count me among the ones that didn't read thoroughly, but the warning icon and a deprecated tag sure caught my eye.

[commonsensesoftware]

@trlevvis You're not alone. I spent almost 2 years trying to do the right thing with MS to no avail. I committed to refactoring everything and publishing with new package identifiers Feb '22 (which was the original MS suggestion 😿). Things went official in Aug '22. .NET 5 is not officially supported in later versions (e.g. .NET 6, 7, 8) so I've been trying to come up with progressively increasing ways to get the word out there.

[iamcymentho]

Thank you for the update. Your dedication to the API Versioning project and the community is truly appreciated. We look forward to the next chapter and the exciting developments to come in v6.0

[Taiwopeter-babs]

@commonsensesoftware Thank you for everything.

[IhnatKlimchuk]

Thank you Chris for your hard work!