Creating Your Own NuGet Package

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.

XML Tag

Description

id

A string that acts as a unique identifier for your package. e.g. MyFirstNuGetPkg

description

Description of the package

version

Version number of the package e.g. 1.2.3.4

authors

A comma separated list of authors of the package.

owners

A comma separated list of the package owners.

licenseUrl

A URL pointing to the license agreement for the package.

projectUrl

A URL pointing to the web page of the package.

iconUrl

A URL for the image to use as the icon for the package. The icon file should be a 32x32 pixel .png file with transparent background.

requireLicenseAcceptance

A Boolean value (true / false) that specifies whether the consumer of the package needs to accept package licensing terms before the package is installed.

tags

A list of keywords separated by space character relevant to the package. Used while searching for a package.

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.

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.

Package Manager Options
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:

NuGetPkgClient - Manage NuGet Packages
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.

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.



About the Author

Bipin Joshi

Bipin Joshi is a blogger and writes about apparently unrelated topics - Yoga & technology! A former Software Consultant by profession, Bipin has been programming since 1995 and has been working with the .NET framework ever since its inception. He has authored or co-authored half a dozen books and numerous articles on .NET technologies. He has also penned a few books on Yoga. He was a well known technology author, trainer and an active member of Microsoft developer community before he decided to take a backseat from the mainstream IT circle and dedicate himself completely to spiritual path. Having embraced Yoga way of life he now codes for fun and writes on his blogs. He can also be reached there.

Related Articles

Downloads

Comments

  • pfHos dEB CJya

    Posted by TxsbjjNeSU on 07/08/2013 01:56am

    buy hydrocodone online buy hydrocodone online usa - hydrocodone with alcohol effects

    Reply
Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Live Event Date: December 11, 2014 @ 1:00 p.m. ET / 10:00 a.m. PT Market pressures to move more quickly and develop innovative applications are forcing organizations to rethink how they develop and release applications. The combination of public clouds and physical back-end infrastructures are a means to get applications out faster. However, these hybrid solutions complicate DevOps adoption, with application delivery pipelines that span across complex hybrid cloud and non-cloud environments. Check out this …

  • VMware vCloud® Government Service provided by Carpathia® is an enterprise-class hybrid cloud service that delivers the tried and tested VMware capabilities widely used by government organizations today, with the added security and compliance assurance of FedRAMP authorization. The hybrid cloud is becoming more and more prevalent – in fact, nearly three-fourths of large enterprises expect to have hybrid deployments by 2015, according to a recent Gartner analyst report. Learn about the benefits of …

Most Popular Programming Stories

More for Developers

RSS Feeds