Do all intermediate target framework versions have to be specified in NuGet packages?

Question

The NuGet documentation on enforced package conventions explains:

NuGet copies assemblies from only a single library folder. For example, suppose a package has the following folder structure:
\lib
    \Net20
        \MyAssembly.dll (v1.0)
        \MyAssembly.Core.dll (v1.0)
    \Net40
        \MyAssembly.dll (v2.0)
When the package is installed in a project that targets the .NET Framework 4, MyAssembly.dll (v2.0) is the only assembly installed. MyAssembly.Core.dll (v1.0) is not installed. (One reason why NuGet behaves this way is that MyAssembly.Core might have been merged into version 2.0 of MyAssembly.)

In this example, if you want MyAssembly.Core.dll to be installed in a project that targets the .NET Framework 4, you must include it in the Net40 folder as well as in the Net20 folder.

The rule about copying assemblies from only one folder also applies to the root lib folder. Suppose a package has the following folder structure:
\lib
    \MyAssembly.dll (v1.0)
    \MyAssembly.Core.dll (v1.0)
    \Net40
        \MyAssembly.dll (v2.0)
In projects that target the .NET Framework 2.0 and the .NET Framework 3.5, NuGet copies both MyAssembly.dll and MyAssembly.Core.dll. But as was true of the previous example, in projects that target the .NET Framework 4, only MyAssembly.dll *from the *Net40 folder will be copied.

So, for the second example, an explanation is provided what happens when loading the package into .NET 3.5 projects.

Unfortunately, this information is missing for the first example. What files will .NET 3.5 projects get from the NuGet package shown in the first example? Will .NET 3.5 projects simply get no files, or will they get the library targeted at the highest framework version supported by backwards compatibility in the target project (for .NET 3.5 projects, this would mean the .NET 2.0 version of the library)?

There are two concrete implications of why I am interested in this question: Assume I am providing an assembly for which I have compiled a .NET 2.0 version (which should be used for all .NET Framework versions from 2.0 to 4.6), and a .NET 4.6.1 version (using some new BCL API introduced in .NET 4.6.1, meant to be used in .NET 4.6.1 and higher).

1) Can I simply declare the two "key" versions in the .nuspec file:

<file src="net20\MyLibrary.dll" target="lib\Net20"/>
<file src="net461\MyLibrary.dll" target="lib\Net461"/>

or do I have to list all intermediate supported versions:

<file src="net20\MyLibrary.dll" target="lib\Net20"/>
<file src="net20\MyLibrary.dll" target="lib\Net35"/>
<file src="net20\MyLibrary.dll" target="lib\Net40"/>
<file src="net20\MyLibrary.dll" target="lib\Net403"/>
<file src="net20\MyLibrary.dll" target="lib\Net45"/>
<file src="net20\MyLibrary.dll" target="lib\Net451"/>
<file src="net20\MyLibrary.dll" target="lib\Net452"/>
<file src="net20\MyLibrary.dll" target="lib\Net46"/>
<file src="net461\MyLibrary.dll" target="lib\Net461"/>

?¹

2) Likewise, once I have published this package, will it work for future versions of the framework, or will I need to update the package as soon as there is .NET 4.6.2, 4.6.3, 4.7, or in general, anything greater than .NET 4.6.1?

Please be aware that I am asking only one question. I have merely written it down in three different ways to illustrate its significance.

¹: This enumeration is based on the list of supported target frameworks at the time of writing. Furthermore, note that I do not want to support .NET 1.1 (nor any other frameworks), hence I do not want to add any libraries directly to the lib folder as shown in the second example in the documentation cited above.

Matt Ward Matt Ward · Accepted Answer · 2016-06-19T15:05:16

With a NuGet package containing:

\lib
    \Net20
        \MyAssembly.dll (v1.0)
        \MyAssembly.Core.dll (v1.0)
    \Net40
        \MyAssembly.dll (v2.0)

If the above is installed into a project that targets .NET 3.5 then the assemblies from the Net20 folder will be referenced. NuGet will pick the target .NET framework version which has the same version or older since it considers all these versions compatible.

So you do not need to have a directory in the NuGet package for every framework version.

The general rule is that your NuGet package should have directories only for those frameworks for the assemblies you include actually target. When a newer version of the .NET framework is released the NuGet package can still be used. So in your second example I would just create the NuGet package using the simpler .nuspec file:

<file src="net20\MyLibrary.dll" target="lib\Net20"/>
<file src="net461\MyLibrary.dll" target="lib\Net461"/>

Do all intermediate target framework versions have to be specified in NuGet packages?

1 Answers