Improve documentation for Central Package Management (#3414)

Author: jeffkl

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

@@ -1,4 +1,4 @@
----
+---
 title: Central Package Management
 description: Manage your dependencies in a central location and how you can get started with central package management.
 author: jondouglas
@@ -18,7 +18,7 @@ Historically, NuGet package dependencies have been managed in one of two locatio
 - `packages.config` - An XML file used in older project types to maintain the list of packages referenced by the project.
 - `<PackageReference />` - An XML element used in MSBuild projects defines NuGet package dependencies.
 
-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
+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.
 
 The feature is available across all NuGet integrated tooling, starting with the following versions.
@@ -57,7 +57,7 @@ version.
 </Project>
 ```
 
-For each project, you then define a `<PackageReference />` but omit the `Version` attribute since the version will be attained from a corresponding
+For each project, you then define a `<PackageReference />` but omit the `Version` attribute since the version will be obtained from a corresponding
 `<PackageVersion />` item.
 
 ```xml
@@ -81,19 +81,24 @@ simplicity, only one `Directory.Packages.props` file is evaluated for a given pr
 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.
 
-Here's an example, consider the following repository structure:
+Consider the following repository structure:
 
 ```
-Repository
- |-- Directory.Packages.props
- |-- Solution1
-     |-- Directory.Packages.props
-     |-- Project1
- |-- Solution2
-     |-- Project2
+📂 (root)
+ ├─📄 Directory.Packages.props
+ |
+ ├─📂Solution1
+ |  ├─ 📄Directory.Packages.props
+ |  |
+ |  └─ 📂 Project1
+ |      └─📄Project1.csproj
+ |
+ └─ 📂 Solution2
+    └─ 📂 Project2
+        └─ 📄 Project2.csproj
 ```
 
-- Project1 will evaluate the `Directory.Packages.props` file in the `Repository\Solution1\` directory and it must manually import the next one if so desired.
+- `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.
   ```xml
   <Project>
     <Import Project="$([MSBuild]::GetPathOfFileAbove(Directory.Packages.props, $(MSBuildThisFileDirectory)..))" />
@@ -102,14 +107,14 @@ Repository
     </ItemGroup>
   </Project>
   ```
-- Project2 will evaluate the `Directory.Packages.props` file in the `Repository\` directory.
+- `Project2.csproj` will evaluate the `Directory.Packages.props` file in the root directory.
 
-**Note:** MSBuild will not automatically import each `Directory.Packages.props` for you, only the first one closest to the project.  If you have multiple
-`Directory.Packages.props`, you must import the parent one manually while the root `Directory.Packages.props` would not.
+**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
+`Directory.Packages.props` files, you must import any files in parent directories manually.
 
 ## Get started
 
-To fully onboard your repository, consider taking these steps:
+To fully onboard your repository, follow these steps:
 
 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`.
@@ -251,8 +256,3 @@ this warning, map your package sources with [package source mapping](https://aka
 ```
 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.
 ```
-
-
-
-> [!Note]
-> 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

@@ -11,51 +11,49 @@ f1_keywords:
 
 # NuGet Error NU1008
 
-> Projects that use central package version management should not define the version on the PackageReference items but on the PackageVersion items: PackageId.
+> 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.
 
-### Issue
+## Issue
 
-When using central package management, versions must be defined on the PackageVersion item.
-
-In your project file, you may see:
+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:
 
 ```xml
-<!-- In the project file. -->
-<PackageReference Include="PackageId" Version="5.1.0" />
+<ItemGroup>
+  <PackageReference Include="PackageName" Version="5.1.0" />
+</ItemGroup>
 ```
 
-### Solution
-
-- Remove the version from the PackageId PackageReference.
-- You may need to add or update the PackageVersion item for PackageId in Directory.Packages.props
-
-    Example:
+Alternatively, a `<PackageReference />` item is defined with a child `<Version />` element that has a value specified:
+```xml
+<ItemGroup>
+  <PackageReference Include="PackageName">
+    <Version>5.1.0</Version>
+  </PackageReference>
+</ItemGroup>
+```
 
-    ```xml
-    <!-- In the project file. -->
-    <PackageReference Include="PackageId" />
-    ```
+Projects configured to use [Central Package Management](../../consume-packages/Central-Package-Management.md) should not define a version on `<PackageReference />` items.
+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.
 
-    ```xml
-    <!-- In the Directory.Packages.props -->
-    <PackageVersion Include="PackageId" Version="5.1.0" />
-    ```
+## Solution
 
-- Alternatively, you may override an individual package version by using the `VersionOverride` property on a `<PackageReference />` item.
-This overrides any `<PackageVersion />` defined centrally.
+- Remove the `Version` attribute or child `<Version />` element from the `<PackageReference />` item:
 
-    Example:
+  ```xml
+  <ItemGroup>
+    <PackageReference Include="PackageName" />
+  </ItemGroup>
+  ```
 
-    ```xml
-    <!-- In the project file. -->
-    <PackageReference Include="PackageId" VersionOverride="3.0.0" />
-    ```
+- 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:
 
-    ```xml
-    <!-- In the Directory.Packages.props -->
-    <PackageVersion Include="PackageId" Version="5.1.0" />
-    ```
+  ```xml
+  <ItemGroup>
+    <PackageVersion Include="PackageName" Version="5.0.1" />
+  </ItemGroup>
+  ```
 
+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.
 
 > [!NOTE]
 > 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

@@ -11,12 +11,29 @@ f1_keywords:
 
 # NuGet Error NU1009
 
-> 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
+> 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.
 
-### Issue
+## Issue
 
-Implicitly defined packages should not be managed centrally.
+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).
+Implicitly defined packages are generally declared by an SDK to include packages on your behalf.
+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).
 
