James Montemagno
James Montemagno

Live, Love, Bike, and Code.



Portable Class Library Tips and Tricks

James MontemagnoJames Montemagno

There has been a recent explosion of PCL use since Microsoft and Xamarin added official support for Xamarin.Android and Xamarin.iOS. It is really amazing to have one project that is shared completely across Android, iOS, and all of the Windows platforms. I have blogged before about how to get “fake” PCL support, but I wanted to give an updated post on how to get up and running with a bunch of tips as well.

It is important to remember that there is nothing special you need to do to get PCL support. If you copied over dlls or added xml files you should remove all of this and just use the Stable branches of Xamarin to get official support.

What is a PCL and what are profiles?

A PCL is a portable class library which is a project template inside of VS and XS which allows you to select platform targets that the project will be compatible with. This is amazing because you have one project that works everywhere. PCLs have actually been around since VS 2010, but they have always been locked into Windows specific platforms, but that all changed last November when Microsoft and Xamarin announced a major partnership which included PCL support for Xamarin.Android and Xamarin.iOS apps. PCLs use these things called “profiles”, which are actually supposed to be hidden from developers, but you will see them everywhere. Profile numbers are a peek into what platforms the PCL supports and how NuGet handles PCL support when installing. There are several parts to a profile such as net45, wp8, and now monotouch and monoandroid. PCLs work a bit interestingly which is that the DLss that are in the .NET subset are actually more like stub methods or interfaces that you are developing against. The DLL that gets used is the DLL that is included in the base project. This still puzzles me a bit and I am not a Microsoft PCL compiler expert like Daniel Plaisted, so you can ask him tons of questions on Twitter.

Tips & Tricks

  1. Remember that PCLs are platform independent. Not all APIs will be available to you.

  2. Don’t try to put platform specific code in a PCL, that is now what they are for. Abstract all platform specific code with interface that you implement on each platform

  3. PCL’s are great for large or small libraries, try to break your project up into small re-usable components. For instance I have a Settings PCL that is cross platform compatible that I reuse on every project. Growing a large PCL is fine, but try to think about how you can reuse code on more projects

  4. Choose only the targets you want to support. The more you select the smaller the subset of .NET you will get. If you select Windows Phone which doesn’t have HTTPClient you will not get access to it.

  5. Use NuGet to fill in the gaps. If you need to use a specific PCL profile be sure to search NuGet to see if there is something to fill in the missing functionality such as HTTPClient or PCL Storage.

  6. Recommendation is to leave out Silverlight and Windows Phone if you are not currently developing for these platforms as they will limite your APIs.

  7. This means use Profile 7 or Profile 78 for your projects based on your needs.


Here is a short guide on how to create your first PCL:

Visual Studio

Inside of Visual Studio it is easy to create a PCL by simply selecting File->New Project -> C# -> Portable Class Library.

When you select this you will see a dialog pop up asking you what platforms you wish to support.

That’s it you are good to go. As you can see they hide the “Profile” from you, but if you expand your References folder and select the .NET Subset DLL you will see in the path a specific profile that you are using.

Xamarin Studio

Similar to Visual Studio you will create a new PCL by selecting File->New Project -> C# -> Portable Library:

Now instead of popping up the target dialog like Visual Studio does you need to actually edit the project properties to specify the correct PCL Profile:

PCL/NuGet Issues

All PCLs and NuGets are not created equal and you will need to do some testing that is for sure. One issue that a lot of people might run into is with Json.NET that has an official Xamarin Component and also an official NuGet as well. While the NuGet does have official support for Xamarin.iOS and Xamarin.Android and issue does comes up if you are using profiles that include .NET 4.5, which is that Json.NET will install a newer version that is including System.Runtime.Dynamic, which is not supported in Xamarin.iOS. This means that that NuGet in general just will not work. There are a few work around for this and I recommend simply installing the Json.NET component in both the Android and iOS project and then manually referencing this DLL (iOS or Android it doesn’t matter) in your PCL. The only thing you will really miss is the DeserializeAsync, which you can create your self easily by wrapping it in a Task. This may change in the future as I have been working with James to get this fixed, but this can be the case with any NuGet out there so be careful.

I hope this helps you get up and running with PCLs. I love PCLs because they are awesome so always feel free to reach out to me on Twitter with questions.


Live, Love, Bike, and Code

Checkout my monthly newsletter that you should subscribe to!