Skip to content

Commit fd0813a

Browse files
jeffkljeffkl
authored
Merge pull request #3460 from NuGet/main
2 parents 029a5df + 68bfa76 commit fd0813a

File tree

5 files changed

+170
-130
lines changed

5 files changed

+170
-130
lines changed

‎docs/concepts/Auditing-Packages.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -72,9 +72,13 @@ Note that the [V2 protocol is deprecated](../nuget-org/overview-nuget-org.md#api
7272
</configuration>
7373
```
7474

75-
Audit sources are available from [NuGet 6.12, .NET 9.0.100 SDK, and Visual Studio 2022 17.12](../release-notes/NuGet-6.12.md).
76-
Prior to this version, NuGet Audit will only use package sources to download vulnerability information.
77-
Audit sources are not used by `dotnet list package --vulnerable` at this time.
75+
**Note**: The table below lists features that support Audit Sources.
76+
77+
| Introduced In | Feature Supporting Audit Sources |
78+
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
79+
| [NuGet 6.12, .NET 9.0.100 SDK, and Visual Studio 2022 17.12](../release-notes/NuGet-6.12.md) | Restore |
80+
| [NuGet 6.14, .NET 9.0.300 SDK](../release-notes/NuGet-6.14.md) | `dotnet package list --vulnerable` |
81+
| Not yet supported | NuGet AuditSources support in the Visual Studio Package Manager UI |
7882

7983
#### Excluding advisories
8084

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

Lines changed: 103 additions & 86 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,79 +9,62 @@ 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.
20-
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.
23-
24-
The feature is available across all NuGet integrated tooling, starting with the following versions.
25-
26-
* [Visual Studio 2022 17.2](https://visualstudio.microsoft.com/downloads/)
27-
* [.NET SDK 6.0.300](https://dotnet.microsoft.com/download/dotnet/6.0)
28-
* [nuget.exe 6.2.0](https://www.nuget.org/downloads)
29-
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.
32-
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.
17+
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)).
3518

3619
## Enabling Central Package Management
3720

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`.
21+
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`.
22+
23+
You can create it manually, or use the .NET CLI:
4024

41-
You can create it manually or you can use the dotnet CLI:
42-
``` shell
25+
```shell
4326
dotnet new packagesprops
4427
```
4528

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.
29+
Inside `Directory.Packages.props`, define `<PackageVersion />` elements to specify the package IDs and versions used by your projects.
4830

4931
```xml
5032
<Project>
5133
<PropertyGroup>
5234
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
5335
</PropertyGroup>
5436
<ItemGroup>
55-
<PackageVersion Include="Newtonsoft.Json" Version="13.0.1" />
37+
<PackageVersion Include="PackageA" Version="1.0.0" />
38+
<PackageVersion Include="PackageB" Version="2.0.0" />
5639
</ItemGroup>
5740
</Project>
5841
```
5942

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.
43+
In each project file, define `<PackageReference />` elements without the `Version` attribute.
44+
The version will be resolved from the corresponding `<PackageVersion />` entry in `Directory.Packages.props`.
6245

6346
```xml
6447
<Project Sdk="Microsoft.NET.Sdk">
6548
<PropertyGroup>
6649
<TargetFramework>net6.0</TargetFramework>
6750
</PropertyGroup>
6851
<ItemGroup>
69-
<PackageReference Include="Newtonsoft.Json" />
52+
<PackageReference Include="PackageA" />
7053
</ItemGroup>
7154
</Project>
7255
```
7356

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

76-
## Central Package Management rules
59+
## Central Package Management Rules
7760

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

81-
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
82-
be evaluated for it. This allows you extra control at various levels of your repository.
64+
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.
65+
This allows extra control at various levels of your repository.
8366

84-
Consider the following repository structure:
67+
Consider the following repository directory structure:
8568

8669
```
8770
📂 (root)
@@ -98,50 +81,86 @@ Consider the following repository structure:
9881
└─ 📄 Project2.csproj
9982
```
10083

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.
102-
```xml
103-
<Project>
104-
<Import Project="$([MSBuild]::GetPathOfFileAbove(Directory.Packages.props, $(MSBuildThisFileDirectory)..))" />
105-
<ItemGroup>
106-
<PackageVersion Update="Newtonsoft.Json" Version="12.0.1" />
107-
</ItemGroup>
108-
</Project>
109-
```
110-
- `Project2.csproj` will evaluate the `Directory.Packages.props` file in the root directory.
84+
`Project1.csproj` will use the `Directory.Packages.props` file in the `Repository\Solution1\` directory.
85+
If you want to include settings from a parent `Directory.Packages.props`, you must manually import it.
86+
87+
```xml
88+
<Project>
89+
<Import Project="$([MSBuild]::GetPathOfFileAbove(Directory.Packages.props, $(MSBuildThisFileDirectory)..))" />
90+
<ItemGroup>
91+
<PackageVersion Update="Newtonsoft.Json" Version="12.0.1" />
92+
</ItemGroup>
93+
</Project>
94+
```
95+
96+
`Project2.csproj` will evaluate the `Directory.Packages.props` file in the root directory.
11197

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.
98+
> [!NOTE]
99+
> MSBuild will only automatically import the first `Directory.Packages.props` file it finds in the project directory or any parent directory.
100+
> If you have multiple such files, you must manually import parent files as needed.
114101
115-
## Get started
102+
## Getting Started
116103

117104
To fully onboard your repository, follow these steps:
118105

119-
1. Create a new file at the root of your repository named `Directory.Packages.props` that declares your centrally defined package versions and set
120-
the MSBuild property `ManagePackageVersionsCentrally` to `true`.
106+
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`.
121107
2. Declare `<PackageVersion />` items in your `Directory.Packages.props`.
122108
3. Declare `<PackageReference />` items without `Version` attributes in your project files.
123109

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

126-
## Transitive pinning
112+
## Using Different Versions for Different Target Frameworks
127113

128-
You can automatically override a transitive package version even without an explicit top-level `<PackageReference />` by opting into a feature known as
129-
transitive pinning. This promotes a transitive dependency to a top-level dependency implicitly on your behalf when necessary.
130-
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.
114+
As NuGet packages evolve, package owners may drop support for older target frameworks.
115+
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.
131116

132-
You can enable this feature by setting the MSBuild property `CentralPackageTransitivePinningEnabled` to `true` in a project or in a `Directory.Packages.props`
133-
or `Directory.Build.props` import file:
117+
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.
118+
119+
```xml
120+
<Project Sdk="Microsoft.NET.Sdk">
121+
<PropertyGroup>
122+
<TargetFrameworks>netstandard2.0;net8.0;net472</TargetFrameworks>
123+
</PropertyGroup>
124+
<ItemGroup>
125+
<PackageReference Include="PackageA" />
126+
</ItemGroup>
127+
</Project>
128+
```
129+
130+
In this case, define different versions for each target framework in your `Directory.Packages.props` using [MSBuild conditions](/visualstudio/msbuild/msbuild-conditions):
131+
132+
```xml
133+
<Project>
134+
<PropertyGroup>
135+
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
136+
</PropertyGroup>
137+
<ItemGroup>
138+
<PackageVersion Include="PackageA" Version="1.0.0" Condition="'$(TargetFramework)' == 'netstandard2.0'" />
139+
<PackageVersion Include="PackageA" Version="2.0.0" Condition="'$(TargetFramework)' == 'net8.0' Or '$(TargetFramework)' == 'net472'" />
140+
</ItemGroup>
141+
</Project>
142+
```
143+
144+
## Transitive Pinning
145+
146+
You can automatically override a transitive package version without an explicit top-level `<PackageReference />` item by opting into a feature known as transitive pinning.
147+
This promotes a transitive dependency to a top-level dependency implicitly on your behalf when necessary.
148+
149+
Note that downgrades are not allowed when transitive pinning a package.
150+
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.
151+
152+
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:
134153

135154
```xml
136155
<PropertyGroup>
137156
<CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
138157
</PropertyGroup>
139158
```
140159

141-
### Transitive pinning and pack
160+
### Transitive Pinning and Pack
142161

143-
When a package is transitively pinned, your project uses a higher than the one requested by your dependencies.
144-
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.
162+
When a package is transitively pinned, your project uses a higher version than the one requested by your dependencies.
163+
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.
145164

146165
In the following example, `PackageA 1.0.0` has a dependency on `PackageB 1.0.0`.
147166

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

171190
```xml
172-
<group targetFramework="net6.0">
173-
<dependency id="PackageA" version="1.0.0" exclude="Build,Analyzers" />
174-
<dependency id="PackageB" version="2.0.0" exclude="Build,Analyzers" />
175-
</group>
191+
<group targetFramework="net6.0">
192+
<dependency id="PackageA" version="1.0.0" exclude="Build,Analyzers" />
193+
<dependency id="PackageB" version="2.0.0" exclude="Build,Analyzers" />
194+
</group>
176195
```
177196

178-
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.
197+
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.
179198

180-
## Overriding package versions
199+
## Overriding Package Versions
181200

182-
You can override an individual package version by using the `VersionOverride` property on a `<PackageReference />` item. This overrides any `<PackageVersion />`
183-
defined centrally.
201+
You can override an individual package version by using the `VersionOverride` property on a `<PackageReference />` item.
202+
This will take precedence over any centrally defined `<PackageVersion />`.
184203

185204
```xml
186205
<Project>
@@ -202,22 +221,19 @@ defined centrally.
202221
</Project>
203222
```
204223

205-
You can disable this feature by setting the MSBuild property `CentralPackageVersionOverrideEnabled` to `false` in a project or in a `Directory.Packages.props` or
206-
`Directory.Build.props` import file:
224+
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:
207225

208226
```xml
209227
<PropertyGroup>
210228
<CentralPackageVersionOverrideEnabled>false</CentralPackageVersionOverrideEnabled>
211229
</PropertyGroup>
212230
```
213231

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

217234
## Disabling Central Package Management
218235

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

222238
```xml
223239
<PropertyGroup>
@@ -227,17 +243,18 @@ If you would like to disable central package management for a particular project
227243

228244
## Global Package References
229245

230-
> [!Note]
246+
> [!NOTE]
231247
> 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.
232248
233-
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:
249+
A global package reference is used to specify that a package will be used by every project in a repository.
250+
This includes packages that do versioning, extend your build, or any other packages that are needed by all projects.
251+
Global package references are added to the PackageReference item group with the following metadata:
234252

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

240-
241258
`GlobalPackageReference` items should be placed in your `Directory.Packages.props` to be used by every project in a repository:
242259

243260
```xml
@@ -248,11 +265,11 @@ A global package reference is used to specify that a package will be used by eve
248265
</Project>
249266
```
250267

251-
## Warning when using multiple package sources
268+
## NU1507 Warning When Using Multiple Package Sources
252269

253-
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
254-
this warning, map your package sources with [package source mapping](https://aka.ms/nuget-package-source-mapping) or specify a single package source.
270+
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.
271+
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.
255272

256273
```
257-
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.
274+
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.
258275
```

0 commit comments

Comments
 (0)