企业官网建设流程全解析

.NET MAUI 源码仓库开发调试实战指南：从 Sandbox 复现问题到 Helix 设备测试

【免费下载链接】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 开源仓库中的 docs/DevelopmentTips.md 编写，面向希望在.NET MAUI 框架源码层面进行复现问题、断点调试、本地构建与云端设备测试的开发者。全文涵盖：如何用 VS Code 打开仓库工作区并选择目标设备、如何借助 Sandbox 示例项目直接引用源码打断点、dotnet cake系列工具命令的用法、用build.sh/build.cmd在本地.dotnet目录自举 SDK 与工作负载、MSBUILDDEBUGONSTART调试 MSBuild Task 的完整流程，以及如何把设备测试提交到 Helix 云基础设施并行执行。读完本文，你将具备一套从"本地复现 bug"到"云端验证修复"的完整工程能力。

一、快速开始：用 VS Code 打开仓库并选择测试设备

1.1 打开仓库工作区

. .NET MAUI 仓库根目录自带 maui.code-workspace 工作区文件，其内容将仓库根目录作为一个文件夹，并预设了默认解决方案：

{ "folders": [ { "path": "." } ], "settings": { "dotnet.defaultSolution": "Microsoft.Maui-vscode.sln" } }

在 VS Code 中直接打开本地克隆的 .NET MAUI 仓库根目录即可，VS Code 会自动检测到该 workspace 文件并提示你打开它（选择 "Open Workspace" 即可）。工作区预设的默认解决方案是 Microsoft.Maui-vscode.sln，这是专为 VS Code 场景裁剪的解决方案，避免直接加载完整的 Microsoft.Maui.sln 而拖慢 IntelliSense 初始化。

小贴士：第一次打开后，IntelliSense 及其他后台任务可能需要约一分钟才能完成初始化。如果项目尚未"安定"下来，直接使用命令面板执行任务可能会出现 "Pick Startup Project has resulted in an error." 的报错，稍等片刻再试即可。

1.2 通过 "Pick Device" 选择目标设备

在 VS Code 中，使用命令面板（Windows/Linux 为Ctrl + Shift + P，macOS 为Command + Shift + P）输入pick device：

1. 第一次选择时会列出平台选项（Android、iOS、Mac Catalyst、Windows 等），先选中你要运行的平台；
2. 在接下来的菜单中，选择该平台下当前可用的具体设备（模拟器、模拟器镜像或本机设备）。

仓库中的 .vscode/tasks.json 也提供了Run Sample任务，其底层命令形如：

./bin/dotnet/dotnet build ${input:project} -t:Run -f ${input:framework} -c ${input:configuration} -p:AndroidAttachDebugger=${input:attach}

其中-t:Run表示构建后直接部署运行，-f指定目标框架（如net7.0-android），-p:AndroidAttachDebugger决定是否在启动时挂接 Android 调试器——这与你用命令面板手动选设备的流程本质一致，只是通过任务菜单驱动。

二、用 Sandbox 示例项目复现问题并调试框架源码

2.1 Sandbox 是什么

仓库中的src/Controls/samples/Controls.Sample.Sandbox是一个刻意保持"空"的示例应用，其核心价值在于直接引用 .NET MAUI 源码工程而非打包后的 NuGet 包。查看其项目文件 Maui.Controls.Sample.Sandbox.csproj 可以看到：

<ItemGroup Condition=" '$(UseMaui)' != 'true' "> <ProjectReference Include="..\..\..\Core\src\Core.csproj" /> <ProjectReference Include="..\..\..\Controls\src\Xaml\Controls.Xaml.csproj" /> <ProjectReference Include="..\..\..\Controls\src\Core\Controls.Core.csproj" /> <ProjectReference Include="..\..\..\BlazorWebView\src\Maui\Microsoft.AspNetCore.Components.WebView.Maui.csproj" /> <ProjectReference Include="..\..\..\Controls\Maps\src\Controls.Maps.csproj" /> <ProjectReference Include="..\..\..\Controls\Foldable\src\Controls.Foldable.csproj" /> </ItemGroup>

