How does nuget/msbuild copy the package's lib content to the output directory - rules?

Question

TL;DR: What are the exact rules for consuming the lib directory inside of a nuget package?

When consuming a NuGet package from Visual Studio in my C# .NET SDK projects, the contents of the packages lib folder are copied to the output directory.

There are certain rules governing the layout of the lib folder in the released package, e.g. lib/TxM/* that the files need to be grouped by Target Framework and also I find that *.resources.dll are treated specially.

There are hints scattered in various NuGet doc topics wrt. the layout of this folder, and what would then be copied (by msbuild/nuget) to the projects output folder and what would then be referenced from the project itself ("linked").

However, I cannot find a proper documentation for the rules governing the consumption of the files from the nupckg content from Visual Studio.

Specifically I seem to observe, and I think I've seen it mentioned, that only files directly at lib/TxM/*.* will be referenced and any subfolders ignored -- what are the exact rules governing this?

---

Listing the snippets I found so far

The following is a list of info I found so far on this.

A specific gem I want to highlight is "For many packages the lib works the same way it does in NuGet 2.x," ... if anyone could tell me what the rules were/are, that'd be much appreciated.

https://learn.microsoft.com/en-us/nuget/create-packages/select-assemblies-referenced-by-projects#packagereference-support :

... uses PackageReference, NuGet selects compile and runtime assets ...

Compile assets prefer ref/<tfm>/*.dll (for example ref/net6.0/*.dll), but if that does not exist, then it will fall back to lib/<tfm>/*.dll (for example lib/net6.0/*.dll).

Runtime assets prefer runtimes/<rid>/lib/<tfm>/*.dll... fall back to lib/<tfm>/*.dll

https://github.com/NuGet/docs.microsoft.com-nuget/blob/9c6c26ea385deaad4bd92a7a88d170796352bab1/docs/archive/project-json-and-uwp.md#L65 :

Lib : For many packages the lib works the same way it does in NuGet 2.x, but with expanded options for what names can be used inside it and better logic for picking the correct sub-folder when consuming packages.

https://learn.microsoft.com/en-us/nuget/reference/nuspec#including-assembly-files :

If you follow the conventions described in Creating a Package, you do not have to explicitly specify a list of files in the .nuspec file. ...

When a package is installed into a project, NuGet automatically adds assembly references to the package's DLLs, excluding those that are named .resources.dll because they are assumed to be localized satellite assemblies.

https://learn.microsoft.com/en-us/nuget/create-packages/creating-a-package#from-a-convention-based-working-directory :

lib/{tfm} : Assembly (.dll), documentation (.xml), and symbol (.pdb) files for the given Target Framework Moniker (TFM)

https://learn.microsoft.com/en-us/nuget/create-packages/supporting-multiple-target-frameworks#framework-version-folder-structure :

... you always make subfolders under lib using different case-sensitive framework names ...

... You should never have a version of the library that is not specific to a framework and placed directly in the root lib folder. ...

... To easily include all these files when building the package, use a recursive ** wildcard in the <files> section of your .nuspec:

<file src="lib\**" target="lib/{framework name}[{version}]" /> 

Answer 1

From the description, you have already found many related documents. Those should be enough to explain many things you want.

A specific gem I want to highlight is "For many packages the lib works the same way it does in NuGet 2.x,"

For this thing you want to know, you can take a look of these official documents:

Group dependencies by target frameworks of Nuget 2

And

Grouping content files and PowerShell scripts by target framework of Nuget 2