Manage dependencies with .NET Core SDK 1.0

With the move of .NET Core projects from project.json to csproj and MSBuild, a significant investment also happened that resulted in unification of the project file and assets that allow tracking of dependencies. For .NET Core projects, this is similar to what project.json did. There is no separate JSON or XML file that tracks NuGet dependencies. With this change, we've also introduced another type of reference into the csproj syntax called the <PackageReference>.

This document describes the new reference type. It also shows how to add a package dependency using this new reference type to your project.

The new <PackageReference> element

The <PackageReference> has the following basic structure:

<PackageReference Include="PACKAGE_ID" Version="PACKAGE_VERSION" />

If you are familiar with MSBuild, it will look familiar to the other reference types that already exist. The key is the Include statement, which specifies the package ID that you wish to add to the project. The <Version> child element specifies the version to get. The versions are specified as per NuGet version rules.


If you're not familiar with the project-file syntax, see the MSBuild project reference documentation for more information.

Use conditions to add a dependency that's available only in a specific target, as shown in the following example:

<PackageReference Include="PACKAGE_ID" Version="PACKAGE_VERSION" Condition="'$(TargetFramework)' == 'netcoreapp2.1'" />

The dependency will only be valid if the build is happening for that given target. The $(TargetFramework) in the condition is an MSBuild property that's being set in the project. For most common .NET Core applications, you will not need to do this.

Add a dependency to the project

Adding a dependency to your project is straightforward. Here is an example of how to add Json.NET version 9.0.1 to your project. Of course, it is applicable to any other NuGet dependency.

Your project file has two or more <ItemGroup> nodes. One of the nodes already has <PackageReference> elements in it. You can add your new dependency to this node or create a new one; the result will be the same.

The following example uses the default template that's dropped by dotnet new console. This is a simple console application. When you open up the project, you'll find the <ItemGroup> with already existing <PackageReference> in it. Add the following to it:

<PackageReference Include="Newtonsoft.Json" Version="9.0.1" />

After this, save the project and run the dotnet restore command to install the dependency.


Starting with .NET Core 2.0 SDK, you don't have to run dotnet restore because it's run implicitly by all commands that require a restore to occur, such as dotnet new, dotnet build and dotnet run. It's still a valid command in certain scenarios where doing an explicit restore makes sense, such as continuous integration builds in Azure DevOps Services or in build systems that need to explicitly control the time at which the restore occurs.

The full project looks like this:

<Project Sdk="Microsoft.NET.Sdk">

    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />

Remove a dependency from the project

Removing a dependency from the project file involves simply removing the <PackageReference> from the project file.