From eb16785abe43002b34e7cf91f8af17a435c111db Mon Sep 17 00:00:00 2001
From: Jeff Kluge <jeffkl@microsoft.com>
Date: Wed, 17 Jun 2026 15:09:35 -0700
Subject: [PATCH] Add ItemPackageVersion for central package management

---
 .../ItemTests.cs                              | 70 +++++++++++++++++++
 .../PackageFeed.Items.cs                      | 13 ++++
 .../ProjectCreator.Items.cs                   | 22 ++++++
 .../PublicAPI/net10.0/PublicAPI.Unshipped.txt |  2 +
 .../PublicAPI/net472/PublicAPI.Unshipped.txt  |  2 +
 .../PublicAPI/net8.0/PublicAPI.Unshipped.txt  |  2 +
 6 files changed, 111 insertions(+)

diff --git a/src/Microsoft.Build.Utilities.ProjectCreation.UnitTests/ItemTests.cs b/src/Microsoft.Build.Utilities.ProjectCreation.UnitTests/ItemTests.cs
index c5511f6..5ccdf85 100644
--- a/src/Microsoft.Build.Utilities.ProjectCreation.UnitTests/ItemTests.cs
+++ b/src/Microsoft.Build.Utilities.ProjectCreation.UnitTests/ItemTests.cs
@@ -5,6 +5,7 @@
 using Microsoft.Build.Evaluation;
 using Shouldly;
 using System.Collections.Generic;
+using System.IO;
 using System.Linq;
 using Xunit;
 
@@ -219,6 +220,75 @@ public void PackageReference()
                     StringCompareShould.IgnoreLineEndings);
         }
 
+        [Fact]
+        public void PackageVersion()
+        {
+            string feedRootPath = Path.Combine(Path.GetTempPath(), Path.GetRandomFileName());
+            Directory.CreateDirectory(feedRootPath);
+
+            PackageFeed.Templates.SinglePackage(feedRootPath, out Package package);
+
+            ProjectCreator.Create(projectFileOptions: NewProjectFileOptions.None)
+                .ItemPackageVersion(package)
+                .Xml.ShouldBe(
+                    @"<Project>
+  <ItemGroup>
+    <PackageVersion Include=""SomePackage"">
+      <Version>1.0.0</Version>
+    </PackageVersion>
+  </ItemGroup>
+</Project>",
+                    StringCompareShould.IgnoreLineEndings);
+        }
+
+        [Fact]
+        public void PackageVersionWithConditionAndLabel()
+        {
+            string feedRootPath = Path.Combine(Path.GetTempPath(), Path.GetRandomFileName());
+            Directory.CreateDirectory(feedRootPath);
+
+            PackageFeed.Templates.SinglePackage(feedRootPath, out Package package);
+
+            ProjectCreator.Create(projectFileOptions: NewProjectFileOptions.None)
+                .ItemPackageVersion(package, condition: "623C8EF659D946FBBF61CBF7F767C19A", label: "label")
+                .Xml.ShouldBe(
+                    @"<Project>
+  <ItemGroup>
+    <PackageVersion Include=""SomePackage"" Condition=""623C8EF659D946FBBF61CBF7F767C19A"" Label=""label"">
+      <Version>1.0.0</Version>
+    </PackageVersion>
+  </ItemGroup>
+</Project>",
+                    StringCompareShould.IgnoreLineEndings);
+        }
+
+        [Fact]
+        public void PackageVersionWithMetadata()
+        {
+            string feedRootPath = Path.Combine(Path.GetTempPath(), Path.GetRandomFileName());
+            Directory.CreateDirectory(feedRootPath);
+
+            PackageFeed.Templates.SinglePackage(feedRootPath, out Package package);
+
+            ProjectCreator.Create(projectFileOptions: NewProjectFileOptions.None)
+                .ItemPackageVersion(
+                    package,
+                    metadata: new Dictionary<string, string?>
+                    {
+                        { "Custom", "1A6A6B7A09B64A4F9D71A56AA19B9A0A" },
+                    })
+                .Xml.ShouldBe(
+                    @"<Project>
+  <ItemGroup>
+    <PackageVersion Include=""SomePackage"">
+      <Custom>1A6A6B7A09B64A4F9D71A56AA19B9A0A</Custom>
+      <Version>1.0.0</Version>
+    </PackageVersion>
+  </ItemGroup>
+</Project>",
+                    StringCompareShould.IgnoreLineEndings);
+        }
+
         [Fact]
         public void ProjectReferenceAnotherProject()
         {
diff --git a/src/Microsoft.Build.Utilities.ProjectCreation/PackageFeed.Items.cs b/src/Microsoft.Build.Utilities.ProjectCreation/PackageFeed.Items.cs
index 867b296..567d51f 100644
--- a/src/Microsoft.Build.Utilities.ProjectCreation/PackageFeed.Items.cs
+++ b/src/Microsoft.Build.Utilities.ProjectCreation/PackageFeed.Items.cs
@@ -23,5 +23,18 @@ public ProjectCreator ItemPackageReference(Package package, string? includeAsset
         {
             return ItemPackageReference(package.Id, package.Version, includeAssets, excludeAssets, privateAssets, metadata, condition, label);
         }
+
+        /// <summary>
+        /// Adds a &lt;PackageVersion /&gt; item to the current item group.
+        /// </summary>
+        /// <param name="package">The <see cref="Package" /> of the package to version.</param>
+        /// <param name="metadata">An optional <see cref="IDictionary{String,String}" /> containing metadata for the item.</param>
+        /// <param name="condition">An optional condition to add to the item.</param>
+        /// <param name="label">An optional label to add to the item.</param>
+        /// <returns>The current <see cref="ProjectCreator" />.</returns>
+        public ProjectCreator ItemPackageVersion(Package package, IDictionary<string, string?>? metadata = null, string? condition = null, string? label = null)
+        {
+            return ItemPackageVersion(package.Id, package.Version, metadata, condition, label);
+        }
     }
 }
