Deploying Silverlight assemblies via NuPack

Yesterday there was quite a buzz around something Microsoft just released called “NuPack” which is described as:

NuPack is a free open source package manager that makes it easy for you to find, install, and use .NET libraries in your projects. It works with all .NET project types (including, but not limited to, both ASP.NET Web Forms and ASP.NET MVC).

NuPack enables developers who maintain open source projects (for example, projects like Moq, NHibernate, Ninject, StructureMap, NUnit, Windsor, RhinoMocks, Elmah, etc) to package up their libraries and register them with an online gallery/catalog that is searchable.

It’s a pretty cool mechanism for getting .NET libraries.  For other open source developers this concept isn’t something new (i.e., gems).  But for .NET developers it might be because it is a difference from the way we typically have received dependent and 3rd party assemblies for our projects.  It provides a PowerShell script mechanism for adding packages as well as the well-known “Add Reference” gesture for VS developers.

All the initial information around NuPack has been from folks like Scott Guthrie, Phil Haack, David Ebbo, etc.  You might recognize these names from the ASP.NET world.  In fact if you do your first “list-package” command you’ll see a lot of ASP.NET-related packages.  If you didn’t know any better and weren’t an ASP.NET developer you might ignore this.  However, NuPack is for everyone!

One of the most commonly installed items for Silverlight developers after the toolset is the Silverlight Toolkit.  It is a plethora of controls that frankly you probably can’t live without (at least one of them) if you are developing a broad Silverlight application.  After spending a few minutes reading on NuPack I decided to explore.

My initial playground – Building the MyNuLibrary package

I first just wanted to play around and created a Silverlight class library MyNuLibrary.  It has one class Math that just has two functions.  The contents is pretty much irrelevant here.  I wanted to create a package for this and test it out.

In my project structure I decided to put the tools in the project.  To be clear, this felt completely wrong.  My “tools” shouldn’t be a part of my project.  I think this will be resolved with better build task integration, but for now to create a package you need the NuPack.exe tool.  I put that and NuPack.Core.dll in a Tools folder in my project.  I then created my manifest (MyNuLibrary.nuspec) file as follows and put it in the root of my project (marking the build action as None of course):

   1: <?xml version="1.0" encoding="utf-8"?>

   2: <package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">

   3:     <metadata>

   4:         <id>MyNuLibrary</id>

   5:         <version>1.4</version>

   6:         <authors>

   7:             <author>Tim Heuer</author>

   8:         </authors>

   9:         <language>en-US</language>

  10:         <description>Custom Silvelright Math library</description>

  11:     </metadata>

  12:     <files src="bin\debug\MyNuLibrary.dll" target="lib\SL4" />

  13: </package>

You can see that the <files/> node tells the package where to put things.  Notice the lib\SL4 target attribute value.  This tells NuPack (and installers of the package) that this library is really targeting Silverlight 4 (uses TargetFramework value of the source project when installing the package to verify).  There is more information on the NuPack project site about this.

Since my tools were relative to the root I needed to provide the bin\debug path in the source attribute value.  Initially this caused me problems as the NuPack.exe unmodified then bundled them into lib\SL4\bin\debug\MyNuLibrary.dll path.  When installing (using add-package) it failed because it said it couldn’t find any assembly that would match my project.  Apparently right now NuPack expects binaries to be in the framework folders, but not in tree structure.  For me, I modified PathResolver (in NuPack.Core):

   1: if (actualPath.StartsWith(basePath, StringComparison.OrdinalIgnoreCase))

   2:     {

   3:         //packagePath = actualPath.Substring(basePath.Length).TrimStart(Path.DirectorySeparatorChar);

   4:         packagePath = Path.GetFileName(actualPath);

   5:     }

   6:     else

   7:     {

   8:         packagePath = Path.GetFileName(actualPath);

   9: }

for my needs.  I’ve communicated the issue to some folks on the NuPack core team and I think there may be some changes (I haven’t submitted a patch yet until I understand the need for the original code path).  And yes, I realize my change above effectively makes the if…else do the same thing and thus the if…else isn’t needed.  Again, I’m awaiting confirmation of the valid scenarios before submitting what I think the patch should be.

