When a NuGet package is packed from a library targeting netstandard2.0, net8.0 and net10.0, what lands under lib/, and which folder does net9.0 use?
answer
- one lib/<tfm> folder per target
- one dependency group per target
- highest framework not above the consumer's
- net9.0 consumer gets net8.0
- NU5128 for lib and group mismatches
basics
~20 sPack writes one lib/<tfm>/ folder per target framework and one dependency group per framework in the nuspec. A net9.0 consumer gets lib/net8.0, the highest compatible framework not above its own, while a .NET Framework consumer falls back to lib/netstandard2.0.
solid answer
~40 sFor a project whose `TargetFrameworks` lists `netstandard2.0;net8.0;net10.0`, `dotnet pack` builds each framework and lays out `lib/netstandard2.0/`, `lib/net8.0/` and `lib/net10.0/`, each with that build's DLL and XML docs. The nuspec gets a matching `<group targetFramework=...>` per framework, so package dependencies can differ by target — a package referenced only for `netstandard2.0` appears only in that group. At restore time NuGet picks the folder that best matches the **consumer's** framework: an exact match if there is one, otherwise the highest compatible framework not above it. A `net9.0` app gets `lib/net8.0`, a `net10.0` app gets `lib/net10.0`, a `net481` app gets `lib/netstandard2.0`. Never put a DLL directly in `lib/`: PackageReference ignores it. When lib folders and dependency groups disagree, pack warns **NU5128**.
code
xml · 9 lines<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>netstandard2.0;net8.0;net10.0</TargetFrameworks>
<PackageId>Shared.Validation</PackageId>
</PropertyGroup>
<ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
<PackageReference Include="System.Text.Json" Version="10.0.0" />
</ItemGroup>
</Project>go deeper
Recall that a multi-targeted package has one lib/<tfm> folder per framework and that NuGet picks the one that fits the consuming project.
Explain the nearest-not-above selection rule with examples, per-framework dependency groups, and why a DLL in the root of lib is ignored.
Choose which targets a shared package carries, keep APIs consistent across them, and test consumers per framework rather than trusting the library build.
Set the support window for internal packages — when to drop netstandard2.0 or an old .NET target — balancing consumers still on old frameworks against maintenance cost.
## Why multi-target a package The shared validation library is consumed by services on .NET 10, a batch job still on .NET 8, and an old .NET Framework 4.8.1 tool. One package can serve all of them if it carries one build per target framework. The `TargetFrameworks` property in the project drives that; this question is about what the **package** looks like and how consumers pick from it. ## What pack writes With `<TargetFrameworks>netstandard2.0;net8.0;net10.0</TargetFrameworks>`, pack runs an inner build per framework and assembles: - `lib/netstandard2.0/Shared.Validation.dll` (+ `.xml`) - `lib/net8.0/Shared.Validation.dll` (+ `.xml`) - `lib/net10.0/Shared.Validation.dll` (+ `.xml`) - a `.nuspec` whose `<dependencies>` holds one `<group targetFramework="...">` per framework Folder names are the framework's short name, and the folder per framework is the whole point: NuGet docs warn that an assembly placed directly in `lib/` (or a non-framework subfolder) is ignored with PackageReference. ## Different dependencies per framework Each dependency group lists the packages referenced for that build. A polyfill needed only on .NET Standard is referenced conditionally and then appears only in the `.NETStandard2.0` group: ```xml <ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'"> <PackageReference Include="System.Text.Json" Version="10.0.0" /> </ItemGroup> ``` A `net10.0` consumer therefore never downloads it. The opposite mistake — a hand-written nuspec whose dependency groups do not line up with the lib folders — triggers **NU5128**, which lists groups to add or folders that have no group. ## How a consumer's framework picks a folder When a project restores the package, NuGet matches the project's target framework against the package's folders: 1. If a folder matches exactly, use it. 2. Otherwise use the folder for the **highest framework version that is less than or equal to** the project's, among compatible ones. 3. If nothing is compatible, restore reports an error rather than installing the package. Applied to the three folders: | Consumer target | Folder used | Why | |---|---|---| | `net10.0` | `lib/net10.0` | exact match | | `net9.0` | `lib/net8.0` | highest .NET folder not above 9.0 | | `net8.0` | `lib/net8.0` | exact match | | `net481` | `lib/netstandard2.0` | .NET Framework 4.6.1+ implements .NET Standard 2.0 | NuGet also takes compile and runtime assets each from **one** folder: if compatible assets exist in `ref/` they are used for compilation and `lib/` is ignored for that purpose, and compatible `runtimes/` assets likewise win at run time. ## Design guidance for the package - Keep a `netstandard2.0` target only while a .NET Framework consumer, or another platform that implements only .NET Standard, needs it; it costs testing effort and blocks newer APIs. - Add the newest LTS target (`net10.0`) to use newer APIs and avoid polyfill dependencies for modern consumers. - Make sure every public API exists in every target, or consumers moving between frameworks will see members disappear. - Test the package from a consumer per framework, not just the library's own build. ## Letting the SDK check the targets The SDK's package validation can enforce that last rule. With `EnablePackageValidation` set to `true`, a validation step runs after `Pack`; its compatible-framework validator checks that code compiled against one framework in the package can run against the others, which catches a public member that exists in `lib/net10.0` but not in `lib/net8.0`. Adding `PackageValidationBaselineVersion` also compares the package with a previously released version. For a library consumed across three frameworks, turning this on is cheaper than discovering the gap from a consumer's `MissingMethodException`. The practical interview answer is the mapping rule plus the warning: packages choose by **consumer** framework, nearest-not-above, and a DLL outside a framework folder is invisible to PackageReference.
- Why is it wrong to put Shared.Validation.dll directly in lib/ of a hand-built package?With PackageReference, assemblies in the root of `lib` or in non-framework subfolders are ignored; that layout was only honoured by packages.config. NuGet needs a framework folder such as `lib/net8.0/` to know which consumers the assembly is compatible with.
- What does NU5128 warn about?That the target frameworks in the nuspec's dependency groups and those of the lib or ref folders do not match exactly — for example a `lib/netstandard2.0` folder with no `.NETStandard2.0` dependency group. The warning lists the groups to add or the folders to fix, so consumers of each framework get the right dependencies.
- A net9.0 consumer of this package gets lib/net10.0, the newest folder.
- Placing the DLL directly in lib/ makes it work for every framework.
- All target frameworks of a package must share one dependency list.
- A .NET Framework 4.8.1 app cannot use a package without a net481 folder.
- NuGet merges assemblies from several lib folders into one consumer build.