企业官网建设流程全解析

WinUI 3 应用构建、运行与启动验证完全指南（Build, Run, and Launch Verification）

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本文档面向在 Windows 上使用 C# 与 Windows App SDK 开发 WinUI 3 桌面应用的开发者与 AI Agent，系统讲解从「构建」到「真实启动验证」的完整闭环流程：如何识别打包（packaged）与未打包（unpackaged）两种部署模型、如何选择与模型匹配的启动路径、如何用客观证据确认应用真正打开了主窗口，以及当启动崩溃、MSB3073、XamlCompiler.exe等故障出现时如何逐步隔离并恢复。读完本文，你将能构建一套可重复、可验证的 WinUI 应用「改代码 → 构建 → 启动 → 验证 → 交付」工作流。本文以仓库中 build-run-and-launch-verification.md 为核心骨架，并结合 SKILL.md 及其余 reference 文档中的脚手架、配置与排查细则展开。

这份参考文档的定位与适用场景

build-run-and-launch-verification.md是本技能中优先级标记为CRITICAL的核心参考文件。它在技能的路由表中被明确指派给以下场景（见 SKILL.md 的 Common Routes 一节）：

• 需要构建（build）、运行（run）一个 WinUI 应用；
• 遇到启动失败（launch failures）、启动崩溃（startup crashes）；
• 需要对应用做最终验证（final verification），确认它确实在当前机器上打开了窗口。

换句话说，只要任务涉及「构建产物是否可用」「应用是否真的起来了」，就应当以本文件为行为准则。它强调的核心原则只有一条：构建成功 ≠ 运行成功，必须用客观证据验证真实启动。

配套地，技能中还有两份紧密相关的参考文件：决定项目形态与打包模型的 foundation-setup-and-project-selection.md，以及针对模板级恢复的 foundation-template-first-recovery.md，本文会沿用到它们的内容。

必选工作流：从改代码到交付的七步闭环

原文档定义了一套「Required Workflow」，要求每次有意义的代码编辑后都要构建，任务收尾时再构建一次，并在条件允许时运行应用。完整拆解如下：

1. 识别真实构建目标：先弄清楚
   • solution 或 project 文件是哪个（.sln/.csproj）；
   • 构建配置（Configuration），通常为Debug/Release；
   • 目标平台（Platform），例如x64；
   • 部署模型是打包还是未打包。
2. 每次有意义编辑后构建一次，任务完成时再构建一次——不要只在最后一次性构建。
3. 条件允许时运行应用。尤其是当用户明确要求运行，或本次改动涉及启动、导航、资源或打包相关代码时，必须运行。
4. 使用与部署模型匹配的启动路径：
   • 打包应用的本地开发：通常走 Visual Studio 部署（F5）或其他能感知包（package-aware）的流程；
   • 未打包应用的本地开发：通常直接运行用户真正会执行的构建产物.exe。
5. 用客观证据验证真实启动，包括但不限于：
   • 非零的主窗口句柄（main window handle）；
   • 符合预期的窗口标题（window title）；
   • 进程响应正常、可见的 Shell 窗口存在；
   • 没有立即出现的启动异常或崩溃。
6. 完成后保留验证通过的实例：无论是首次脚手架还是后续「构建-修复」循环，只要启动验证成功，除非用户明确要求不要运行，否则把最终验证通过的实例保持打开，让用户能亲眼看到它工作。
7. 启动失败或验证结果模糊时必须先调试，绝不能直接宣称「应用准备好了」。

这七步与本技能在 SKILL.md 中的硬性规则完全一致：其中明确要求「任何创建或修改 WinUI 应用的工作，都要先做一套完整但最小的编辑集，然后默认构建并运行，即使客户没有明确要求验证」。如果运行中的实例锁住了输出文件而还有更多工作要做，就停止它、重新构建、重新启动，继续验证循环。

打包 vs 未打包：先选模型，再写代码

原文档强调：必须在开始编写启动、持久化和启动说明之前，就有意识地选好其中一种模型，并给出了三条硬性规则：

