ASP.NET Core 2.1 becomes ASP.NET Core 2.3

[terrajobst]

We'll be reshipping ASP.NET Core 2.1 as ASP.NET Core 2.3 and encourage ASP.NET Core 2.2 users to update to it. In this post I'll provide more background.

Note

This post only applies if you're using ASP.NET Core on .NET Framework. If you're using ASP.NET Core 2.x on .NET Core 2.x, it is already out of support, and you should upgrade to a supported version such as .NET 8.

Background

Early versions of ASP.NET Core were provided for .NET Framework and .NET Core. Since 2021, ASP.NET Core 2.1 is supported only when running on .NET Framework. ASP.NET Core 2.2 has been out of support on all platforms since 2019.

This happened before we had a predictable schedule and alternate releases of Standard Term Support (STS) and Long Term Support (LTS). Many users upgraded to ASP.NET Core 2.2, not realizing that this reduced their support duration.

As a result, we now have users that are running on the unsupported version of ASP.NET Core 2.2 on .NET Framework.

Product	.NET Framework Support
ASP.NET Core 2.1	Supported
ASP.NET Core 2.2	Ended December 23, 2019

How to stay supported

• If you're on .NET Core, you should upgrade to .NET 8 and use ASP.NET Core 8
• If you're on .NET Framework, you can either migrate to .NET 8 or upgrade to ASP.NET Core 2.3, which is the same code as ASP.NET Core 2.1 (see below)

Since ASP.NET Core 2.x for .NET Framework is just a set of packages, downgrading isn't that easy; there are well over one hundred packages and not all of them have 2.x version numbers. To make matters worse, there are NuGet packages out there that also upgraded to ASP.NET Core 2.2. Downgrading to ASP.NET Core 2.1 would mean that NuGet fails to restore these dependencies with errors.

In order to make this easier, we'll reship ASP.NET Core 2.1 as ASP.NET Core 2.3, thus facilitating this downgrade as a package upgrade.

You might wonder why we don't reship ASP.NET Core 2.2 as 2.3 instead. The answer is breaking changes. ASP.NET Core 2.2 went out of support five years ago, while ASP.NET Core 2.1 kept being supported. We feel it would be wrong to force ASP.NET Core 2.1 users to accommodate those breaking changes in order to stay supported.

Users on ASP.NET Core 2.2 are unsupported and won't receive any security updates. Our priority is to help those users to get onto a supported version of ASP.NET Core for .NET Framework.

By reshipping ASP.NET Core 2.1 as ASP.NET Core 2.3, we provide users on ASP.NET Core 2.2 an off ramp to the supported version via a regular NuGet upgrade. Users on ASP.NET Core 2.1 will also be pulled forward to 2.3, but since it's the same code as 2.1, there are no breaking changes. Moving forward, all updates to ASP.NET Core 2.1 will be published as 2.3. However, if you're using ASP.NET Core 2.1, you don't need to move to 2.3 in order to get updates. If we find security issues with 2.1 packages, those will be marked as vulnerable and the recommended version will be versioned as 2.3. Except for the version number changes, that's how ASP.NET Core 2.1 works today, so there are no changes for you and you don't need to preemptively update to ASP.NET Core 2.3 to receive those warnings.

Caution

Please note that if you're using ASP.NET Core 2.2, you will not be getting vulnerability warnings via NuGet because the product is out of support. There is no change here, this has been the case since ASP.NET Core 2.2 went out of support five years ago. Therefore, if you're on ASP.NET Core 2.2, we strongly recommend to update to ASP.NET Core 2.3 as soon as possible in order to receive security fixes again.

We understand that this can be confusing, but we believe it's the best compromise to help ASP.NET Core 2.2 users to get back onto a supported train.

Product	.NET Framework Support
ASP.NET Core 2.1	Supported with ASP.NET Core 2.3
ASP.NET Core 2.2	Ended December 23, 2019
ASP.NET Core 2.3	Supported, same code as 2.1

Summary

For .NET Core, ASP.NET Core 2.x is and remains unsupported.

The following statements are specific for ASP.NET Core 2.x on .NET Framework:

• ASP.NET Core 2.1 is and remains supported.
• ASP.NET Core 2.2 is and remains unsupported.
• We're re-versioning ASP.NET Core 2.1 as ASP.NET Core 2.3 to allow ASP.NET Core 2.2 users to move to a supported version.
• Users on ASP.NET Core 2.1 should update to ASP.NET Core 2.3. Since it's the same code as ASP.NET Core 2.1, there are no breaking changes or feature additions. This operation won't require any code changes on your side. But it will make your life easier as all future updates will be versioned as 2.3.x, so you'll have a consistent set of versions.
• Users on ASP.NET Core 2.2 update to ASP.NET Core 2.3. This will ensure you get off of the unsupported version and thus will get security fixes. You should expect breaking changes as you're effectively downgrading to the code from ASP.NET Core 2.1. If you can't live without the features being added in ASP.NET Core 2.2, you'll have to migrate to a supported .NET version with those features, such as .NET 8.
• This does not extend or reduce the support durations of any products, nor which versions of .NET are supported where. It's purely a re-versioning of ASP.NET Core 2.1 in order to help the math in the package manager. The net effect of this change is that the last supported version of ASP.NET Core for .NET Framework is also the highest minor version (2.3).

