FrameworkReference 替换为适用于 Windows SDK 的 WindowsSdkPackageVersion

项目
01/29/2025

从 .NET 5.0.8（包括 .NET SDK 5.0.302 和 .NET SDK 5.0.205）开始，面向 Windows 的开发人员无法使用 FrameworkReference 项替代其 Windows SDK 目标包的版本。 WindowsSdkPackageVersion 属性替换了此功能。

注意

不建议替代 Windows SDK 版本，因为 .NET 5+SDK 中包含 Windows SDK 目标包。相反，若要引用最新的 Windows SDK 包，请更新 .NET SDK 的版本。

引入的版本

.NET SDK 5.0.302、.NET SDK 5.0.205

以前的行为

开发人员可以使用 FrameworkReference 项替代 .NET 5 应用程序中的 Windows SDK 包版本。例如：

<ItemGroup>
  <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" RuntimeFrameworkVersion="10.0.19041.18" />
  <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" TargetingPackVersion="10.0.19041.18" />
</ItemGroup>

新行为

WindowsSdkPackageVersion 属性取代了 FrameworkReference 替代的行为。例如：

<PropertyGroup>
  <WindowsSdkPackageVersion>10.0.19041.18</WindowsSdkPackageVersion>
</PropertyGroup>

更改类别

此更改可能会影响 源兼容性。

更改原因

引入此更改是为了简化面向 C#/WinRT 生成的 Windows SDK 包的包替代行为。

建议的操作

面向 Windows SDK 时，请删除 .NET 5+ 应用项目文件中对 FrameworkReference 的任何使用。

使用 Windows 应用 SDK时，如果 .NET SDK 无法解析所需的 Windows SDK 包版本，则可能需要显式添加 WindowsSdkPackageVersion 属性。由于 Windows 应用 SDK 和 .NET SDK 的不同发布机制（其中 .NET SDK 通过 Visual Studio 提供），可能会出现此问题。请参阅此 GitHub 问题中的详细信息。在 .NET SDK 解析所需的 Windows SDK 包版本后，还可以考虑删除 WindowsSdkPackageVersion 属性，确保拥有最新的 Windows SDK 包。这通常在 Visual Studio 发布新版本并升级到该版本之后发生。

受影响的 API

Windows SDK 目标包提供的 .NET 5 和更高版本中的 Windows API。

通过