Skip to content

Commit 9dfbb5e

Browse files
jeffkljeffkl
committed
Cleanup
1 parent 9576cbd commit 9dfbb5e

File tree

1 file changed

+84
-82
lines changed

1 file changed

+84
-82
lines changed

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

Lines changed: 84 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Central Package Management
3-
description: Manage your dependencies in a central location and how you can get started with central package management.
3+
description: Manage your dependencies in a central location and learn how to get started with Central Package Management.
44
author: jondouglas
55
ms.author: jodou
66
ms.date: 05/09/2022
@@ -9,75 +9,75 @@ ms.topic: conceptual
99

1010
# Central Package Management (CPM)
1111

12-
Dependency management is a core feature of NuGet. Managing dependencies for a single project can be easy. Managing dependencies for multi-project solutions
13-
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
14-
can leverage NuGet's central package management (CPM) features to do all of this from the ease of a single location.
12+
Dependency management is a core feature of NuGet.
13+
While managing dependencies for a single project is straightforward, it becomes increasingly complex as the number of projects in a solution grows.
1514

16-
Historically, NuGet package dependencies have been managed in one of two locations:
15+
If you manage common dependencies for many different projects, you can leverage NuGet's Central Package Management (CPM) features to do all of this from a single, central location.
1716

18-
- `packages.config` - An XML file used in older project types to maintain the list of packages referenced by the project.
19-
- `<PackageReference />` - An XML element used in MSBuild projects defines NuGet package dependencies.
17+
Historically, NuGet package dependencies have been managed in one of two ways:
2018

21-
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
22-
`Directory.Packages.props` file and an MSBuild property.
19+
- `packages.config` – An XML file used in older project types to maintain the list of packages referenced by the project.
20+
- `<PackageReference />` – An XML element in MSBuild project files that defines NuGet package dependencies.
2321

24-
The feature is available across all NuGet integrated tooling, starting with the following versions.
22+
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 and an MSBuild property.
23+
24+
This feature is available across all NuGet-integrated tooling, starting with the following versions:
2525

