search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.53k stars 25.3k forks source link

Documentation instructs users to install deprecated package. #33149

Open JaredShaver opened 1 month ago

JaredShaver commented 1 month ago

Description

The instructions on the page say "To install the new data protection system into an existing ASP.NET 4.5.1+ project, install the package Microsoft.AspNetCore.DataProtection.SystemWeb." However, the Microsoft.AspNetCore.DataProtection.SystemWeb is marked as deprecated. There is no documentation on what the supported package should be.

Page URLs

Content source URL

Document IDs

53e91296-c75c-b446-1487-6710b024ad60 d42b1eab-9682-ea69-f203-e519b456a56f

Article author

@Rick-Anderson

JaredShaver commented 1 month ago

Another link directing users to use the deprecated package is also here: https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/introduction?view=aspnetcore-8.0#package-layout

Rick-Anderson commented 1 month ago

@claudiaregio @wsloth @amcasey please advise.

amcasey commented 1 month ago

ASP.NET Core 2.2 is definitely not supported. ASP.NET Core 2.1 is supported, but I don't know whether that extends to the SystemWeb package - I suspect not. I'm guessing the supported mechanism when using Framework in IIS is machinekey, but I'll see if I can confirm.

amcasey commented 1 month ago

Yep, SystemWeb 2.1 is supported - it's 2.2 that's deprecated. See https://dotnet.microsoft.com/en-us/platform/support/policy/aspnet/2.1-packages

JaredShaver commented 1 month ago

Yep, SystemWeb 2.1 is supported - it's 2.2 that's deprecated. See https://dotnet.microsoft.com/en-us/platform/support/policy/aspnet/2.1-packages

I am a little confused, there is no dates for a support policy on the page, just a list of packages. This page says .NET Core 2.1 was out of support as of August 21, 2021. https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core Is there even anything .NET 2.X specific about the Microsoft.AspNetCore.DataProtection.SystemWeb package other than its reference to ASP.NET 2.X packages? If they were just updated to .NET 8, would there even be any code changes needed?

amcasey commented 1 month ago

It is definitely confusing. .NET Core 2.1 is indeed out of support. However, you can still use ASP.NET Core 2.1, with .NET Framework, which is not out of support.

ASP.NET Core 8.0 doesn't work with .NET Framework, so I'm not sure SystemWeb is needed there, though I may be missing something.

Perhaps you could say a bit more about your scenario and what you're trying to accomplish?

JaredShaver commented 1 month ago

We are moving ASP.NET Framework 4.8 applications to containers and need a solution for dealing with the machinekey. The ASP.NET Core Data Protection has functionality for storing and rotating keys using Azure Key Vault and blob storage which we want to leverage for these migrating apps. According to https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/compatibility/replacing-machinekey?view=aspnetcore-8.0 this is supported via Microsoft.AspNetCore.DataProtection.SystemWeb but installing it shows warnings that the package is deprecated. If this package is abandonware we really don't want to waste time migrating to it. If it isn't abandoned, it would be nice to have an updated version of the package that is being maintained with its references updated to the latest versions. Since Microsoft.AspNetCore.DataProtection is .NETStandard 2.0 this shouldn't be problematic.

amcasey commented 1 month ago

installing it shows warnings that the package is deprecated

Yes, sorry about that - you'll have to manually specify 2.1 and not just install latest.

it would be nice to have an updated version of the package that is being maintained with its references updated to the latest versions

Tell me more about this? I think you're saying you want to use the 8.0 version of Microsoft.AspNetCore.DataProtection?

amcasey commented 1 month ago

Turns out this is already tracked here: https://github.com/dotnet/aspnetcore/issues/56993

JaredShaver commented 1 month ago

That's good news that there is a plan to bring the code back for the package in a separate repository. For the original issue, until it is and a new version published to NuGet, it would be helpful to update the documentation to direct users to install the specific supported version of the package so they aren't confused.