Skip to content

Commit 0a5f55c

Browse files
jeffkljeffkl
authored
Improve documentation for Central Package Management (#3414)
1 parent ebe6f76 commit 0a5f55c

File tree

8 files changed

+193
-93
lines changed

8 files changed

+193
-93
lines changed

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

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
---
1+
---
22
title: Central Package Management
33
description: Manage your dependencies in a central location and how you can get started with central package management.
44
author: jondouglas
@@ -18,7 +18,7 @@ Historically, NuGet package dependencies have been managed in one of two locatio
1818
- `packages.config` - An XML file used in older project types to maintain the list of packages referenced by the project.
1919
- `<PackageReference />` - An XML element used in MSBuild projects defines NuGet package dependencies.
2020

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
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
2222
`Directory.Packages.props` file and an MSBuild property.
2323

2424
The feature is available across all NuGet integrated tooling, starting with the following versions.
@@ -57,7 +57,7 @@ version.
5757
</Project>
5858
```
5959

60-
For each project, you then define a `<PackageReference />` but omit the `Version` attribute since the version will be attained from a corresponding
60+
For each project, you then define a `<PackageReference />` but omit the `Version` attribute since the version will be obtained from a corresponding
6161
`<PackageVersion />` item.
6262

6363
```xml
@@ -81,19 +81,24 @@ simplicity, only one `Directory.Packages.props` file is evaluated for a given pr
8181
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
8282
be evaluated for it. This allows you extra control at various levels of your repository.
8383

84-
Here's an example, consider the following repository structure:
84+
Consider the following repository structure:
8585

8686
```
87-
Repository
88-
|-- Directory.Packages.props
89-
|-- Solution1
90-
|-- Directory.Packages.props
91-
|-- Project1
92-
|-- Solution2
93-
|-- Project2
87+
📂 (root)
88+
├─📄 Directory.Packages.props
89+
|
90+
├─📂Solution1
91+
| ├─ 📄Directory.Packages.props
92+
| |
93+
| └─ 📂 Project1
94+
| └─📄Project1.csproj
95+
|
96+
└─ 📂 Solution2
97+
└─ 📂 Project2
98+
└─ 📄 Project2.csproj
9499
```
95100

96-
- Project1 will evaluate the `Directory.Packages.props` file in the `Repository\Solution1\` directory and it must manually import the next one if so desired.
101+
- `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.
97102
```xml
98103
<Project>
99104
<Import Project="$([MSBuild]::GetPathOfFileAbove(Directory.Packages.props, $(MSBuildThisFileDirectory)..))" />
@@ -102,14 +107,14 @@ Repository
102107
</ItemGroup>
103108
</Project>
104109
```
105-
- Project2 will evaluate the `Directory.Packages.props` file in the `Repository\` directory.
110+
- `Project2.csproj` will evaluate the `Directory.Packages.props` file in the root directory.
106111

107-
**Note:** MSBuild will not automatically import each `Directory.Packages.props` for you, only the first one closest to the project. If you have multiple
108-
`Directory.Packages.props`, you must import the parent one manually while the root `Directory.Packages.props` would not.
112+
**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
113+
`Directory.Packages.props` files, you must import any files in parent directories manually.
109114

110115
## Get started
111116

112-
To fully onboard your repository, consider taking these steps:
117+
To fully onboard your repository, follow these steps:
113118

114119
1. Create a new file at the root of your repository named `Directory.Packages.props` that declares your centrally defined package versions and set
115120
the MSBuild property `ManagePackageVersionsCentrally` to `true`.
@@ -251,8 +256,3 @@ this warning, map your package sources with [package source mapping](https://aka
251256
```
252257
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.
253258
```
254-
255-
256-
257-
> [!Note]
258-
> Central package management 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).

‎docs/reference/errors-and-warnings/NU1008.md

Lines changed: 30 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -11,51 +11,49 @@ f1_keywords:
1111

1212
# NuGet Error NU1008
1313

14-
> Projects that use central package version management should not define the version on the PackageReference items but on the PackageVersion items: PackageId.
14+
> The following PackageReference items cannot define a value for Version: PackageName. Projects using Central Package Management must define a Version value on a PackageVersion item.
1515
16-
### Issue
16+
## Issue
1717

18-
When using central package management, versions must be defined on the PackageVersion item.
19-
20-
In your project file, you may see:
18+
A project is configured to use NuGet [Central Package Management](../../consume-packages/Central-Package-Management.md) and a `<PackageReference />` item is defined which specifies a value for the `Version` attribute:
2119

2220
```xml
23-
<!-- In the project file. -->
24-
<PackageReference Include="PackageId" Version="5.1.0" />
21+
<ItemGroup>
22+
<PackageReference Include="PackageName" Version="5.1.0" />
23+
</ItemGroup>
2524
```
2625

27-
### Solution
28-
29-
- Remove the version from the PackageId PackageReference.
30-
- You may need to add or update the PackageVersion item for PackageId in Directory.Packages.props
31-
32-
Example:
26+
Alternatively, a `<PackageReference />` item is defined with a child `<Version />` element that has a value specified:
27+
```xml
28+
<ItemGroup>
29+
<PackageReference Include="PackageName">
30+
<Version>5.1.0</Version>
31+
</PackageReference>
32+
</ItemGroup>
33+
```
3334

34-
```xml
35-
<!-- In the project file. -->
36-
<PackageReference Include="PackageId" />
37-
```
35+
Projects configured to use [Central Package Management](../../consume-packages/Central-Package-Management.md) should not define a version on `<PackageReference />` items.
36+
The version should be defined in on a corresponding `<PackageVersion />` item with the same identifier in [Directory.Packages.props](../../consume-packages/Central-Package-Management.md#enabling-central-package-management) file instead.
3837

39-
```xml
40-
<!-- In the Directory.Packages.props -->
41-
<PackageVersion Include="PackageId" Version="5.1.0" />
42-
```
38+
## Solution
4339

44-
- Alternatively, you may override an individual package version by using the `VersionOverride` property on a `<PackageReference />` item.
45-
This overrides any `<PackageVersion />` defined centrally.
40+
- Remove the `Version` attribute or child `<Version />` element from the `<PackageReference />` item:
4641

47-
Example:
42+
```xml
43+
<ItemGroup>
44+
<PackageReference Include="PackageName" />
45+
</ItemGroup>
46+
```
4847

49-
```xml
50-
<!-- In the project file. -->
51-
<PackageReference Include="PackageId" VersionOverride="3.0.0" />
52-
```
48+
- Define a `<PackageVersion />` item that specifies the version in the [Directory.Packages.props](../../consume-packages/Central-Package-Management.md#enabling-central-package-management) file with the same identifier as the `<PackageReference />` item:
5349

54-
```xml
55-
<!-- In the Directory.Packages.props -->
56-
<PackageVersion Include="PackageId" Version="5.1.0" />
57-
```
50+
```xml
51+
<ItemGroup>
52+
<PackageVersion Include="PackageName" Version="5.0.1" />
53+
</ItemGroup>
54+
```
5855

56+
Alternatively, Central Package Management allows overriding centrally defined package versions. See [Overriding Package Versions](../../consume-packages/Central-Package-Management.md#overriding-package-versions) for more information.
5957

6058
> [!NOTE]
6159
> Note that metadata such as [IncludeAssets, PrivateAssets etc.](../../consume-packages/Package-References-in-Project-Files.md#controlling-dependency-assets) should remain on the PackageReference item.

‎docs/reference/errors-and-warnings/NU1009.md

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,29 @@ f1_keywords:
1111

1212
# NuGet Error NU1009
1313

14-
> The packages PackageId are implicitly referenced. You do not typically need to reference them from your project or in your central package versions management file. For more information, see https://aka.ms/sdkimplicitrefs
14+
> The following PackageReference items are implicitly defined and cannot define a PackageVersion item: PackageName. Projects using Central Package Management require that implicit package versions be specified by the PackageReference item.
1515
16-
### Issue
16+
## Issue
1717

18-
Implicitly defined packages should not be managed centrally.
18+
A project is configured to use NuGet [Central Package Management](../../consume-packages/Central-Package-Management.md) and a `<PackageVersion />` item is defined in the [Directory.Packages.props](../../consume-packages/Central-Package-Management.md#enabling-central-package-management) file for a package that is [implicitly defined](https://aka.ms/sdkimplicitrefs).
19+
Implicitly defined packages are generally declared by an SDK to include packages on your behalf.
20+
For these packages, the owner of the SDK controls the version being used and a user should not define a version with [Central Package Management](../../consume-packages/Central-Package-Management.md).
1921

20-
### Solution
22+
```xml
23+
<ItemGroup>
24+
<PackageReference Include="Microsoft.NETCore.App" Version="9.0.0" IsImplicitlyDefined="true" />
25+
</ItemGroup>
26+
```
2127

22-
Remove the PackageVersion for PackageId
28+
## Solution
29+
30+
- Remove the `PackageVersion` item from the [Directory.Packages.props](../../consume-packages/Central-Package-Management.md#enabling-central-package-management) file that corresponds to the implicitly defined package:
31+
32+
```xml
33+
<ItemGroup>
34+
<PackageVersion Include="Microsoft.NETCore.App" Version="1.0.0" />
35+
</ItemGroup>
36+
```
37+
38+
> [!NOTE]
39+
> Some SDKs allow you to override the implicitly defined package version by setting a specific MSBuild property for that package and the SDK may have documentation on how to do so.

‎docs/reference/errors-and-warnings/NU1010.md

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,27 @@ f1_keywords:
1111

1212
# NuGet Error NU1010
1313

14-
> The PackageReference items PackageId do not have corresponding PackageVersion.
14+
> The following PackageReference items do not define a corresponding PackageVersion item: PackageName. Projects using Central Package Management must declare PackageReference and PackageVersion items with matching names
1515
16-
### Issue
16+
## Issue
1717

18-
The PackageReference PackageId is missing a PackageVersion item.
18+
A project is configured to use NuGet [Central Package Management](../../consume-packages/Central-Package-Management.md) and a `<PackageReference />` item is defined but a corresponding `<PackageVersion />` item with the same name is not defined in the [Directory.Packages.props](../../consume-packages/Central-Package-Management.md#enabling-central-package-management) file:
1919

20-
### Solution
20+
```xml
21+
<ItemGroup>
22+
<PackageReference Include="PackageName" />
23+
</ItemGroup>
24+
```
2125

22-
Add a PackageVersion item for PackageId in the [Directory.Packages.props](../../consume-packages/Central-Package-Management.md).
26+
## Solution
27+
28+
- Define a `<PackageVersion />` item that specifies the version in the [Directory.Packages.props](../../consume-packages/Central-Package-Management.md#enabling-central-package-management) file with the same identifier as the `<PackageReference />` item:
29+
30+
```xml
31+
<ItemGroup>
32+
<PackageVersion Include="PackageName" Version="5.0.1" />
33+
</ItemGroup>
34+
```
35+
- If a `<PackageVersion />` item is properly defined and this error occurs in Visual Studio, check the Error List window for errors related to loading the project or failed [design time builds](https://github.com/dotnet/project-system/blob/main/docs/design-time-builds.md).
36+
If Visual Studio is not able to successfully load the project or a design time build fails, NuGet may log this error because it does not have the required information to restore.
37+
Resolving these underlying issues should fix this error.

‎docs/reference/errors-and-warnings/NU1011.md

Lines changed: 24 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -11,27 +11,38 @@ f1_keywords:
1111

1212
# NuGet Error NU1011
1313

14-
> Centrally defined floating package versions are not allowed.
14+
> The following PackageVersion items cannot specify a floating version: PackageName.
1515
16-
### Issue
16+
## Issue
1717

18-
By default, `<PackageVersion />` items cannot contain floating versions. NuGet's central package management (CPM) is considered an enterprise-level feature which provides easier version
19-
management at scale as well as deterministic and secure restores. The use of floating versions introduces the possibility for a bad package to be introduced into your build
20-
after it has been pushed to a feed. This can lead to a situation where you made no changes in your repository but suddenly something is broken and there is no way for you to
21-
get back into a good state without removing the floating version or pushing a newer version of the package which is fixed. Using non-floating versions means that every upgrade
22-
to a package is backed by a commit in your repository making it easy to determine what change caused the break and to revert a commit to get back into a good state.
18+
A project is configured to use NuGet [Central Package Management](../../consume-packages/Central-Package-Management.md) and a `<PackageVersion />` item is defined which specifies a [floating version](../../concepts/Package-Versioning.md#version-ranges) value for the `Version` attribute:
2319

24-
The [Transitive Pinning](../../consume-packages/Central-Package-Management.md#transitive-pinning) feature is designed to allow you to explicitly override the transitive versions in your graph for more control. Using a floating version as an override could make restores of different projects end up with different versions for the package that is supposed to be pinned, thus going against the promise of using the central version.
20+
```xml
21+
<ItemGroup>
22+
<PackageVersion Include="PackageName" Version="1.*" />
23+
</ItemGroup>
24+
```
25+
By default, `<PackageVersion />` items cannot specify floating versions.
26+
NuGet's [Central Package Management](../../consume-packages/Central-Package-Management.md) provides users the ability to manage package versions in a single location as well as deterministic and secure restores.
27+
The use of floating versions introduces the possibility for a bad package to be introduced into your build after it has been pushed to a feed.
28+
This can lead to a situation where you made no changes in your repository but suddenly something is broken due to a problem in a new package and there is no way for you to get back into a good state without removing the floating version or pushing a newer version of the package which is fixed.
29+
Using non-floating versions means that every upgrade to a package is backed by a commit in your repository, making it easy to determine what change caused the break and allows you to revert a commit to get back into a good state.
30+
31+
Also, when using the [transitive pinning](../../consume-packages/Central-Package-Management.md#transitive-pinning) feature of [Central Package Management](../../consume-packages/Central-Package-Management.md), using a floating version as an override could make restores of different projects end up with different versions for the package that what is supposed to be pinned, thus going against the promise of using the centrally defined version.
2532

2633
NuGet recommends you use automation like [Dependabot](https://docs.github.com/code-security/dependabot/working-with-dependabot) to keep package versions up-to-date which provides
27-
a streamlined way of keeping packages updated while integrating into your existing developer workflow of a pull request, automated build validation, and testing all backed by a
28-
commit in your repository.
34+
a streamlined way of updating package versions while integrating into your existing developer workflow of a pull request, automated build validation, and testing all backed by a commit in your repository.
2935

36+
## Solution
3037

31-
### Solution
38+
- It is recommended to change the floating version to a [non floating version range](../../concepts/Package-Versioning.md#version-ranges):
39+
```xml
40+
<ItemGroup>
41+
<PackageVersion Include="PackageName" Version="1.0.0" />
42+
</ItemGroup>
43+
```
3244

33-
It is recommended to change the floating version to a [non floating version range](../../concepts/Package-Versioning.md#version-ranges). If that is not possible, you can enable
34-
floating versions with CPM by setting an MSBuild property:
45+
- If that is not possible, or you wish to use floating versions with Central Package Management, you can do so by setting an MSBuild property:
3546

3647
```xml
3748
<PropertyGroup>

‎docs/reference/errors-and-warnings/NU1013.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: NuGet Error NU1013
3+
description: NU1013 error code
4+
author: jeffkl
5+
ms.author: jeffkl
6+
ms.date: 03/24/2025
7+
ms.topic: reference
8+
f1_keywords:
9+
- "NU1013"
10+
---
11+
12+
# NuGet Error NU1013
13+
14+
> The following PackageReference items cannot specify a value for VersionOverride: PackageName. Projects using Central Package Management are currently configured to disable this functionality.
15+
16+
### Issue
17+
18+
A project is configured to use NuGet [Central Package Management](../../consume-packages/Central-Package-Management.md) and a `<PackageReference />` item is defined which specifies a value for the `VersionOverride` attribute but this functionality has been disabled:
19+
20+
```xml
21+
<PropertyGroup>
22+
<CentralPackageVersionOverrideEnabled>false</CentralPackageVersionOverrideEnabled>
23+
</PropertyGroup>
24+
<ItemGroup>
25+
<PackageReference Include="PackageName" VersionOverride="9.0.0" />
26+
</ItemGroup>
27+
```
28+
29+
### Solution
30+
- Remove the `VersionOverride` attribute from the `<PackageReference />` item:
31+
32+
```xml
33+
<ItemGroup>
34+
<PackageReference Include="PackageName" />
35+
</ItemGroup>
36+
```
37+
38+
- You can configure [Central Package Management](../../consume-packages/Central-Package-Management.md) to allow or disallow `VersionOverride` with the MSBuild property `CentralPackageVersionOverrideEnabled`. See [Overriding Package Versions](../../consume-packages/Central-Package-Management.md#overriding-package-versions) for more information.

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy