WinUI (microsoft-ui-xaml) 本地开发包实战：用 C++ 示例应用测试 WinUI 3 修改

WinUI (microsoft-ui-xaml) 本地开发包实战用 C 示例应用测试 WinUI 3 修改【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xaml本文基于 microsoft-ui-xaml 仓库的官方文档 Testing WinUI 3 Changes with Sample C App (Dev Package) 整理并扩充。它讲解的是一套完整的本地验证工作流在仓库中修改 WinUI 源码后如何通过 Visual Studio 创建一个 C 打包 WinUI 应用将其从公共 NuGet 包切换到本地构建产出的开发包Dev Package从而在自己的改动上直接运行与调试。读完本文你将掌握本地开发包的产出位置与版本规则、NuGet 包源切换的四步操作、.vcxproj中必须清理和添加的项以及该工作流背后的源码级依据。1. 工作流总览为什么需要“开发包 示例 C 应用”在 WinUI 仓库中提交修改之前开发者需要确认改动在真实应用中表现正确。直接跑仓库内置测试覆盖的是自动化场景而对于 UI 行为、样式、交互类的修改更直观的方式是“造一个最小的 C WinUI 应用让它加载你本地构建的 WinUI然后手动验证”。这条链路的关键部件是本地开发包Dev Package仓库根目录的 PackageStore/readme.md 明确了该目录的定位“Local source for packages. Places nupkg files in this directory to test them out before uploading.”本地包源用于在上传前测试 nupkg 文件本地构建build.cmd完成后会产出一个名为Microsoft.WindowsAppSDK.WinUI的 WinUI 组件包放入PackageStore。打包入口是仓库根目录的 pack.component.cmd其帮助文本写明“Builds the Microsoft.WindowsAppSDK.WinUI component nuget package into the PackageStore directory”且默认版本为固定的3.0.0-dev可通过/version参数覆盖从组件包的元数据 build/nuspecs/Microsoft.WindowsAppSDK.WinUI.nuspec 可以看到它依赖Microsoft.Web.WebView2、Microsoft.WindowsAppSDK.Base、Microsoft.WindowsAppSDK.Foundation、Microsoft.WindowsAppSDK.InteractiveExperiences等包——这意味着你的 C 应用仍会从公共源拉取这些依赖只有 WinUI 部分来自本地构建。原始文档给出的完整流程共 9 步下表先做总览随后逐节展开步骤内容关键产物/对象1构建 WinUI 仓库本地开发包PackageStore目录2安装 Visual Studio 模板组件WinUI C 应用开发工具3创建示例 C 项目WinUI Blank App (Packaged)4添加本地包源LocalWinAppSDK→PackageStore路径5更新主包版本Microsoft.WindowsAppSDK指向本地开发版6移除公共包条目删除packages.config中的公共版本条目7清理.vcxproj引用移除公共版本引用加WindowsAppSDKSelfContained8删除过期包目录packages目录下的公共版本文件夹9Clean Rebuild应用加载本地构建的 WinUI2. 前置条件构建 WinUI 仓库第一步要求你先能构建 WinUI 仓库本身。官方文档指向 开发者指南其核心要求如下均摘自该指南适用前提为 Windows 最新 Visual Studio磁盘与内存单次构建约消耗 80GB 磁盘为避免 PCH 构建时内存耗尽建议将系统盘页面文件固定设置为至少 64GB核心数超过 24 时可能需要更大Visual Studio 组件通过仓库根目录的.vsconfig文件导入安装配置确保组件齐全。注意机器上不应安装独立的 “Visual Studio Build Tools”否则会干扰构建初始化与构建命令在仓库根目录的 CMD 中运行init.cmd或 PowerShell 中运行init.ps1它会恢复 NuGet 包并设置平台/配置环境变量默认组合为x64Debug常用组合包括平台配置init 命令x86Debuginit.cmd x86chkx86Releaseinit.cmd x86frex64Debuginit.cmd默认/init.cmd x64chkx64Releaseinit.cmd x64frearm64Debuginit.cmd arm64chkarm64Releaseinit.cmd arm64fre随后在根目录运行build.cmd执行全量构建对dxaml\Microsoft.UI.Xaml.sln与controls\MUXControls.sln做msbuild /m。两点与本工作流直接相关每次git pull之后必须重新运行init.cmd构建成功后本地 WinUI 组件包会出现在PackageStore目录中其文件名中的版本如3.0.0-dev就是后续示例应用要引用的版本号。构建排错可参考 常见错误 FAQ进阶构建选项见 building-advanced.md。3. 安装 Visual Studio 模板组件创建一个 C WinUI 示例项目需要对应的模板与工具链。原文档要求在 Visual Studio Installer 中勾选Workload工作负载WinUI application developmentIndividual Components单个组件C WinUI app development tools仓库自身的.vsconfig构建 WinUI 用与此处的模板组件是两套东西两者都要装前者保证build.cmd能跑通后者保证你能新建 WinUI C 工程。4. 创建示例 C 项目原文档给出的操作路径打开 Visual StudioNew Project → 搜索WinUI Windows C选择WinUI Blank App (Packaged)。新建的项目默认引用的是公共版本最新 stable/prerelease的Microsoft.WindowsAppSDKNuGet 包此时应用运行的是官方发布版 WinUI——这正是要替换的部分。建议先完整编译并运行一次该空白应用确认模板与本机环境没有问题再进行后续改造。5. 添加本地包源Package Source这是整个工作流的“开关”让 NuGet 能找到PackageStore里的本地开发包。右键项目 →Manage NuGet PackagesNuGet 包管理器点击齿轮Package Sources图标点击新增源NameLocalWinAppSDKSource你本地 WinUI 仓库的PackageStore目录完整路径点击OK保存。从源码角度印证这个设计PackageStore在仓库中就是作为本地 NuGet 源使用的tools/clean.cmd 的清理逻辑会直接对该目录执行git clean说明它只存放构建产物、不提交到版本库仓库中另一条等价工作流ad-hoc 快速内环测试也是通过nuget.config的packageSources把packagestore指向repo-root\PackageStore实现的。两种方式本质相同本文档采用的是 Visual Studio UI 方式更直观。6. 将主包切换到本地开发版本在包源下拉框中选择LocalWinAppSDK进入Installed选项卡找到Microsoft.WindowsAppSDK选择本地构建产生的 WinUI 版本。关于版本号仓库源码给出了确切答案pack.component.cmd 中默认-VersionOverride 3.0.0-dev即本地开发包版本固定为3.0.0-dev除非构建时用/version覆盖。因此“选择最新 WinUI 版本”实际指的就是这个3.0.0-dev开发版。还有一个必须注意的平台匹配问题从源码结构看本地 WinUI 组件包只包含你构建时那一种目标平台的二进制例如默认x64 Debug不像公共 WinAppSDK 包覆盖 x86/x64/arm64 全部平台。因此示例应用的目标平台必须与本地构建的平台一致默认把应用改为 x64 构建。这一点在 ad-hoc 内环文档 中也有明确说明“the local WinUI component package only supports a single target platform unlike the real WinAppSDK package”。7. 移除公共版本包条目packages.config切换包源后项目中仍残留公共版本的引用。原文档提供了两种做法直接通过 Installed 选项卡卸载/替换更快的方式编辑packages.config删除所有带公共版本例如1.8.x的Microsoft.WindowsAppSDK.*条目。这些Microsoft.WindowsAppSDK.*条目对应的是公共包展开后的子包Base、Foundation、InteractiveExperiences 等。之所以要彻底移除而不是共存是因为公共版本与本地3.0.0-dev组件的运行时版本约束无法同时满足构建期会因组件版本与Microsoft.WindowsAppSDK.Runtime预期不一致而失败。仓库中类似的版本冲突报错样例见 ad-hoc 文档“One or more referenced Windows App SDK components are newer than the versions expected by the Microsoft.WindowsAppSDK.Runtime package”——其解法同样是移除冲突引用而不是给版本属性打补丁。8. 清理 .vcxproj 并开启 Self-Contained这是最容易遗漏的一步原文档操作在解决方案资源管理器中Unload卸载项目直接编辑.vcxproj文件删除其中所有指向公共版本的Microsoft.WindowsAppSDK相关引用片段在PropertyGroup LabelGlobals下添加WindowsAppSDKSelfContainedtrue/WindowsAppSDKSelfContainedReload重新加载项目。WindowsAppSDKSelfContained的作用是让应用以自包含方式携带所需运行时位不依赖机器上安装的系统级 WinAppSDK 运行时——在测试本地开发包时这能保证加载的就是你本地构建的 DLL。仓库内大量示例工程也是这么配置的例如 Samples/ChartApp/ChartAppCsUnpackaged/ChartAppCsUnpackaged.csproj 中即有WindowsAppSDKSelfContainedtrue/WindowsAppSDKSelfContained部分项目则对ARM64EC平台条件性地开启如 Samples/TableViewApp/TableViewAppCsUnpackaged/TableViewAppCsUnpackaged.csproj。本地开发包本身默认就是 Self-Contained 语义ad-hoc 文档指出“local WinUI component package defaults to Self-Contained unlike the real package which defaults to Framework-Dependent”示例工程侧同步开启可以保持一致也便于调试。9. 删除过期的本地包目录在项目的packages文件夹中删除所有公共版本的Microsoft.WindowsAppSDK.*子目录。这一步的必要性源于 NuGet 的缓存模型NuGet 假定同一版本号的内容不可变immutablerestore 时若本地缓存里已存在该版本目录就直接复用。公共版本的残留目录一旦留在packages下就可能让构建继续解析到旧的公共位。清理后再构建NuGet 才会重新从LocalWinAppSDK源解包本地开发版本。10. Clean Rebuild 验证最后执行 Build →Clean Solution然后Rebuild。验证成功与否有两个可检查的信号构建层面Rebuild 成功且packages目录中解包出来的是3.0.0-dev的本地包内容运行层面按 F5 启动应用后打开调试模块窗口Debug → Windows → Modules找到Microsoft.UI.Xaml确认其路径来自你应用输出目录中由本地包展开的位ad-hoc 文档 进一步建议核对Microsoft.ui.xaml.pdb符号路径应类似repo-root\BuildOutput\obj\amd64chk\dxaml\xcp\dxaml\dllsrv\winrt\native\Microsoft.ui.xaml.pdb即符号确实来自你的本地构建而不是公共发布版本。若符号路径不对说明应用仍在加载公共包位需要回头检查第 79 步是否清理干净。11. 后续迭代与相关文档完成上述配置后你的 C 应用就运行在本地 WinUI 之上可以开始验证自己的修改。需要注意迭代节奏如果修改涉及更广泛的改动如 API 面变化仅增量重建单个 DLL 不够需要重跑build.cmd重新产出本地组件包重新打包后还需删除本地包缓存中对应版本目录以强制 NuGet 重新解包NuGet 视固定版本号为不可变。快速内环的具体技巧单 DLL 增量重建、DLL 直接替换等可参考 ad-hoc-testing-of-local-build-with-fast-inner-loop.md。与本主题相关的其他文档开发者指南仓库构建的完整前提本文第 2 步的依据Sample Apps 构建文档仓库内置示例应用WinUIGallery、WinUICppDesktopSampleApp 等如何对接本地构建或公共 WinAppSDK 包测试系统总览 与 Testing FAQ自动化测试体系与本手工验证工作流互补调试指南加载符号、定位崩溃问题的通用方法。适用前提与限制本工作流面向 Windows Visual Studio 环境本地开发包版本固定为3.0.0-dev且只包含单一目标平台的二进制示例应用平台必须与init.cmd设置的构建平台一致公共依赖Base/Foundation/InteractiveExperiences/WebView2仍从公共源还原因此构建机需要能访问 nuget.org。【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xaml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考