NuGet: references to assemblies in runtimes folder not added

by

This is what I’ve finally figured out/guessed (because as best I can tell there’s no official documentation for some of this)

  • Files added to the /runtimes folder aren’t automatically added as references to the target project.
  • The /ref and /runtime folder should be used in conjunction with each other and only for the .NET Core target. As best I can .NET Framework targets apparently don’t support these folders.
  • The /ref folder is for compile time references and anything added here will be added as a reference to the target project.
  • Assemblies in the /ref folder don’t need to have an implementation – every public API could just throw a not implemented exception. In practice however you typically just take a copy of one of the implementation assemblies and declare it as the compile time API.
  • I’ve read (but haven’t tested myself) that assemblies in the /ref folder must be “Any CPU” builds. You can use CorFlags utility to patch an implementation assembly for this if necessary.
  • The /runtimes folder is used to provide an implementation assemblies for any references included in the /ref folder. These assemblies are used at runtime and during deployment.
  • The /runtimes folder can include additional assemblies that are only required at runtime and don’t need to be seen by the client project. These additional assemblies won’t be included as references in the target project but will be available for run/deployment.
  • As mentioned by others, the files in the /runtimes folder aren’t copied to the output folder of the build. Instead config files are placed there that tell the runtime how to locate the /runtimes files from the NuGet cache.
  • For .NET Framework targets (ie: net461) just use the /lib folder as there’s no other runtimes for .NET aside from Windows anyway.

Putting this all together, my original example, should have looked like this:

/lib/net461/myassembly.dll                       (net461/Windows Compile and Runtime)
/runtimes/osx/lib/netcoreapp2.0/myassembly.dll   (netcore/OSX Runtime)
/runtimes/win/lib/netcoreapp2.0/myassembly.dll   (netcore/Win Runtime)
/ref/netcoreapp2.0/myassembly.dll                (netcore/* Compile Time)

Leave a Comment