.NET MAUI Profiled AOT：基于 Android AOT Profiler 的启动性能优化实践指南

.NET MAUI Profiled AOT：基于 Android AOT Profiler 的启动性能优化实践指南

【免费下载链接】maui.NET MAUI is the .NET Multi-platform App UI, a framework for building native device applications spanning mobile, tablet, and desktop.项目地址: https://gitcode.com/GitHub_Trending/ma/maui

本文是 .NET MAUI 仓库中 src/ProfiledAot/README.md 的深度展开版本，完整覆盖 Android Profiled AOT（启动剖析 AOT）配置的生成、更新、验证与排查全流程。你将掌握如何基于Mono.AotProfiler.Android工具链重新录制 MAUI 三种官方模板的 AOT 剖析文件，如何用adb logcat量化应用启动耗时，以及如何逐条验证目标方法是否被真正 AOT 编译——这是 .NET MAUI 维护者改善 Android 冷启动性能的标准工作流。

背景：为什么 .NET MAUI Android 需要 Profiled AOT

Android 应用在 Release 构建下通常采用 Ahead-of-Time（AOT）或 Profile-Guided AOT 来避免 JIT 运行时的即时编译开销，从而显著缩短冷启动时间。对于通用框架来说，一个关键问题是：无法预先知道开发者应用的启动代码路径。因此 .NET MAUI 采用了"剖析式 AOT"（Profiled AOT）策略：

1. 先在受控环境下运行官方模板生成的示例应用，由Mono.AotProfiler.Android采集实际启动阶段被调用的方法集合；
2. 将采集结果导出为.aotprofile剖析文件，随 NuGet 包发布；
3. 开发者构建自己的应用时，MAUI 构建任务把该剖析文件作为 AOT 提示注入，仅对这些热点方法做 AOT 编译，从而在启动时间与包体大小之间取得平衡。

本仓库中的 AOT 剖析流程基于开源工具Mono.Profiler.Android（其用法源自 Jonathan Peppers 维护的 Mono.Profiler.Android 项目），MAUI 通过 NuGet 包Mono.AotProfiler.Android集成该能力。

剖析项目在仓库中的布局

ProfiledAot子项目集中在 src/ProfiledAot 目录下，结构如下：

src/ProfiledAot/ ├── README.md # 本文对应的原始操作文档 ├── build.proj # 录制入口：临时生成模板项目并触发 Record 目标 └── src/ ├── Directory.Build.props # Release 配置、开启 AndroidEnableAotProfiler ├── Directory.Build.targets # Record 目标链：录制、剥离、导出方法名 ├── CommonMethods.cs # 刻意覆盖通用热路径的公共调用样例 ├── Strings.resx # 触发 ResourceManager 路径的本地化资源 ├── maui/ # 对应 `dotnet new maui` 的替换文件 │ ├── MainPage.xaml.cs │ ├── App.xaml │ ├── AppShell.xaml │ ├── Tabs.xaml │ └── AppFlyoutPage.xaml └── maui-blazor/ # 对应 `dotnet new maui-blazor` 的替换文件 └── MainPage.xaml.cs

其中build.proj是录制的总入口，它根据App属性动态生成对应模板项目，再逐级把src/$(App)/下的文件拷贝进临时项目覆盖默认页面，最终委托 MSBuild 执行Record目标（详见 build.proj）。

更新 AOT Profile 的完整流程

1. 准备 Release 构建环境

先按照仓库的 DEVELOPMENT.md 完成 MAUI 本地构建，务必使用 Release 配置：

./.dotnet/dotnet build --configuration=Release

剖析流程依赖仓库自带的本地 .NET SDK（./.dotnet/dotnet），因此后续所有命令都在仓库根目录下执行。

2. 对三种模板分别录制 Profile

对每种"类型"的官方模板运行Record目标：

./.dotnet/dotnet build src/ProfiledAot/build.proj -bl -p:App=maui ./.dotnet/dotnet build src/ProfiledAot/build.proj -bl -p:App=maui-sc ./.dotnet/dotnet build src/ProfiledAot/build.proj -bl -p:App=maui-blazor

三种App值对应的模板语义（见 build.proj 中对_TemplateName与_TemplateParameters的映射）：

-bl会生成 MSBuild 二进制日志（.binlog），后续排查空 Profile 问题时会用到。如果你更希望使用 x86_64 模拟器，可以追加：

./.dotnet/dotnet build src/ProfiledAot/build.proj -bl -p:App=maui -r android-x64

