Centrally managing NuGet package versions

Status	Reviewing
Author(s)	Anand Gaurav (@adgrv), Cristina Manu

Solution Details

To get started, you will need to create an MSBuild props file at the root of the solution named Directory.Packages.props that declares the centrally defined packages' versions.

In this example, packages like Newtonsoft.Json are set to version 10.0.1. The PackageReference in the projects would not specify the version information. All projects that reference this package will refer to version 10.0.1 for Newtonsoft.json.

Directory.Packages.props

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <ItemGroup>
    <PackageVersion Include="MSTest.TestAdapter" Version="1.1.0" />
    <PackageVersion Include="MSTest.TestFramework" Version="1.1.18" />
    <PackageVersion Include="Newtonsoft.Json" Version="10.0.1" Pin="true" />
  </ItemGroup>
</Project>

SampleProject.csproj

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

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" />
  </ItemGroup>
</Project>

Opt-in Central Package Version Management

If the file Directory.Packages.props exists on the project path the project is automatically opt-in. If individual projects need to opt-out they can set EnableCentralPackageVersions MsBuild property to false as below.

<EnableCentralPackageVersions>false</EnableCentralPackageVersions>

In addition only specific types of projects will be supported for Central Package Version Management. Refer to this to see the exclusions.

Transitive dependencies: One should not be listing the transitive dependencies either in the Directory.Packages.props or as PackageReference for the projects. However the central package versions will win in the transitive dependency resolution.

DotNet CLI Experience

The dotnet commands dotnet add and dotnet remove will work without any changes if the project is opt-out Central Package Version Management. For the cases when a project is opt-in Central Package Version Management the following rules apply.

dotnet add

> dotnet add [PROJECT] package [PACKAGE_NAME] [-h|--help] [-f|--framework] [--interactive] [-n|--no-restore] [--package-directory] [-s|--source] [-v|--version] [--force-version-update](*)

Description

It will add a package reference to the project. The Package version will be added only to the Directory.Packages.props file. To update the version in the Directory.Packages.props file use the --force-version-update(*) option.

Arguments

PROJECT

Specifies the project file. If not specified, the command searches the current directory for one.

PACKAGE_NAME

The package reference to add.

Options

-f|--framework

Adds a package reference only when targeting a specific framework. The framework information will be added to the Directory.Packages.props file.

<ItemGroup Condition="'$(TargetFramework)' == 'net46'">
    <Package Include="MyPackage" Version="11.0.1" />
</ItemGroup>

The command will fail if the framework is not compatible with the project's frameworks.

-v|--version

Adds the specific version of the package to the Directory.Packages.props file. The command will fail if there is a conflict between this version and a version of the same package specified in the Directory.Packages.props file.

--force-version-update

Adds the specific version of the package to the Directory.Packages.props file. The command will override any existent package version in the Directory.Packages.props file. The project file will be updated to:

  <ItemGroup>
    <PackageReference Include="MyPackage" />
  </ItemGroup>

Examples

dotnet add when the PackageReference for Newtonsoft.Json exists in the Directory.Packages.props file

ProjectA> dotnet add package newtonsoft.json
Successfully added package 'Newtonsoft.Json' to ProjectA. The centrally package version is '12.0.1'.

A new PackageReference will be added to the ProjectA.csproj. The new PackageReference will not have a Version attribute.

dotnet add when PackageReference for Newtonsoft.Json does not exist in the Directory.Packages.props file

ProjectA> dotnet add package newtonsoft.json 
Successfully added package 'Newtonsoft.Json' to ProjectA. Successfully added version 12.0.2 for package Newtonsoft.Json in '<path>\Directory.Packages.props'.  

A new PackageReference will be added to the Directory.Packages.props file. The entry will contain the '12.0.1' version.
A new PackageReference will be added to the ProjectA.csproj. The new PackageReference will not have a Version attribute.

dotnet add --version when the PackageReference for Newtonsoft.Json exists in the Directory.Packages.props file.

