Skip to content

Commit c6a9009

Browse files
JonDouglasJonDouglas
authored
Merge pull request NuGet#2692 from NuGet/cpm
Central Package Management Doc
2 parents 74cf41b + b84fafc commit c6a9009

File tree

2 files changed

+159
-0
lines changed

2 files changed

+159
-0
lines changed

‎docs/TOC.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232
### [PackageReference in project files](consume-packages/package-references-in-project-files.md)
3333
### [Migrate packages.config to PackageReference](consume-packages/migrate-packages-config-to-package-reference.md)
3434
### [packages.config](reference/packages-config.md)
35+
### [Central Package Management](consume-packages/Central-Package-Management.md)
3536
# Create packages
3637
## [Overview and workflow](create-packages/overview-and-workflow.md)
3738
## [Create a package (dotnet CLI)](create-packages/creating-a-package-dotnet-cli.md)

‎docs/consume-packages/Central-Package-Management.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
title: Central Package Management
3+
description: Manage your dependencies in a central location and how you can get started with central package management.
4+
author: jondouglas
5+
ms.author: jodou
6+
ms.date: 2/25/2022
7+
ms.topic: conceptual
8+
---
9+
10+
# Central Package Management
11+
12+
Dependency management is a core feature of NuGet. Managing dependencies for a single project can be easy. Managing dependencies for multi-project solutions can prove to be difficult as they start to scale in size and complexity. In situations where you manage common dependencies for many different projects, you can leverage NuGet's central package management features to do all of this from the ease of a single location.
13+
14+
Historically, NuGet package dependencies have been managed in two main locations:
15+
16+
- `packages.config` - An XML file used in older project types to maintain the list of packages referenced by the project.
17+
- `<PackageReference />` - An XML element used in new project types that manages NuGet dependencies directly within project files.
18+
19+
Starting with [NuGet 6.2](..\release-notes\NuGet-6.2.md), you can centrally manage your dependencies in your projects with the addition of a `Directory.Packages.props` file.
20+
21+
The feature is available across all NuGet integrated tooling.
22+
23+
* [Visual Studio 2022 17.2 and later](https://visualstudio.microsoft.com/downloads/)
24+
* [.NET SDK 6.0.300 and later](https://dotnet.microsoft.com/download/dotnet/6.0)
25+
* [nuget.exe 6.2.0 and later](https://www.nuget.org/downloads)
26+
27+
Older tooling will ignore Central Package Management configurations and features. To use this feature to the fullest extent, ensure all your build environments use the latest compatible tooling versions.
28+
29+
Central Package Management will apply to all `<PackageReference>` projects – including [legacy .csproj](https://github.com/dotnet/project-system/blob/main/docs/feature-comparison.md) – as long as compatible tooling is used.
30+
31+
## Enabling Central Package Management
32+
33+
To get started with central package management, you can create a `Directory.Packages.props` file at the root of your solution.
34+
35+
Inside, you can define each of the respective package versions required of your solution using `<PackageVersion />` elements that define the package ID and version.
36+
37+
```xml
38+
<Project>
39+
<ItemGroup>
40+
<PackageVersion Include="Newtonsoft.Json" Version="13.0.1" />
41+
</ItemGroup>
42+
</Project>
43+
```
44+
45+
Within a project of the solution, you can then use the respective `<PackageReference />` syntax you know and love, but without a `Version` attribute to infer the centrally managed version instead.
46+
47+
```xml
48+
<Project Sdk="Microsoft.NET.Sdk">
49+
50+
<PropertyGroup>
51+
<TargetFramework>net6.0</TargetFramework>
52+
</PropertyGroup>
53+
54+
<ItemGroup>
55+
<PackageReference Include="Newtonsoft.Json" />
56+
</ItemGroup>
57+
</Project>
58+
```
59+
60+
Now you're using central package management and managing your versions in a central location!
61+
62+
## Central Package Management rules
63+
64+
The `Directory.Packages.props` file has a number of rules with regards to where it's located in a repository's directory and its context. For the sake of simplicity, only one `Directory.Packages.props` file is evaluated for a given project.
65+
66+
What this means is that if you had multiple `Directory.Packages.props` files in your repository, the file that is closest to your project's directory will be evaluated for it. This allows you extra control at various levels of your repository.
67+
68+
Here's an example, consider the following repository structure:
69+
70+
```
71+
Repository
72+
|-- Directory.Packages.props
73+
|-- Solution1
74+
|-- Directory.Packages.props
75+
|-- Project1
76+
|-- Solution2
77+
|-- Project2
78+
```
79+
80+
- Project1 will evaluate the `Directory.Packages.props` file in the `Repository\Solution1\` directory.
81+
- Project2 will evaluate the `Directory.Packages.props` file in the `Repository\` directory.
82+
83+
## Get started
84+
85+
To fully onboard your repository, consider taking these steps:
86+
87+
1. Create a new file at the root of your repository named `Directory.Packages.props` that declares your centrally defined package versions in.
88+
2. Declare `<PackageVersion />` items in your `Directory.Packages.props`.
89+
3. Declare `<PackageReference />` items without `Version` attributes in your project files.
90+
91+
<!--For an idea of how central package management may look like, refer to our [samples repo](https://github.com/NuGet/Samples/tree/main/CentralPackageManagementExample).-->
92+
93+
## Transitive pinning
94+
95+
You can automatically override a transitive package version even without an explicit top-level `<PackageReference />` by opting into a feature known as transitive pinning. This promotes a transitive dependency to a top-level dependency implicitly on your behalf when necessary.
96+
97+
You can enable this feature by setting the MSBuild property `CentralPackageTransitivePinningEnabled` to `true` in a project or in a `Directory.Packages.props` or `Directory.Build.props` import file:
98+
99+
```xml
100+
<PropertyGroup>
101+
<CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
102+
</PropertyGroup>
103+
```
104+
105+
## Overriding package versions
106+
107+
You can override an individual package version by using the `VersionOverride` property on a `<PackageReference />` item. This overrides any `<PackageVersion />` defined centrally.
108+
109+
```xml
110+
<Project>
111+
<ItemGroup>
112+
<PackageVersion Include="PackageA" Version="1.0.0" />
113+
<PackageVersion Include="PackageB" Version="2.0.0" />
114+
</ItemGroup>
115+
<Project>
116+
```
117+
118+
```xml
119+
<Project Sdk="Microsoft.NET.Sdk">
120+
<PropertyGroup>
121+
<TargetFramework>net6.0</TargetFramework>
122+
</PropertyGroup>
123+
<ItemGroup>
124+
<PackageReference Include="PackageA" VersionOverride="3.0.0" />
125+
</ItemGroup>
126+
<Project>
127+
```
128+
129+
You can disable this feature by setting the MSBuild property `EnablePackageVersionOverride` to `false` in a project or in a `Directory.Packages.props` or `Directory.Build.props` import file:
130+
131+
```xml
132+
<PropertyGroup>
133+
<EnablePackageVersionOverride>false</EnablePackageVersionOverride>
134+
</PropertyGroup>
135+
```
136+
137+
When this feature is disabled, specifying a `VersionOverride` on any `<PackageReference />` item will result in an error at restore time indicating that the feature is disabled.
138+
139+
## Disabling Central Package Management
140+
141+
If you'd like to disable central package management for any reason, you can disable this feature with the following:
142+
143+
```xml
144+
<ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
145+
```
146+
147+
## Warning when using multiple package sources
148+
149+
When using central package management, you will see a `NU1507` warning if you have more than one package source defined in your configuration. To resolve this warning, map your package sources with [package source mapping](https://aka.ms/nuget-package-source-mapping) or specify a single package source.
150+
151+
```
152+
There are {0} package sources defined in your configuration. When using central package management, please map your package sources with package source mapping (https://aka.ms/nuget-package-source-mapping) or specify a single package source.
153+
```
154+
155+
> [!Note]
156+
> This feature is in active development. We appreciate you trying it out and providing any feedback you may have at [NuGet/Home](https://github.com/nuget/home/issues).
157+
>
158+
> * There is currently no support in Visual Studio or the .NET CLI for Central Package Management.

0 commit comments

Comments
 (0)