Aspnet-api-versioning: Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer 4.1.0 to 4.1.1 is a breaking change

[colinangusmackay]

Be careful with your versioning. If you are using SemVer then breaking changes mean bumping the major part of the version number.

• Version 4.1.0 of Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer supports .NET Standard 2.0
• Version 4.1.1 does not and forces .NET Core 3.1. This is a breaking change for those that are not on .NET Core 3.1 yet.

Therefore a patch bump is highly inappropriate. This should have been Version 5.0.0 due to this breaking change.

[commonsensesoftware]

Fair, but there's already been a long-known plan to drop .NET Standard 2.0. It only existed to support OData. The 4.0 release coincided with .NET Core 3.0 and 4.1 coincided with .NET Core 3.1. Semantic versioning doesn't discuss or otherwise cover multi-target scenarios. .NET 3.1 cannot be run on .NET Core 3.0 (and this did happen to a few people), so by this logic those should have been major version bumps too. Also keep in mind that the .NET Standard 2.0 implementation targeted the older ASP.NET Core 2.2 platform. This was only done to support OData until they caught up.

In retrospect, I _could_ have delayed dropping the support, but it causes my a bunch of infrastructure headache (such as build) that I was happy to be rid of now that OData finally supports .NET Core 3.1. 4.1.1 was meant to align all variants on .NET Core.

There have been zero functional changes since the 4.0 release. For those that may be still running on ASP.NET Core 2.2, you should stick with 4.0 until you can upgrade. There currently isn't any significant new work or features that older flavors should worry about missing out on. I typically do not support patching older releases unless there is something glaring that people need, which is quite rare. In addition to normal release tagging, I've also started leaving branches at the release boundaries to make it easier for those that may need to fork and do their own thing.

Thanks for the feedback. It's appreciated. I don't know that I agree it should have necessarily been a major version bump, but - yeah - it probably shouldn't have been a patch version. ;)

[CesarD]

I was using the package on a library with .Net Standard 2.1 and now it prevents me from upgrading to a minor version...
Why can't this accept .Net Standard 2.x and force us to have our libraries coupled to .Net Core?

[commonsensesoftware]

@CesarD you'll need to elaborate on your scenario before I reevaluate and take action. What's the significance of upgrading a minor version in this case? To be as clear as possible:

Support for .NET Standard is being dropped

Now, perhaps you're wondering why. I'm more than content with supporting the widest targets as possible and I've done so for a long time. It no longer makes sense however. ASP.NET Core 3.0+ no longer supports .NET Standard. In addition, their new model is to reference the entire framework not just the packages you need (though that's not technically what the linker does). As has been the case with OData, I do not have the resources or capacity to support multiple, active versions of ASP.NET Core. Should an issue actually arise in an older version, I have patched older versions albeit rarely. I can count the number of times that's happened on one hand with extra fingers.

As I mentioned above, the multi-targeting support for 4.0 was primarily for OData, but it also served as an anchor point for those still on ASP.NET Core 2.2 to get all of the features (mostly) and fixes up to that point. There haven't been any other changes since that time. I don't believe NuGet currently has a mechanism that reflects the notion of a framework; otherwise, it would be easier to advertise. The decision to drop .NET Standard is, therefore, based on circumstance. ASP.NET Core 3.0+ only supports .NET Core so too must these libraries use .NET Core 3.0+ as well.

I've been doing some form of multi-targeting for nearly a decade. The evolution of PCL and then .NET Standard were certainly welcome, but now that the whole stack is actively supporting multi-targeting as a first-class citizen, it's seemingly unnecessary. There's a lot of debate if there will ever be another iteration of .NET Standard after 2.1. This because all of the stacks finally line up. If you didn't know or hadn't seen, 4.8 will be the last version of the full .NET Framework. Sometime (next year I believe), we will see .NET Core become just ".NET". The "Core" suffix has just been a way to distinguish it from the full framework. .NET Standard has merely been a way to bridge, map, and at times _monkey patch_ the gaps between the platforms.

