At work we're starting to use NuGet in a big way to componentise and manage dependencies between our different libraries. I remember the first time I needed to setup a package finding the process a little less than straightforward, I've just come to create the NHaml NuGet package and this time round things seem a little simpler, so here's how I've just done it, step by step.
To be clear - this is going to be a 101, beginner's level tutorial. First up, we're going to install the NuGet Package Explorer and create a basic .nuspec file from the an existing .csproj file (the .nuspec file is an XML file the tells the NuGet package command all about your package you want to make). Next we'll take a look at the generated .nuspec XML markup, tailor that .nuspec file to suit our needs, then finally generate and publish a .nupkg package file.
Step 1 - Install NuGet Package Explorer and NuGet
First step is to get ourselves over to http://nuget.codeplex.com/releases/view/59864, to download and install the NuGet Package Explorer. At the time of writing this, the current version is 3.2. Now you can use this tool to generate your .nuspec file from scratch, but just going to use it to tweak our nuspec file and publish our package. To actually create our .nuspec file, we'll use the NuGet command line tool.
There are two ways to get the NuGet command line tools installed. (Note wote we'll be going with the second option in this example, because it gives our solution NuGet Package Restore functionality)
Option 1 - Download the command line NuGet.exe from http://nuget.codeplex.com/releases/view/58939, and place it somewhere sensible perhaps in a "tools" folder in your solution folder, or somewhere global if you want to update your Path system variable, so you can just open a command line anywhere you like and type "Nuget".
Option 2 - Use the Visual Studio NuGet tools addin http://visualstudiogallery.msdn.microsoft.com/27077b70-9dad-4c64-adcf-c7cf6bc9970c. Once you've installed this addin, you'll be able to right-click any solution in Visual Studio and select "Enable NuGet Package Restore". This will not only enable NuGet package restore, it'll also automatically place NuGet exe in a ".nuget/" folder relative to your solution file.
Step 2 - Create Our Nuspec File
Now that we've got our tools installed, we need to decide what we want in our NuGet package. We want our NuGet package to be the thing that an end user will pull into their solution, and instantly be able to do something useful. In my case I have a few assemblies to choose from - I have my core NHaml view engine assembly, which on its own is just a templating engine, and I have my NHaml.Mvc solution, which includes the NHaml view engine plus the wiring to work inside any MVC project. So of course I'm going to NuGet this NHaml.Mvc project.
Now that we know what project(s) we want our NuGet file based on, let's look at how to make our .nuspec file. Again, we've got two options here.
Option 1 - Use The Tools to Help
- First open a command prompt in the same folder as your .csproj file (in my case "System.Web.NHaml.Mvc3.csproj"), and execute the following command:
- Double click on the generated .nupkg file to open it in the NuGet Package Explorer
- Click Edit -> Edit MetaData to edit things such as the description, authors, etc (note these properties originally come from any AssemblyInfo.cs files in your VS project - if they're totally wrong, fix your AssemblyInfo file first)
- Check the assemblies that already been included in your project, if anything's missing right-click and select "Add existing file"
- When you're happy with the contents of your package, from the File menu select "Save Metadata As", to save our you .nuspec file, typically alongside your .csproj file.
Option 2 - Hand Crank the File Using An Example
The above process is all well and good if you already have a feel for what's going on, or you don't want to delve too deeply into the inner workings of NuGet, but if you're anything like me and want to get a little deeper, it may actually be worth starting with the raw .nuspec XML file. In our case, the user friendly process above produced the following .nuspec file:
<?xml version="1.0" encoding="utf-8"?>
<authors>Andrew Peters,Steve Wagner,Simon Cropp,Zsolt Sz. Sztupák,Russell Allen</authors>
<description>NHaml view engine configured to work inside a Microsoft MVC3 project</description>
<file src="bin\Debug\System.Web.NHaml.dll" target="lib\net40\System.Web.NHaml.dll" />
<file src="bin\Debug\System.Web.NHaml.Mvc3.dll" target="lib\net40\System.Web.NHaml.Mvc3.dll" />
Note there's nothing too mysterious here, we've not had to delve into the territory of package dependencies since we don't have any, but for an introduction to this area try the Nuspec Reference over at http://docs.nuget.org/docs/reference/nuspec-reference
Step 3 - Create Our .Nupkg Package File
Now that we've got our .nuspec file, we can generate our .nupkg file by simply running the following command:
..\..\.nuget\NuGet.exe pack System.Web.NHaml.Mvc3.nuspec
Step 4 - Publishing Our .Nupkg Package File
With our .nupkg file built, we're ready to publish it to some sort of feed so that we can reference it from another solution. There are ways to host private NuGet feeds, for example if you're using TeamCity you can automate some of this, but I'm ready to publish this package to the official NuGet feed.
- Register for an account at http://nuget.org/
- Check your profile to find your "API Key"
- Open your newly generated .nupkg file in the NuGet Package Explorer
- From the File menu, click Publish
- Enter your API key
- Click Publish
Step 5 - Test Your Package
Of course, make sure you test your package at this point! Use it in a Hello World style example and make sure it puts the right files in the right places. If all is well, congratulations, you've just published your first NuGet package.