[Breaking change]: .NET 11+ shared framework includes Microsoft.Extensions.* Abstractions/Options/Primitives packages

[ericstj]

Description

In .NET 11 and later, nine Microsoft.Extensions.* libraries (Abstractions, Options, and Primitives) are now included in the base shared framework (see PR dotnet/dotnet#5206 and final decision in dotnet/runtime#67487). This means:

• PackageReference to these libraries is no longer required when targeting .NET 11+.
• If you reference these packages on .NET 11+, you'll see a build warning (NU1510) that you can remove by deleting the PackageReference.
• In rare cases, new name/type conflicts could occur if you have source or full type names that shadow new APIs now present in the base shared framework.
• Self-contained applications which don't enable trimming may grow in size. Framework-dependent applications may shrink. AOT and trimmed applications should remain unchanged.

Links:

• Primary PR: dotnet/dotnet#5206
• Discussion: dotnet/runtime#67487
• Warning details (NU1510)

Version

.NET 11 Preview 4

Previous behavior

Before .NET 11, the following Microsoft.Extensions.* libraries were not present in the base shared framework and were required as PackageReferences in projects that needed them. Their absence from the shared framework meant their assemblies would routinely be copied to the output folder when packages referenced.

Packages:

• Microsoft.Extensions.Caching.Abstractions
• Microsoft.Extensions.Configuration.Abstractions
• Microsoft.Extensions.DependencyInjection.Abstractions
• Microsoft.Extensions.Diagnostics.Abstractions
• Microsoft.Extensions.FileProviders.Abstractions
• Microsoft.Extensions.Hosting.Abstractions
• Microsoft.Extensions.Logging.Abstractions
• Microsoft.Extensions.Options
• Microsoft.Extensions.Primitives

New behavior

On .NET 11 or newer, these nine libraries are part of the base shared framework:

• You'll receive warning NU1510 if you reference these packages explicitly (see link above).
• To resolve NU1510, simply remove the PackageReference (the library is now always present).
• These assemblies will no longer be copied to your output folder since the framework provides them.
• In rare cases, more APIs in the default load set may result in source/type name conflicts; typical resolutions involve more explicit using directives or aliases.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

Reduce application size, package dependencies, servicing when depending on these commonly used libraries.

Recommended action

• If you see warning NU1510 for these Microsoft.Extensions packages, remove the PackageReference (not the warning). Your code should continue to work as before, as the APIs are now present in the runtime.
• If you hit a compile-time name conflict (rare): resolve it with a more explicit using directive, an alias, or a fully qualified type name as needed.
• If you were including these assemblies in your deployment of your framework dependent application, they are no longer required.
• No other migration steps should be required for the vast majority of applications.

Feature area

Core .NET libraries

Affected APIs

• Microsoft.Extensions.Caching.Abstractions
• Microsoft.Extensions.Configuration.Abstractions
• Microsoft.Extensions.DependencyInjection.Abstractions
• Microsoft.Extensions.Diagnostics.Abstractions
• Microsoft.Extensions.FileProviders.Abstractions
• Microsoft.Extensions.Hosting.Abstractions
• Microsoft.Extensions.Logging.Abstractions
• Microsoft.Extensions.Options
• Microsoft.Extensions.Primitives

---

Associated WorkItem - 567074