Resolving Microsoft.Windows.SDK.NET.Ref Error in .NET MAUI with Community Toolkit

Problem

When updating your .NET 8 MAUI application to use the Community Toolkit MVVM (version 8.3.1 or later), you may encounter the following error when running the Windows version:

MVVMTKCFG0003 This version of the MVVM Toolkit requires 'Microsoft.Windows.SDK.NET.Ref' version '10.0.19041.38' or later. Please update to .NET SDK 8.0.109, 8.0.305, or 8.0.402 (or later). Alternatively, use a temporary 'Microsoft.Windows.SDK.NET.Ref' reference by setting the 'WindowsSdkPackageVersion' property in your .csproj file. For your project configuration, it is recommended to set the package version to '10.0.19041.41'.

This occurs because the Community Toolkit MVVM requires a more recent version of the Windows SDK reference package than what your project currently references.

Solutions

Recommended Fix: Set WindowsSdkPackageVersion

1. Open your .csproj file
2. Add the following property group:

<PropertyGroup>
    <WindowsSdkPackageVersion>10.0.19041.41</WindowsSdkPackageVersion>
</PropertyGroup>

Complete Example

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>
        net8.0-android;
        net8.0-ios;
        net8.0-maccatalyst
    </TargetFrameworks>
    <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">
        $(TargetFrameworks);net8.0-windows10.0.19041.0
    </TargetFrameworks>
    <OutputType>Exe</OutputType>
    <UseMaui>true</UseMaui>
    <SingleProject>true</SingleProject>
    
    <!-- Add this property -->
    <WindowsSdkPackageVersion>10.0.19041.41</WindowsSdkPackageVersion>
  </PropertyGroup>
  
  <!-- Other configuration -->
</Project>

If you're managing multiple projects, you can add this property to a Directory.Build.props file to apply it solution-wide.

Alternative Solution: Downgrade Toolkit (Temporary Workaround)

If the preferred solution doesn't resolve your issue or isn't feasible:

1. Remove the current Toolkit version:

dotnet remove package CommunityToolkit.Mvvm

2. Install version 8.2.2:

dotnet add package CommunityToolkit.Mvvm --version 8.2.2

WARNING

This is only a temporary solution and should be used if the main fix doesn't work for your specific environment. You'll miss security patches and features from newer toolkit versions.

Explanation

Why This Happens

The Community Toolkit MVVM (v8.3.1+) has a dependency on Windows SDK reference package 10.0.19041.38 or later. However:

• The default reference in .NET projects is typically 10.0.19041.34
• Updating the .NET SDK alone won't change this implicit reference
• Specifying the version in TargetFrameworks (e.g., net8.0-windows10.0.19041.41) is invalid since framework moniker versions don't map directly to package versions

How the Fix Works

Setting <WindowsSdkPackageVersion> directly specifies which version of the Windows SDK reference package to use. This bypasses the default outdated version while maintaining the correct target framework moniker (net8.0-windows10.0.19041.0).

Additional Recommendations

1. Verify you have these .NET 8 SDK versions installed:

   • 8.0.109
   • 8.0.305
   • 8.0.402 (or newer)
   • Use dotnet --list-sdks to check

2. Confirm Windows Target Framework Version remains:

   net8.0-windows10.0.19041.0

   (The build number suffix .41 should only be specified in <WindowsSdkPackageVersion>)

3. If problems persist:

   • Clean solution: dotnet clean
   • Delete bin and obj folders
   • Restart Visual Studio or your development environment

For ongoing updates and community discussions, reference these resources:

• GitHub Issue: Windows SDK Version Requirement
• MVVM Toolkit Compatibility Source