-### Solution
+```xml
+<ItemGroup>
+  <PackageReference Include="Microsoft.NETCore.App" Version="9.0.0" IsImplicitlyDefined="true" />
+</ItemGroup>
+```
 
-Remove the PackageVersion for PackageId
+## Solution
+
+- 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:
+
+  ```xml
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.NETCore.App" Version="1.0.0" />
+  </ItemGroup>
+  ```
+
+> [!NOTE]
+> 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

@@ -11,12 +11,27 @@ f1_keywords:
 
 # NuGet Error NU1010
 
-> The PackageReference items PackageId do not have corresponding PackageVersion.
+> 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
 
-### Issue
+## Issue
 
-The PackageReference PackageId is missing a PackageVersion item.
+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:
 
-### Solution
+```xml
+<ItemGroup>
+  <PackageReference Include="PackageName" />
+</ItemGroup>
+```
 
-Add a PackageVersion item for PackageId in the [Directory.Packages.props](../../consume-packages/Central-Package-Management.md).
+## Solution
+
+- 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:
+
+  ```xml
+  <ItemGroup>
+    <PackageVersion Include="PackageName" Version="5.0.1" />
+  </ItemGroup>
+  ```
+- 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).
+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.
+Resolving these underlying issues should fix this error.

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

@@ -11,27 +11,38 @@ f1_keywords:
 
 # NuGet Error NU1011
 
-> Centrally defined floating package versions are not allowed.
+> The following PackageVersion items cannot specify a floating version: PackageName.
 
-### Issue
+## Issue
 
-By default, `<PackageVersion />` items cannot contain floating versions.  NuGet's central package management (CPM) is considered an enterprise-level feature which provides easier version
-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
-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
-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
-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.
+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:
 
-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.
+```xml
+<ItemGroup>
+  <PackageVersion Include="PackageName" Version="1.*" />
+</ItemGroup>
+```
+By default, `<PackageVersion />` items cannot specify floating versions.
+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.
+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.
+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.
+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.
+
+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.
 
 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
-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
-commit in your repository.
+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.
 
+## Solution
 
-### Solution
+- It is recommended to change the floating version to a [non floating version range](../../concepts/Package-Versioning.md#version-ranges):
+```xml
+<ItemGroup>
+  <PackageVersion Include="PackageName" Version="1.0.0" />
+</ItemGroup>
+```
 
-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
-floating versions with CPM by setting an MSBuild property:
+- 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:
 
 ```xml
 <PropertyGroup>

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

@@ -0,0 +1,38 @@
+---
+title: NuGet Error NU1013
+description: NU1013 error code
+author: jeffkl
+ms.author: jeffkl
+ms.date: 03/24/2025
+ms.topic: reference
+f1_keywords:
+  - "NU1013"
+---
+
+# NuGet Error NU1013
+
+> The following PackageReference items cannot specify a value for VersionOverride: PackageName.  Projects using Central Package Management are currently configured to disable this functionality.
+
+### Issue
+
+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:
+
+```xml
+<PropertyGroup>
+  <CentralPackageVersionOverrideEnabled>false</CentralPackageVersionOverrideEnabled>
+</PropertyGroup>
+<ItemGroup>
+  <PackageReference Include="PackageName" VersionOverride="9.0.0" />
+</ItemGroup>
+```
+
+### Solution
+- Remove the `VersionOverride` attribute from the `<PackageReference />` item:
+
+```xml
+<ItemGroup>
+  <PackageReference Include="PackageName" />
+</ItemGroup>
+```
+
+- 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.