Background and motivation
Over time types have been removed from the Microsoft.Extensions.* libraries that have made it difficult for customers to use newer versions of those packages on older frameworks.
All of these APIs were obsoleted in a predictable way - first marking as obsolete for one release, then removal in a following release - however that removal has proven to be more breaking for the ecosystem in some cases.
The largest problem that has come up a lot is the removal of types that were used by ASP.NET Core in 2.x. Many of the libraries from this release are still the latest in use by .NETFramework customers - since that's the last version of the product that supported .NETFramework.
Bringing back these APIs has a small cost to maintenance, but will unblock folks from taking newer extensions packages and will allow other packages built on top of these extensions to safely take on the latest version without regressing people. It will also simplify our story for the Microsoft.Extesions packages in terms of best practice reccomendations. We can tell folks it's safe to reference the latest version that is supported and has the API they wish to use (same as we recommend for System.Text.Json) and not require folks to specialize and cross-target for each TFM to select a different version.
We've chosen to bring back API as
[EditorBrowsable(EditorBrowsableState.Never)]
[Obsolete("This property is retained only for compatibility. ...", error: true)]To discourage use. This will fix binary compatibility, reduce discoverability, source compatibility is still broken by default but has the workaround of annotating consuming code with obsolete.
API Proposal
See https://github.com/dotnet/runtime/pull/85846/files?file-filters%5B%5D=.cs&show-viewed-files=true for added API
API added back is not subject to review since it must be identical to what was previously exposed.
I'm seeking approval / acknowledgement for adding back this API for the sake of binary compatibility.
We looked at all the API breaking changes between 2.1 and today and choose to add back API based on the following:
- Entry point API - extension methods, public properties on types we expect users to interact with.
- High usage
API was not brought back based on the following:
- Bringing back would break a runtime scenario like DI
- Pub-ternals which we never expect users to interact with
- Concrete types where we expect users to interact with interfaces
We double checked any case where we were excluding API and it's usage showed significant numbers to understand if there was a significant use case we were missing. One case of this was NullScope where we found all the usage was from tool-like packages redistributing the Microsoft.Extensions binaries themselves as an app layout - and is this not subject to break through package upgrade.
Usage analysis: xls md
API Usage
N/A
Alternative Designs
Only do this in implementation assemblies and not reference assemblies. This isn't helpful since we don't ship the reference assemblies in nuget packages.
Risks
We may not have brought back enough API - we can always bring back more based on customer feedback. We have tested some scenarios (like 2.1 ASP.NET Core App on NetFx with the latest packages - fixed).
Normal set of risk with adding API - name collisions, reflection ambiguity, etc. We've tried to anticipate some of this - like the DI consumption of constructors and reduced the API exposed to mitigate risk.
Background and motivation
Over time types have been removed from the Microsoft.Extensions.* libraries that have made it difficult for customers to use newer versions of those packages on older frameworks.
All of these APIs were obsoleted in a predictable way - first marking as obsolete for one release, then removal in a following release - however that removal has proven to be more breaking for the ecosystem in some cases.
The largest problem that has come up a lot is the removal of types that were used by ASP.NET Core in 2.x. Many of the libraries from this release are still the latest in use by .NETFramework customers - since that's the last version of the product that supported .NETFramework.
Bringing back these APIs has a small cost to maintenance, but will unblock folks from taking newer extensions packages and will allow other packages built on top of these extensions to safely take on the latest version without regressing people. It will also simplify our story for the Microsoft.Extesions packages in terms of best practice reccomendations. We can tell folks it's safe to reference the latest version that is supported and has the API they wish to use (same as we recommend for
System.Text.Json) and not require folks to specialize and cross-target for each TFM to select a different version.We've chosen to bring back API as
To discourage use. This will fix binary compatibility, reduce discoverability, source compatibility is still broken by default but has the workaround of annotating consuming code with obsolete.
API Proposal
See https://github.com/dotnet/runtime/pull/85846/files?file-filters%5B%5D=.cs&show-viewed-files=true for added API
API added back is not subject to review since it must be identical to what was previously exposed.
I'm seeking approval / acknowledgement for adding back this API for the sake of binary compatibility.
We looked at all the API breaking changes between 2.1 and today and choose to add back API based on the following:
API was not brought back based on the following:
We double checked any case where we were excluding API and it's usage showed significant numbers to understand if there was a significant use case we were missing. One case of this was
NullScopewhere we found all the usage was from tool-like packages redistributing the Microsoft.Extensions binaries themselves as an app layout - and is this not subject to break through package upgrade.Usage analysis: xls md
API Usage
N/A
Alternative Designs
Only do this in implementation assemblies and not reference assemblies. This isn't helpful since we don't ship the reference assemblies in nuget packages.
Risks
We may not have brought back enough API - we can always bring back more based on customer feedback. We have tested some scenarios (like 2.1 ASP.NET Core App on NetFx with the latest packages - fixed).
Normal set of risk with adding API - name collisions, reflection ambiguity, etc. We've tried to anticipate some of this - like the DI consumption of constructors and reduced the API exposed to mitigate risk.