Portable Class Libraries and NuGet lib folders

PCLs and NuGet lib folders.md

(This is in response to the conversation started by this tweet asking why the portable HttpClient package has platform-specific library folders in addition to the portable folder.)

Sometimes in a portable library you want to be able to call APIs that aren't portable. The functionality may be exposed differently on different platforms, or you may want to "light up" and take advantage of functionality on platforms where it's available. Here are some blog posts about how to do this:

• Using Target-Specific Code in a Portable Library
• How to Make Portable Class Libraries Work for You
• Portable Class Library Enlightenment / Adaptation

Also, see my PCL Storage library for an example of a slightly different way to do this.

So when you do this, you end up with multiple DLLs, generally one Portable Class Library, and one DLL for each platform you light up on. When you create a NuGet package, PCLs should reference the PCL DLL, and platform-specific projects should reference the PCL plus any platform-specific DLLs for that platform. When you reference a NuGet package, NuGet chooses the "best" matching lib folder and your project will reference all the DLLs in that folder. It will never add references to DLLs from multiple different folders (that would be harder to reason about and unexpected in a lot of cases), so the platform-specific lib folders in the NuGet package include both the portable DLLs as well as the platform-specific DLLs for the platform they are targeting.

This also means that you need to reference these NuGet packages from any platform-specific projects that reference a PCL that references the package. For example, if you have a solution with a Portable Class Library which is referenced by a desktop .NET app, a Windows Phone app, and a Windows Store app, and the PCL references HttpClient, then each of the platform-specific projects need to also reference HttpClient. This is because the PCL project only gets a reference to the PCL pieces of the HttpClient library, but the platform-specific projects need to reference the DLLs specific to each platform. We are thinking about some changes to NuGet that would make this unnecessary. For now, we work around it for the .NET Framework NuGet packages by giving you build warnings when a reference is missing.

Thanks i always wondered this.

@LuisAlbertoPenaNunez also recommended reading is http://log.paulbetts.org/the-bait-and-switch-pcl-trick/

Is it common, reasonable, or even expected that a bait-and-switch NuGet package support being consumable from a PCL? If so, how should the NuGet package be setup?

Thanks.