• 打包应用可以依赖包标识（package identity）与基于包（package-backed）的存储；
• 未打包应用不得假设存在包标识，必须对依赖它的 API 加保护或替换实现；
• Windows.Storage.ApplicationData.Current这类 API 在未打包运行时可能直接失败，即使构建完全成功——不要把打包专属假设混进未打包的启动路径。

这条规则在技能的其他文档中被反复印证：foundation-setup-and-project-selection.md 给出了更完整的决策矩阵：

windows-app-sdk-lifecycle-notifications-and-deployment.md 补充了底层原因：未打包应用必须考虑bootstrapper 与运行时初始化要求；除非通过部署模型刻意建立包标识，否则未打包应用默认视为无包标识。存储、设置和启动服务必须与部署模型对齐，凡是假设了打包存储或激活机制的服务，在进行本地未打包验证前都要重新设计。

在脚手架阶段就定下模型

技能要求通过dotnet new winui脚手架显式指定模型，而不是事后转换。来自 SKILL.md 的脚手架命令与支持选项如下：

dotnet new winui -o <AppName> [选项]

受支持选项（不要臆造不存在的 flag）：

如果用户要求打包行为，传--unpackaged false；否则保持模板默认值（默认即打包）。脚手架生成后，用dotnet build针对生成的.csproj验证，再按对应打包模型的正确路径启动新应用，确认存在真实顶层窗口，而不是只看启动器进程的退出码。

构建与启动指引：平台、路径与进程管理

原文档在「Build and Launch Guidance」中给出四条实操准则：

1. 显式指定平台目标。WinUI 输出对架构默认值很敏感，如果AnyCPU造成歧义，本地验证就用x64。对应命令示例（同时可见于 foundation-template-first-recovery.md）：

dotnet build MyApp.sln -c Debug -p:Platform=x64

2. 未打包验证优先启动构建出的.exe，路径形如bin\Debug\...\win-x64\或项目指定的输出路径——这也是用户在真实使用中会直接运行的那个可执行文件。

3. 验证成功后不要立刻关掉应用。启动验证成功不等于任务完成：保持窗口打开，除非它阻塞了下一步必要动作。

4. 把dotnet run抛出的 bootstrapper、部署或 COM 激活错误当作信号——它说明当前选定的启动路径或打包设置与现有应用不匹配，需要回到打包模型与启动路径的选择上去。

5. 重建前先停掉旧实例——如果旧实例锁定了输出文件（.exe 被占用导致无法覆盖），会直接导致构建失败。

结合 foundation-environment-audit-and-remediation.md 的「Required vs Optional」清单，正常 C# WinUI 3 开发的前置条件包括：受支持的 Windows 构建版本、带 WinUI C# 支持的 Visual Studio、Windows SDK 10.0.19041.0 或更高、可用于 XAML 编译的 MSBuild、.NET SDK 6 或更高；Developer Mode 与 WinGet 通常可选但常被推荐。这些前置条件不满足时，构建/启动验证无从谈起。

启动失败调试：区分环境问题与代码问题

原文档给出的核心调试原则是：先把环境问题与应用代码的启动崩溃分开。如果应用在显示窗口之前就退出，先检查启动路径：

• App.xaml
• 合并的资源字典（merged resource dictionaries）
• 转换器（converters）
• MainWindow
• 启动期间用到的服务

foundation-template-first-recovery.md 为「启动或清单类问题」提供了标准恢复回路，与本文档衔接如下：

1. 确认预期的打包模型与启动路径；
2. 当前启动形态不清晰时，用相同打包选择脚手架一个临时对比应用：

dotnet new winui -n RecoveryReference -o RecoveryReference --use-slnx false --no-solution-file false # 目标应用是未打包时追加：--unpackaged true

3. 只对启动与共享资源区域做 diff：App.xaml、App.xaml.cs、MainWindow.xaml/MainWindow.xaml.cs（或应用实际的 shell 入口点）、合并资源字典、启动相关项目属性；
4. 把可疑区域回退到模板生成形态，直到构建恢复干净；
5. 显式针对具体架构构建（如上面的-p:Platform=x64命令）；
6. 用正确的打包/未打包路径启动，确认客观启动信号；
7. 以小块为单位重新应用自定义修改，每次有意义的编辑后都构建并运行。