默认的RuntimeIdentifier是android-arm64（定义于 build.proj），实际 AOT 剖析在设备/模拟器上完成，运行时架构应与目标设备一致。

3. Record 目标背后发生了什么

Record目标并非一个简单任务，而是由一串子目标串联而成（定义于 src/Directory.Build.targets）：

<RecordDependsOn> Clean; _ClearSystemProperties; <!-- 清空 debug.mono.log，避免历史遗留配置 --> BuildAndStartAotProfiling; <!-- 部署并启动应用，同时开启 AOT 剖析 --> _Sleep; <!-- 睡眠 5 秒，等待启动路径执行完毕 --> FinishAotProfiling; <!-- 结束剖析并把数据写回 socket --> _StripAppMethods; <!-- 从剖析文件中剥离应用自身程序集 --> _SaveMethodNames; <!-- 导出方法名清单，便于 diff --> </RecordDependsOn>

几个值得注意的实现细节：

• _ClearSystemProperties通过adb shell setprop debug.mono.log ''把系统属性置空，防止上一次调试会话遗留的 Mono 日志配置干扰录制；
• _Sleep使用RoslynCodeTaskFactory内联定义的Sleep任务固定等待 5000ms（见 src/Directory.Build.targets），保证应用启动路径被充分执行；
• _StripAppMethods调用aprofutil -sd --filter-module="^(?!$(App)).+"把示例应用自身的程序集（如ProfiledAotMaui.dll）从剖析文件中剔除，因为真实用户应用的命名不同，保留它们只会白白增大 Profile（见 src/Directory.Build.targets）；
• _SaveMethodNames用aprofutil -m把 Profile 中的方法名列表导出为文本（见 src/Directory.Build.targets）。

录制成功后，MSBuild 会打印目标 Profile 的落盘位置：

Success! See changes in: <输出目录>maui.aotprofile

4. 剖析时的工程配置

录制用的临时项目继承了 src/Directory.Build.props 中的关键属性：

• <Configuration>Release</Configuration>：强制 Release 构建；
• <AndroidEnableAotProfiler>true</AndroidEnableAotProfiler>：开启 AOT Profiler，这是录制的基础开关；
• <RunAOTCompilation>false</RunAOTCompilation>：录制阶段不真正做 AOT 编译；
• <AndroidNeedsInternetPermission>true</AndroidNeedsInternetPermission>：录制样例中CommonMethods.Invoke()需要发起 HTTP 请求；
• <AndroidPackageFormat>apk</AndroidPackageFormat>与AndroidUseDefaultAotProfile/MauiUseDefaultAotProfile均为false：避免默认 Profile 干扰录制结果（见 src/Directory.Build.targets）。

同时临时项目以PackageReference方式引入剖析工具链Mono.AotProfiler.Android，并以AndroidAotProfile Include="custom.aprof"声明输出 Profile（见 src/Directory.Build.targets）。

5. 录制样例覆盖的通用热路径

为了让 Profile 覆盖到各种业务应用的公共启动路径，录制项目注入了 CommonMethods.cs。该文件注释明确列出了"我们总是希望被 AOT"的公共代码路径，包括：

• 字符串插值、Split分割；
• int.Parse()/int.ToString()；
• 文化感知的字符串比较（因此用#pragma warning disable CA1307主动关掉相关分析器警告，见 CommonMethods.cs）；
• ResourceManager资源查找（通过 Strings.resx 中的SomeString触发）；
• 常见 Essentials API：Connectivity.NetworkAccess、DeviceInfo.Idiom、AppInfo.RequestedTheme；
• GridLayoutManager的 Measure 测量；
• Label与FontAttributes；
• Microsoft.Maui.Graphics.Color的颜色解析（MistyRose命名色与#663399十六进制色）；
• System.Threading.Tasks.Task与System.Net.Http.HttpClient的异步请求。

该样例会被三种模板的启动页在启动时调用：maui模板在 MainPage.xaml.cs 的Start()中执行CounterBtn.Text = await CommonMethods.Invoke();，maui-blazor模板则在 MainPage.xaml.cs 构造函数中直接_ = CommonMethods.Invoke();。这意味着录制的 Profile 天然覆盖了 MAUI 控件、Essentials、Graphics、BlazorWebView 等框架级热路径。

6. 用方法名清单跟踪变化

maui.aotprofile.txt与maui-blazor.aotprofile.txt是 Profile 内方法名的清单文件。它们不会随 NuGet 包发布，仅供开发者在仓库内跟踪 Profile 随版本的变化。注意这些文本并非总是有序的，原始文档给出的技巧是：在 VS Code 中用Ctrl+Shift+P打开命令面板，执行Sort lines ascending按字母序排序后做 diff。

关键判断准则：如果重新录制后文本文件没有变化，那么大概率没有必要更新.aotprofile文件——这能显著节省无谓的 Profile 迭代时间。

验证新 Profile：启动耗时对比测试

更新 Profile 之后，必须回归验证：新的启动耗时应"持平或略优于"旧值。流程如下：

1. 重新构建 Release 版 MAUI

./.dotnet/dotnet build --configuration=Release

2. 创建测试项目并运行

mkdir foo && cd foo ../.dotnet/dotnet new maui ../.dotnet/dotnet build -c Release -t:Run -f net7.0-android

3. 通过 adb logcat 量化启动耗时

运行应用数次后抓取系统记录的 "Displayed" 时间戳：

$ adb logcat -d | grep Displayed 02-22 15:50:50.502 1802 1962 I ActivityTaskManager: Displayed com.companyname.foo/crc64808a40cc7e533249.MainActivity: +477ms 02-22 15:50:51.703 1802 1962 I ActivityTaskManager: Displayed com.companyname.foo/crc64808a40cc7e533249.MainActivity: +477ms 02-22 15:50:52.926 1802 1962 I ActivityTaskManager: Displayed com.companyname.foo/crc64808a40cc7e533249.MainActivity: +477ms

ActivityTaskManager打出的+477ms即 Activity 从创建到首帧显示的耗时，多次运行取稳定值即可作为启动性能基线。

4. 使用仓库自带脚本做自动统计

仓库提供了两个脚本化工具替代手工 grep：

• eng/scripts/profile-android.ps1：仓库内置的 PowerShell 脚本。它自动完成"构建部署 → 循环拉起应用 → 解析Activity.*Manager.+Displayed日志 → 计算平均耗时"的流程，支持-iterations（默认 10 次）、-sleep（默认 3 秒）等参数，并会输出均值、标准误差与标准差：

PS> ./eng/scripts/profile-android.ps1 -project .\Path\To\MyApp.csproj -package com.mycompany.myapp -iterations 3 Average(ms): 1513.33333333333 Std Err(ms): ... Std Dev(ms): ...

• 社区维护的profile.ps1（来自 Jonathan Peppers 的 maui-profiling 脚本库），作为补充手段参考。

故障排查：Profile 为空或数据异常

症状 1：生成的*.aotprofile.txt为空

打开.binlog查看aprofutil的输出，若看到类似下面的内容，说明 profiler 完全没有采集到任何数据：

Task Exec 85ms CommandLineArguments = "D:\.nuget\packages\mono.aotprofiler.android\9.0.0-preview1\tools\aprofutil" -s -v -p 9999 -o "custom.aprof" Reading from '127.0.0.1:9999'... Read 19 bytes... Read total 19 bytes... Summary: Modules: 0 Types: 0 Methods: 0 Going to write the profile to 'custom.aprof'

Modules: 0 / Types: 0 / Methods: 0意味着 profiler 从 9999 端口只读到 19 字节的空数据。

症状 2：Mono profiler 初始化失败

为 Mono 打开详细日志：

adb shell setprop debug.mono.log default,assembly,mono_log_level=debug,mono_log_mask=all

注意：src/ProfiledAot/src/Directory.Build.targets中有一个目标会把debug.mono.log置空以排除干扰，调试期间需要先注释掉该行（对应_ClearSystemProperties中的setprop debug.mono.log ''，见 src/Directory.Build.targets），否则你设置的属性会在录制时被清掉。

一个正常的 Mono profiler 启动日志应该长这样：

05-21 11:38:30.032 28555 28555 W monodroid: Initializing profiler with options: aot:port=9999,output=/data/user/0/com.companyname.maui/files/.__override__/arm64-v8a/profile.aotprofile 05-21 11:38:30.032 28555 28555 I monodroid-assembly: Trying to load shared library '/data/app/~~aLsIB6f0cwe4kpqTjGW6KA==/com.companyname.maui-8LChNbDvTnxGHnFnUt1vBw==/lib/arm64/libmono-profiler-aot.so' 05-21 11:38:30.033 28555 28555 W monodroid: Looking for profiler init symbol 'mono_profiler_init_aot'? 0x7826470468 ... 05-21 11:38:35.531 28555 28555 I mono-prof: AOT profiler data written to 'socket' 05-21 11:38:35.534 28555 28555 E mono-prof: aot profiler data saved to the socket

对照上面的日志，失败点通常有三种：

