NuGet 101: Introduction to NuGet

6 min readMay 7, 2018

What is NuGet ?

NuGet is a free and open-source package manager designed for the Microsoft development platform (formerly known as NuPack).[2][3] Since its introduction in 2010, NuGet has evolved into a larger ecosystem of tools and services.[4]

NuGet is distributed as a Visual Studio extension. Starting with Visual Studio 2012, NuGet comes pre-installed by default. NuGet is also integrated with SharpDevelop. NuGet can also be used from the command line and automated with scripts.

It supports multiple programming languages, including:

.NET Framework packages
Native packages written in C++,[5] with package creation aided by CoApp

Why to use?

An essential tool for any modern development platform is a mechanism through which developers can create, share, and consume useful code. Often such code is bundled into “packages” that contain compiled code (as DLLs) along with other content needed in the projects that consume these packages.

For .NET (including .NET Core), the Microsoft-supported mechanism for sharing code is NuGet, which defines how packages for .NET are created, hosted, and consumed, and provides the tools for each of those roles.

Put simply, a NuGet package is a single ZIP file with the .nupkg extension that contains compiled code (DLLs), other files related to that code, and a descriptive manifest that includes information like the package's version number. Developers with code to share create packages and publish them to a public or private host. Package consumers obtain those packages from suitable hosts, add them to their projects, and then call a package's functionality in their project code. NuGet itself then handles all of the intermediate details.

Because NuGet supports private hosts alongside the public nuget.org host, you can use NuGet packages to share code that’s exclusive to an organization or a work group. You can also use NuGet packages as a convenient way to factor your own code for use in nothing but your own projects. In short, a NuGet package is a shareable unit of code, but does not require nor imply any particular means of sharing.

Whatever its nature, a host serves as the point of connection between package creators and package consumers. Creators build useful NuGet packages and publish them to a host. Consumers then search for useful and compatible packages on accessible hosts, downloading and including those packages in their projects. Once installed in a project, the packages’ APIs are available to the rest of the project code.

NuGet tools

nuget.exe CLI: Provides all NuGet capabilities, with some commands applying specifically to package creators, some applying only to consumers, and others applying to both. For example, package creators use the nuget pack command to create a package from various assemblies and related files, package consumers use nuget install to include packages in a project folder, and everyone uses nuget config to set NuGet configuration variables. As a platform-agnostic tool, the NuGet CLI does not interact with Visual Studio projects.
dotnet CLI: Provides certain NuGet CLI capabilities directly within the .NET Core tool chain. As with the NuGet CLI, the dotnet CLI does not interact with Visual Studio projects.
Package Manager Console: Provides PowerShell commands for installing and managing packages in Visual Studio projects.
Package Manager UI: Provides an easy-to-use UI for installing and managing packages in Visual Studio projects.
Manage NuGet UI: Provide an easy-to-use UI for installing and managing packages in Visual Studio for Mac projects.
MSBuild: Provides the ability to create packages and restore packages used in a project directly through the MSBuild tool chain.

NuGet CLI

What is NuGet CLI? :

The NuGet Command Line Interface (CLI), nuget.exe, provides the full extent of NuGet functionality to install, create, publish, and manage packages without making any changes to project files.

To use any command, open a command window or bash shell, then run nuget followed by the command and appropriate options, such as nuget help pack (to view help on the pack command).

Installing nuget.exe

Windows

Visit nuget.org/downloads and select NuGet 3.3 or higher (2.8.6 is not compatible with Mono). The latest version is always recommended, and 4.1.0+ is required to publish packages to nuget.org.
Each download is the nuget.exe file directly. Instruct your browser to save the file to a folder of your choice. The file is not an installer; you won't see anything if you run it directly from the browser.
Add the folder where you placed nuget.exe to your PATH environment variable to use the CLI tool from anywhere.

macOS/Linux

Behaviors may vary slightly by OS distribution.

Install Mono 4.4.2 or later.
Execute the following commands at a shell prompt:

3. Create an alias by adding the following script to the appropriate file for your OS (typically ~/.bash_aliases or ~/.bash_profile):

4. Reload the shell. Test the installation by entering nuget with no parameters. NuGet CLI help should display.

Availability

See feature availability for exact details.

All commands are available on Windows.
All commands work with nuget.exe running on Mono except where indicated for pack, restore, and update.
The pack, restore, delete, locals, and push commands are also available on Mac and Linux through the dotnet CLI.

Common Commands

pack: Creates a NuGet package from a .nuspec or project file. When running on Mono, creating a package from a project file is not supported.
push: Publishes a package to a package source.
config: Gets or sets NuGet configuration values.
help or ?: Displays help information or help for a command.
locals: Lists locations of the global-packages, http-cache, and temp folders and clears the contents of those folders.
restore: Restores all packages referenced by the package management format in use. When running on Mono, restoring packages using the PackageReference format is not supported.
setapikey: Saves an API key for a given package source when that package source requires a key for access.
spec: Generates a .nuspec file, using tokens if generating the file from a Visual Studio project.

Command option names are case-insensitive. Options that are deprecated are not included in this reference, such as NoPrompt (replaced by NonInteractive) and Verbose (replaced by Verbosity).

dotnet CLI

The dotnet command-line interface, which runs on Windows, Mac OS X, and Linux, provides a number of essential nuget.exe commands as listed below. If dotnet satisfies your needs, it's not necessary to use nuget.exe.

For complete information on dotnet, see .NET Core command-line interface (CLI) tools.

Package consumption

dotnet add package: Adds a package reference to the project file, then runs dotnet restore to install the package.
dotnet remove package: Removes a package reference from the project file.
dotnet restore: Restores the dependencies and tools of a project. As of NuGet 4.0, this runs the same code as nuget restore.
dotnet nuget locals: Lists locations of the global-packages, http-cache, and temp folders and clears the contents of those folders.

Package creation

dotnet pack: Packs the code into a NuGet package. As of NuGet 4.0, this runs the same code as nuget pack.
dotnet nuget push: Pushes a package to a server and publishes it, applicable to nuget.org, Visual Studio Team Services, and third-party NuGet servers.
dotnet nuget delete: Deletes or unlists a package from a host, applicable to nuget.org, Visual Studio Team Services, and third-party NuGet servers.

Package targeting compatibility

A “compatible” package means that it contains assemblies built for at least one target .NET framework that’s compatible with the consuming project’s target framework. Developers can create packages that are specific to one framework, as with UWP controls, or they can support a wider range of targets. To maximize a package’s compatibility, developers target .NET Standard, which all .NET and .NET Core projects can consume. This is the most efficient means for both creators and consumers, as a single package (usually containing a single assembly) works for all consuming projects.

Package developers who require APIs outside of .NET Standard, on the other hand, create separate assemblies for the different target frameworks they want to support and include all of those assemblies in the same package (which is called “multi-targeting”). When a consumer installs such a package, NuGet extracts only those assemblies that are needed by the project. This minimizes the package’s footprint in the final application and/or assemblies produced by that project. A multi-targeting package is, of course, more difficult for its creator to maintain.

Targeting .NET Standard supercedes the previous approach of using various portable class library (PCL) targets. This documentation therefore focuses on creating packages for .NET Standard.

/cheers

[NEXT] → Building a private NuGet Server