Continuing to support .NET Standard in a general sense depends on who your base is. If you need to support full .NET Framework consumers, then it's an option; otherwise, moving to .NET Core (soon to just be .NET) makes more sense. In this case, we're talking about a library implementation that would split across two major versions of a dependency. That is not tenable long term. In just about any other scenario that wouldn't be the case so multi-targeting is easier and makes more sense. At some point you may run into an impasse. New language features and libraries will only be available on .NET (Core) going forward. A key reason for this is that there are changes required to the CLR which could not be done without a full .NET Framework upgrade. The new model will allow things to evolve faster and without risk of breaking code dependent on the older runtimes.

To summarize, I'm willing to consider your ask, but you need to clarify and justify why it's needed. If you are trying to support ASP.NET Core 2.2, then you should lock your reference version at 4.0. If you want an open-ended semantic version, then you should use the range [4.0.0-4.1.0). This is where patches are expected to ship - if ever.

I hope that helps clarify things.

[CesarD]

ASP.NET Core 3.0+ no longer supports .NET Standard

Sorry, before replying anything I have to ask: what's the source for such statement? I haven't read such a thing, and here it says that .Net Core 3.0 implements .Net Standard 2.1.

So I have a library with common configurations and functions that I use across multiple services which so far was working fine with v4.1.0 of this package and now to update the nuget to 4.1.1 I should move my entire library to .Net Core 3.0. That feels off and that's why I agree with @colinangusmackay about the versioning issue.

Most likely I could convert my library with not much issue, but for the rest of the users I'm not sure if that would be the case.

[alexjustus]

ASP.NET Core 3.0+ no longer supports .NET Standard

Sorry, before replying anything I have to ask: what's the source for such statement?

I'd like to second this. I haven't seen this mentioned in any official communication from Microsoft either (that's not to say it isn't true; I may have just missed it).

This would definitely change the way we configure our projects. If Microsoft are indeed dropping .NET Standard moving forward then we'll move our in-house libraries over to .NET Core too.

[commonsensesoftware]

Let's back up.

.NET Core 3.0+ can consume .NET Standard 2.0/2.1. .NET Core is a super set of what those targets offer. ASP.NET Core 3.0+ ships as a complete framework. You can no longer reference individual packages via NuGet. Instead, you reference the entire framework - kind of like the notion of a _meta-package_. There's a lot of reasons for this decision, but it wasn't mine nor do I have control over. It was mind-bending for me and I asked some of the same questions you did. Essentially, the ASP.NET Core team felt it wasn't worth continuing to constrain the framework to .NET Standard limitations (e.g. older APIs), multi-targeting with differences was getting too costly, and .NET Core is now the future. This wasn't true in previous versions and consideration was given that many developers may still be using the full .NET Framework. The team wanted to provide some time for people to migrate. The general thought process is that all new work should be on .NET Core (again - not my thoughts) as it will be .NET 5.0+.

The API Versioning libraries for ASP.NET Core has directly framework dependencies; specifically to the current versions. I do not plan, nor have ever had plans, to support multiple major versions of ASP.NET Core side-by-side (namely 2.2 and 3.1). To prevent OData from being completely left in the dust, the 4.0/4.1 packages still include .NET Standard targets for ASP.NET Core 2.2. Aside from not being current and a major version back, this version also did not have LTS. If this issue is about your support with .NET Standard on ASP.NET 2.2, then you should target 4.0. If this issue is instead about .NET Standard support with ASP.NET Core 3.1, either you are not directly consuming ASP.NET libraries or there's something about referencing individual libraries/packages that support .NET Standard that I do not understand (but am happy to learn about).

There's also a chance things are not working they way you think they are. I saw this issue a number of times during the transition to .NET Core 3.0. Folks were trying to make this library work with .NET Core 3.0 before it officially supported it. Since it previously targeted .NET Standard 2.0 and did not clip off the next major version (as I recall), this would allow NuGet to update the package reference. Depending on what you did at runtime, things _may_ work. Some found out the hard way that things will happily compile because the surface areas are compatible, but the things sometimes failed at runtime because of an underlying incompatibility (ex: namespace change, remove type, etc). There are quite a few closed issues related to TypeLoadException or MissingMethodException that highlight this scenario. I mention this because if your library targets .NET Standard 2.0/2.1, this library, and someone tries to run it on .NET Core 3.0+, there are similar landmines that could happen.

The future roadmap has been in circulation since about May (I think around the \\BUILD) time frame. Here are some interesting links to check out:

• .NET Core Roadmap
• Introducing .NET 5.0
• .NET Core is the Future of .NET

