Clarification of lib vs ref & runtimes folders

[toptensoftware]

I'm hoping someone can clarify the correct usage of the /lib/ folder vs /ref/ and /runtimes/ folders.

I have a project that targets a couple of platforms, (eg: win and osx). The public api to is identical on all platforms, but the implementation on each is very different. eg: the windows build pinvokes to Win32, while the osx build uses ObjC interop.

From this documentation it sounds like the /lib/ folder should be used for platform independent assemblies and platform specific libraries the /ref/ folder should be used for compile time references and the /runtimes/ folder for the per-platform implementation assemblies. In other words you should use either:

• /lib/ OR
• /ref and /runtimes

So, I would expect this should work:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
  <metadata>

    <!-- snipped irrelevant stuff -->

    <references>
        <group targetFramework="net5.0">
            <reference file="packtest.dll" />
        </group>
    </references>

    <dependencies>
        <group targetFramework="net5.0">
        </group>
    </dependencies>

  </metadata>
  <files>
  
    <!-- net5.0 Reference -->
    <file src= ".\bin\Release\net5.0\packtest.dll" target="ref\net5.0" />

    <!-- net5.0 Runtime (Windows) -->
    <file src= ".\bin\Release\net5.0\packtest.dll" target="runtimes\win\lib\net5.0" />

    <!-- later, will be adding something like this-->
    <!-- net5.0 Runtime (OSX) -->
    <!--file src= ".\bin\Release\osx\net5.0\packtest.dll" target="runtimes\osx\lib\net5.0" /-->

  </files>
</package>

But, when building the package I get the following errors:

Error NU5018: Invalid assembly reference 'packtest.dll'. 
Ensure that a file named 'packtest.dll' exists in the lib directory.

Why? Shouldn't the files /ref and /runtimes suffice? What would the assembly in the root /lib/ folder be used for and wouldn't putting the assembly in the /lib/ folder result in the wrong assembly being used on unsupported target platforms?

Also:

• I've tried setting the reference group target framework to 'net5.0-windows7.0' but get the same error.
• I've tried changing the nuspec to also include both /lib/ folder and the /ref and /runtimes folders., but when I consume the package in a project I'm pretty sure it's using the lib folder and not the runtimes folder.
• I've tried guessing various flavors of the runtimes folder structure like : runtimes\win7-x64\lib\net5.0, runtimes\win10-x64\lib\net5.0 and runtimes\win7\lib\net5.0-windows7.0 but nuget seems insistent that something be provided in the /lib/ folder.

And finally, and perhaps most interestingly I tried this:

1. Built the package with all three /lib/, /ref/ and /runtimes/ folders
2. Opened the .nupkg as a zip file and deleted the /lib/ folder
3. Tested the package in a test project and it appears to work fine for compile, run and deploy.

Seems like nuget's error message is wrong and should allow empty /lib/ folder if there's /ref and /runtimes folders.

Am I missing something? Is there a work around for this? Any help greatly appreciated.

Using: nuget.exe version 5.10.0.7240

[zivkan]

Don't use the <references> section in the metadata. That's a packages.config-era feature, whereas the top level ref and runtimes folders are PackageReference only. In other words, <references> only works in lib/, which is where I expect the error is coming from. In PackageReference, assets under runtimes/ are never passed to the compiler, whereas assets under ref/ are only passed to the compiler, never copied to the output folder.

[toptensoftware]

Thanks for the fast reply. What you've described makes perfect sense but when I remove that section I get a warning to put it back:

WARNING: NU5131: References were found in the nuspec, but some reference assemblies were not found in both the nuspec and ref folder. Add the following reference assemblies:
- Add packtest.dll to the net5.0 reference group in the nuspec

The package seems to work fine though and at least the warning can be suppressed.

It's hard to get this stuff right when the warning is telling you to do the wrong thing. Or is it?

[zivkan]

NU5131 is encouraging you to make your package compatible for your package consumers who are using packages.config: https://docs.microsoft.com/en-us/nuget/create-packages/select-assemblies-referenced-by-projects

but by using the package's runtimes/ folder, it means the package can't be compatible with packages.config. Well, it could be, but you'd have to duplicate the work that NuGet does for the runtimes/ asset selection in your own targets file. So unfortunately as a package author of an advanced package, you need to decide whether you want to support your users who use packages.config, or if you'll only support users using PackageReference.

We should probably change NU5131 to only warn when a package is compatible with packages.config, but not PackageReference. SDK style projects don't support packages.config, and new versions of .NET can only be built with SDK style projects, hence fewer and fewer projects are going to use packages.config as time goes by. PackageReference compatibility is much more important for the future than packages.config compatibility.

For now, I suggest you <NoWarn>NU5131</NoWarn>

[toptensoftware]

Hi Andy. Thanks for your explanation of this. This is a private package that only needs to support SDK style projects so <nowarn> will suffice.

btw: the article you linked to mentions a /runtime folder. I presume that's a typo and they mean /runtimes?

[levicki]

@zivkan This error message tripped me up too.

Can you please clarify whether AnyCPU (i.e. compile-time) assembly should go to ref or lib?

[zivkan]

Assemblies in both ref/ and lib/ should be AnyCPU. Architecture specific assemblies should only go in runtimes/, ideally.

NuGet selects assemblies under ref/ to send to the compiler, and if there are no ref/, then it uses lib/. The compiler complains when the current project's architecture is different to the package's.

NuGet selects runtimes/ files to copy to the output (bin/) directory after the build (technically the SDK does, NuGet just tells it these are the runtime files), and if there are no runtimes/ files, then it uses lib/.