All that aside, I then added a post-build event to my project (note I added quoted params here which is not in the CodePlex documentation sample – if you don’t use quotes and you have spaces in your paths, then your post-build will fail…adding the quotes saves you time):

   1: "$(ProjectDir)Tools\NuPack.exe" "$(ProjectDir)MyNuLibrary.nspec"

And upon build I now have a MyNuLibrary.1.4.nupkg file as an artifact of my build.  Done!  If we look at the contents (it’s actually just a OPC ZIP file we can see the structure and you’ll notice that our binary is in the lib\SL4 folder.

Surfacing MyNuLibrary package

The next step is to have your package visible somewhere.  The NuPack VS shell and the Add Reference dialog can recognize 2 types of paths: an Atom feed or a local directory.  For testing I just used a local directory using the settings in VS:

And then when I run list-package it shows only my packages from that “feed”:

Now I can consume it.

Consuming MyNuLibrary package

Now I can start a new Silverlight project and open up the VS Package Window and initiate a command to add the package.  I call add-package MyNuLibrary and see that my Silverlight project gets the reference automatically included in my project (and the literal binary is placed alongside my solution for the reference path):

And I’m done.  Pretty cool.  Any updates I (as the library author) would just update my .nuspec file to the new version, generate a new package, and publish it again.  The app developer can initiate update-package MyNuLibrary and get the updated bits.

Real world – Silverlight Toolkits

While my above exercise was interesting and demonstrated that NuPack could be used for Silverlight projects as well (ahem, SilverlightContrib) I thought I’d explore a more useful sample.  I took the Silverlight Toolkit binaries and packaged them up for NuPack.  Here was my manifest:

   1: <?xml version="1.0" encoding="utf-8"?>

   2: <package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">

   3:     <metadata>

   4:         <id>SilverlightToolkit</id>

   5:         <version>4.0.40413.2020</version>

   6:         <authors>

   7:             <author>Microsoft</author>

   8:         </authors>

   9:         <language>en-US</language>

  10:         <description>Silverlight Toolkit providing a set of controls</description>

  11:     </metadata>

  12:     <files src="Binaries\System.Windows.Controls.Toolkit.dll" target="lib\SL4" />

  13:     <files src="Binaries\System.Windows.Controls.Input.Toolkit.dll" target="lib\SL4" />

  14:     <files src="Binaries\System.Windows.Controls.Layout.Toolkit.dll" target="lib\SL4" />

  15:     <files src="Binaries\System.Windows.Controls.Data.Toolkit.dll" target="lib\SL4" />

  16:     <files src="Binaries\System.Windows.Controls.DataVisualization.Toolkit.dll" target="lib\SL4" />

  17: </package>

Since the source code is available for the toolkit I just used that base (hence the “Binaries”) folder name in the manifest.

The end result is me being able to include the Silverlight Toolkit and referencing it in one step rather than downloading, installing the MSI, and adding references.  Here’s a quick video of how simple that was:

Awesome huh?  Now I could (and probably should have) actually made these independent packages so you could only get the Visualizations if you didn’t need anything else…and then could use the dependency feature of NuPack if needed.

Notice how I also did the Silverlight for Windows Phone Toolkit as well and that it automatically added the Icons for the ApplicationBar in my project as well.  That was due to a helpful tip from Phil about naming conventions in the package.

Summary

I think NuPack is pretty cool  Yes, flame away that it is nothing new conceptually.  That’s fine.  However the interation into the tool I use most is great and that I don’t have to go to a different console window and then back and forth.  That level of integration is pretty slick.

Will the Silverlight Toolkit(s) be deployed like this?  Who knows, right now it is just an experiment.  But it was pretty cool to see it all working as expected.  I think for an alpha view of the process it’s pretty good.  Oh and if you want IntelliSense on the nuspec file, they’ve published the schema so you can put that in a text file (nuspec.xsd) and place it in your %ProgramFiles%\Microsoft Visual Studio 10.0\Xml\Schemas directory.  Then notice my xmlns that I have in the snippets above?  Adding that will give you IntelliSense on the file format.

Hope this helps!