There has been no announcement that .NET Standard is gone, but there are some discussions happening as to whether it is still needed.

[alexjustus]

Thanks for your detailed response Chris.

The general thought process is that all new work should be on .NET Core (...) as it will be .NET 5.0+.

I think this is a key statement right here, and something that I need to continue to remind myself of.

In our case we have an ASP.NET Core 3 client app (target framework netcoreapp3.0) and several in-house .NET Standard libraries (target framework netstandard2.1).
The library projects targeting .NET Standard is simply a quirk of history: The project began back when .NET "vNext" launched and targeting .NET Standard for library projects was considered best practice at the time.

Back to the issue at hand: We've solved it for now by remaining on version 4.0.0 (as you suggested).

[geredwards]

Also affected by this breaking. I have various .net Standard libraries used by numerous dotnet core 3.1 apps - and either I fix the .net standard references on 4.0 and hope there are no incompatibilities ever introduced in the future, or I dig up the whole lot.
This change seems to be based on future, _possible_ changes, rather than current status.
Any chance it could be un-done for 4.2?
Otherwise, keep up the good work! :-)

[commonsensesoftware]

@geredwards it would seem you followed the same or similar situation outlined above. Let me try to reiterate the statements above. ASP.NET Core 3.1 does not ship any .NET Standard 2.0/2.1 libraries; it only ships .NET Core 3.1. This means that ASP Versioning can only target .NET Core 3.1 when running against ASP.NET 3.1. For any library that doesn't directly reference an ASP.NET Core 3.1 library, you are free to use .NET Standard 2.0/2.1 if you want to.

The .NET Standard 2.0 support in the API Versioning library is for ASP.NET Core 2.2; the package multi-targets both versions of the platform. This is incompatible with ASP.NET Core 3.1. If you are trying to use API Versioning with .NET Standard and running on .NET Core 3.1, then your references are wrong and at risk of failing at runtime. It _may_ work, but that doesn't mean it's correct. The reason it might work is because the implementation is almost the same between the two so automatic assembly redirection will likely work. There are edge cases, which I've already seen, where it will not work at runtime, but will happily compile.

.NET Standard 2.1 is subset of .NET Core 3.1 so I don't see how any combination of .NET Standard will reliably work in .NET Core 3.1. I didn't anticipate this level of confusion. I'm starting to think I should not have multi-targeted to support OData and just waited until they had a .NET Core 3.0+ implementation.

We can debate version numbers and it's pretty hard to not say there should have been at least a minor bump, but the only _change_ is dropping .NET Standard because it isn't supported directly by any ASP.NET Core 3.1 libraries. Not everyone is or wants to come to ASP.NET Core 3.1, which is why there was a demarcation line at API Versioning 4.0. If you're targeting ASP.NET Core 2.2, this is where you should stay. Ideally, I wanted to drop the .NET Standard support in 4.1 to coincide with the .NET Core 3.1 release. I suppose that was technically possible without any other loss in functionality since OData would have had a working version at 4.0.

I'm happy to continue the discussion and/or explain further. I don't have the capacity to support ASP.NET Core 2.2 and 3.1 side-by-side long term so I don't foresee anything being _undone_ or otherwise going backward. If there is some way to make .NET Standard work in this context (which I currently do not understand how), I'm more than willing to oblige.

[CesarD]

ASP.NET Core 3.1 does not ship any .NET Standard 2.0/2.1 libraries; it only ships .NET Core 3.1.

Hi. I don't want to be rude or look like a d*ck, but where is the documentation link for supporting this statement?
It really has me surprised because, if this is really the case, I'm totally in the dark about it and would like to know more about the case.
Thanks.

[commonsensesoftware]

@all, here's some information that I've spelunked on your behalf. Hopefully, it will shed some additional light and context around this issue.

Overview

• Upgrading a .NET Standard 2.0 library to .NET Core 3
• Libraries that depend on ASP.NET NuGet packages
• MSDN: Migrating libraries via multi-targeting
  
  
  
  • This is the current multi-targeting scenario, but was only ever meant to support OData on ASP.NET Core 2.2
  
  
  • I do not have plans to continue supporting ASP.NET Core 2.2 with new features side-by-side
  
  

Source Code