1. libmono-profiler-aot.so共享库加载失败；
2. 找不到mono_profiler_init_aot初始化符号；
3. 即便初始化成功，profiler 也没有返回任何数据。

这类问题的修复需要重新构建libmono-profiler-aot.so。由于该原生库与 .NET 运行时版本强绑定，MAUI 通常需要为每个 .NET 大版本发布对应新版的Mono.Profiler.Android（仓库当前使用的Mono.AotProfiler.Android版本见 src/Directory.Build.targets，历史迭代可参考 Mono.Profiler.Android 项目中的相关 PR）。

NuGet 缓存注意事项

对比"更新前后"效果时，需要确保本地实际使用的是新生成的 Profile：

• 可用如下命令把新 Profile 直接覆盖到 NuGet 缓存中的 MAUI 构建任务包内：

cp -Verbose src\Controls\src\Build.Tasks\nuget\buildTransitive\netstandard2.0\*.aotprofile ~\.nuget\packages\microsoft.maui.controls.build.tasks\9.0.100-preview.2-dev\buildTransitive\netstandard2.0\

上述源路径对应仓库中 Profile 的"发布前"位置——Microsoft.Maui.Controls.Build.Tasks的 NuGet 打包目录，其netstandard2.0/buildTransitive下的 targets 文件通过三个AndroidAotProfile项分别引入maui.aotprofile、maui-sc.aotprofile与maui-blazor.aotprofile（见 Microsoft.Maui.Controls.targets），这也印证了最终发布的 Profile 去向。

• 若%NUGET_PACKAGES%中存在陈旧的*-dev构建残留，可能干扰对比结果，必要时手动清空所有开发版缓存目录：

rm -r ~\.nuget\packages\*\*-dev\

验证特定方法是否真的被 AOT

剖析文件生效与否，最终要落到"具体方法是否被 AOT 编译"这一层面。

开启 AOT 日志

先清空 logcat，再打开 AOT 相关的 Mono 日志掩码：

adb logcat -c adb shell setprop debug.mono.log default,timing=bare,assembly,mono_log_level=debug,mono_log_mask=aot

重启应用后检索 AOT 日志：

$ adb logcat -d | grep AOT 02-23 09:03:46.327 10401 10401 D Mono : AOT: FOUND method Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView:.ctor () [0x6f9efd0150 - 0x6f9efd0340 0x6f9efd260c]

AOT: FOUND method ...表示该方法命中了剖析文件并被 AOT 编译（方括号内是编译产物的地址区间）。

如何解读AOT NOT FOUND

密切关注任何可疑的AOT NOT FOUND消息，但请理性看待以下两类"预期内的未命中"：

02-23 09:03:46.327 10401 10401 D Mono : AOT NOT FOUND: (wrapper runtime-invoke) object:runtime_invoke_void (object,intptr,intptr,intptr). 02-23 09:03:46.334 10401 10401 D Mono : AOT NOT FOUND: (wrapper managed-to-native) System.Diagnostics.Debugger:IsAttached_internal (). 02-23 09:03:46.367 10401 10401 D Mono : AOT NOT FOUND: (wrapper native-to-managed) Android.Runtime.JNINativeWrapper:Wrap_JniMarshal_PPL_V (intptr,intptr,intptr).

以(wrapper ...)开头的条目属于运行时生成的包装器（如runtime-invoke、managed-to-native、native-to-managed桥接方法），它们本就不在剖析文件覆盖范围内，出现AOT NOT FOUND是正常现象。需要重点关注的是业务代码或框架方法的未命中——那才意味着 Profile 存在覆盖盲区，值得向.aotprofile补充对应调用路径后重新录制。

实践小结

• 更新节奏：只有*.aotprofile.txt方法名清单发生变化时才需要同步更新二进制.aotprofile；否则跳过，避免无谓的 Profile 变更。
• 质量门槛：任何 Profile 更新都必须通过启动耗时回归（Displayed时间持平或更优）与AOT NOT FOUND审计双重验证。
• 工具链版本：libmono-profiler-aot.so与 .NET 主版本强绑定，换 .NET 大版本时需同步升级Mono.AotProfiler.Android并重新构建原生 profiler 库。
• 文件流向：Profile 的录制产物最终通过 Microsoft.Maui.Controls.targets 随Microsoft.Maui.Controls.Build.TasksNuGet 包发布，成为所有 MAUI Android 应用默认的 AOT 启动提示。

【免费下载链接】maui.NET MAUI is the .NET Multi-platform App UI, a framework for building native device applications spanning mobile, tablet, and desktop.项目地址: https://gitcode.com/GitHub_Trending/ma/maui