//  Fails on version conflict
ProjectA> dotnet add package newtonsoft.json --version 11.0.1
error: '<path>\Directory.Packages.props' already contains a reference to `Newtonsoft.Json` version 12.0.2. To force the version update use 'dotnet add package newtonsoft.json --version 11.0.1 --force-version-update'. To add a reference to the existent `Newtonsoft.Json` version 11.0.1 use 'dotnet add package newtonsoft.json '

//  Success on --force-version-update
ProjectA> dotnet add package newtonsoft.json --version 11.0.1 --force-version-update
Successfully added package 'Newtonsoft.Json' to ProjectA. Successfully updated package 'Newtonsoft.Json' version from 12.0.2 to 11.0.1.

dotnet add package --version --framework when the framework is not compatible with ProjectA's frameworks

ProjectA> dotnet add package newtonsoft.json --version 11.0.1 --framework net45
error: Package 'Newtonsoft.Json' is incompatible with 'user specified' frameworks in project 'ProjectA.csproj'.

There will be no updates added to any of the files Directory.Packages.props or ProjectA.csproj

dotnet add package --version --framework when the framework is compatible with the ProjectA's frameworks

ProjectA> dotnet add package newtonsoft.json --version 11.0.1 --framework net46
Successfully added package 'Newtonsoft.Json' to ProjectA. Successfully added package 'Newtonsoft.Json' version 11.0.1 for TFM net46 in '<path>\Directory.Packages.props'.

<ItemGroup Condition="'$(TargetFramework)' == 'net46'">
    <Package Include="Newtonsoft.Json" Version="11.0.1" />
</ItemGroup>

ProjectA.csproj will be updated to include a reference to Newtonsoft.Json.

dotnet remove

> dotnet remove [PROJECT] package [PACKAGE_NAME] [-h|--help]

Description

Removes a package reference from a project. It does not remove the package reference from the Packges.props.

Arguments

PROJECT

Specifies the project file. If not specified, the command searches the current directory for one.

PACKAGE_NAME

Examples

ProjectA> dotnet remove package newtonsoft.json
Successfully removed package 'Newtonsoft.Json' from ProjectA. The Directory.Packages.props was not changed. To clean not used package references from the Directory.Packages.props use 'dotnet nuget versions --gc' command.  

The ProjectA.csproj will have the package reference for Newtonsoft.Json removed. No change will be applied to Directory.Packages.props file.

dotnet nuget versions

> dotnet nuget versions [SOLUTION_PROJECT] [-h|--help] [--gc] [--dry-run]

Description

It evaluates the packages used be the projects specified by [SOLUTION_PROJECT] and removes any not used package references from Directory.Packages.props file.

Arguments

SOLUTION_PROJECT

A solution or a project file. If not specified, the command searches the current directory for a solution or a project file. If multiple are found the command will error.

Options

--gc

The package references not referenced in any of the projects will be deleted from the Directory.Packages.props. If the Package references are pinned in the central file the elements are not removed.

<Package Include="Newtonsoft.Json" Version="10.0.1" Pin="true"/>

--dry-run

It will print the items that will be removed from the Directory.Packages.props file.

Examples

ProjectA> dotnet nuget versions MySolution1.sln --dry-run
4 not used packages will be removed from [path]\Directory.Packages.props.
PackageId : 'Newtonsoft.Json' Version:"12.0.0"  
PackageId : 'XUnit' Version: "2.4.0"  
PackageId : 'NUnit' Version: "3.9.0"  
PackageId : 'EnityFramework' Version: "6.2.0"  

3 packages were pinned and they will not be removed.
PackageId : 'NuGet.Packaging' Version:"5.3.0". The Package is not a direct or a transitive dependency.
PackageId : 'NuGet.Common' Version:"5.2.0". The Package is a direct dependency for projects: ProjectA.
PackageId : 'System.Threading' Version:"4.0.11". The Package is a transitive dependency for projects: ProjectB, ProjectC.