也就是说，当UseMaui != 'true'（即不使用全局安装的 MAUI workload）时，Sandbox 会以ProjectReference方式引用Core、Controls.Core、Controls.Xaml、BlazorWebView、Maps、Foldable 等源码工程。这意味着：

• 你可以在.NET MAUI 框架源码里直接下断点，逐行步进到控件渲染、布局、绑定等内部实现；
• 在 Sandbox 页面里粘贴你遇到的复现代码，即可在可控的最小工程中观察框架行为。

Sandbox 工程本身还包含MainPage.xaml、SandboxShell.xaml等页面文件，以及 Android/iOS/MacCatalyst/Windows/Tizen 各平台入口，属于一个完整的 MAUI 单项目（SingleProject=true）应用，随时可以往里面加页面与代码。

2.2 将 Sandbox 设为启动项目

要让 VS Code 知道你要运行的是 Sandbox，使用命令面板（Ctrl+Shift+P或 macOSCommand+Shift+P）输入pick startup，选择".NET MAUI: Pick Startup Project"，然后在列表中选择Controls.Sample.Sandbox工程。

之后配合第一节的 "Pick Device" 流程，即可把 Sandbox 部署到你选定的设备/模拟器上运行。

2.3 提交 PR 的注意事项

重要：Sandbox 属于个人复现环境，提交 Pull Request 时不要把你对 Sandbox 工程的改动一并提交（例如临时加进去的复现代码、调试输出等）。你可以用git status检查改动范围，只提交与问题修复相关的源码与测试改动。

三、Cake 工具命令：仓库根目录的日常瑞士军刀

以下参数均可配合dotnet cake命令在仓库根目录使用。它们属于工具性命令，日常开发中若只需准备 .NET SDK 与 workload，官方更推荐直接使用./build.sh -restore（Windows 用./build.cmd -restore）——这一点详见第四节。

3.1--target=publicapi：重建公共 API 清单

dotnet cake --target=publicapi

• 作用：清空并重新生成所有 MAUI 工程的PublicAPI.Unshipped.txt文件（覆盖 Core、Controls、Essentials、Graphics 四大模块）。
• 适用场景：当你新增了公共 API 却收到"缺少 API 声明"类编译错误时，运行一次即可自动补齐。
• 平台处理：非 Windows 环境自动跳过 Windows 专属文件，且始终跳过 Tizen 文件（以及 macOS 专属文件）。

其实现位于 eng/cake/dotnet.cake 的Task("publicapi")：脚本会依次扫描src/Core/src/PublicAPI、src/Controls/src/Core/PublicAPI、src/Essentials/src/PublicAPI、src/Graphics/src/Graphics/PublicAPI目录下的所有PublicAPI.Unshipped.txt，清空后以PublicApiType=Generate属性重新构建Controls.Core.csproj以回填当前实际 API。这些清单文件在仓库中真实存在，例如 src/BlazorWebView/src/Maui/PublicAPI 下按net-android、net-ios、net-tizen、net-windows、net等目标框架各有一份PublicAPI.Shipped.txt与PublicAPI.Unshipped.txt。

3.2--clean：清理本地增量构建缓存

dotnet cake --clean

• 问题背景：切换分支或同步 main 分支后，增量构建偶尔会"坏掉"（出现莫名其妙的编译或链接错误）。
• 常见粗暴解法：git clean -xdf删除全部本地缓存，但代价是未提交的改动也会被一并抹掉。
• 推荐解法：使用--clean递归删除本地各工程的obj/bin目录，既清除了缓存，又保留你的未提交修改。

3.3 指定目标平台：--android/--ios/--windows/--catalyst

dotnet cake --target=VS --workloads=global --android --ios

• 上面的命令表示：以全局 workload 方式准备 .NET，构建并启动 Visual Studio，同时只启用 Android 与 iOS 两个平台。
• 注意：如果你在项目里新增或更换了平台，需要先执行git clean -xdf彻底清理后重新构建，否则新旧平台的残留产物会互相干扰。

四、Blazor Hybrid