So, if you use lib/, then projects using packages.config can use your package, but it will only use those lib/ files, as packages.config doesn't know anything about ref/ or runtimes/.

If you want to make your package compatible with PackageReference only, then use refs/ and runtimes/, and don't use lib/ (and nowarn NU5131)

Since this question was originally asked in 2021, I wrote these docs, which I hope helps: https://learn.microsoft.com/en-us/nuget/create-packages/native-files-in-net-packages

[levicki]

This isn't about native files though. It is just about producing an library which has both x86 and x64 version and AnyCPU is there for designer since it is a Form.

<dependencies>
<group targetFramework=".NETFramework48" />
</dependencies>
</metadata>
<files>
<file src="bin\x86\Release\net.levicki.ModernApp.dll" target="runtimes\win-x86\lib\net48\net.levicki.ModernApp.dll" />
<file src="bin\x64\Release\net.levicki.ModernApp.dll" target="runtimes\win-x64\lib\net48\net.levicki.ModernApp.dll" />
<file src="bin\ref\Release\net.levicki.ModernApp.dll" target="ref\net48\net.levicki.ModernApp.dll" />
<file src="LICENSE.md" target="LICENSE.md" />
</files>

This is what I did in the end, but the warning tripped me.

[zivkan]

This isn't about native files though

The title of the doc was intended to increase the chance that people will find it when googling, as my experience is that the vast majority of questions I saw around this space were from people creating packages that P/Invoke into native libraries.

The doc is really about the lib/, refs/ and runtimes/ directories. If you have a suggestion for a better title for the docs page, we can update it.

[levicki]

I read it, it is pretty long and convoluted (because nuget and .Net after all are complex) and it seems that all examples are for .Net 5.0+.

However, .Net Framework 4.8 is still so widely used that it won't be going away anytime soon.

As an example of why I am bringing that up, just a few days ago NCR Corporation finally released an update for their NCR APTRA ATM and kiosk software and guess what? They updated .Net 4.5 to .Net 4.7.2 if I am not mistaken.

They have a huge amount of libraries and dependences and tools, not to mention that any compiler and tooling upgrades require software recertifications which is hideously expensive in banking industry (same goes for medical and many other sectors).

Wishing that people will drop .Net 4.8 and switch to .Net 10.0, not keeping tooling parity, and not providing examples for .Net 4.8 isn't really helping anyone. This isn't meant as criticism directed towards you or your work, just stating the (hopefully) obvious.

This example from your docs in particular is weird:

Contoso.Native.1.0.0.nuspec
ref/net8.0/Contoso.Native.dll
...
runtimes/win-x64/lib/net8.0/Contoso.Native.dll
runtimes/win-x64/native/contoso.dll

1. Why is Contoso.Native.dll called Native when it's presumably bytecode?
2. Why is lib folder containing Contoso.Native.dll, but native folder is containing contoso.dll? What does native even mean in this convoluted context?

To me, native always meant and always will mean x86/x64 CPU code, not IL. It also implies not managed to people who use a lot of P/Invoke and C++/CLI like I do so the example is actually confusing. IMO, .Net assemblies shouldn't have Native in the name unless they are Native AOT in which case that should be clearly stated.

Finally, I think there should be an example for .Net Framework 4.8 with different platforms, at least some common cases.

1. Including x86 and x64 native DLLs for say 7-Zip (7za.dll) and providing x86 and x64 managed libraries that use them.
2. Including x86 and x64 managed libraries which use say WinForms (I wasn't aware you also need to include AnyCPU for DesignTime).

Hope that helps.

[alex-vander-tuig]

@zivkan , I've encountered the following behavior and I am wondering if you can clarify if this is the intended behavior or not:

Let's say I have a nuget package that contains 3 dlls:
AssemblyA.dll that targets net10.0 and compiles as AnyCpu
AssemblyB.dll that targets net10.0-windows and compiles as AnyCpu
AssemblyC.dll that targets net10.0-windows and compiles as x86 & x64

Based on the documentation and examples, I would believe that the correct format of the Nuget package would be as follows:

• lib/net10.0/AssemblyA.dll
• runtimes/win/lib/net10.0/AssemblyB.dll
• runtimes/win-x86/lib/net10.0/AssemblyC.dll
• runtimes/win-x64/lib/net10.0/AssemblyC.dll
• ref/net10.0/AssemblyB.dll
• ref/net10.0/AssemblyC.dll (I understand this should be an AnyCpu build)

What I've found is that if another project uses this Nuget package, it will compile as expected. However, at runtime on a Windows x64 machine, the only assembly that will be found is AssemblyC.dll. When trying to use a type in AssemblyA.dll or AssemblyB.dll, a FileNotFoundException will be thrown. The runtime behavior is as though if a runtime folder of best fit exists for a given Nuget package, it will only look there at runtime for ALL assemblies in the Nuget package.

The other assemblies are copied correctly to the expected locations in the /bin folder. If I delete the application's deps.json file (or just the runtimeTargets value for the package within the deps.json file), then AssemblyA.dll types are resolved because the assembly is within the same folder as the executable.

Effectively, there is no "fallback" to the executable's folder for AssemblyA.dll or runtimes\win folder for AssemblyB.dll. The workaround is to duplicate AssemblyA.dll and AssemblyB.dll into runtimes/win-x86 and runtimes/win-x64, and add AssemblyA.dll to the ref folder.

Is this the intended behavior?

[zivkan]

All of this was designed and implemented years before I joined NuGet, so I can't say whether it's by design. All I can say is this is how it works.

The risk of breaking someone if this was to change is pretty high, so I doubt we'd ever change it. Especially when our official guidance is 1 assembly per package, so you can put AssemblyA.dll in another package and make it a dependency of your current package.