解决 .NET MAUI 中 Community Toolkit 的 Microsoft.Windows.SDK.NET.Ref 错误

问题描述

当在 .NET 8 MAUI 应用程序中更新 Community Toolkit MVVM 后，尝试运行 Windows 版本时出现以下错误：

MVVMTKCFG0003 This version of the MVVM Toolkit requires 'Microsoft.Windows.SDK.NET.Ref' version '10.0.19041.38' or later...
当前配置建议：将包版本设置为 '10.0.19041.41'

该错误通常发生在以下场景：

更新 Community Toolkit.Mvvm 到 v8.3.1 或更高版本
项目使用 net8.0-windows10.0.19041.0 目标框架
默认引用的 Windows SDK 包版本过低（10.0.19041.34）

注意

修改 TargetFrameworks 中的版本号为 net8.0-windows10.0.19041.41（如问题中尝试的方法）会导致框架不被识别，这不是正确解决方案。

解决方案

通过向项目文件添加 Windows SDK 包版本来显式指定所需版本：

步骤 1：编辑项目文件 (.csproj)

在文本编辑器或 Visual Studio 中打开 .csproj 文件，在 <PropertyGroup> 部分添加以下配置：

xml

<PropertyGroup>
  <!-- 设置 Windows SDK 包版本 -->
  <WindowsSdkPackageVersion>10.0.19041.41</WindowsSdkPackageVersion>
</PropertyGroup>

步骤 2：清理并重建项目

bash

dotnet clean
dotnet build

推荐操作

为确保全局生效（特别是多项目解决方案），可在解决方案根目录创建 Directory.Build.props 文件并添加相同配置

问题根源

Community Toolkit v8.3.1 强制要求 Windows SDK 包版本不低于 10.0.19041.38，而 .NET SDK 默认引用的是 10.0.19041.34 版本。通过添加显式版本声明可覆盖默认引用：

替代方案（临时应急）

不推荐

降级 Community Toolkit 是临时解决方案，可能导致错过关键更新：

bash

# 不推荐的降级方案
dotnet add package CommunityToolkit.Mvvm --version 8.2.2

附加说明

该问题源于 Toolkit 的目标平台兼容性检查（参见源码 WindowsSdk.targets#L30）
官方问题跟踪：GitHub Issue #951
确保已安装 .NET SDK 推荐版本（8.0.109/8.0.305/8.0.402 或更高）

验证修复后，项目应能正常编译运行 Windows 目标平台。保持 TargetFrameworks 为原始配置即可（如 net8.0-windows10.0.19041.0），无需修改平台版本号。

相关文章

解决 .NET MAUI 中 Community Toolkit 的 Microsoft.Windows.SDK.NET.Ref 错误 ​

问题描述 ​

解决方案 ​

步骤 1：编辑项目文件 (.csproj) ​

步骤 2：清理并重建项目 ​

问题根源 ​

替代方案（临时应急） ​

附加说明 ​