若要构建并运行 Blazor Desktop（即 Blazor Hybrid / Blazor WebView for Desktop）示例，请查阅仓库内 Blazor WebView 相关示例工程，例如 src/BlazorWebView/samples/BlazorWinFormsApp、src/BlazorWebView/samples/BlazorWpfApp 与共享的 src/BlazorWebView/samples/WebViewAppShared。这些工程演示了如何在 WinForms / WPF 中承载 Blazor WebView、如何使用RootComponent注册 Razor 组件以及如何做 JS 互操作。具体构建运行方式以对应工程及仓库 src/BlazorWebView 目录下的源码说明为准。

五、高级场景：用本地.dotnet自举构建整个仓库

5.1 推荐方式：build.sh/build.cmd

这是官方推荐的 .NET SDK 与 workload 准备方式，底层基于 Arcade 构建基础设施。仓库根目录提供了 build.sh 与 build.cmd 脚本，以及配套的eng/common工具链。

第一步：恢复 .NET SDK 与 workload 到本地.dotnet目录

./build.sh -restore

Windows 下：

.\build.cmd -restore

第二步（可选）：同时构建解决方案

./build.sh -restore -build

.\build.cmd -restore -build

第三步（可选）：打包 NuGet 包

./build.sh -restore -pack

.\build.cmd -restore -pack

执行-restore后，本地的 SDK 会落在.dotnet目录，后续所有./bin/dotnet/dotnet ...形式的命令都使用这套自举 SDK，从而保证构建的是当前分支的源码而非已发布的正式包。

5.2 通过 Cake 目标启动 IDE

仓库的 eng/cake/dotnet.cake 定义了VS、VSCode、Insiders三个 IDE 启动目标，它们都会先执行Clean→dotnet（自举 SDK）→dotnet-buildtasks（构建 MSBuild Task）→dotnet-pack（按需打包），再以自举的 .NET 环境变量启动 IDE：

dotnet tool restore dotnet cake --target=VS

启动 VS Code：

dotnet tool restore dotnet cake --target=VSCode

从源码看，StartVisualStudioForDotNet()在 Windows 上通过VSWhereLatest找到最新版 Visual Studio 并打开Microsoft.Maui-windows.slnf（非 Windows 上则打开Microsoft.Maui-mac.slnf），同时注入DOTNET_INSTALL_DIR、DOTNET_ROOT、PATH等环境变量，确保 IDE 内部使用的就是本地.dotnet（见 dotnet.cake 中的SetDotNetEnvironmentVariables）。

5.3 用--sln把分支改动实测到你的项目上

如果你想知道某个分支的修改能否解决你遇到的问题，可以用--sln参数让 MAUI 先完成打包，再用本地包打开你的解决方案：

dotnet tool restore dotnet cake --sln="<download_directory>\MauiApp2\MauiApp2.sln" --target=VS

注意：打包只在第一次运行时自动执行；如果你改了代码需要重新打包，必须显式加上--pack标志。

5.4--pack：把分支改动装进本地 dotnet

dotnet tool restore dotnet cake --target=VS --pack --sln="<download_directory>\MauiApp2\MauiApp2.sln"

--pack会在本地 dotnet 安装目录内生成 .NET MAUI 的 pack（包括模板改动），此后你就能用本地 dotnet 的 CLI 命令创建/部署应用，并且所有行为都基于当前分支的改动。

用新 pack 创建一个全新 MAUI 应用：

dotnet tool restore dotnet cake --pack mkdir MyMauiApp cd MyMauiApp ..\bin\dotnet\dotnet new maui ..\bin\dotnet\dotnet build -t:Run -f net[current_sdk_version]-android

其中net[current_sdk_version]指代当前 SDK 对应的目标框架版本（仓库 dotnet.cake 中的DefaultDotnetVersion默认值为net10.0，请以你本地eng/Versions.props实际版本为准）。

5.5 拆开跑的完整命令序列

如果不希望走完整 Cake 流程，也可以按顺序手动执行：

# 1. 安装本地构建工具（cake、pwsh 等） dotnet tool restore # 2. 在 bin\dotnet 中自举 .NET SDK dotnet build src\DotNet\DotNet.csproj # 3. 构建 MAUI 的 MSBuild Tasks .\bin\dotnet\dotnet build Microsoft.Maui.BuildTasks.slnf # 4. 构建其余全部 MAUI 代码 .\bin\dotnet\dotnet build Microsoft.Maui.sln # 5. 启动 Visual Studio dotnet cake --target=VS

