为何.NET 8.0 WPF应用无法加载Microsoft.Web.WebView2.Wpf程序集？

问题描述 #

我在.NET 8.0 WPF应用中使用WebView2时遇到以下问题：

• 已通过NuGet安装Microsoft.Web.WebView2包，项目引用了Microsoft.Web.WebView2.Core、Microsoft.Web.WebView2.WinForms、Microsoft.Web.WebView2.Wpf
• Debug输出文件夹中存在对应版本的DLL文件
• 在XAML的TabItem用户控件中添加简单WebView2控件后，立即触发XDG0003错误：无法加载程序集Microsoft.Web.WebView2.Wpf, Version=1.0.3351.48, Culture=neutral, PublicKeyToken=2a8ab48044d2601e
• 错误仅出现在TabItem用户控件中，不影响应用实际运行，目前暂未找到根因仍继续使用

排查与解决步骤 #

1. 清理重建项目 #

• 右键项目 → 选择清理
• 手动删除Debug/Release输出文件夹
• 右键项目 → 选择重新生成
• 重启Visual Studio后重新打开项目

2. 统一NuGet包版本 #

• 打开NuGet包管理器，确认Microsoft.Web.WebView2包版本与引用的Microsoft.Web.WebView2.Wpf等依赖包版本完全一致
• 若存在版本不匹配，卸载所有WebView2相关包后，重新安装同一版本的Microsoft.Web.WebView2包（NuGet会自动管理所有依赖引用）

3. 修正项目文件引用配置 #

• 右键项目 → 选择编辑项目文件
• 移除手动添加的Microsoft.Web.WebView2.Wpf等直接引用，仅保留NuGet自动生成的PackageReference，示例配置：

<PackageReference Include="Microsoft.Web.WebView2" Version="1.0.3351.48" />

• 确保无重复或冲突的引用条目

4. 清除XAML设计器缓存 #

• 关闭Visual Studio
• 删除以下目录的缓存文件：
  • %LOCALAPPDATA%\Microsoft\VisualStudio\<你的VS版本>\Designer\ShadowCache
  • %LOCALAPPDATA%\Temp\VSWebCache
• 重新打开项目验证错误是否消失

5. 延迟TabItem内WebView2初始化 #

由于错误仅出现在TabItem场景，可能是设计器在Tab未激活时提前加载控件导致，可通过代码延迟初始化：

• 在XAML中不直接声明WebView2，改为在TabItem的Loaded事件中初始化：

private WebView2 webView;

private void TabItem_Loaded(object sender, RoutedEventArgs e)
{
    if (webView == null)
    {
        webView = new Microsoft.Web.WebView2.Wpf.WebView2();
        webView.Source = new Uri("https://www.example.com");
        // 将控件添加到TabItem的内容容器中
        (sender as TabItem).Content = webView;
    }
}

6. 检查WebView2 Runtime环境 #

• 确认已安装与NuGet包版本匹配的WebView2 Runtime
• 若未安装，可添加Microsoft.Web.WebView2.Runtime NuGet包，让应用自动携带对应版本的Runtime

内容的提问来源于stack exchange，提问作者Nicolas