Difficulty maintaining compatibility with installed .NET versions due to NuGet package versioning

[michmela44]

I'm encountering issues while trying to ship a .NET 8 application without bundling additional platform binaries—relying entirely on the presence of the system-installed .NET runtime.

However, due to NuGet package versioning, I’m forced to include assemblies that require newer runtime components than what may be present—even when targeting .NET 8 LTS.

We are preparing to release an application that has been migrated from .NET Framework 4.8 to .NET 8.0, and we are unsure how distribution should be handled given these scenarios.

---

Example 1: System.Formats.Nrbf

• Target framework: .NET 8
• We use System.Formats.Nrbf for .NET Framework 4.8 migration compatibility.
• Package version is 9.0.3, which depends on:
  • System.Reflection.Metadata ≥ 9.0.3
  • which in turn depends on System.Collections.Immutable ≥ 9.0.3

This results in the app requiring framework components that may not exist on a machine with only the base .NET 8.0.10 install, unless those assemblies are explicitly bundled.

---

Example 2: Microsoft.Extensions.Logging

• In a plain .NET 8 app (non-ASP.NET), referencing Microsoft.Extensions.Logging leads to similar issues, including dependencies like System.Diagnostics.DiagnosticSource.
• Even patch-level mismatches (e.g., built on 8.0.13, deployed on 8.0.10) have caused runtime failures unless assemblies are manually shipped.

---

Attempts to Work Around:

• I’ve tried stripping DLLs from the output to allow the runtime to resolve them from the shared framework. However, patch-level mismatches often cause the app to fail to start.
• Maintaining an ever-growing list of DLLs to exclude from the installer has proven fragile and difficult.

---

Key Questions:

1. Is there a supported way to use .NET 8 NuGet packages without bundling newer framework binaries?
2. Are patch versions (e.g., 8.0.10 vs. 8.0.13) guaranteed to be runtime-compatible?
3. What is Microsoft’s intended guidance for compatibility when consuming packages like System.Formats.Nrbf or Microsoft.Extensions.Logging?
4. Should developers avoid packages outside the shared framework if they want to avoid shipping DLLs?
5. Or is it expected that if you use anything beyond the base shared framework, a self-contained or framework-dependent deployment (with copied DLLs) is required?

---

Thank you!

[marcpopMSFT]

Asking @ericstj to answer these questions as it's really about library dependency chains and the shared framework.

[ericstj]

Is there a supported way to use .NET 8 NuGet packages without bundling newer framework binaries?

The SDK will compare what's in the framework to what you reference. If what you reference is newer then they become app-local.
In past SDKs we were very conservative about this calculation where most comparisons were done against GA version of the framework (for framework dependent) since that's what the SDK would have you target.
In 10.0 SDK this improves a bit as we made a blanket adjustment to prune overlapping packages of the same major.minor version -- dotnet/sdk#44566.
You can always force the package to be ignored with ExcludeAssets
 

Are patch versions (e.g., 8.0.10 vs. 8.0.13) guaranteed to be runtime-compatible?

Yes. When a package overlaps with the framework we fix it's assembly version and surface area. Packages of the same major.minor version will have the same assembly version and API when targeting the overlapping framework.
 

What is Microsoft’s intended guidance for compatibility when consuming packages like System.Formats.Nrbf or Microsoft.Extensions.Logging?

When referencing packages that overlap with the framework and you care about servicing bands, choose the package versions that match the servicing band you wish to remain in.

If instead you prefer features over servicing bands - you can reference newer packages - these will become app-local since then are from a newer framework release. You can safely use these so long as your target framework is in support. If the release the packages' came from (eg: 9.0) goes out of support before your target framework (eg: net8.0) you may need to update to a new package release (eg:10.0). This is the cost of taking newer features from newer releases.
 

Should developers avoid packages outside the shared framework if they want to avoid shipping DLLs?

Prefer the API from the target framework over the package - if it is present. If you need the new API / package - you can use it. Plan to remove it when that API is back in the framework (and you no longer need newer API).

As I mentioned above - this does get better in 10.0 SDK with package pruning.

Or is it expected that if you use anything beyond the base shared framework, a self-contained or framework-dependent deployment (with copied DLLs) is required?

Only dependencies you need are copied app-local - whether your app is framework dependent or self-contained.

cc @richlander @ViktorHofer