ProjectA> dotnet nuget versions MySolution1.sln --gc
4 not used packages were removed from [path]\Directory.Packages.props.
PackageId : 'Newtonsoft.Json' Version:"12.0.0"  
PackageId : 'XUnit' Version: "2.4.0"  
PackageId : 'NUnit' Version: "3.9.0"  
PackageId : 'EnityFramework' Version: "6.2.0"  

Visual Studio Experience

Only for SDK Style projects install/unistall/update package references will be supported in Visual Studio. For the Package Reference legacy style projects the updates need to be manually performed.

For a project that is opt-out from Central Package Version Management the install/unistall/update of package versions will work as currently.

The Directory.Packages.props file exists at the solution level and projects are not opt-out from Central Package Version Management.

Project PMUI Experience

Install a package in the project, with a specific version already used in the solution

The UI will present the version installed in the Directory.Packages.props file. The other versions wil be available as currently.

a. User chooses the Recommended version and install.
Result: A new entry <PackageReference Include="EntityFramework" /> is added to the project's file.

b. The user does not select the recommended version but a different version.

Result: The user will be presented with the confirmation window. Confirmation dialog while updating a package version:

After the confirmation:

• A new entry <PackageReference Include="EntityFramework" /> is added to the project's file
• The version in the Directory.Packages.props is updated.

Install a package in the project that was not installed in the Directory.Packages.props

The UI will be as currently. User can select the version desired and chose to install. Result:

• A new entry <PackageReference Include="EntityFramework" /> is added to the project's file
• A new entry <Package Include="EntityFramework" Version="6.0.2"/> is added to Directory.Packages.props file.

Update a package version

On version update:

• If the project had a PackageReference element with a version, the Version metadata will be removed.
• The reference in the Directory.Packages.props is updated to the new version.

UnInstall a package

On uninstall

• The entry <PackageReference Include="EntityFramework" /> is removed from the project's file
• No change is applied to the Directory.Packages.props file.

Install/Update/Uninstall for legacy PackageReference projects opted-in Central Package Version Management

The user will be presented with an info dialog when trying to access "Manage NuGet packages" and the update is not possible.

Install/Update/Uninstall for projects opted-out Central Package Version Management

The experience is unchanged. The 'Version' value of the PackageReference element at the project level will be updated/added/removed.

Solution PMUI Experience

Install a package in the project, with a specific version already used in the solution

The UI will be similar with the current UI but the Centrally Managed package versions are marked.

a. User chooses the Centrally managed pacakge version to be installed.

Result: A new entry <PackageReference Include="EntityFramework" /> is added to the project's file.

b. The user does not select the recommended version but a different version.

Result: The user will be presented with a confirmation window that will inform that the version will be changed for the set of projects. Confirmation dialog while updating a package version:

After the confirmation:

• A new entry <PackageReference Include="EntityFramework" /> is added to the project's file.
• The version in the Directory.Packages.props is updated.

Install a package in the project that was not installed in the Directory.Packages.props

The UI will be as currently. User can select the version desired and chose to install. Result:

• A new entry <PackageReference Include="EntityFramework" /> is added to the project's file.
• A new entry <Package Include="EntityFramework" Version="6.0.2"/> is added to Directory.Packages.props file.

UnInstall a package

On uninstall

• The entry <PackageReference Include="EntityFramework" /> is removed from the projects' file.
• There is not any modification applied to the Directory.Packages.props file.

Install/Update/Uninstall for legacy PackageReference projects opted-in Central Package Version Management

The Solution PMUI will grey out the boxes for the Legacy Projects opted-in Central Package Version Management

Install/Update/Uninstall for projects opted-out Central Package Version Management

The experience is unchanged. The 'Version' value of the PackageReference element at the project level will be updated/added/removed.

What is currently not supported in Central Package Version Management

Project types not supported

