Visual Studio

Central Package Management for .NET Projects

Nowadays, every non-trivial software project depends on a number of external dependencies. Good software design is all about modularity, and that’s one of the reasons behind NuGet’s success in the .NET world. NuGet is the famous, well-integrated package manager for .NET with hundreds of thousands of public packages. Modern .NET projects utilize NuGet packages a lot, and the tool just got better. The NuGet team has just released the central package management feature. 

To download the source code for this article, you can visit our GitHub repository.

Let’s have a look at what it’s all about!

What Is Central Package Management and Why Do We Need It?

Central Package Management is exactly what its name suggests. It’s a way of controlling versions of NuGet packages in a centralized location. This solution follows the modern pattern of using Directory.*.props files to share the settings between multiple projects. 

In this case, the file is called Directory.Packages.props. 

Before this feature was available, we had to set each NuGet package version in each project one by one. This was tedious and error-prone – even with the ‘Manage Packages for Solution’ feature of Visual Studio. Package version conflicts are annoying when they break our builds, but they are a whole different level of hell when they fail at runtime.

Having the versions of dependencies in one place guarantees that all projects use the same thing. And since it’s just one file, it’s much faster to edit.

So, let’s see how to start using it!

How to Use Central Package Management

First of all, we need to add the Directory.Packages.props file into our repository. The root folder of the solution is a good place to start:

<Project>
  <ItemGroup>
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.1" />
    <PackageVersion Include="Serilog" Version="1.59.0" />
  </ItemGroup>
</Project>

Adding this file should then enable the central management for all the projects unless they opt-out.

However, at the time of writing, this feature is only available in the preview version of Visual Studio (17.2). Until it is officially released, we need to opt-in to enable this feature. In order to do that, we need to add <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> to our project files. Alternatively, we can use the Directory.Build.props file to control this setting centrally, as we’ve described in our article about setting the C# version for all projects

Next, let’s adjust the project files to handle centrally managed packages:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" />
  </ItemGroup>
</Project>

As we can see, the project file has only the reference to the package name – it does not contain the Version attribute.

It’s important to notice, that if we decide to use Central Package Management for a project, we cannot add NuGet packages in the traditional way. If we attempt to do that, we will see an NU1008 error: 

Projects that use central package version management should not define the version on the PackageReference items but on the PackageVersion items.

Notice also the subtle difference between the project file and the Directory.Packages.props – the latter specifies PackageVersion elements, not PackageReference. This can be tricky if we just copied the packages section from the project file.

That’s it – building our project now should trigger proper NuGet resolution. The Preview version of Visual Studio can act a bit flaky – sometimes it helps to restart and delete the hidden .vs folder if it gets stuck.

Fine-Tuning the Central Package Management

In some cases, we might need a bit more granular control over the versions of packages. One of the ways of achieving it is to declare the VersionOverride attribute on the package reference in the project file:

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" />
  <PackageReference Include="Serilog" VersionOverride="2.11.0" />
</ItemGroup>

In this case, the current project uses the Serilog package in version 2.11. NuGet will ignore the version specified in Directory.Packages.props.

Another way of adding more granularity to the package resolution logic is to use more Directory.Packages.props files. The version resolution mechanism applies the file that is closest to the project that is being resolved. This means a subfolder of a repository can have its own Directory.Packages.props file, and the projects in this subfolder and below will have that file applied:

Root
 |-- Directory.Packages.props
 |-- Directory.Build.props
 |-- NuGet.config
 |-- MySolution.sln
 |-- MyProject
     |-- MyProject.csproj
 |-- Subfolder
     |-- Directory.Packages.props
     |-- ProjectInSubfolder.csproj

However, only one file applies to a project. This means that packages are declared in the top-level Directory.Packages.props file don’t apply in projects where a subfolder Directory.Packages.props file exists.

In order to use them, we need to define them separately!

Conclusion

Central Package Management is a very nice addition to the NuGet ecosystem. It simplifies dependency management, which can be quite challenging in complex projects. Unfortunately, at the time of writing, there is no GUI support for this feature. Luckily, there are plans to include that at some point, so the experience will be even better.

Bartosz Jarmuż

Share
Published by
Bartosz Jarmuż

Recent Posts

Code Maze Weekly #134

Issue #134 of the Code Maze weekly. Check out what's new this week and enjoy…

Updated Date Aug 12, 2022

Heap Sort in C#

In this article, we'll look at the heap sort algorithm in C#. We'll discuss what…

Updated Date Aug 11, 2022

Flags Attribute For Enum in C#

In this article, we are going to learn about the Flags attribute for enum in…

Aug 10, 2022

Code Maze Weekly #133

Issue #133 of the Code Maze weekly. Check out what's new this week and enjoy…

Updated Date Aug 5, 2022

Type Checking and Type Casting in C#

In this article, we are going to learn various ways of converting a value from…

Updated Date Aug 5, 2022

Sort Dictionary by Value in .NET

In this article, we are going to learn how to sort the values in the…

Updated Date Aug 4, 2022