Learn how to create your first NuGet package

NuGet Package(WARNING: This post is machine-translated. A proper translation is in the works).

 

The issue is far from new NuGet-in fact, nowadays it is almost impossible to create a project in Visual Studio that does not have any packages NuGet in use.

However, for more convenient that these packages might be, the truth is that few teams have created packages to share their libraries of internal use by finding that a lot of work.

Did you know that create a package NuGet for internal use library is more simple than it seems? See in this post how to create your first NuGet package.

The idea of this post is to help you in creating your first NuGet package. This means that we’re not going deep into any of the aspects of the creation of packages. On the other hand, the official website of NuGet has a detailed documentation about creating packages, for when you are ready to deepen. Meanwhile, let’s start with the basics.

All of the examples from now on will use a hypothetical CPF validation library is made in c #, created by a team in a fictitious company named Fabrikam, you want to share this library with other internal teams within the same company.

Basic concepts

NuGet packages are a convenient mechanism for sharing software artifacts. Although optimized for share libraries .NET assemblies, they can be used for much more than apenas.net, being used to package virtually anything that needs to be versioned and distributed in convenient way. Want a sample? Did you know there are several cases of NuGet packages that contain only scripts PowerShell? Is a convenient way to package and redistribute scripts that are used, for example, during the build and deployment process of an application.

Technically speaking, a package NuGet is just a ZIP file that follows a naming pattern and contains a metadata file describing the contents of that file. Means that, since following the appropriate conventions, we could create a NuGet package just by using a compression tool such as 7-Zip.

Let’s see now each of these three aspects: naming, metadata and content.

NuGet package name

NuGet packages should follow a Convention to be named. You should necessarily follow the same Convention for your package to be recognized by NuGet:

<Nome do="" pacote="">. <Versão semver="">. nupkg</Versão></Nome>

In the package name, you can use letters, numbers and periods. A common strategy part avoid name collisions is to use your company name as a prefix in the name of the library, as we do with .NET assemblies. In our example, our package will be called Fabrikam. ValidadorCPF. The extension of the file, in turn, should always be nupkg. Let’s talk now about versioning.

Package versioning

The package versioning is a central aspect in NuGet. After all, one of the great benefits of using NuGet is able to manage the different dependencies for a project, updating them where desired or necessary. To do this, you do need to use a schema for description of the package version.

The problem is a version number, it’s something common in our day, is far from consistent. After all, if you get in a circle of friends and programmers submit a version number such as 1.0.3.257 and ask what is the meaning of each of the segments (and under what circumstances they should be incremented) will probably hear very different explanations.

In an attempt to create a consistent algorithm for definition of version numbers, was born the initiative of Versioning Semantics (Semantic Versioning), which describes how to create a version identifier, which the meaning of each segment and in what circumstances increases them. The NuGet, fortunately, follows the pattern set in the website semver.org, which is the official source of documentation for the Semantic Versioning. It is important that you familiarize yourself with this concept; take a break from reading this post, go to semver.org and then come back here. I hope;-).

Returning to our example, chose decided my first package will be born with the 1.0 version. In this way, the full name of my package (now with the version number) is:

Fabrikam. ValidadorCPF. nupkg 1.0.0.

Simple, huh? Now let’s talk about the metadata required to describe our package.

Metadata-the manifest file

When you access the dialog box from Visual Studio Packages management (or when browsing the site NuGet.org) may notice that a package NuGet contains several metadata that help describes it. Information such as name, author, description, dependencies … Without it, other programmers would have trouble understanding so that your package serves. These metadata are part of a specification file NuGet-a manifest XML file, with a predetermined format and nuspec extension. We need to create this file and embeds it in our package (IE, put it inside the zip file).

NuGet dialog box in Visual Studio, showing the various NuGet package metadata: the ID (1), (2) description and other information such as version, authors, and site license project (3)
484

The full definition of the nuspec file format is available on the official website of NuGet, if you want to delve into later. Let’s see now the basic elements for the creation of a manifesto to describe our CPF validation package:

<?xml version="1.0" encoding="utf-8"?>
<package></package>
  <metadata></metadata>
    <id>Fabrikam. ValidadorCPF</id>
    <version>1.0.0</version>
    <authors>Fabrikam's shared services team</authors>
    <description>This package provides CPF validation routines for .NET applications</description>
    <language>en</language>
    <projectUrl>http://intranet.fabrikam.com/componentes/Fabrikam.ValidadorCPF</projectUrl>
    <licenseUrl>http://intranet.fabrikam.com/componentes/Fabrikam.ValidadorCPF/license.htm</licenseUrl>
 

Example of the file ValidadorCPF. nuspec Fabrikam.

This is the typical NuGet package manifest. In it you see the elements that, minimally, need to be present in file to describe your nuspec package. The elements are self-explanatory, except perhaps the two URLs. The first, <projectURL>, indicates where a developer who want more information about your library can find a website with documentation.</projectURL> Can be a wiki, a TFS team project, a repository from GitHub. Already < licenseurl=””> points to a document with the license of use of the component. This information is more important for publicly shared components, but sometimes even internal components may have different license models – especially when we have outsourced teams from different companies consuming our components.

Where do I put the nuspec file? The best place to put it is in the project, next to the .csproj file of the library. The nuspec should be placed under version control, along with the rest of the library code.