注意：这些命令大多依赖步骤 2 自举出的bin\dotnet里的 SDK，因此顺序不能颠倒；dotnet tool restore负责把仓库 .config 下声明的本地工具（Cake 等）恢复到.config/dotnet-tools.json指定的版本。

六、调试 MSBuild Tasks：让构建停下来等你挂调试器

MSBuild Task 在构建进程内部执行，常规方式很难断点调试。.NET MAUI 仓库的做法是利用MSBUILDDEBUGONSTART环境变量：将其设为2时，MSBuild 会在继续执行前阻塞并等待调试器连接，控制台会输出类似：

Waiting for debugger to attach (dotnet PID 13001). Press enter to continue...

之后在 IDE 中挂接到该 PID，再回到命令行按回车放行，即可从断点处逐步调试 Task 代码。

6.1 各平台启动命令

macOS

MSBUILDDEBUGONSTART=2 ~/<some maui checkout>/dotnet-local.sh build -m:1

Linux

MSBUILDDEBUGONSTART=2 ~/<some maui checkout>/dotnet-local.sh build -m:1

Windows

set MSBUILDDEBUGONSTART=2 ~/<some maui checkout>/dotnet-local.cmd build -m:1

-m:1非常关键：它把 MSBuild 限制为单节点，否则调试器挂接的进程可能与实际执行 Task 的进程不一致，导致断点不命中。若当前 checkout 中不存在dotnet-local.sh/dotnet-local.cmd（仓库快照中未包含该脚本），可改用自举出的./bin/dotnet/dotnet或./.dotnet/dotnet配合同样的环境变量执行build -m:1。

6.2 在 IDE 中挂接进程

• Visual Studio：打开Microsoft.Maui.sln解决方案，使用菜单Debug → Attach to Process，选择输出提示中的 dotnet PID。
• VS Code：打开仓库工作区，使用Run and Debug面板中的Attach to Process选项，输入 PID 后连接。

连接成功后，回到命令行按Enter让 MSBuild 继续。此后你可以在Task 代码中设置断点并单步执行（注意：Target 是 MSBuild 脚本，无法断点，只有 C# 编写的 Task 可以）。

6.3 在 VS Code 里自动填充

如果你在 VS Code 中进行 in-tree 调试，可以使用Build Platform Sample命令——它会询问你是否调试 MSBuild Tasks，并自动为你填好MSBUILDDEBUGONSTART。查看 .vscode/tasks.json 可以看到，Build Platform Sample任务的debugbuildtasks输入项正好提供""与"MSBUILDDEBUGONSTART=2"两个选项，选择后者即可。启动后 PID 文本会出现在 VS Code 的Terminal面板中，再用Attach to Process挂接即可。

七、集成测试：构建与运行 MAUI 模板

集成测试工程位于src/TestUtils/src/Microsoft.Maui.IntegrationTests，它包含"构建并/或运行 MAUI 模板或其他项目"的测试。仓库中的 dotnet.cake 也内置了dotnet-integration-build与dotnet-integration-test两个 Cake 目标。

你既可以在 VS 的测试资源管理器（Test Explorer）中运行，也可以从命令行用dotnet test精确指定某个测试：

dotnet test src/TestUtils/src/Microsoft.Maui.IntegrationTests --logger "console;verbosity=diagnostic" --filter "Name=Build\(\"maui\",\"net7.0\",\"Debug\",False\)"

说明：

• --logger "console;verbosity=diagnostic"：输出诊断级日志，便于观察模板创建与构建过程的每一步；
• --filter "Name=Build(...)"：按方法名精确过滤（注意方法名中的括号与引号在命令行里需要转义）；
• 该测试的本质是：用指定版本的模板创建一个maui应用，在 Debug 配置下构建，并验证是否成功——这也是检验"分支改动是否破坏模板"的最直接手段。

八、在 Helix 上运行设备测试

.NET MAUI 支持借助 .NET Engineering Services 的Helix（基于 XHarness）把设备测试分发到云端的真实设备/模拟器上并行执行。Helix 提供跨平台、多设备的云端测试基础设施，本地构建好测试包后提交上去，即可在 CI 或自用场景下大规模跑设备测试。

