Creating a Nuget Package - Step by Step

Creating a Nuget Package - Step by Step

Creating a Nuget Package is a relatively straightforward process, but can be a little daunting the first time. This tutorial takes you through the process step by step.

Microsoft has comprehensive documentation on Nuget, but we've simplified the process here to help.

Your Project

Ideally your Nuget package should be a .NET Framework Class Library. In our instance, we use a C# instance, and the package is, for all intents, a normal class library.

Any files that you want to include in your package, such as documentation or a readme.md file, should be included in the project.

Creating a .nuspec File

The main component of a Nuget package is the .nuspec file. This is an XML file that represents your package, and contains all the information that Nuget.org requires to publish your package.

Whilst not essential, it makes life somewhat easier if you include the .nuspec file in the root of your project.

An empty .nuspec file is shown below. This is the basic structure that you can use to create your first package.

<?xml version="1.0"?>
<package  xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
  <metadata>    
    <id></id>
    <version></version>
    <title></title>
    <authors></authors>
    <owners></owners>
    <licenseUrl></licenseUrl>
    <projectUrl></projectUrl>
    <iconUrl></iconUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description></description>
    <releaseNotes></releaseNotes>
    <copyright></copyright>
    <tags></tags>
    <dependencies>
      <dependency id="" />
    </dependencies>
    <summary></summary>
  </metadata>
  <files>
    <file src="" target="" />
  </files>
</package>

A Real Example - Our ErrLog.IO .Nuspec File

<?xml version="1.0"?>
<package  xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
  <metadata>    
    <id>errlog.io</id>
    <version>1.1.18</version>
    <title>ErrLog.IO Error and Exception Logging Tool</title>
    <authors>Matthew Proctor, Michael Sanders, Alastair Bateman</authors>
    <owners>kutamo</owners>
    <licenseUrl>https://errlog.io/terms</licenseUrl>
    <projectUrl>https://errlog.io/docs/getting-started</projectUrl>
    <iconUrl>https://www.errlog.io/images/errlog_dark_logo.png</iconUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>ErrLog.IO is an exception and error logging tool</description>
    <releaseNotes>Bug fixes and performance improvements </releaseNotes>
    <copyright>Copyright 2017 Kutamo Pty. Ltd.</copyright>
    <tags>exceptions web http error logging</tags>
    <dependencies>
      <dependency id="Newtonsoft.Json" version="10.0"  />
    </dependencies>
    <summary>ErrLog.IO is an exception and error logging tool.</summary>
  </metadata>
  <files>
    <file src="readme.md" target="" />
  </files>
</package>

Required .nuspec Elements

Useful, but Optional, .nuspec Elements

The .nuspec file has a lot of additional configuration options, which are documented here.

A Picture is Worth a Thousand Pull Requests

To help differentiate your package from the thousands of others in the Nuget.org library, it's a great idea to create your own logo.

Logos must be a 64x64 pixel image with a transparent background, and are included in the <iconUrl></iconUrl> element of the .nuspec file.

Including a README.MD File

A readme.md file is a great way of providing your users with instructions on how to use your package.

This will be displayed in Visual Studio after your package is installed, and is written using markdown.

You can check out our readme file here.

Building Your Package

Once you've created your .nuspec file, it's now time to build your package!

Nuget.Org provides an application nuget.exe that is used to bundle your library into a Nuget package. You should already have this installed if you are using Visual Studio, or you can download it from nuget.org/downloads.

Nuget.exe needs to run from within your project folder, so the simplest method is to drop into this from a command prompt or powershell window.

cd \your_project_folder\

Nuget.Exe Package Repository

If your library uses any packages, you'll need to tell Nuget where they are on your PC. This is done by running nuget.exe with the -Set repositoryPath parameter.

Your packages folder is typically in the root folder of your Solution, if you're using Visual Studio.

nuget.exe config -Set repositoryPath="\full-path-to-your-packages-folder\"

We can now create our package. In the example below, we are setting the build configuration to Release.

nuget.exe pack -IncludeReferencedProjects -properties Configuration=Release

Using these options, Nuget will create a .nupkg that includes any referenced packages and projects.

The package filename is automatically created, using the format [package id].[package version].nupkg

For example, a recent ErrLog.IO package filename is errlog.io.1.1.18.nupkg.

Deploying Your Package to Nuget.Org

Once you have your .nupkg file ready, you can now deploy it to Nuget.Org.

At this point, we're assuming you have already created an account on Nuget.Org, and have created an API Key.

Uploading a Package Manually

You can simply upload your .nupkg file to nuget by visiting https://www.nuget.org/packages/manage/upload.

Nuget will open your package, read the .nuspec file, and publish your package all in a single step.

Automating and Scripting Deployment

nuget.exe has the ability of uploading your package automatically - this means you can write a script to automatically build and deploy your package simply and without interaction.

In order to upload your package via nuget.exe, we first need to set the API key. You can create an API key from within your account on Nuget.Org.

nuget.exe config setApiKey aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Once you've set the API Key, you can now push your package to Nuget.Org using Nuget.Exe. That sounds strange, no matter how many times you say it.

nuget.exe push [your-package-filename].nupkg -Source https://www.nuget.org/api/v2/package

Handy Hint!

The push command also supports wildcards, so you can just push any .nupkg file you have in the folder automatically with a single command.

nuget.exe push *.nupkg -Source https://www.nuget.org/api/v2/package

How We Build & Deploy the ErrLog.IO Nuget Package

We use a simple batch file to automatically build and deploy our ErrLog.IO Nuget Package, which we're happy to share below (with a few items obfuscated).

REM Move to project folder
cd E:\ErrLog\ErrLogNuget\

REM Configure Nuget Settings
nuget config -Set repositoryPath="E:\ErrLog\packages"
nuget setApiKey aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

REM Create Nuget Package
nuget pack -IncludeReferencedProjects -properties Configuration=Release

REM Deploy to Nuget.Org
nuget push *.nupkg -Source https://www.nuget.org/api/v2/package

Nuget Statistics

Your Nuget package page gives you a handy summary of your package downloads, as well as more detail in the form of a pivot table, allowing you to review downloads per version and per client type.

Final Thoughts

Deploying a Nuget package for worldwide distribution is easy, but it's also easy to accidentally deploy a broken package, as testing is your responsibility.

Make sure you have a solid test process for downloading and validating your package as soon as it's published, to ensure that your users have a great, and bug-free, experience.

References

• Nuget Documentation
• Nuget's .nuspec Reference