对于不透明的MSB3073和XamlCompiler.exe失败，原文档的处置是：先把结构简化回模板生成的启动与共享资源形态，再做更激进的结构改动。附带几条细则：

• 失败点不明确时，增量恢复复杂的启动片段——最小化的App.xaml加最小化的MainWindow是合法的隔离步骤；
• 诊断信息看起来过时或与当前文件不一致时，先做一次干净构建再深入排查；
• 长期修复优先恢复「最后一次已知良好」的模板化共享资源状态，而不是把样式内联进页面作为永久方案（后者被明确列为 Avoid）；
• 未打包启动时，务必审查持久化、通知、存储与激活代码里隐藏的包标识假设。

其他常见恢复检查项（同样来自模板优先恢复文档）：确认 WinUI 3 启动代码没有使用Window.Current（应使用显式new Window()）；确认x:Class、命名空间与 code-behind 名称仍然匹配；确认合并资源字典干净加载后再叠层；确认项目内容项与运行时期望的本地数据/资源文件一致。

退出标准：什么才算「真的完成了」

原文档以四条 Exit Criteria 收束，这也是每次交付前必须逐条核对的门槛：

1. 从预期的本地工作流构建成功——不是换一种歪门邪道的命令，而是用户实际会用的那条路径；
2. 从预期的本地工作流启动成功——启动路径与打包模型匹配；
3. 确认存在真实的顶层窗口或等价预期 UI——进程起来了不够，窗口必须真实存在；
4. 没有未解决的启动异常——不能带着悬挂的异常交付。

testing-debugging-and-review-checklists.md 把验证循环扩展到了更完整的交付面：构建通过、功能在目标机器配置上可用、应用启动并显示预期 shell 或窗口、亮/暗/高对比模式下可用、主流程可键盘访问、缩放行为/启动/交互响应性都已检查。调试工具方面，视觉迭代用Hot Reload，布局与属性排查用Live Visual Tree 与 Live Property Explorer，帧与响应性问题用WPR / WPA；当进程在窗口出现前死亡时，使用**启动异常详情、调试器输出或事件查看器（Event Viewer）**定位问题。

与脚手架工具链的衔接：从环境就绪到启动验证

本技能把「环境就绪」「打包选择」「启动验证」视为三项互相独立的检查——通过一项不能证明其他项（见 SKILL.md 的 Environment Rules）。因此在做启动验证之前，机器应当已经通过技能内置的引导流程完成准备：

winget configure -f config.yaml --accept-configuration-agreements --disable-interactivity

这条命令以技能目录下的 config.yaml 为唯一事实来源，其内容会：启用 Developer Mode（Microsoft.Windows.Settings/WindowsSettings，DeveloperMode: true）、安装 Visual Studio Community 2026（Microsoft.WinGet.DSC/WinGetPackage，id 为Microsoft.VisualStudio.Community）、并通过Microsoft.VisualStudio.DSC/VSComponents安装Microsoft.VisualStudio.Workload.ManagedDesktop、Microsoft.VisualStudio.Workload.Universal与Microsoft.VisualStudio.ComponentGroup.WindowsAppSDK.Cs三个组件，同时以断言验证操作系统不低于10.0.17763。模板可用性也要先确认：

dotnet new list winui

只有模板就绪、工具链可用，dotnet new winui脚手架出来的项目才有资格进入本文的「构建 → 运行 → 启动验证」闭环。整套流程在技能中的分工可参考 _sections.md：构建/运行/启动验证问题路由到本文档，模板级恢复路由到foundation-template-first-recovery.md，机器就绪检查路由到foundation-environment-audit-and-remediation.md。

小结

WinUI 3 应用的「完成」定义不是编译通过，而是从用户实际使用的工作流中构建成功、以匹配部署模型的路径启动、出现真实顶层窗口、无未解决启动异常。围绕这一定义，本文完整展开了必选工作流七步、打包/未打包决策与 API 边界、平台与路径选择、启动故障的模板优先恢复法以及最终退出标准，并与仓库中 SKILL.md、config.yaml 及各 CRITICAL/HIGH 级参考文档相互印证，形成一套可直接执行的开发与验证纪律。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills