Click here to Skip to main content
13,398,338 members (36,591 online)
Click here to Skip to main content
Add your own
alternative version

Tagged as

Stats

3.8K views
9 bookmarked
Posted 8 Nov 2017

Creating a Nuget Package - Step by Step

, 8 Nov 2017
Rate this:
Please Sign up or sign in to vote.
How to create 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 standard .NET Framework Class Library

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

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.

Nuget Package Logo

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.

Nuget Package Summary

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

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

matthewproctor
CEO Kutamo and ErrLog.IO
Australia Australia
Pluralsight Author, .Net Developer, Writer & Blogger

http://www.kutamo.com/
http://www.errlog.io/
http://www.matthewproctor.com/
http://www.pluralsight.com/author/matthew-proctor

I am an Australian IT professional based in Melbourne, Victoria, Australia.

I'm a polyglot programmer, being proficient in a number of languages and frameworks including C#, VB.Net, F#, Javascript, Perl, Powershell and Z80 & 6502 assembly. Smile | :)

You may also be interested in...

Comments and Discussions

 
-- There are no messages in this forum --
Permalink | Advertise | Privacy | Terms of Use | Mobile
Web04 | 2.8.180216.1 | Last Updated 8 Nov 2017
Article Copyright 2017 by matthewproctor
Everything else Copyright © CodeProject, 1999-2018
Layout: fixed | fluid