Using NuGet to spice up your development project

.NET Development anno 2010 has gotten more complex than ever before. There’s a huge load of libraries and tools you can use in your application. Each of these libraries requiring their own way of configuring them. While choice is a good thing, I can’t say it makes it any easier to develop a good piece of software. In this article I will show you a new way to manage add-ons for your development projects through the use of the NuGet package manager.

What is NuGet?

The NuGet packagemanager is an add-on for Visual Studio and PowerShell with allows you to add packages to your Visual Studio solutions. A package can be one assembly containing a useful library, but it can also be a set of libraries with configuration. As I mentioned before, you normally would configure a package yourself. With NuGet, the package manager will do that for you, saving you time getting up to speed with your development project.

NuGet contains the infrastructure to load packages into your Visual Studio projects. The community provides the packages to load. There’s a ton of projects out there that are already offering a wide range of packages. Check out the screenshot below to get a sense of how big the stack of packages is right now.

All of these packages can be used in your application. NuGet not only allows you to install packages, but it can also update packages you’re already using in your application. Which is a good thing, considering the speed at which some packages are changing these days and the amount of work that goes into updating a package by hand.

 

Using NuGet to add packages to your project

To get started using NuGet in Visual Studio you need to download the NuGet Visual Studio extension, which can be found here. It will install an extra contextmenu option in Visual Studio and a settings dialog to configure extra feeds with different packages.

Adding a package to your Visual Studio project using NuGet can be done by right-clicking on the reference element of a project and choosing Add Library Package Reference

This will give you the dialog I showed in the previous section. In this dialog you can select the packages you want and click install to add them to your project. The NuGet package manager will take care of everything, from adding references to your project to updating your web.config file.

For example, you can add the Razor viewengine to your ASP.NET MVC project by right-clicking on the webproject and select the Add Library Package Reference option. Select the online tab on the left side and type in Razor as the searchterm in the searchbox. You will see something like the screenshot below.

To install the package, click the install button. This will install the razor viewengine assemblies and update the web.config file of your application.

When you no longer need or want the Razor viewengine, you can uninstall it by opening up the Add Libray Package Reference dialog and click the uninstall button for the Razor viewengine package. This will remove the references from the project and revert the changes to the web.config file.

Note: NuGet comes with a package manager console. You can use this as an alternative to the package manager dialog. Although really powerful, it’s more a thing for the console type of guys. Check out the documentation for it here.

Creating a new package

Using the NuGet package manager is one thing, but you’re probably thinking by now: Can I add my own packages? The answer is: Yes you can. Creating a new package is done by following these easy steps.

Step 1: Get the commandline utilities

By default if you install NuGet, you will install it as a Visual Studio 2010 extension. This extension however does not allow you to author a new package. To create a new package you will need to download the NuGet commandline utilities.

Step 2: Create a filesystem structure to package

Every NuGet package is made out of a manifest file and a specific file structure. For your convenience I’ve added an image below that shows you what the filesystem structure looks like.

The easiest way to create a package is to place a set of assemblies in the root of the lib folder inside the package root folder. By doing this, you’re telling NuGet to always install these assemblies when the package is added to a project. I however, you have a package that has different assemblies for different versions of the .NET Framework, you will need to place them in framework specific folders. Check out the documentation to get more information.

A package can contain other files besides assemblies, such as configuration transforms, source transforms and content files. All these files need to be added to the content folder of the package.

The configuration transformations used in NuGet are those you’re probably familiar with from ASP.NET 4 and Visual Studio 2010. With these transformations you can add the necessary configuration sections to an existing configuration file. Check out the ASP.NET documentation for more info.

Along with configuration transformations you can use source file transformations. You can use this to add specific source files to the project when the package is added to the project through the package manager. A source file that needs to be transformed, has to end with the .pp extension. In this file you can than use template parameters that will be replaced during transformation.

Step 3: Create a manifest file

To complete the package you will need a manifest file. This file specifies what package you’re distributing along with the files that are contained in the package. A very basic manifest file looks like this:

<?xml version="1.0" encoding="utf-8"?>
<package>
  <metadata>
    <id>MyLibary</id>
    <version>1.0.0</version>
    <authors>Willem Meints</authors>
    <dependencies>
      <dependency id="sample-package" version="1.0.0" />
      <dependency id="extended-sample-packge" minversion="1.1.0" />
    </dependencies>
  </metadata>
  <files>
    <file src="binReleaseMyLibrary.Core.dll" target="libnet20"/>
    <file src="binReleaseMyLibrary.Contract.dll" target="libnet20"/>
    <file src="templatesMySourceFile.cs.pp" target="content"/>
  </files>
</package>

The metadata section of the manifest tells the NuGet package manager what kind of package it is dealing with. The files section tells the package manager where to get the files and where to put them inside the package.

Note: I think you may have noticed that the structure I described in the previous section isn’t really required. It’s perfectly fine to use any other file structure that matches your personal environment. The structure used in the previous section is merely to demonstrate what a package looks like.

For a full description of the NuGet manifest file I recommend you check out the official documentation.

Step 4: Packaging the files

Once you have the file structure you want for your package and the manifest file to describe the contents of the package, you’re ready to create the package. For this you need the nuget tool from step 1. Execute the following commandline to create the package:

nuget pack MyPackage.nuspec –OutputDirectory <Output directory> –BasePath <Root path>

The root path used is required when you specify relative folder locations for files in the package. The output directory parameter specifies where to place the package that is created.

Step 5: Publishing your package

Because NuGet is still in the pre-RTM state, there’s no official way to publish your package. To get your package out to the public and make it available inside Visual Studio 2010 you need to place it inside the mercurial repository of the nupackages project on codeplex. Once the RTM release is available, there will be an official website where you can submit your packages.

The complete guide on how to publish your package can be found on the codeplex website of the nupackages project.

Conclusion

The NuGet project is still under development, but a great source for a wide variety of open source and closed source packages. There are a lot of projects already contributing their packages to the repository. You will be amazed how easy it is to find and use the packages you want.

Just by looking at the amount of packages available and the amount of information available, I can tell that this thing is going to be big. The dark days of manually downloading packages and adding them to your projects are officially over!

Share this