Central Package Managed Version is supported only for "Package Reference" projects types.

Dual feature opt-in and opt-out

A project opted-in Central Package Version Management cannot be used in a Visual Studio solution that is not opted-in Central Package Version Management.

Tooling

• Visual Studio and DotNet CLI support only SDK style projects. For Legacy ProjectReference style projects all the updates need to be manually applied.

• The initial Directory.Packages.props will be created only through dotnet.exe not Visual Studio.

FAQ

How to enable the Central Package Version Management?

See Opt-in Central Package Version Management.

How a project can opt-out from Central Package Version Management?

Individual projects can opt-out of Central Package Version Management by using the EnableCentralPackageVersions MsBuild property as below.

<EnableCentralPackageVersions>false</EnableCentralPackageVersions> 

By default projects are opted-out from Central Package Version Management.

How do I transform my existing projects to use this functionality?

Manually create the Directory.Packages.props and remove the version information from the project files.

Will a central defined Package version influence transitive dependency resolution ?

Yes. If a package version is mentioned in the Directory.Packages.props any transitive dependency will be resolved to the central defined version.

For example in the scenario below PackageB depends on PackageC version 2.0.0. PackageC version 3.0.0 is added to the Directory.Packages.props file. The PackageC reference resolution for SampleProject will be 3.0.0.

Directory.Packages.props

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <ItemGroup>
    <PackageVersion Include="PackageA" Version="1.0.0" />
    <PackageVersion Include="PackageB" Version="1.0.0" />
    <PackageVersion Include="PackageC" Version="3.0.0" />
  </ItemGroup>
</Project>

SampleProject.csproj

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

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="PackageB" />
  </ItemGroup>
</Project>

Will be changes in the pack command ?

If a project had a transitive dependency enforced through central definition the dependency is added to the list of packet direct dependencies.

Where are PrivateAssets/ExcludeAssets/IncludeAssets defined?

These are per project properties and should be defined in the PackageReference nodes in the project file.

How does restore NoOp work i.e. when does NuGet try to actually restore or choose not to restore?

The current logic is used except that the package versions are referenced from the Directory.Packages.props file.

Can I use my custom version of Directory.Packages.props?

This will not be supported in the first feature version.

Can I use the Central Package Version Management and still preserve the Version metadata?

No, an error will be generated if the Version attribute is present at the project PackageReference elements.

Can I have a given set of package versions for all the projects but a different set for a specific project?

To override the global packages' version constraints for a specific project, you can define Directory.Packages.props file in the project root directory. This will override the global settings from the solution Directory.Packages.props file.

What happens when there are multiple Directory.Packages.props file available in a project's context?

In order to remove any confusion, the Directory.Packages.props nearest to the project will override all others. At a time only one Directory.Packages.props file is evaluated for a given project.

E.g. in the below scenario

Repo
 |-- Directory.Packages.props
 |-- Solution1
     |-- Directory.Packages.props
     |-- Project1
 |-- Solution2
     |-- Project2

In the above scenario:

• Project1 will refer to only `Repo\Solution1\Directory.Packages.props``
• Project2 will refer to only Repo\Directory.Packages.props

Can I specify NuGet sources in the Directory.Packages.props file?

This is not part of the spec/feature but specifying sources in the Directory.Packages.props file seems like a good idea.

Can I change my repo to use the Central Package Version Management and use old tools later?

No. Because the Version will be removed from the projects' level you cannot use old tools to build the repo.

Next Steps (post MVP)

1. > dotnet nuget versions [SOLUTION_PROJECT] [-h|--help] [--consolidate/centralize] [--dry-run] New command to support migration scenarios. It will create the Directory.Packages.props file.

2. Allow custom file for the central packages file.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <CentralPackagesFile>$(MSBuildThisFileDirectory)MyPackageVersions.props</CentralPackagesFile>
  </PropertyGroup>
</Project>

Naming

The name is not definitive and we are looking for better name pattern.