Appendix B. NuGet basics

Because I use NuGet for all the demos and examples in this book, I thought it would be a good idea to go over the basics of NuGet for those who aren’t familiar with it. NuGet is a tool that has fundamentally changed the way I install, update, and use third-party libraries when writing .NET projects. It’s become one of those “how did I ever get anything done without it?” tools.

In this appendix I’ll show you how to install NuGet (if you are using Visual Studio 2012, then you already have it installed). Then I’ll show you how to use it to install packages, then how package restore works. I’m not going to attempt to document every feature of NuGet—just enough to get by in this book. Comprehensive NuGet documentation (including how to build your own packages and how to run private NuGet servers) is available at NuGet.org.

B.1. Introduction to NuGet

NuGet is an open source package manager for .NET that used to be known as NuPack. NuGet was created by a team at Microsoft and was contributed to the Outercurve Foundation. It has become the de facto package manager tool for .NET and is currently integrated with Visual Studio 2012.

B.1.1. Installing NuGet

If you don’t already have NuGet, there are just a few easy steps to install it. First, you are required to have PowerShell installed. If you are running Windows 7 or later, you already have it, otherwise you’ll need to manually install PowerShell. Second, go to NuGet.org and click the Install NuGet button to download the VSIX (Visual Studio extension) file, as shown in figure B.1. Open that file, and you will be taken through the installation process. Administrator access is required.

Figure B.1. Installing Nuget from NuGet.org

Alternatively, you can install it right from Visual Studio’s extension manager (Tools -> Extension Manager), as in figure B.2. Again, administrator access is required.

Figure B.2. Install NuGet from Extension Manager

B.1.2. Installing packages with NuGet UI

There are two primary ways to install NuGet packages while in Visual Studio: you can use the NuGet UI, or you can type commands at the NuGet Package Manager Console.

To use the NuGet UI as show in figure B.3, right-click a project’s References in the Solution Explorer. Click Manage NuGet Packages. Use the search box to search for keywords or a specific package name. For instance, you could search for NHibernate or for ORM. Once you’ve found the package you want, click the Install button.

Figure B.3. Installing a package with the NuGet UI

If the package you are installing has dependencies on other packages, NuGet will also install those. For instance, the Fluent NHibernate package has a dependency on NHibernate, so if I install Fluent NHibernate, it will check to make sure that NHibernate is already installed, and install it if it’s not.

You can also see a list of packages that you’ve already installed and update/uninstall them. Packages are installed to a Packages folder that NuGet creates. NuGet also creates repositories.config and packages.config files that tell your project where to find the dependencies (as well as how to restore them, as you’ll see later).

B.1.3. Install packages with Package Manager Console

Once NuGet is installed, you will have a new window available in Visual Studio called the Package Manager Console. To show this window, click View -> Other Windows -> Package Manager Console. As in figure B.4, you will then see a PowerShell window with a PM> prompt where you can type in commands.

Figure B.4. Opening the Package Manager Console

At this command prompt, you can get a list of commands by typing get-Help NuGet. To install a package, use the Install-Package command, with the name of the package. If you aren’t sure of the spelling, you can use the Tab key to get intellisense. For instance, if I type Install-Package PostS then press Tab, I’ll see a list of suggestions, starting with PostSharp.

Once a package installs, you should see a message like the following:

PM> Install-Package jQuery
Successfully installed 'jQuery 1.9.1'.
Successfully added 'jQuery 1.9.1' to HelloWorld.

After that, another PM> prompt will appear for further commands.

B.2. NuGet package restore

NuGet has a very convenient feature called package restore that allows you to restore a package from a NuGet repository automatically. If the actual DLL and associated files of a package are not checked into source control, for instance, NuGet will notice that the files are missing and attempt to restore them when you try to compile.

B.2.1. Solution Explorer

By default, Visual Studio 2010’s Solution Explorer only lists the solution if there are multiple projects in the solution. To change that behavior so that it always shows the solution, go to Tools -> Options -> Projects and Solutions -> General, and check the Always show solution box, as in figure B.5.

Figure B.5. Always show solution in Visual Studio

Once you do this, then you can more easily access the solution settings in Solution Explorer.

B.2.2. Enabling package restore

Now that you have the solution showing, right-click the solution in Solution Explorer and click Enable NuGet package restore (as in figure B.6). This will add a .nuget folder to your solution that contains NuGet.Config, NuGet.exe, and NuGet.targets.

Figure B.6. Enabling package restore feature

At this point, NuGet package restore is now enabled for your solution. I have enabled it on all the source code samples available for this book. Therefore, the .nuget folder is in source control (GitHub), but not the packages themselves.

B.2.3. What package restore does

Try this: install a package in your project using NuGet, then enable NuGet Package Restore, close Visual Studio, and then delete the package from the packages folder. When you open the solution in Visual Studio again and try to compile, you will get an error, because the package files that your project depends on have been deleted.

NuGet Package restore can fix this problem. In Visual Studio, go to Tools -> Options -> Package Manager and check Allow NuGet to download missing packages during build (as in figure B.7). This does exactly what it sounds like. When you try to compile, NuGet will notice that a package is missing and attempt to download the missing package files. Once NuGet is finished restoring the package, the build process will continue as normal.

Figure B.7. Enabling downloading of missing packages

This step allows you to commit everything except the package binaries to source control. Binaries can be very large, and keeping them in source control can make using a distributed version control system more difficult. The source code samples for this book, for instance, would be several hundred megabytes bigger. Using NuGet’s package restore with the samples is like lazy loading the packages: you don’t actually need them until you start compiling.