[WeihanLi]

seemed no packages have been published so far

[cremor]

Please clarify which .NET Hosting bundle version we are supposed to use for ASP.NET Core 2.1/2.3. See also dotnet/AspNetCore.Docs#22565

[mkArtakMSFT]

seemed no packages have been published so far !

This post was meant to give a heads-up, laying out a plan that we're executing on. We're working on building these packages and will have them published within a month or so.

[HamsterExAstris]

What will this entail for Microsoft.Extensions.Diagnostics.HealthChecks?

This was a new package in 2.2. There was some earlier discussion of backporting to 2.1 to facilitate dropping the .NET Standard target from newer versions, but that never materialized.

[SRJames]

Any ETA on this?

[danmoseley]

@joperezr for question about Microsoft.Extensions.Diagnostics.HealthChecks

ETA I think is Jan- @wtgodbe

[joperezr]

Microsoft.Extensions.Diagnostics.HealthChecks is not covered by the support policy that was targeting the 2.1 packages. The full list of packages that are impacted by this change are listed here https://dotnet.microsoft.com/en-us/platform/support/policy/aspnet/2.1-packages.

Microsoft.Extensions.Diagnostics.HealthChecks was released after 2.1, and is covered by the regular aspnetcore support policy: https://dotnet.microsoft.com/en-us/platform/support/policy/aspnet#dotnet-core

[terrajobst]

@HamsterExAstris

To rephrase what @joperezr said: ASP.NET Core 2.2 remains unsupported. We don't plan on backporting anything in 2.2 to 2.1. Moving from 2.2 to 2.3 is a breaking change because you're essentially downgrading to the code from 2.1. This means that upgrading to 2.3 means you'll lose access to Microsoft.Extensions.Diagnostics.HealthChecks.

If you don't mind being on unsupported bits, you can just stay on 2.2. In that case nothing changes -- you were running on unsupported bits before.

[HamsterExAstris]

@terrajobst We won't be unsupported, because we can still use v9.0.0+. The previously-proposed idea was to backport it so that a tripping hazard for ASP.NET Core users could be removed, while keeping .NET Framework users in support.

It sounds like the plan is no changes, which works just fine.

[terrajobst]

That's fair. I meant specifically the 2.2 version of the package remains unsupported and is essentially unavailable. But yes, you can of course use a later version.

[plave0]

@terrajobst, I am working on https://github.com/microsoft/service-fabric-aspnetcore, where we depend on ASP.NET Core 2.1. We have noticed that depending on ASP.NET Core 2.1 packages introduces vulnerable transitive dependencies to the project, e.g.:

Transitive Package                                           Resolved   Severity   Advisory URL
   > Microsoft.AspNetCore.Http                                  2.1.1      High       https://github.com/advisories/GHSA-hxrm-9w7p-39cc
   > Microsoft.AspNetCore.Server.Kestrel.Core                   2.1.3      High       https://github.com/advisories/GHSA-6px8-22w5-w334
                                                                           High       https://github.com/advisories/GHSA-242j-2gm6-5rwx
   > Microsoft.AspNetCore.Server.Kestrel.Transport.Sockets      2.1.3      High       https://github.com/advisories/GHSA-vmch-3w2x-vhgq
   > System.IO.Pipelines                                        4.5.0      High       https://github.com/advisories/GHSA-j378-6mmw-hqfr
   > System.Text.Encodings.Web                                  4.5.0      Critical   https://github.com/advisories/GHSA-ghhp-997w-qr28

Is it planned for these vulnerabilities to be fixed in ASP.NET Core 2.3?

[terrajobst]

@plave0 I believe we will, but I have pinged my team to validate.

[wtgodbe]

The 2.3.0 packages are now live on nuget.org!

[vernou]

From the support policy documentation :

ASP.NET Core 2.1 on .NET Framework

Support for ASP.NET Core 2.3 on .NET Framework matches the ASP.NET Support policy for other package-based ASP.NET frameworks. The complete list of packages covered by this policy can be seen in ASP.NET Core 2.3 Supported Packages.

Few packages Microsoft.Extensions.* are integrated in 2.3. For example, Microsoft.Extensions.Logging.Console isn't in the list. So Microsoft.Extensions.Logging.Console is no longer supported in .NET Framework.

Of course, I am misunderstanding, but can you clarify this point?

[KalleOlaviNiemitalo]

I think they expect you to use Microsoft.Extensions.Logging.Console 8.0.1 (LTS) or 9.0.1 (STS), which are supported on .NET Framework according to dotnet/extensions#4952 (reply in thread). Be aware that some other packages target .NET Framework but are not supported on that.

[gravity00]

@wtgodbe thanks for explaining it, didn't know this was intended.
I'll respond here instead of on issue #59882 because it should be the better place.

