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.
="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
="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
| Element | Description or Details |
id | The case-insensitive package identifier, which must be unique across nuget.org. IDs may not contain spaces or characters that are not valid for a URL, and generally follow .NET namespace rules. |
version | The version of the package, following the major.minor.patch pattern. Ensure you update this value for each subsequent package deployment. |
description | A long description of the package for UI display - this should be a description of your package and what functionality it provides.. |
authors | A comma-separated list of packages authors, matching the profile names on nuget.org. |
Useful, but Optional, .nuspec Elements
| Element | Description or Details |
title | Simply the title of your package, typically used in UI displays as on nuget.org and the Package Manager in Visual Studio. If not specified, the package ID is used. |
projectUrl | A URL for your package's home page, often shown in UI displays as well as nuget.org. |
licenseUrl | A URL for your package's license, if it has one. |
iconUrl | A URL for a 64x64 image with transparent background to use as the icon for the package in UI display. This must be a fully qualified URL. If you don't specify one, your package will have the default Nuget logo. |
releaseNotes | A brief description of the changes made in this release of your package. |
copyright | Copyright details for your package. |
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
