Creating Your Own NuGet Package

CodeGuru content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

Introduction

NuGet is a free and open source

package management system for .NET

applications. The primary goal of NuGet is to help developers simplify the process

of incorporating third party libraries into their .NET applications. There are

several NuGet packages available for you to use or you can build your own. This

step-by-step article shows what it takes to create your own NuGet package. The

package can then be submitted to NuGet Gallery or can be hosted locally.

Creating a Library That Will Go as a Package

Before you create any NuGet package you will need to create and assemble all

the pieces that go as a package. As an example, you will bundle a .NET class

library and its help file into a package. So, begin by creating a class library

project in Visual

Studio 2010. Name the project NuGetPkgLib. The class library will have

a single class named TemperatureConverter that converts temperatures from Celsius

to Fahrenheit and vice versa. The TemperatureConverter class is shown below:

namespace NuGetPkgLib

{

    public class TemperatureConverter

    {

        public decimal ToFahrenheit(decimal t)

        {

            return (t * 1.8m) + 32;

        }

 

        public decimal ToCelsius(decimal t)

        {

            return (t - 32) / 1.8m;

        }

    }

}

As you can see, ToFahrenheit() and ToCelsius() methods of the

TemperatureConverter class simply convert a supplied temperature value to

Fahrenheit and Celsius respectively. Build the class library project so that

you get NuGetPkgLib.dll assembly as the output. Also create an HTML file

(Overview.htm) that will act as a help or readme file for the class library.

Creating a NuSpec File

In order to create a NuGet package you need to create an XML file containing

metadata of the package. This file is referred as NuSpec file and has an

extension of .nuspec. Though you can create a NuSpec file manually from

scratch, here you will use the NuGet.exe command line tool for that purpose.

The NuGet command line tool can produce the NuSpec file with basic XML markup

that you can modify as per your requirements. You can download the NuGet Command

Line here. Once you download NuGet.exe in a well-known location of your

machine (say C:\NuGet) you can run the tool as follows:

NuGet.exe spec

Running NuGet command line tool with spec option generates a new NuSpec file

with basic XML markup. You can, of course, modify the markup to suit your

needs. If you run the above command in a folder where your class library

project file (.csproj) resides, then the generated NuSpec file will assume the

same name as the class library project (NuGetPkgLib.nuspec); otherwise the

NuSpec file will have name Package.nuspec. In any case the NuSpec file contains

certain XML tags. The meaning of these tags is given in the following table.

Now open the newly created .nucpec file in Visual Studio or Notepad and

modify it as shown below:

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

<package>

  <metadata schemaVersion="2">

    <id>TemperatureConverter</id>

    <version>1.0.0.0</version>

    <authors>Bipin Joshi</authors>

    <description>

      TemperatureConverter helps you convert temperatures from

      Celsius to Fahrenheit and vice a versa.

    </description>

    <projectUrl>http://www.someurl.com</projectUrl>

    <licenseUrl>http://www.someurl.com/license.aspx</licenseUrl>

    <requireLicenseAcceptance>true</requireLicenseAcceptance>

    <tags>Temperature Celsius Fahrenheit</tags>

    <iconUrl>C:\Bipin\NuGetPkgLib\NuGetPkgIcon.png</iconUrl>

  </metadata>

</package>

All the information mentioned above appears in the "Manage NuGet

Packages" option of Visual Studio 2010. The following figure shows the

"Manage NuGet Packages" dialog with NuGetPkgLib package selected.

Figure 1: The "Manage NuGet Packages" dialog with NuGetPkgLib package

selected

Notice how all the information is displayed in the main area (center of the

dialog) and information pane (right side). 

The XML markup tags shown in the above table are just the basic ones. The complete

reference of available tags can be read from NuGet website.

It would be worthwhile to note a couple of XML tags that you may need

frequently in addition to the ones mentioned above.

Your package might be dependent on some .NET framework assemblies such that

referring those assemblies in the client project is mandatory. You can

automatically add reference to .NET framework assemblies when the client

installs your package by adding the following markup:

 <frameworkAssemblies>

   <frameworkAssembly assemblyName="System.Drawing" />

</frameworkAssemblies>

As you can see, the <frameworkAssemblies> section includes one or more

assembly references (System.Drawing in this case). When a NuGet package is

installed, references to these assemblies are automatically added.

At times you may want to explicitly specify the files to be included in the

package. In such cases you can use <files> section as shown below:

 <files>

  <file src="bin\debug\NuGetPkgLib.dll" target="lib" />

  <file src="help\Overview.htm" target="help" />

</files>

In the above example only NuGetPkgLib.dll and Overview.htm files will be

copied to the target folder after the package is installed.

Build the Package

Now that your NuSpec file is ready, let’s build the package based on it. Go

in the folder where the NuGetPkgLib.nuspec file resides and execute the

following command:

NuGet.exe pack

The NuGet command line tool will then read the .nuspec file and generate a

NuGet package file having the extension .nupkg. You can also specify the

.nuspec file name explicitly as follows:

NuGet.exe pack NuGetPkgLib.nuspec

Publish the Package

Once you build a NuGet package you are ready to publish it. If you wish to

make the package available to the world then you need to publish it into NuGet Gallery. For the sake of this article,

however, you will publish the package locally so that you can use it in your

projects.

First of all, create a folder on your machine and name it as NuGetPkg. Copy

the .nupkg file generated earlier to this folder. Now, open Visual Studio and

locate Tools > Options menu item. Locate Package Manager Options and select

Package Sources.

Figure 2: Package Manager Options

Add a new package source with name My Packages and folder NuGetPkg (or

whatever you named it at your end). Adding a new package source will enable

Visual Studio to search and locate your local packages. 

Install the Package

Now that you have added a package source let’s use the package in a client

application. Create a new Console Application and name it as NuGetPkgClient.

Right click on the project in the Solution Explorer and select "Manage

NuGet Packages". Doing so will open a dialog as shown below:

Figure 3: NuGetPkgClient – Manage NuGet Packages

Select My Packages under Installed Packages and you should see the

TemperatureConverter package you created earlier. Click on the Install button

so as to install the package and associated files. The following figure shows

how the TemperatureConverter.dll assembly is added to the client application.

Figure 4: How the TemperatureConverter.dll assembly is added to the client application

Notice how reference is automatically added to NuGetPkgLib and

System.Drawing (since we specified it in NuSpec file) assemblies.

Summary

Creating your own NuGet package involves creating a NuSpec file, building a package

based on the metadata of NuSpec file and then publishing the package. A NuSpec

file is an XML file that can be generated using the NuGet command line tool –

NuGet.exe – and contains metadata of the package. The metadata of a package

includes its Id, description, version, authors, licensing URL, project URL,

tags, referenced assemblies and files. Based on the NuSpec file a package can

be built using the NuGet command line tool. The package thus created can be

hosted in the NuGet Gallery for global consumption or it can be hosted locally.