---

The thing with this change, which is affecting dozens of our on-prem applications that sadly can't be migrated due to running on older Windows Servers on .NET Framework, is that bumping version 2.1 to 2.3 removed some code added on 2.2 which, despite 2.1 being the LTS, it isn't expected since it is a breaking change on a minor version upgrade.

If developers (like myself) don't expect to receive breaking changes on SemVer minor version updates, specially from packages provided by a company like Microsoft that values code stability, they should feel comfortable to configure NuGet to automatically update on minors.

Here's a simple example that is affecting us substantially.

Imagine that you have some internal helper NuGet package that depends on Microsoft.EntityFrameworkCore.Relational and says: "as long as you give me any version 2 of EF Core greater than 2.2.0, I can work with it"

<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="[2.2.*, 3.0.0)" />
  </ItemGroup>
</Project>

And now let's say that it uses the method ApplyConfigurationsFromAssembly (introduced on 2.2 but now inexistent on 2.3) to scan itself to register some IEntityTypeConfiguration on some DbContext.

protected override void OnModelCreating(ModelBuilder builder)
{
    base.OnModelCreating(builder);
    builder.ApplyConfigurationsFromAssembly(GetType().Assembly);
}

And now let's say you have some web application that uses this NuGet but, again because it trustes on Microsoft on following SemVer on its packages, also configures it to automatically update ASPNET Core on minors.

<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore" Version="[2.*, 3.0.0)" />
    <PackageReference Include="TheInternalPackageThatDependesOnEFCore" Version="[1.*, 2.0.0)" />
  </ItemGroup>
</Project>

The developer opens Visual Studio, version 2.3 of ASPNET Core is downloaded, everything compiles as expected but now the application throws runtime exceptions are thrown because the method ApplyConfigurationsFromAssembly is not found.

Now, the developers have some options:

1. Change the internal packages to use only code available on version 2.1/2.3, if possible;
2. Fix the versions of both the internal packages and host applications to only support version 2.2;

Whatever the decision is, it forces, not encourages developers to change their code, which has obvious costs.
You may be lucky and only have one or two applications in this scenario, but sadly my company is not one of the lucky ones.

---

I do understand this probably can't be reverted, it is a massive problem that we'll have to deal with, but I just want to say that I wasn't expecting a company like Microsoft to decide not to follow SemVer guidelines, specially on a packages with more than 7 years of existence.

[wtgodbe]

Thanks for the thoughtful response - we understand this is inconvenient for users of 2.2, but as mentioned in the original comment in this issue, that version of .NET has been out of support since 2019 - we've found ourselves in a bit of a "Rock and a hard place" situation with 2.x, as up until this 2.3 release, customers with PackageReferences using version 2.* would get the unsupported 2.2 version resolved, and often didn't know they were using an unsupported package. Furthermore, Visual Studio would suggest 2.2 as "upgrades" to customers w/ 2.1 PackageReferences, even though 2.2 is out of support and 2.1 isn't.

We were highly motivated to get those customers off of the unsupported version of ASP.NET, and felt there were more customers in that bucket than in the one you described in your comment. Pasting the guidance from the top-level comment below:

Users on ASP.NET Core 2.2 update to ASP.NET Core 2.3. This will ensure you get off of the unsupported version and thus will get security fixes. You should expect breaking changes as you're effectively downgrading to the code from ASP.NET Core 2.1. If you can't live without the features being added in ASP.NET Core 2.2, you'll have to migrate to a supported .NET version with those features, such as .NET 8.

[cremor]

Now that 2.3 is out I'd like to repeat my question from above:

Please clarify which .NET Hosting bundle version we are supposed to use for ASP.NET Core 2.1/2.3. See also dotnet/AspNetCore.Docs#22565

[wtgodbe]

The hosting bundle is no longer in support for 2.1/2.3 - the only things still in support are the nuget packages listed here, running on .NET Framework

[cremor]

So are we expected to use a currently supported hosting bundle with 2.1/2.3?
Meaning MS supports hosting bundle 8/9 (right now) when used in combination with ASP.NET Core 2.1/2.3 (running on .NET Framework runtime)?

[wtgodbe]

Yes, we recommend installing an in-support hosting bundle such as the 8.0 or 9.0. You can use the command line options described here to avoid installing the 8.0/9.0 runtimes if all you want is ANCM. For full framework, we only ever supported out-of-process hosting. You'll likely also need to specify AspNetCoreModuleV2 in your web.config (see example here)

[KalleOlaviNiemitalo]

You can use the command line options described here to avoid installing the 8.0/9.0 runtimes if all you want is ANCM.

Is that the correct link? The script looks like it's for installing Visual Studio, and I don't see any ANCM-related options listed.

[wtgodbe]

My mistake, copy-paste error 😆. This is the correct link - I'll update my original comment as well

[cremor]

Ok, so exactly what @shirhatti has written in dotnet/AspNetCore.Docs#22565? Would be great to see that in the official documentation.