diff --git a/src/Microsoft.Build.Utilities.ProjectCreation/ProjectCreator.Items.cs b/src/Microsoft.Build.Utilities.ProjectCreation/ProjectCreator.Items.cs
index 5d49083..318c6be 100644
--- a/src/Microsoft.Build.Utilities.ProjectCreation/ProjectCreator.Items.cs
+++ b/src/Microsoft.Build.Utilities.ProjectCreation/ProjectCreator.Items.cs
@@ -176,6 +176,28 @@ public ProjectCreator ItemPackageReference(string include, string? version = nul
                 label: label);
         }
 
+        /// <summary>
+        /// Adds a &lt;PackageVersion /&gt; item to the current item group.
+        /// </summary>
+        /// <param name="include">The name of the package to version.</param>
+        /// <param name="version">The version of the package to reference.</param>
+        /// <param name="metadata">An optional <see cref="IDictionary{String,String}" /> containing metadata for the item.</param>
+        /// <param name="condition">An optional condition to add to the item.</param>
+        /// <param name="label">An optional label to add to the item.</param>
+        /// <returns>The current <see cref="ProjectCreator" />.</returns>
+        public ProjectCreator ItemPackageVersion(string include, string version, IDictionary<string, string?>? metadata = null, string? condition = null, string? label = null)
+        {
+            return ItemInclude(
+                itemType: "PackageVersion",
+                include: include,
+                metadata: metadata.Merge(new Dictionary<string, string?>
+                {
+                    { "Version", version },
+                }),
+                condition: condition,
+                label: label);
+        }
+
         /// <summary>
         /// Adds a &lt;ProjectReference /&gt; item to the current item group.
         /// </summary>
diff --git a/src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net10.0/PublicAPI.Unshipped.txt b/src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net10.0/PublicAPI.Unshipped.txt
index 00524cf..a800721 100644
--- a/src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net10.0/PublicAPI.Unshipped.txt
+++ b/src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net10.0/PublicAPI.Unshipped.txt
@@ -10,6 +10,8 @@ Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward.LatestFeature
 Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward.LatestMajor = 3 -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward
 Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward.LatestMinor = 2 -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward
 Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward.LatestPatch = 0 -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward
+Microsoft.Build.Utilities.ProjectCreation.ProjectCreator.ItemPackageVersion(Microsoft.Build.Utilities.ProjectCreation.Package! package, System.Collections.Generic.IDictionary<string!, string?>? metadata = null, string? condition = null, string? label = null) -> Microsoft.Build.Utilities.ProjectCreation.ProjectCreator!
+Microsoft.Build.Utilities.ProjectCreation.ProjectCreator.ItemPackageVersion(string! include, string! version, System.Collections.Generic.IDictionary<string!, string?>? metadata = null, string? condition = null, string? label = null) -> Microsoft.Build.Utilities.ProjectCreation.ProjectCreator!
 Microsoft.Build.Utilities.ProjectCreation.ProjectCreator.TryBuild(System.Collections.Generic.IDictionary<string!, string!>? globalProperties, out bool result) -> Microsoft.Build.Utilities.ProjectCreation.ProjectCreator!
 static Microsoft.Build.Utilities.ProjectCreation.GlobalJsonCreator.Create(string? directory, string! sdkVersion, Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward? rollForward = null, bool? allowPrerelease = null) -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonCreator!
 static Microsoft.Build.Utilities.ProjectCreation.GlobalJsonCreator.Create(System.IO.DirectoryInfo! directory, string! sdkVersion, Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward? rollForward = null, bool? allowPrerelease = null) -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonCreator!