2626
* [Visual Studio 2022 17.2](https://visualstudio.microsoft.com/downloads/)
2727
* [.NET SDK 6.0.300](https://dotnet.microsoft.com/download/dotnet/6.0)
2828
* [nuget.exe 6.2.0](https://www.nuget.org/downloads)
2929

30-
Older tooling will ignore central package management configurations and features. To use this feature to the fullest extent, ensure all your build environments
31-
use the latest compatible tooling versions.
30+
Older tooling will ignore Central Package Management configurations and features.
31+
To use this feature to the fullest extent, ensure all your build environments use the latest compatible tooling versions.
3232

33-
Central package management applies to all `<PackageReference>`-based MSBuild projects (including
34-
[legacy CSPROJ](https://github.com/dotnet/project-system/blob/main/docs/feature-comparison.md)) as long as compatible tooling is used.
33+
Central Package Management applies to all `<PackageReference>`-based MSBuild projects (including [legacy CSPROJ](https://github.com/dotnet/project-system/blob/main/docs/feature-comparison.md)) as long as compatible tooling is used.
3534

3635
## Enabling Central Package Management
3736

38-
To get started with central package management, you must create a `Directory.Packages.props` file at the root of your repository and set the MSBuild property
39-
`ManagePackageVersionsCentrally` to `true`.
37+
To get started with Central Package Management, create a `Directory.Packages.props` file at the root of your repository and set the MSBuild property `ManagePackageVersionsCentrally` to `true`.
38+
39+
You can create it manually, or use the .NET CLI:
4040

41-
You can create it manually or you can use the dotnet CLI:
42-
``` shell
41+
```shell
4342
dotnet new packagesprops
4443
```
4544

46-
Inside, you then define each of the respective package versions required of your projects using `<PackageVersion />` elements that define the package ID and
47-
version.
45+
Inside `Directory.Packages.props`, define `<PackageVersion />` elements to specify the package IDs and versions used by your projects.
4846

4947
```xml
5048
<Project>
5149
<PropertyGroup>
5250
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
5351
</PropertyGroup>
5452
<ItemGroup>
55-
<PackageVersion Include="Newtonsoft.Json" Version="13.0.1" />
53+
<PackageVersion Include="PackageA" Version="1.0.0" />
54+
<PackageVersion Include="PackageB" Version="2.0.0" />
5655
</ItemGroup>
5756
</Project>
5857
```
5958

60-
For each project, you then define a `<PackageReference />` but omit the `Version` attribute since the version will be obtained from a corresponding
61-
`<PackageVersion />` item.
59+
In each project file, define `<PackageReference />` elements without the `Version` attribute.
60+
The version will be resolved from the corresponding `<PackageVersion />` entry in `Directory.Packages.props`.
6261

6362
```xml
6463
<Project Sdk="Microsoft.NET.Sdk">
6564
<PropertyGroup>
6665
<TargetFramework>net6.0</TargetFramework>
6766
</PropertyGroup>
6867
<ItemGroup>
69-
<PackageReference Include="Newtonsoft.Json" />
68+
<PackageReference Include="PackageA" />
7069
</ItemGroup>
7170
</Project>
7271
```
7372

74-
Now you're using central package management and managing your versions in a central location!
73+
Now you're using Central Package Management and managing your versions in a central location!
7574

7675
### Using Different Versions for Different Target Frameworks
7776

78-
As NuGet packages evolve, sometimes package owners drop support for older target frameworks.
79-
This can cause issues for developers of libraries that still target older frameworks where they want to reference newer versions of packages with newer target frameworks.
80-
For example, this project targets .NET Standard 2.0, .NET 8.0, and .NET Framework 4.7.2 but references `PackageA` which no longer supports .NET Standard 2.0 in its latest version.
77+
As NuGet packages evolve, package owners may drop support for older target frameworks.
78+
This can cause issues for developers of libraries that still target older frameworks but want to reference newer versions of packages for newer target frameworks.
79+
80+
For example, if your project targets .NET Standard 2.0, .NET 8.0, and .NET Framework 4.7.2, but `PackageA` no longer supports .NET Standard 2.0 in its latest version, you can specify different versions for each target framework.
8181

8282
```xml
8383
<Project Sdk="Microsoft.NET.Sdk">
@@ -90,7 +90,7 @@ For example, this project targets .NET Standard 2.0, .NET 8.0, and .NET Framewor
9090
</Project>
9191
```
9292

93-
In this case, you can define different versions for each target framework in your `Directory.Packages.props` using [MSBuild conditions](/visualstudio/msbuild/msbuild-conditions):
93+
In this case, define different versions for each target framework in your `Directory.Packages.props` using [MSBuild conditions](/visualstudio/msbuild/msbuild-conditions):
9494

9595
```xml
9696
<Project>
@@ -104,15 +104,15 @@ In this case, you can define different versions for each target framework in you
104104
</Project>
105105
```
106106

107-
## Central Package Management rules
107+
## Central Package Management Rules
108108

109-
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
110-
simplicity, only one `Directory.Packages.props` file is evaluated for a given project.
109+
The `Directory.Packages.props` file has specific rules regarding its location and context within a repository.
110+
Only one `Directory.Packages.props` file is evaluated for a given project by default.
111111

112-
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
113-
be evaluated for it. This allows you extra control at various levels of your repository.
112+
If you have multiple `Directory.Packages.props` files in your repository, the file closest to a given project's directory will be evaluated for it.
113+
This allows extra control at various levels of your repository.
114114

115-
Consider the following repository structure:
115+
Consider the following repository directory structure:
116116

117117
```
118118
📂 (root)
@@ -129,50 +129,54 @@ Consider the following repository structure:
129129
└─ 📄 Project2.csproj
130130
```
131131

132-
- `Project1.csproj` will load the `Directory.Packages.props` file in the `Repository\Solution1\` directory first and it must manually import any parent ones if desired.
133-
```xml
134-
<Project>
135-
<Import Project="$([MSBuild]::GetPathOfFileAbove(Directory.Packages.props, $(MSBuildThisFileDirectory)..))" />
136-
<ItemGroup>
137-
<PackageVersion Update="Newtonsoft.Json" Version="12.0.1" />
138-
</ItemGroup>
139-
</Project>
140-
```
141-
- `Project2.csproj` will evaluate the `Directory.Packages.props` file in the root directory.
132+
`Project1.csproj` will use the `Directory.Packages.props` file in the `Repository\Solution1\` directory.
133+
If you want to include settings from a parent `Directory.Packages.props`, you must manually import it.
134+
135+
```xml
136+
<Project>
137+
<Import Project="$([MSBuild]::GetPathOfFileAbove(Directory.Packages.props, $(MSBuildThisFileDirectory)..))" />
138+
<ItemGroup>
139+
<PackageVersion Update="Newtonsoft.Json" Version="12.0.1" />
140+
</ItemGroup>
141+
</Project>
142+
```
143+
144+
`Project2.csproj` will evaluate the `Directory.Packages.props` file in the root directory.
142145

143-
**Note:** MSBuild will not automatically import each `Directory.Packages.props` for you, only the first one found in the project directory or any parent directory. If you have multiple
144-
`Directory.Packages.props` files, you must import any files in parent directories manually.
146+
> [!NOTE]
147+
> MSBuild will only automatically import the first `Directory.Packages.props` file it finds in the project directory or any parent directory.
148+
> If you have multiple such files, you must manually import parent files as needed.
145149
146-
## Get started
150+
## Getting Started
147151

148152
To fully onboard your repository, follow these steps:
149153

150-
1. Create a new file at the root of your repository named `Directory.Packages.props` that declares your centrally defined package versions and set
151-
the MSBuild property `ManagePackageVersionsCentrally` to `true`.
154+
1. Create a new file at the root of your repository named `Directory.Packages.props` that declares your centrally defined package versions and set the MSBuild property `ManagePackageVersionsCentrally` to `true`.
152155
2. Declare `<PackageVersion />` items in your `Directory.Packages.props`.
153156
3. Declare `<PackageReference />` items without `Version` attributes in your project files.
154157

155-
For an idea of how central package management may look like, refer to our [samples repo](https://github.com/NuGet/Samples/tree/main/CentralPackageManagementExample).
158+
For an example of how Central Package Management may look, refer to our [samples repository](https://github.com/NuGet/Samples/tree/main/CentralPackageManagementExample).
156159

157-
## Transitive pinning
160+
## Pinning Transitive Packages to Different Versions
158161

159-
You can automatically override a transitive package version even without an explicit top-level `<PackageReference />` by opting into a feature known as
160-
transitive pinning. This promotes a transitive dependency to a top-level dependency implicitly on your behalf when necessary.
161-
Note that downgrades are not allowed when transitive pinning a package. If you attempt to pin a package to a lower version than the one requested by your dependencies, restore will raise a [NU1109](../reference/errors-and-warnings/NU1109.md) error.
162+
You can automatically override a transitive package version without an explicit top-level `<PackageReference />` item by opting into a feature known as transitive pinning.
163+
This promotes a transitive dependency to a top-level dependency implicitly on your behalf when necessary.
162164

163-
You can enable this feature by setting the MSBuild property `CentralPackageTransitivePinningEnabled` to `true` in a project or in a `Directory.Packages.props`
164-
or `Directory.Build.props` import file:
165+
Note that downgrades are not allowed when transitive pinning a package.
166+
If you attempt to pin a package to a lower version than the one requested by your dependencies, restore will raise a [NU1109](../reference/errors-and-warnings/NU1109.md) error.
167+
168+
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:
165169

166170
```xml
167171
<PropertyGroup>
168172
<CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
169173
</PropertyGroup>
170174
```
171175

172-
### Transitive pinning and pack
176+
### Transitive Pinning and Pack
173177

174-
When a package is transitively pinned, your project uses a higher than the one requested by your dependencies.
175-
If you create a package from your project, in order to ensure that your package will work, NuGet will promote the transitively pinned dependencies to explicit dependencies in the nuspec.
178+
When a package is transitively pinned, your project uses a higher version than the one requested by your dependencies.
179+
If you create a package from your project, to ensure that your package will work, NuGet will promote the transitively pinned dependencies to explicit dependencies in the nuspec.
176180

177181
In the following example, `PackageA 1.0.0` has a dependency on `PackageB 1.0.0`.
178182

@@ -200,18 +204,18 @@ In the following example, `PackageA 1.0.0` has a dependency on `PackageB 1.0.0`.
200204
When you use the pack command to create a package, both packages will appear in the dependency group.
201205

202206
```xml
203-
<group targetFramework="net6.0">
204-
<dependency id="PackageA" version="1.0.0" exclude="Build,Analyzers" />
205-
<dependency id="PackageB" version="2.0.0" exclude="Build,Analyzers" />
206-
</group>
207+
<group targetFramework="net6.0">
208+
<dependency id="PackageA" version="1.0.0" exclude="Build,Analyzers" />
209+
<dependency id="PackageB" version="2.0.0" exclude="Build,Analyzers" />
210+
</group>
207211
```
208212

209-
Because of this, the use of transitive pinning should be carefully evaluated when authoring a library as it may lead to dependencies you did not expect.
213+
Because of this, the use of transitive pinning should be carefully evaluated when authoring a library, as it may lead to dependencies you did not expect.
210214

211-
## Overriding package versions
215+
## Overriding Package Versions
212216

213-
You can override an individual package version by using the `VersionOverride` property on a `<PackageReference />` item. This overrides any `<PackageVersion />`
214-
defined centrally.
217+
You can override an individual package version by using the `VersionOverride` property on a `<PackageReference />` item.
218+
This will take precedence over any centrally defined `<PackageVersion />`.
215219

216220
```xml
217221
<Project>
@@ -233,22 +237,19 @@ defined centrally.
233237
</Project>
234238
```
235239

236-
You can disable this feature by setting the MSBuild property `CentralPackageVersionOverrideEnabled` to `false` in a project or in a `Directory.Packages.props` or
237-
`Directory.Build.props` import file:
240+
You can disable this feature by setting the MSBuild property `CentralPackageVersionOverrideEnabled` to `false` in a project or in a `Directory.Packages.props` or `Directory.Build.props` import file:
238241

239242
```xml
240243
<PropertyGroup>
241244
<CentralPackageVersionOverrideEnabled>false</CentralPackageVersionOverrideEnabled>
242245
</PropertyGroup>
243246
```
244247

245-
When this feature is disabled, specifying a `VersionOverride` on any `<PackageReference />` item will result in an error at restore time indicating that
246-
the feature is disabled.
248+
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.
247249

248250
## Disabling Central Package Management
249251

250-
If you would like to disable central package management for a particular project, you can disable it by setting the MSBuild property
251-
`ManagePackageVersionsCentrally` to `false`:
252+
To disable Central Package Management for a specific project, set the MSBuild property `ManagePackageVersionsCentrally` to `false`:
252253

253254
```xml
254255
<PropertyGroup>
@@ -258,17 +259,18 @@ If you would like to disable central package management for a particular project
258259

259260
## Global Package References
260261

261-
> [!Note]
262+
> [!NOTE]
262263
> This feature is only available in Visual Studio 2022 17.4 or higher, .NET SDK 7.0.100.preview7 or higher, and NuGet 6.4 or higher.
263264
264-
A global package reference is used to specify that a package will be used by every project in a repository. This includes packages that do versioning, extend your build, or any other packages that are needed by all projects. Global package references are added to the PackageReference item group with the following metadata:
265+
A global package reference is used to specify that a package will be used by every project in a repository.
266+
This includes packages that do versioning, extend your build, or any other packages that are needed by all projects.
267+
Global package references are added to the PackageReference item group with the following metadata:
265268

266269
* `IncludeAssets="Runtime;Build;Native;contentFiles;Analyzers"`<br/>
267-
This ensures that the package is only used as a development dependency and prevents any compile-time assembly references.
270+
This ensures that the package is only used as a development dependency and prevents it from being included as a compile-time assembly reference.
268271
* `PrivateAssets="All"`<br/>
269272
This prevents global package references from being picked up by downstream dependencies.
270273

271-
272274
`GlobalPackageReference` items should be placed in your `Directory.Packages.props` to be used by every project in a repository:
273275

274276
```xml
@@ -279,11 +281,11 @@ A global package reference is used to specify that a package will be used by eve
279281
</Project>
280282
```
281283

282-
## Warning when using multiple package sources
284+
## NU1507 Warning When Using Multiple Package Sources
283285

284-
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
285-
this warning, map your package sources with [package source mapping](https://aka.ms/nuget-package-source-mapping) or specify a single package source.
286+
When using Central Package Management, NuGet will log an [`NU1507`](../reference/errors-and-warnings/nu1507.md) warning if more than one package source is defined in your configuration.
287+
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.
286288

287289
```
288-
There are 3 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.
290+
There are 3 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.
289291
```

0 commit comments

Comments
 (0)