Contents – setting the files package

Still in our archive nuspec, need now to list which files should be included in our package. To keep our simple example, will include only one file: the assembly of our CPF validation library.

Package contents NuGet is set from the element <files>.</files> Take a look at how is our file, now changed to include our library and its documentation XML file (generated from the XML comments):

<?xml version="1.0" encoding="utf-8"?>
<package></package>
  <metadata></metadata>
    <id>Fabrikam. ValidadorCPF</id>
    <version>1.0.0</version>
    <authors>Fabrikam's shared services team</authors>
    <description>This package provides CPF validation routines for .NET applications</description>
    <language>en</language>
    <projectUrl>http://intranet.fabrikam.com/componentes/Fabrikam.ValidadorCPF</projectUrl>
    <licenseUrl>http://intranet.fabrikam.com/componentes/Fabrikam.ValidadorCPF/license.htm</licenseUrl>
 
  <files></files>
    <file src="binReleaseFabrikam.ValidadorCPF.dll" target="lib"></file>
    <file src="binReleaseFabrikam.ValidadorCPF.xml" target="lib"></file>
 

Featured lines we can that our two files are obtained from the BinRelease folder of the project and copied to a folder named lib, through the target attribute of the element <file>.</file> Incidentally, remember that we put in the same folder as the .csproj nuspec? This is one of the reasons: enable relative references.

This lib folder has a special meaning for the NuGet: Any assemblies found in this folder during installation of the package will be referenced in the target project. That is, if someone from our company add our package NuGet a .NET project any, our library (which was copied to the lib folder) will be automatically added to the project references. Exactly the behavior we want.

Now it’s time to see all that work. Though “theoretically” we can use 7-Zip, in practice have a easier way of creating our package!

Generating the file. nupkg

With the nuspec file created, everything is pretty easy. We will use the command line tool NuGet (nuget.exe; download instructions here).

The first thing to do is compile your project in Release mode (because it is the setting that we’re referencing the nuspec file for example). Then, open the command prompt and, from the folder where are the project files, run:

nuget pack Fabrikam. ValidadorCPF. nuspec

The result is your nupkg file, ready for use. Alegre

Ready to test? Then open your Visual Studio and follow the steps below.

Dialog box with the options of NuGet
437

In Tools | Options, search for “nuget” (1). Then, select the option Package Sources (2) and click the button to add a new NuGet package origin (3). Give a name to this new origin (4), enter the directory where we just generate the nupkg file (5) and then click Update (6) and OK.

Finally, create a new .NET project and select the “Manage NuGet Packages …”.

New package being listed in Visual Studio
434

NuGet window, select the source (1) we just created and see what happens!

Distributing packages

Obviously none of this makes sense if you can’t share your packages with the other developers of the company. Soon comes the question: where to host my packages so that other developers have access? Well, that depends on if your package is public or private.

Public packages

Public packages (which can be freely used by developers inside and outside your company), the obvious choice is the nuget.org. However, for being a repository accessible to the general public, is not the best place to publish test suites. While you are testing their packages, use the website service myget.org. The free plan is sufficient for testing purposes.

Private packages

If your packages are only for internal use of your business, a public repository is obviously not a good option. There are a number of options to host repositories NuGet in private cloud or within your company:

In most cases (with the exception of AppVeyor and network folders), you need to create an account. Once created, your account will contain information critical to the publishing process: your API key (API Key). This key will be used by the command push NuGet, responsible for publishing your package to your repository. The command is:

nuget push-Source <URL do="" servidor="" de="" destino="">-ApiKey <sua chave="" de="" api=""></sua> </URL>

Developers who are using their packages need to add your repository to Visual Studio. The process is identical to that we used above to add the test folder; the difference is that instead of pointing to a local directory on the computer, they would add the URL of your feed NuGet. Each repository NuGet represents your feed URLs differently. Check the documentation of your chosen store to know what URL should be added to the Visual Studio.

Conclusion

Phew! I know it’s a lot for a post, but I think with that you can start building your first packages. There is still much more to be explored in this matter. Stay tuned for the next posts on NuGet!

Oh, leave an exercise to you, dear reader: If you notice well, you’ll see that many of the metadata included in our nuspec file typically are present also in our .NET assembly, through the various assembly metadata attributes. Information such as name, description, author, version, and other likely duplicates. Wouldn’t it be a lot cooler if instead of entering this information on the nuspec file, we could instruct the NuGet to seek it in our design in packaging time? So we could keep this data in one place: in the .NET project!

The exercise, therefore, is: How do the NuGet reuse metadata for assembly that we have in our project, so you don’t need to retype the same data on the nuspec file?

Good exercise! Oh, and be sure to share your opinion in the comments!

A hug,
Igor

Author: Igor Abade

Igor Abade V. Leite ([email protected]) is a Visual Studio ALM MVP (Microsoft Most Valuable Professional) since 2006. Speaker at various Software Development community events (TechEd Brasil, The Developers’ Conference, DevOps Summit Brasil, Agile Brazil, Visual Studio Summit, QCON among others), has also written articles in magazines and websites such as MSDN Brazil. Since March/2011 is one of the owners of Lambda3, a Brazilian consulting company specialized in ALM, software development and training. Visit his blog about VS ALM at http://www.tshooter.com.br/ and follow him on Twitter @igorabade.

Leave your comment!