tools

What is NuGet?

NuGet is a package manager for Microsoft .NET. It installs packages and manages dependencies for .NET projects. It is like Maven (Java) or pip (Python). The NuGet Gallery hosts thousands of popular packages like Json.NET, NUnit, and jQuery. If you develop .NET applications (like in C#), then you probably need to use NuGet.

Installing Packages

The easiest way to use NuGet is through Visual Studio, which includes NuGet features by default. Packages are managed per project. Right-click on a project in Solution Explorer and select “Manage NuGet Packages…” to open the project’s package manager page.

The Browse tab lets you search and install new packages.
The Installed tab shows which packages are installed and can uninstall them.
The Updates tab lets you update packages to their latest versions.

The NuGet Package Manager page for a project in Visual Studio

When packages are installed and updated, NuGet also pulls any dependencies they require. Visual Studio also creates a packages.config file for all dependencies. Then, just build and run!

	<?xml version="1.0" encoding="utf-8"?>
	<packages>
	<package id="FluentAssertions" version="5.4.1" targetFramework="net461" />
	<package id="Newtonsoft.Json" version="11.0.2" targetFramework="net461" />
	<package id="SpecFlow" version="2.4.0" targetFramework="net461" />
	<package id="SpecRun.Runner" version="1.8.0" targetFramework="net461" />
	<package id="SpecRun.SpecFlow" version="1.8.0" targetFramework="net461" />
	<package id="SpecRun.SpecFlow.2-4-0" version="1.8.0" targetFramework="net461" />
	<package id="System.ValueTuple" version="4.5.0" targetFramework="net461" />
	</packages>

view raw

example-nuget-quick-ref-packages-config.xml

hosted with ❤ by GitHub

NuGet Configuration

NuGet can be configured using a NuGet.Config file. This file can be placed under a project directory, a solution directory, or a system-wide location. One of the most common settings is the package sources: NuGet uses the public nuget.org repository by default, but others (like private company repos) can also be added. Check the nuget.config reference online for docs on all options. (Package sources can also be configured through Visual Studio under Tools > NuGet Package Manager > Package Manager Settings.)

	<?xml version="1.0" encoding="utf-8"?>
	<configuration>
	<packageSources>
	<add key="nuget.org" value="https://www.nuget.org/api/v2/" />
	<add key="my.company.com" value="https://my.company.com/httpAuth/app/nuget/v1/FeedService.svc/" />
	</packageSources>
	</configuration>

view raw

example-nuget-quick-ref-nuget-config.xml

hosted with ❤ by GitHub

NuGet Package Manager Console

Sometimes, it’s helpful to control NuGet directly through the Package Manager Console. From the menu bar: Tools > NuGet Package Manager > Package Manager Console. For example, when packages get messed up, I’ll run “Update-Package -Reinstall” to reinstall everything. (Right-clicking the solution and selecting “Restore NuGet Packages” never seems to work for me.) Check the help command or the official guide for more info.

The NuGet Package Manager Console in Visual Studio

NuGet CLI

The NuGet CLI nuget.exe provides the full extent of NuGet features, including the ability to make packages. It is more powerful than the Package Manager Console. It must be installed independently – it does not come with Visual Studio. Check the NuGet CLI reference online for full details. The .NET Core CLI dotnet.exe can also be used for managing packages. See the feature comparison for the differences.

The NuGet CLI

Creating a NuGet Package

A NuGet package is basically a ZIP file with a .nupkg extension. It typically contains an assembly DLL and maybe other related files. Creating a NuGet package is pretty easy:

Install the NuGet CLI.
Create a .nuspec file for the project.
Add appropriate settings to the .nuspec file.
Run the “nuget pack” command to create the .nupkg file.
Publish the .nupkg file to the desired destination.

The .nuspec file can be created by running the “nuget spec” command in the project’s directory. The generated <project-name>.nuspec file will contain replacement tokens that will be substituted with values from the project’s AssemblyInfo when the package is built. Make sure to set AssemblyInfo values appropriately for the substitution. The version is especially important, and the automatic version format may be useful for guaranteeing uniqueness. Be sure to add any packages upon which the project depends as dependencies, too. (The .nuspec file can also be created manually.) Refer to the .nuspec reference for full details.

The standard package creation command is “nuget pack <project-name>.nuspec”. However, if the .nuspec file contains replacement tokens, then use “nuget pack <project-name>.csproj” instead. Once the package is created, it can be published publicly to nuget.org or to a private NuGet feed.

Below is an example .nuspec file with replacement tokens:

	<?xml version="1.0"?>
	<package >
	<metadata>

	<id>$id$</id>
	<version>$version$</version>
	<title>$title$</title>
	<authors>$author$</authors>
	<owners>$author$</owners>
	<requireLicenseAcceptance>false</requireLicenseAcceptance>
	<description>$description$</description>
	<copyright>$copyright$</copyright>
	<tags>tag1 tag2</tags>

	<dependencies>
	<dependency id="Newtonsoft.Json" version="11.0.2" />
	<dependency id="RestSharp" version="106.3.1" />
	<dependency id="Selenium.Support" version="3.14.0" />
	<dependency id="Selenium.WebDriver" version="3.14.0" />
	</dependencies>

	</metadata>
	</package>

view raw

example-nuget-quick-ref-nuspec.xml

hosted with ❤ by GitHub

Resources

While recently deploying a new Python Django app to Heroku, I noticed the documentation mentioned a tool I hadn’t known before: pipenv. I thought to myself, “Great, now I need to learn a new tool. What was so bad about pip and virtualenv?” So, I did my research, and BOOM! Yes. Mind blown. Life changed. This.

What It Is

Pipenv is the Python packaging and environments tool for champions.

It unites pip, Pipfile, and virtualenv into a sophisticated workflow with simple commands.
It automatically creates virtual environments for projects.
It automatically updates package dependencies (and their dependencies).
It locks versions for deterministic builds.

Despite some controversy and limitations, I strongly recommend using pipenv for most new Python projects. The Python Packaging Authority recommends it, too.

What It’s About

Packages and environments (“packagement”) are essential to Python development. Typically, Pythoneers create a virtual environment for each project and install dependent packages into it locally using pip. They then “freeze” the dependencies into a requirements.txt file so that others can easily recreate the environment. Virtual environments thus enable different projects to use different package versions without global conflict.

Unfortunately, this traditional workflow has some problems:

It uses multiple tools instead of one and requires many commands.
Different projects can do the workflow differently, which can be confusing.
The requirements.txt file must be manually generated and can easily fall out of date.
Dev-only dependencies are a hassle to separate.
Uninstalling packages will not remove sub-packages.
Dependencies with version ranges instead of fixed versions cause nondeterministic builds.

Pipenv solves these problems by combining pip, Pipfile, and virtualenv into a standard workflow that automatically handles and locks package updates.

How to Use It

See how simple it is to use pipenv with a Python project:

# Install pipenv
pip install pipenv

# Create a new project directory
mkdir panda_project
cd panda_project
echo "print('hello')" > main.py

# Init pipenv:
# Creates a virtual environment
# Then creates Pipfile and Pipfile.lock files
pipenv install

# Install a package:
# Updates the Pipfiles
pipenv install requests

# Install a dev-only package:
# Updates the Pipfiles
pipenv install --dev pytest

# Run commands in the environment
pipenv run python --version
pipenv run python main.py

More Info

There’s no need for me to repeat what other people have already said:

Official Docs
- Pipenv: Python Dev Workflow for Humans
- Pipenv: The Future of Python Dependency Management (PyCon 2018 talk)
- The pypa/pipenv project on GitHub
- Managing Application Dependencies from PyPA
- Pipenv & Virtual Environments from The Hitchhiker’s Guide to Python
Secondary Articles
- Announcing Pipenv! from Kenneth Reitz, the primary author
- How to manage your Python projects with Pipenv
- Why Python devs should use Pipenv
- Stop everything! Start using Pipenv!
Comparisons
Limitations
- Reddit: Why is pipenv the recommended packaging tool?
- Pipenv: promises a lot, delivers very little

Me, after using pipenv for the first time.

[8/24/2018 Update: Mentioned some of the controversy and limitations of pipenv.]

Automation Panda

A blog for software development and testing

NuGet Quick Reference