ScottPlot 沙盒工程升级 .NET 10 实战:Blazor、MAUI 与 Uno 平台迁移问题全解
ScottPlot 沙盒工程升级 .NET 10 实战:Blazor、MAUI 与 Uno 平台迁移问题全解
导读
本文基于 ScottPlot 仓库中 dev/ai-prompts/2025-03-28 [swharden] target dotnet 10.md 记录的真实排障过程,系统梳理 ScottPlot 5 系列沙盒(Sandbox)工程从 .NET 8/9 升级到 .NET 10 时遇到的四类典型运行时与构建错误。读完本文,你将掌握 Blazor WebAssembly 的 ES6 模块加载与静态资源清单(staticwebassets.endpoints.json)两大 .NET 10 破坏性变更、SkiaSharp 原生 WASM 绑定的配置要点、MAUI 的 WindowsSdkPackageVersion 与打包模式问题,以及 Uno 平台 WinRT.Runtime 程序集版本冲突的解决方法——所有结论均与当前仓库源码逐条对应,可直接对照复现与修复。
一、背景:.NET 10 升级为何会"启动即崩"
ScottPlot 5 的控制层生态覆盖 Blazor、MAUI、WinUI/Uno、WPF、WinForms、Avalonia、Eto 等多个平台,对应沙盒工程集中在 src/ScottPlot5/ScottPlot5 Sandbox/ 目录下。将目标框架从 .NET 8/9 提升到 net10.0 后,最常见的现象不是编译失败,而是应用能构建、却在启动阶段抛出运行时异常。
从仓库现状看,这些沙盒工程已经完成迁移并固化修复成果,例如 Sandbox.Blazor.csproj 与 Sandbox.Blazor.WebAssembly.csproj 均已显式声明 net10.0 目标框架。升级过程中暴露的问题可以归为四大类:
- NuGet 包版本与目标框架不匹配(Blazor、MAUI);
- Blazor WASM 运行时初始化模式的破坏性变更(ES6 模块、静态资源清单);
- SkiaSharp 原生库在 WASM 下的加载失败;
- Windows 平台投影包与打包模式的兼容性问题(MAUI、Uno)。
下面按文档记录的排障顺序逐一展开。
二、Blazor WebAssembly:包版本错配引发 WASM 运行时加载失败
2.1 症状与根因
升级 Sandbox.Blazor 后应用启动即抛异常,报错为:
Failed to fetch dynamically imported module: https://localhost:7014/0
根因有两层:
- 第一层:包版本错配。工程目标框架已改为
net10.0,但Microsoft.AspNetCore.Components.WebAssembly与Microsoft.AspNetCore.Components.WebAssembly.DevServer仍是 .NET 8 时代的8.0.10。ASP.NET Core 运行时与程序集版本不一致,导致 WASM 运行时无法正常初始化。 - 第二层:脚本加载模式过时。WASM 运行时加载失败的直接原因,是 HTML 中仍在使用 .NET 8 时代的脚本加载方式,而 .NET 10 的 Blazor WASM 运行时已改用 ES6 模块(ES Modules)加载机制。
2.2 修复一:升级 ASP.NET Core 包版本
将两个包统一升级到与目标框架一致的版本(.NET 10 对应 10.0.0 或更高)。当前仓库中 Sandbox.Blazor.csproj 的最终形态为:
<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<SignAssembly>false</SignAssembly>
<WasmNativeStrip>false</WasmNativeStrip>
<GenerateStaticWebAssetsEndpointsManifest>true</GenerateStaticWebAssetsEndpointsManifest>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="10.0.0" />
<PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer" Version="10.0.0" PrivateAssets="all" />
<PackageReference Include="SkiaSharp.Views.Blazor" Version="3.119.0" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\..\ScottPlot5 Controls\ScottPlot.Blazor\ScottPlot.Blazor.csproj" />
<ProjectReference Include="..\..\ScottPlot5\ScottPlot.csproj" />
</ItemGroup>
</Project>
其中 DevServer 包标记 PrivateAssets="all",确保开发服务器依赖不会随项目外传。
2.3 修复二:index.html 改用 ES6 模块加载脚本
wwwroot/index.html 中 Blazor 引导脚本必须加上 type="module":
<script src="_framework/blazor.webassembly.js" type="module"></script>
这一行的作用机理:.NET 10 的 Blazor WASM 运行时以 ES6 模块方式加载 .NET 运行时与程序集资源。若继续使用旧式脚本加载(无 type="module"),运行时在解析动态导入模块时会从错误路径(如 https://localhost:7014/0)拉取资源,从而触发上述异常。当前仓库的 Sandbox.Blazor/wwwroot/index.html 已按此模式修正,Demos 目录下的 ScottPlot5 Blazor/index.html 同样统一了脚本加载方式。
提示:若你的应用仍需要旧式启动逻辑,可保留
autostart=false并由 JS 手动调用Blazor.start(),但 .NET 10 推荐直接采用模块化加载。
2.4 升级后新问题:SkiaSharp 原生 DLL 无法加载
包与脚本修好之后,页面加载继续前进,但又抛出新异常:
System.DllNotFoundException: SkiaSharp.dll
System.TypeInitializationException: TypeInitialization_Type, SkiaSharp.SKTypeface
这是 Blazor WebAssembly 下的典型问题:SkiaSharp 的渲染核心依赖原生(native)代码,在浏览器沙箱中必须携带专门的 WebAssembly 原生绑定,而这些原生资产很容易被链接器或发布流程剥离。
对照仓库,ScottPlot.Blazor 控制层通过 BlazorPlot.razor 使用 SKCanvasView(来自 SkiaSharp.Views.Blazor)承载渲染画布,其基类 BlazorPlotBase.cs 在 OnPaintSurface 中调用 Multiplot.Render(e.Surface),因此 SkiaSharp 原生层不可缺失。
修复要点(已在仓库落盘):
WasmNativeStrip=false:禁止裁剪 WASM 原生绑定。属性文档特别强调,若不加此开关,链接器会把运行时必需的 SkiaSharp 原生 WebAssembly 库移除,从而在首次创建SKTypeface时触发TypeInitializationException。- 显式引用
SkiaSharp.Views.Blazor:确保 WebAssembly 原生绑定被显式带入应用,而非仅依赖控制库的传递依赖。 - 控制库按目标框架条件化依赖:ScottPlot.Blazor.csproj 中
Microsoft.AspNetCore.Components.Web按目标框架条件引用,.NET 10 用10.0、.NET 8 用8.0,从而支持同一控制库同时服务新旧两种目标:
<PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="10.0" Condition="'$(TargetFramework)' == 'net10.0'" />
<PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="8.0" Condition="'$(TargetFramework)' == 'net8.0'" />
三、独立 Blazor WASM 应用:staticwebassets.endpoints.json 缺失
3.1 症状
另一个独立的 Blazor WebAssembly 沙盒工程(Sandbox.Blazor.WebAssembly,位于 Demos 目录)升级后抛出:
System.InvalidOperationException: The static resources manifest file
'...\bin\Debug\net10.0\Sandbox.Blazor.WebAssembly.staticwebassets.endpoints.json'
was not found.
3.2 根因:.NET 10 的已知破坏性变更
这是 .NET 10 针对独立(standalone)Blazor WebAssembly 应用的已知破坏性变更:WebAssemblyHostBuilder.CreateDefault(args)(见 Demos 工程的 Program.cs)在启动时会读取 staticwebassets.endpoints.json 清单文件,但 Microsoft.NET.Sdk.BlazorWebAssembly SDK 默认不会为独立 WASM 应用生成该文件。
区分两种情况:
- Hosted(托管)Blazor WASM:由 ASP.NET Core 服务端工程承载,构建时由服务端工程生成该清单,因此无此问题;
- Standalone(独立)Blazor WASM:纯静态发布、无服务端工程,SDK 默认不生成清单,于是运行时找不到文件直接抛
InvalidOperationException。
3.3 修复:显式开启清单生成
在工程文件中加入 MSBuild 属性即可:
<GenerateStaticWebAssetsEndpointsManifest>true</GenerateStaticWebAssetsEndpointsManifest>
该属性指示 SDK 在构建阶段产出 staticwebassets.endpoints.json。执行一次干净的重新构建(clean rebuild)后,bin\Debug\net10.0\ 下会出现该文件,运行时异常随之消除。
当前仓库中 Sandbox.Blazor.WebAssembly.csproj(第 10 行)与 Sandbox.Blazor.csproj(第 9 行)均已加入此属性,可作为模板直接套用。
四、MAUI 沙盒:COM 异常、Windows SDK 投影包与打包模式
4.1 症状
Sandbox.Maui 从 .NET 8 升到 .NET 10 后,启动即崩溃:
System.Runtime.InteropServices.COMException: Class not registered
(0x80040154 (REGDB_E_CLASSNOTREG)) in System.Private.CoreLib.dll
4.2 根因一:重复且过时的 WindowsSdkPackageVersion
文档排查发现工程文件中存在两处 WindowsSdkPackageVersion,且值停留在 .NET 8 时代(如 10.0.19041.34、10.0.19041.38)。这些旧版 Windows SDK 投影包与 .NET 10 运行时不兼容,导致 COM 类注册失败,进而抛出 REGDB_E_CLASSNOTREG。
修复方式是直接删除这两处属性:解决方案中其他面向 Windows 的工程(如 Sandbox.WinUI.Desktop、ScottPlot.Maui)均不显式设置该属性,而是让 .NET 10 SDK 自动解析正确的投影包版本。这一点在 ScottPlot.Maui.csproj 中同样得到印证——它只在 Windows 条件下追加 net10.0-windows10.0.19041.0 目标,不写任何 WindowsSdkPackageVersion。
4.3 根因二:日志包版本滞留 8.0.0
Microsoft.Extensions.Logging.Debug 仍为 8.0.0,与目标框架不符。应升级为 10.0.0。当前 Sandbox.Maui.csproj 已更新:
<PackageReference Include="Microsoft.Extensions.Logging.Debug" Version="10.0.0" />
4.4 根因三:Application.MainPage 弃用
修复完成后应用可以构建运行,但出现弃用警告:
warning CS0618: 'Application.MainPage.set' is obsolete:
'This property is deprecated. Initialize your application by
overriding Application.CreateWindow rather than setting MainPage.'
.NET 10 MAUI 中 Application.MainPage 已标记 obsolete,正确写法是覆写 CreateWindow 并返回承载根页面的 Window。仓库中的 App.xaml.cs 已按新规范实现:
public partial class App : Application
{
public App()
{
InitializeComponent();
}
protected override Window CreateWindow(IActivationState? activationState)
{
return new Window(new AppShell());
}
}
4.5 根因四:MSIX 打包注册失败(Visual Studio 运行场景)
从 Visual Studio 直接运行时再次出现相同 COM 异常,定位到 Windows App SDK 初始化阶段(DeploymentManager.Initialize):应用以打包(MSIX)身份启动,但缺少包注册信息,COM 类自然无法注册。
解决方案是在工程中加入:
<WindowsPackageType>None</WindowsPackageType>
该属性指示构建产出**未打包(unpackaged)**的 Windows 应用,完全绕过 MSIX 包注册流程。这与解决方案中 Sandbox.WinUI.Desktop 的做法一致——Sandbox.WinUI.Desktop.csproj 同样声明了 <WindowsPackageType>None</WindowsPackageType>。当前 Sandbox.Maui.csproj 的最终目标框架与关键属性为:
<TargetFrameworks>net10.0-windows10.0.19041.0</TargetFrameworks>
<WindowsPackageType>None</WindowsPackageType>
4.6 MAUI 升级后的完整工程形态
综合以上修复,Sandbox.Maui.csproj 的最终关键配置如下(节选):
<PropertyGroup>
<TargetFrameworks>net10.0-windows10.0.19041.0</TargetFrameworks>
<SupportedOSPlatformVersion>10.0.17763.0</SupportedOSPlatformVersion>
<TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
<WindowsPackageType>None</WindowsPackageType>
<UseMaui>true</UseMaui>
<SingleProject>true</SingleProject>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Maui.Controls" Version="$(MauiVersion)" />
<PackageReference Include="Microsoft.Maui.Controls.Compatibility" Version="$(MauiVersion)" />
<PackageReference Include="Microsoft.Extensions.Logging.Debug" Version="10.0.0" />
</ItemGroup>
MAUI 控制层 MauiPlot.cs 基于 SKCanvasView 实现 IPlotControl,在桌面端通过 Touch 事件、移动端通过手势识别器接入 UserInputProcessor,升级后无需改动绘制逻辑即可在 .NET 10 下运行。
五、Uno 平台沙盒:WinRT.Runtime 程序集版本冲突
5.1 症状
Sandbox.UnoPlatform 从 .NET 8 升到 .NET 10 后,构建阶段直接报错:
Assembly 'ScottPlot.WinUI' with identity 'ScottPlot.WinUI, Version=5.1.58.0'
uses 'WinRT.Runtime, Version=2.2.0.0' which has a higher version than
referenced assembly 'WinRT.Runtime' with identity
'WinRT.Runtime, Version=2.0.0.0'
5.2 根因:传递依赖解析到旧版 WinRT.Runtime
ScottPlot.WinUI 通过其 Microsoft.WindowsAppSDK 1.5.240802000 依赖被编译为面向 WinRT.Runtime 2.2.0.0;而 Uno SDK 5.3.90 默认将 WinRT.Runtime 解析到较旧的 2.0.0.0。NuGet 依赖解析结果低于被引用程序集的编译版本,触发版本冲突。
5.3 修复:显式引用 Microsoft.Windows.CsWinRT 2.2.0
WinRT.Runtime 程序集由 Microsoft.Windows.CsWinRT 包提供。通过在 Uno 工程中显式引用该包的 2.2.0 版本,NuGet 将把 WinRT.Runtime 统一解析为 2.2.0.0,与 ScottPlot.WinUI 的编译基线对齐:
<PackageReference Include="Microsoft.Windows.CsWinRT" Version="2.2.0" />
当前 Sandbox.UnoPlatform.csproj 的完整关键配置为:
<Project Sdk="Uno.Sdk/5.3.90">
<PropertyGroup>
<TargetFramework>net10.0-windows10.0.22621</TargetFramework>
<WindowsSdkPackageVersion>10.0.22621.34</WindowsSdkPackageVersion>
<WinAppSdkVersion>1.5.240802000</WinAppSdkVersion>
<UnoSingleProject>true</UnoSingleProject>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Windows.CsWinRT" Version="2.2.0" />
<ProjectReference Include="..\..\ScottPlot5 Controls\ScottPlot.WinUI\ScottPlot.WinUI.csproj" />
</ItemGroup>
</Project>
对照 ScottPlot.WinUI.csproj:Windows 目标(net10.0-windows10.0.19041.0)引用 Microsoft.WindowsAppSDK 1.5.240802000 与 SkiaSharp.Views.WinUI,非 Windows 目标(如 net10.0)则引用 Uno.WinUI 6.2.58 与 SkiaSharp.Views.Uno.WinUI。由于 ScottPlot.WinUI 以 WinRT.Runtime 2.2.0 编译,Uno 工程显式锁定同版本即可消除冲突。
注意:Uno 工程自身的
WindowsSdkPackageVersion保留10.0.22621.34是正常的——与 MAUI 场景不同,Uno SDK 需要显式指定 Windows SDK 版本才能正确解析平台投影。
六、升级清单与最佳实践小结
综合文档记录与仓库最终形态,将四个沙盒工程迁移到 .NET 10 的修复要点汇总如下:
| 平台/工程 | 症状 | 修复手段 | 仓库依据 |
|---|---|---|---|
| Sandbox.Blazor(WASM) | Failed to fetch dynamically imported module |
ASP.NET Core 包升至 10.0.0;blazor.webassembly.js 加 type="module" |
Sandbox.Blazor.csproj、index.html |
| Sandbox.Blazor(WASM) | DllNotFoundException: SkiaSharp.dll |
WasmNativeStrip=false;显式引用 SkiaSharp.Views.Blazor |
同上 csproj;ScottPlot.Blazor.csproj |
| Sandbox.Blazor.WebAssembly(独立 WASM) | staticwebassets.endpoints.json was not found |
<GenerateStaticWebAssetsEndpointsManifest>true</...> |
Sandbox.Blazor.WebAssembly.csproj |
| Sandbox.Maui | COMException: Class not registered |
删除重复过时的 WindowsSdkPackageVersion;日志包升 10.0.0;<WindowsPackageType>None</...> |
Sandbox.Maui.csproj |
| Sandbox.Maui | Application.MainPage 弃用警告 |
覆写 CreateWindow 返回 new Window(new AppShell()) |
App.xaml.cs |
| Sandbox.UnoPlatform | WinRT.Runtime 2.2.0 > 2.0.0 版本冲突 |
显式引用 Microsoft.Windows.CsWinRT 2.2.0 |
Sandbox.UnoPlatform.csproj |
迁移时的通用注意事项
- 先对齐包版本,再排查其他问题:升级目标框架后,所有 ASP.NET Core、日志、SDK 相关包都应同步到对应大版本(
10.0.0),版本错配是各类运行时异常的首要嫌疑。 - 关注 .NET 10 的破坏性变更:Blazor WASM 的 ES6 模块加载与
staticwebassets.endpoints.json清单机制、MAUI 的MainPage弃用,均属于官方破坏性变更,需按新规范主动适配。 - SkiaSharp 原生绑定需显式守护:WASM 场景务必设置
WasmNativeStrip=false,否则裁剪器会移除运行时原生库。 - Windows 平台工程尽量让 SDK 自动解析投影版本:除非目标平台(如 Uno)明确要求,否则不要手写
WindowsSdkPackageVersion;打包模式则按需声明WindowsPackageType=None走非打包路径。 - 依赖冲突通过显式锁定版本解决:当传递依赖解析出旧版本程序集时,直接引用提供该程序集的包(如
Microsoft.Windows.CsWinRT)并指定目标版本,是最稳妥的收敛方式。
验证方式
修复完成后,可在对应沙盒工程目录下执行以下命令验证:
dotnet restore
dotnet build -c Debug
dotnet run
以 Sandbox.Blazor 为例(工程位于 src/ScottPlot5/ScottPlot5 Sandbox/Sandbox.Blazor/),独立 WASM 工程则位于 src/ScottPlot5/ScottPlot5 Demos/ScottPlot5 Blazor/。构建产物中应出现 staticwebassets.endpoints.json(独立 WASM 工程),运行时不再抛出模块加载或原生库相关异常,即代表迁移成功。
七、延伸阅读
- 控制库多目标框架方案:ScottPlot.Blazor.csproj(
net8.0;net10.0双目标)、ScottPlot.Maui.csproj(多平台目标)、ScottPlot.WinUI.csproj(Windows 与非 Windows 条件依赖) - Blazor 绘图实现:BlazorPlot.razor、BlazorPlotBase.cs
- MAUI 交互实现:MauiPlot.cs
- 完整沙盒列表:src/ScottPlot5/ScottPlot5 Sandbox