diff --git a/src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net472/PublicAPI.Unshipped.txt b/src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net472/PublicAPI.Unshipped.txt
index 00524cf..a800721 100644
--- a/src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net472/PublicAPI.Unshipped.txt
+++ b/src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net472/PublicAPI.Unshipped.txt
@@ -10,6 +10,8 @@ Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward.LatestFeature
 Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward.LatestMajor = 3 -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward
 Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward.LatestMinor = 2 -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward
 Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward.LatestPatch = 0 -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward
+Microsoft.Build.Utilities.ProjectCreation.ProjectCreator.ItemPackageVersion(Microsoft.Build.Utilities.ProjectCreation.Package! package, System.Collections.Generic.IDictionary<string!, string?>? metadata = null, string? condition = null, string? label = null) -> Microsoft.Build.Utilities.ProjectCreation.ProjectCreator!
+Microsoft.Build.Utilities.ProjectCreation.ProjectCreator.ItemPackageVersion(string! include, string! version, System.Collections.Generic.IDictionary<string!, string?>? metadata = null, string? condition = null, string? label = null) -> Microsoft.Build.Utilities.ProjectCreation.ProjectCreator!
 Microsoft.Build.Utilities.ProjectCreation.ProjectCreator.TryBuild(System.Collections.Generic.IDictionary<string!, string!>? globalProperties, out bool result) -> Microsoft.Build.Utilities.ProjectCreation.ProjectCreator!
 static Microsoft.Build.Utilities.ProjectCreation.GlobalJsonCreator.Create(string? directory, string! sdkVersion, Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward? rollForward = null, bool? allowPrerelease = null) -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonCreator!
 static Microsoft.Build.Utilities.ProjectCreation.GlobalJsonCreator.Create(System.IO.DirectoryInfo! directory, string! sdkVersion, Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward? rollForward = null, bool? allowPrerelease = null) -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonCreator!
diff --git a/src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net8.0/PublicAPI.Unshipped.txt b/src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net8.0/PublicAPI.Unshipped.txt
index 00524cf..a800721 100644
--- a/src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net8.0/PublicAPI.Unshipped.txt
+++ b/src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net8.0/PublicAPI.Unshipped.txt
@@ -10,6 +10,8 @@ Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward.LatestFeature
 Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward.LatestMajor = 3 -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward
 Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward.LatestMinor = 2 -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward
 Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward.LatestPatch = 0 -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward
+Microsoft.Build.Utilities.ProjectCreation.ProjectCreator.ItemPackageVersion(Microsoft.Build.Utilities.ProjectCreation.Package! package, System.Collections.Generic.IDictionary<string!, string?>? metadata = null, string? condition = null, string? label = null) -> Microsoft.Build.Utilities.ProjectCreation.ProjectCreator!
+Microsoft.Build.Utilities.ProjectCreation.ProjectCreator.ItemPackageVersion(string! include, string! version, System.Collections.Generic.IDictionary<string!, string?>? metadata = null, string? condition = null, string? label = null) -> Microsoft.Build.Utilities.ProjectCreation.ProjectCreator!
 Microsoft.Build.Utilities.ProjectCreation.ProjectCreator.TryBuild(System.Collections.Generic.IDictionary<string!, string!>? globalProperties, out bool result) -> Microsoft.Build.Utilities.ProjectCreation.ProjectCreator!
 static Microsoft.Build.Utilities.ProjectCreation.GlobalJsonCreator.Create(string? directory, string! sdkVersion, Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward? rollForward = null, bool? allowPrerelease = null) -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonCreator!
 static Microsoft.Build.Utilities.ProjectCreation.GlobalJsonCreator.Create(System.IO.DirectoryInfo! directory, string! sdkVersion, Microsoft.Build.Utilities.ProjectCreation.GlobalJsonSdkRollForward? rollForward = null, bool? allowPrerelease = null) -> Microsoft.Build.Utilities.ProjectCreation.GlobalJsonCreator!