What is NuGet?

clip_image001

From the NuGet website:

NuGet is a Visual Studio extension that makes it easy to install and update open source libraries and tools in Visual Studio.

Installing NuGet

Method 1: NuGet comes with ASP.Net MVC3

The easiest way would be to have Visual Studio 2010 (any version, even Visual Studio Express is supported) installed, NuGet comes with it. You can easily get ASP.Net MVC3 from the ASP.NET MVC website or with the Microsoft Web Platform Installer. But of course, you can also use NuGet if you’re not developing ASP.Net MVC3 applications.

Method 2: Using the Extension Manager

The second way you can obtain NuGet on your system is by using the Visual Studio Extension Manager. Search in the Online Gallery for the NuGet Package Manager and hit the “Download” button.

ScreenShot001

ScreenShot002

After a restart of Visual Studio the Library Package Manager is available in the Tools menu.

ScreenShot001

Method 3: From the NuGet website

It can hardly be easier, just go to the NuGet website, and click the “Install NuGet” button. This will lead you to the NuGet Package Manager on the Visual Studio Gallery MSDN site click the “Download” button to initiate the installer.

ScreenShot002

This will pop up the same installer as described in the previous method.

Managing Packages

There are 2 ways you can manage packages. The easiest way is by using the Add Library Package Reference GUI. The other way is by using PowerShell commands in the Package Manager Console. In either way you can achieve the most common tasks. The PowerShell method is useful when you don’t have a solution open or when you need commands that are only available as PowerShell commands.

Finding a package using the Add Library Package Reference Dialog

Right-click References in your project, select Add Library Package Reference and look online in the NuGet official package source for the library you want to add to your project.

ScreenShot003

After you hit the Install button, the library will be added to your project.

ScreenShot003

ELMAH (Error Logging Modules and Handlers) is an application-wide error logging facility that is completely pluggable. It can be dynamically added to a running ASP.NET web application, or even all ASP.NET web applications on a machine, without any need for re-compilation or re-deployment.

As you can see, there is a new reference to the Elmah binary added to our project. And if you open the web.config file, you will see that the package installer added the required configuration settings for you.

ScreenShot004

Note: OK, I cheated in the samples above. If you install the 1.2 version (latest at the moment of writing) from the repository, the web.config transformation was removed, and installed the 1.1 version instead using the Package Manager Console.

NuGet is also able to determine if your library has dependencies on other libraries and will install or upgrade them if they are not already installed. All on one single click Smile

ScreenShot004

ScreenShot005

Removing a package

Removing a package is as easy as opening the Add Library Package Reference screen, selecting the Installed packages and hitting the Uninstall button. Et voilà, NuGet does not only remove the libraries, but also cleans up the web.config for you.

ScreenShot005

Updating a package

After a while, you will notice that some packages have been updated in the repository. If you want the updated versions in your project, open up the Add Library Package Reference screen, select Updates and see which packages have updates available. Clicking the Update button of a package will update your project to the latest version.

Finding a package using the Package Manager Console

Anything you did before with the Add Library Package Reference GUI can also be done with the command line. Open up the Package Manager Console PowerShell, start typing a command and hit the TAB button. Yes, the Package Manager Console supports intellisense!

To search for a package, use the Get-Package command (with –Filter or you will get a list of all the packages in the repository):

ScreenShot007

To install a package, use the Install-Package command, followed by the package name. You can even use autocomplete in the package name!

ScreenShot008

Removing a package

How about trying the command Uninstall-Package followed by the package name. Would that uninstall the package?

ScreenShot009

Yes it does! Smile

Updating a package

Then would the command Update-Package update a package just like that?

ScreenShot010

Man, this is easy…

Packages folder

Now, to better understand what happens when we install a package, we can take a look in the packages folder that NuGet has created in our solution’s folder:

ScreenShot011

You can see that a package folder contains several subfolder of which the lib folder is the minimal requirement, that’s where your assembly dll is. In this example of the SqlServerCompact EntityFramework package, we have also a Content folder with an App_Start subfolder, which contains script that runs every time the application starts. And that’s also why the package has a dependency on the WebActivator package.

Any structure of folders and files can be placed in the Content folder, they will be copied in the same structure to your project’s folder. Use this when you want to include JavaScript, CSS, images, or any other file in the project.

This example also contains a tools folder where you can place PowerShell scripts that automatically run when the package is installed or removed.

When we take a look at the NewtonsoftJson package, we can see that the lib folder can also contain subfolders to support multiple .NET Framework versions and profiles. Although this is not a requirement, it can help to better target your package and optimize your code for different frameworks. The NuGet package installer automatically selects the correct version of the assembly in the package.

ScreenShot012

Note: The WebActivator package allows other packages to execute some startup code in web applications by creating an App_Start folder in your project and executing the code that’s inside it. The NuGet documentation details the requirements to use the WebActivator.

NuGet Package Explorer

Another way to look at packages is by using the NuGet Package Explorer application. This is a separate tool that can be downloaded from the NuGet CodePlex page at http://nuget.codeplex.com/releases/view/59864.

This tool gives you all the information that is in the package spec (metadata) file and the package content.

With the Package Explorer you can also edit the package metadata, if you’re not fond of editing the XML spec file. More on that in the next chapter about creating packages.

ScreenShot013

Creating and Publishing Packages

When you want to create and publish packages, you also have the choice between using a GUI, the Package Explorer, and using the command line.

Creating a NuGet package from the command line

First, we need to download the NuGet Command Line from http://nuget.codeplex.com/releases/view/58939, and make sure the NuGet.Exe is in our path.

Let’s create a really straightforward assembly:

ScreenShot014

Before we can create our package, we need to create a Package.spec file; this is the file that contains all the metadata of our package:

ScreenShot015

This is basically a template which you’ll have to modify by yourself. A better way would be to add an AssemblyInfo.cs file with your assembly metadata to your project and include it when compiling the assembly.

ScreenShot017

ScreenShot018

As you can see, you can add or link to a license or license file, a url for an icon, tags, dependencies to other packages and so on. Omit them if you don’t need them. Open it up with the Package Explorer to see the details.

When you build the package with the “nuget pack” command, we get a package file with the version number from the nuspec file, this allows us to differentiate every version we make.

Creating a NuGet package with the NuGet Package Explorer

Everything we did with the NuGet Command Line can also be done with the NuGet Package Explorer. Open up the NuGet Package Explorer, select File – New, and edit your package metadata and contents.

ScreenShot019

The result is the same package, created with another tool. Choose which one fits you best, the NuGet Command Line or the NuGet Package Explorer.

Exploring a NuGet package with the NuGet Package Explorer

A NuGet package is essentially a zip file, so you can extract it and explore its contents. When you extract a package, you see the nuspec file is also included. When you open it with the NuGet Package Explorer, you can see the metadata and contents of the package.

Take a look at the ELMA package:

ScreenShot021

ScreenShot023

File and source code transformations

Often we need to add code to our project, or execute some script after we referenced an assembly and before we can start using it, think of configuration in web.config, or add references to our project.

This is where NuGet gives us Source Code Transformations. The idea is to add a file to your package with just the transformations you need to make to the project’s source file, append it with “.transform” and place it in the Content folder, or any subfolder as it would sit in your project. NuGet than takes that file and merges it with any existing file.

For example the Elmah package needs to add some configuration sections and an HttpHandler to the web.config file. It does this by including a web.config.transform file with just these entries that it needs to add. NuGet will take this file and merge it with the application’s web.config file. Even nicer is that when you decide to remove the Elmah package, NuGet is able to clean up the web.config for you!

ScreenShot024

By adding PowerShell scripts to the Tools subfolder of you package, you can do about anything, not only add install or uninstall of your package, or when the application starts up, possibilities go far beyond that. A good example is the MvcScaffolding package, you should definitely add this and take a look at the package, there is really nice stuff in there.

Publishing your own NuGet packages

One way to publish your packages, besides of pushing them to the official NuGet server at http://nuget.org, is to setup a shared (network) folder. You can do this in the Package Manager Settings dialogue, under Package Manager – Package Sources. Now you have a new package source available when you open the Add Library Package Reference dialogue.

Another way is to create a new empty web application and add the NuGet.Server application. This will download all the required software to setup your own NuGet server. The packages you add to the Packages subfolder of this web application become available in the package feed when you start the application.

The NuGet.org server itself, is an instance of Orchard, so you could set it up in that way, refer to the extensive documentation of Orchard.

Links: