Introduction to NuGet with .NET Core on RHEL

Introduction to NuGet with .NET Core

NuGet is an open source package manager for the .NET Core ecosystem. For those familiar with Red Hat Enterprise Linux (RHEL), you can think of it as the “yum” for pulling libraries into your .NET Core project. Working with NuGet packages in .NET Core applications is accomplished primarily through your project’s .csproj file and the dotnet command-line interface.

Repositories

Just like RHEL, NuGet has its own repositories to get packages. By default, when the .NET Core runtime is installed, the nuget.org repository is added to your system. You can see this by viewing ~/.nuget/NuGet/NuGet.Config.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
  </packageSources>
</configuration>

More information about the various NuGet.Config files and how they’re applied can be found in Microsoft’s documentation for Configuring NuGet Behavior.

Finding a package

Finding a package is an organic process that will undoubtedly change for you over time. In other words, you’ll find your own methods for doing this, so I’ll point you in the right direction and assume you’ll take it from there.

I searched two places first for packages. Which one I use depends upon the information I know about the package already, i.e., whether I know the package name or just the name of a class within the package.

If I already know the package’s name and just want to know the current version and which framework version it targets, I’ll use nuget.org to search by name. For example, the Newtonsoft.Json package page shows the current version is 10.0.3 and it targets .NETStandard 1.3.

Sometimes I only know the name of a class or method. For example, I may have seen a code snippet on Stack Overflow that references the JsonConvert.DeserializeObject method. The nuget.org search won’t work very well here, so Microsoft created their Reverse Package Search tool. Here you can enter any class or method name, and the search results will link to the project on nuget.org.

Be aware that any developer can create an account and upload packages to NuGet. This means that packages need to be vetted before being used in production systems. You can generally trust a package if the download count is high and the package is in active development. When in doubt, be sure to visit the project’s home page, if it exists.

Adding packages to your project

There are two ways of adding a package to your project:

Using the dotnet add command
Manually editing your .csproj file

Using dotnet add is easiest because it will automatically run a package restore and download the package. To use the example above, let’s add the Newtonsoft.Json package to a project. In the project’s root directory (the directory containing your .csproj file), execute the following command.

$ dotnet add package Newtonsoft.Json --version 10.0.3
Microsoft (R) Build Engine version 15.1.1012.6693
Copyright (C) Microsoft Corporation. All rights reserved.

  Writing /tmp/tmpgud8AG.tmp
info : Adding PackageReference for package 'Newtonsoft.Json' into project '/home/redhat/myproject/myproject.csproj'.
log  : Restoring packages for /home/redhat/myproject/myproject.csproj...
info : Package 'Newtonsoft.Json' is compatible with all the specified frameworks in project '/home/redhat/myproject/myproject.csproj'.
info : PackageReference for package 'Newtonsoft.Json' version '10.0.3' updated in file '/home/redhat/myproject/myproject.csproj'.

To add the project manually, you’ll need to edit your project’s .csproj file and then run dotnet restore. Here is what the project file looks like after adding the Newtonsoft.Json package.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp1.1</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="10.0.3"/>
  </ItemGroup>
</Project>

Save the file and then run dotnet restore while in your project folder. This will check the package for compatibility and download the package for use. I find it much easier to use the first method.

Local packages

If you’re developing your own libraries for use across multiple projects, you’ll eventually want to reference those libraries. Since NuGet is the only way to add references to a .NET Core project, you have two options:

You can create an account and upload your package to nuget.org.
You can host an internal NuGet repository.

At the time of writing this post, there is no NuGet hosting software that runs on Linux. So the only option is to use a directory to hold your NuGet packages. Note that this can be a directory on your local machine or a networked file share like NFS. Below I’ll focus on a local directory to keep things simple.

First, create a directory for your packages. This can be anywhere your user has access, but I’ve chosen /usr/share/nuget.

$ sudo mkdir -p /usr/share/nuget
$ sudo chmod 644 /usr/share/nuget

This post doesn’t cover how to create a NuGet package, but copy them into the directory you created above. Now you have to tell .NET about this directory. In your project folder, create a new NuGet.Config with the following content.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="mynuget" value="/usr/share/nuget" />
  </packageSources>
</configuration>

Now add a package to your project using your chosen method from the previous section.

Conclusion

I hope this post helps you in getting started with using NuGet for your .NET Core projects. Please comment below with any tips or suggestions!

Last updated: August 14, 2017

Introduction to NuGet with .NET Core on RHEL