8.1 涉及哪些设备测试工程

仓库中参与 Helix 的测试工程包括：

它们对应的源码分别在 src/Controls/tests/DeviceTests、src/Core/tests/DeviceTests、src/Graphics/tests/DeviceTests、src/Essentials/test/DeviceTests 与 src/BlazorWebView/tests/DeviceTests。

8.2 Helix 队列

当前配置（以仓库 eng/helix_xharness.proj 为准）使用的队列如下：

• iOS：osx.15.arm64.open（对外开源队列）
• Mac Catalyst：osx.15.arm64.open
• Android：ubuntu.2204.amd64.android.33.open

源码中的实际队列定义更为细致（开放场景与内部场景分开）：

<HelixTargetQueues Condition="'$(TargetOS)' == 'ios'">osx.15.arm64.maui.open;osx.26.arm64.open</HelixTargetQueues> <HelixTargetQueues Condition="'$(TargetOS)' == 'maccatalyst'">osx.15.arm64.maui.open;osx.26.arm64.open</HelixTargetQueues> <HelixTargetQueues Condition="'$(TargetOS)' == 'android'">ubuntu.2204.amd64.android.33.open</HelixTargetQueues> <HelixTargetQueues Condition="'$(TargetOS)' == 'windows'">windows.11.amd64.client.open</HelixTargetQueues>

即 iOS/Mac Catalyst 使用 macOS ARM64 队列（同时保留内部HelixInternal=True时的专用队列），Android 使用 Ubuntu + Android 33 模拟器队列，Windows 场景还支持windows.11.amd64.client.open。具体可用队列请以 Helix 服务端实时列表为准。

8.3 本地三步走：构建 → 打包 → 提交

以下命令默认在仓库根目录执行。

Step 1：构建 MSBuild Tasks（必做）

# 恢复 dotnet 工具 dotnet tool restore # 构建 MSBuild Tasks（必需的前置步骤） ./build.sh -restore -build -configuration Release -projects $(PWD)/Microsoft.Maui.BuildTasks.slnf /bl:BuildBuildTasks.binlog -warnAsError false

/bl:BuildBuildTasks.binlog用于输出二进制构建日志，-warnAsError false避免历史告警直接导致失败。

Step 2：构建设备测试工程

# 为所有平台构建设备测试 ./build.sh -restore -build -configuration Release /p:BuildDeviceTests=true /bl:BuildDeviceTests.binlog -warnAsError false

/p:BuildDeviceTests=true是触发设备测试工程参与构建的属性开关。

Step 3：提交到 Helix

先设置 Helix 所需的 CI 环境变量：

export BUILD_REASON=pr export BUILD_REPOSITORY_NAME=maui export BUILD_SOURCEBRANCH=main export SYSTEM_TEAMPROJECT=dnceng export SYSTEM_ACCESSTOKEN=''

然后分别按目标平台提交：

# 提交 Android 设备测试 ./eng/common/msbuild.sh ./eng/helix_xharness.proj /restore /p:TreatWarningsAsErrors=false /t:Test /p:TargetOS=android /bl:sendhelix_android.binlog -verbosity:diag # 提交 iOS 设备测试 ./eng/common/msbuild.sh ./eng/helix_xharness.proj /restore /p:TreatWarningsAsErrors=false /t:Test /p:TargetOS=ios /bl:sendhelix_ios.binlog -verbosity:diag # 提交 Mac Catalyst 设备测试 ./eng/common/msbuild.sh ./eng/helix_xharness.proj /restore /p:TreatWarningsAsErrors=false /t:Test /p:TargetOS=maccatalyst /bl:sendhelix_catalyst.binlog -verbosity:diag

核心是 eng/helix_xharness.proj 这个 MSBuild 项目：它根据TargetOS选择队列与测试场景，自动从artifacts/bin/发现各设备测试工程的产物（MAUIScenario自动发现机制），并以 XHarness 定义每个 work item 的TestTarget（如ios-simulator-64、maccatalyst）。

8.4 Windows 命令

Windows 开发环境使用对应的.cmd文件：

set BUILD_REASON=pr set BUILD_REPOSITORY_NAME=maui set BUILD_SOURCEBRANCH=main set SYSTEM_TEAMPROJECT=dnceng set SYSTEM_ACCESSTOKEN=