• <TargetFramework> in release/3.1 → Microsoft.AspNetCore.Mvc.Core.csproj
• <DefaultNetCoreTargetFramework> in release/3.1 → directory.build.props

NuGet Packages

Most of the ASP.NET Core packages no longer exist in 3.0+ and are referenced via the new <FrameworkReference> element. However, there are a few packages that do not ship out-of-the-box with the framework such as Microsoft.AspNetCore.TestHost. You can see that 3.0.0 only targets netcoreapp3.0 and 3.1.0 only targets netcoreapp3.1.

---

I really don't know when or where the announcement was made about this change. I remember being pretty confused myself when I first had to deal with it. It seemed kind of silly that I now have to reference the _entire_ framework, when I only really need one or two references. In reality, I only get those one or two references based on the _smartness_ of the linker, but _everything_ is logically referenced.

Again, you can use .NET Standard with .NET Core 3.0, but if you're referencing ASP.NET Core libraries, then you have to match their target frameworks, which is currently netcoreapp3.1. In fact, if you look at the master branch, you'll see that it now targets netcoreapp5.0. I have no understanding of the TFMs in this context, but I would have expected it to be net50 based on the roadmap and release of .NET 5.0. Maybe this is temporary and it will change again before release. I honestly have no clue.

I hope that helps, if not a little.

[commonsensesoftware]

This thread has effectively gone dark. I assume all parties interested in voicing their opinion have done so. I trust there has been more than enough time to review the information I've provided and either confirm for yourself or object to my assertions. I'll reiterate that I have no problem supporting .NET Standard on .NET Core if it's supported, but it doesn't seem that it is.

I'm imminently close to needed to push out the next patch. If there's something else I need to change to support your scenario, now is the time to hash that out. Otherwise, I'll move forward with the premise that we are in agreement, even if we don't like the answer.

Thanks

[CesarD]

I guess it now has more sense in the way that everything else is being slowly deprecated: with .NET Standard 2.1 not being implemented in .NET Framework 4.8, that already makes 4.8 virtually dead for library devs that wanted to share their work across both platforms, so the need to use .NET Standard to share libraries between platforms is barely needed now (except for those for Xamarin/Mono, Unity, etc).
I found this issue talking about this as well: https://github.com/dotnet/standard/issues/859

This doesn't mean that .NET Standard is being dropped, though... I haven't read anywhere that there's no support for it anymore, so I would avoid to include that as a reason.
The real reason I see is about it being _less needed_ because of how the rest of the platform is evolving.

All in all: I'm good with retiring .NET Standard support for this specific library because we should already start moving towards .NET Core as a whole and drop .NET Framework for once...
There might still be headaches for those who are still working with it though...

[commonsensesoftware]

Good links. I never claimed it was officially _dead_ and there are still useful scenarios, but it's a lot _less needed_ as you stated. With .NET 5.0 being a major version demarcation line, the full .NET Framework as we've known it is dead at 4.8 and .NET Core simply becomes ".NET". Certainly, for Xamarin/Mono/Unity, there still work to unify things under the hood, but it's happening. A big push for that is the new work happening with Blazor. They want to take the best of .NET Core (of today) and Mono to march toward a single, cohesive framework. In theory, there may finally come a day where a TFM is no longer even needed. 😄

It's unfortunate this is the way things played out in the long haul. This type of multi-targeting was possible and being touted by Mono circa 2005. It's taken 15 years, but we're finally on the right path. .NET Standard was never a silver bullet, but if you ever worked with PCL and the alternatives that came before, you know it was a welcomed change. At least in my experience, even .NET Standard had a bit of a rough start. It wasn't really until 2.0+ that things got _easy_.

In any event, I appreciate the feedback and discussion. I'll leave this open for a few more days so everyone has a chance to voice their option (or merely kvetch 😉) and we'll go from there (hopefully to closure).

[commonsensesoftware]

Thanks for all the discussion on this and keeping me honest. I think we're set to close this topic out. I really need to get Gitter or something going as I suspect this thread could easily just turn into a long-running, but informative, discussion on multi-targeting and all that it entails.

Happy to continue the discussion as necessary or provide any guidance how to setup your own packages/libraries. I don't have anyone else helping run this repo so I really appreciate the community calling me out on decisions because there's no one else reviewing things. 😉

Thanks again!