REM 构建 MSBuild Tasks .\build.cmd -restore -build -configuration Release -projects ".\Microsoft.Maui.BuildTasks.slnf" /bl:BuildBuildTasks.binlog -warnAsError false REM 构建设备测试 .\build.cmd -restore -build -configuration Release /p:BuildDeviceTests=true /bl:BuildDeviceTests.binlog -warnAsError false REM 提交到 Helix（以 Android 为例） .\eng\common\msbuild.cmd .\eng\helix_xharness.proj /restore /p:TreatWarningsAsErrors=false /t:Test /p:TargetOS=android /bl:sendhelix.binlog -verbosity:diag

8.5 配置细节

eng/helix_xharness.proj 是 Helix 配置的核心，主要包含：

• 超时设置：work item 超时 2 小时、测试超时 1 小时（iOS 上个别按类别拆分的 Controls 测试还额外配置了LaunchTimeout10 分钟），定义于各XHarnessAppBundleToTest项的WorkItemTimeout/TestTimeout/LaunchTimeout元数据；
• 测试发现：通过MAUIScenario自动发现每个场景的测试包（遍历artifacts/bin/下的Controls.DeviceTests、Core.DeviceTests等目录）；
• 平台定位：每个平台对应特定目标框架（TargetFrameworkToTest）与 XHarnessTestTarget；
• 队列选择：按TargetOS与HelixInternal选择开放的*.open队列或内部专用队列；
• XHarness 集成：通过IncludeXHarnessCli引入 XHarness 完成设备编排（Windows 目标不使用 XHarness，故IncludeXHarnessCli=false）。

8.6 常见问题排查

1. 构建失败：请先确认已经完成 Step 1（构建 MSBuild Tasks），Helix 提交依赖最新的 Task 二进制；
2. 找不到设备/队列不可用：检查目标队列（如ubuntu.2204.amd64.android.33.open）在 Helix 服务端是否可用；
3. 认证失败：CI 场景下请确保设置了正确的 Azure DevOps 访问令牌（SYSTEM_ACCESSTOKEN）；
4. 超时：默认超时比较宽松，但复杂测试场景（如长时间 UI 交互）可能需要按需调大WorkItemTimeout/TestTimeout。

日志与诊断建议：

• 始终使用/bl:文件名.binlog生成二进制日志，配合dotnet msbuild /bl或其他 binlog 查看工具定位构建阶段问题；
• 提交 Helix 时追加-verbosity:diag获取最大诊断输出；
• 提交完成后，根据 Helix 返回的作业 URL 查看运行结果与设备日志。

8.7 与 CI 的集成

设备测试已接入仓库 CI 流水线，主要通过以下文件：

• eng/pipelines/common/stage-device-tests.yml：流水线模板，定义设备测试阶段；
• eng/test-configuration.json：测试重试配置；
• 满足条件的 PR 构建会自动触发设备测试，无需人工干预。

从 eng/helix_xharness.proj 的队列定义可以看出，同一套提交逻辑既服务于内部 CI（HelixInternal=True的专用队列），也面向开源贡献者（*.open队列），这正是 .NET MAUI 社区化测试协作的基础设施保障。

九、总结

围绕 docs/DevelopmentTips.md 的内容，本文完整覆盖了 .NET MAUI 仓库开发的四类核心场景：

1. 本地复现与断点调试：VS Code 工作区 + "Pick Device" + Sandbox 工程直接引用源码；
2. 日常工具命令：dotnet cake的publicapi、clean、平台参数，以及build.sh/build.cmd的自举构建、--sln、--pack分支实测流程；
3. 构建系统级调试：用MSBUILDDEBUGONSTART=2让 MSBuild 等待调试器，进而单步调试 Task 代码；
4. 云端设备测试：从本地构建设备测试包到提交 Helix 并行执行，再到基于 eng/helix_xharness.proj 的配置与排障。

掌握了这条链路，你就拥有了从"在框架源码里复现一个 bug"到"用云端设备矩阵验证修复"的完整工作流，这也是参与 .NET MAUI 社区开发最常用的实战路径。

【免费下载链接】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