使用快速内循环Fast Inner Loop在本地构建的 WinUI 上进行临时性Ad-Hoc应用测试完整工作流指南【免费下载链接】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导读当你在 WinUImicrosoft-ui-xaml仓库中修改产品代码时最理想的工作方式是改动几行 C几秒内重新编译出Microsoft.UI.Xaml.dll然后在自己的临时测试应用里立刻看到效果。本文档描述的就是这样一套快速内循环fast inner loop工作流——用 Visual Studio 创建一个临时的 ad-hoc 测试应用让它直接消费你本地构建产生的 WinUI 组件包Component Package再配合msb增量编译与 DLL 拷贝实现秒级迭代。读完本文你将掌握如何搭建针对本地构建的 nuget 源与包缓存、如何正确替换包引用Microsoft.WindowsAppSDK→Microsoft.WindowsAppSDK.WinUI、如何定位运行时实际加载的 DLL 路径、以及如何安全地更新被 nuget 缓存住的本地组件包。适用范围本文面向需要修改 WinUI 产品代码并希望快速验证行为的开发者。若你只是想构建并运行仓库自带的示例应用请参考 Building Sample Apps本文讲解的是创建你自己的临时测试应用而不是使用仓库内的测试应用。一、前置条件Prerequisites开始之前你需要满足两条硬性条件能用 Visual Studio 构建并启动 Windows App SDK WinUI 应用。安装最新版 Visual Studio并勾选Windows 应用程序开发Windows Application Development工作负载。能够构建本仓库。完整的环境准备磁盘空间约 80GB、页面文件建议 ≥64GB、.vsconfig 导入、Git 安装等详见 开发者指南。这两个条件缺一不可前者保证你能创建并运行目标应用后者保证你能产出可供消费的本地 WinUI 组件包。二、初始构建Initial Build按常规流程构建仓库即可详见 开发者指南。简而言之在仓库根目录执行init.cmd初始化构建环境、还原 NuGet 包、设置平台/配置环境变量执行build.cmd进行完整构建。如果只想构建产品代码、跳过测试代码可以运行build.cmd product——本工作流不需要测试代码跳过可以显著节省时间。关于构建环境的补充说明来自 开发者指南默认构建环境是x64 Debug内部术语为x64chk也可以通过init.cmd x86chk、init.cmd x64fre、init.cmd arm64chk等切换平台/配置chkDebugfreRelease每次git pull之后需要重新运行init.cmdbuild.cmd实际执行的是msbuild /m分别构建dxaml\Microsoft.UI.Xaml.sln与controls\MUXControls.sln产物是产品与测试二进制。构建成功后仓库会产出一个本地 WinUI 组件包local WinUI component package。build.cmd会把打包好的.nupkg放到仓库的PackageStore目录该目录的 readme 明确说明其定位是本地包源测试 nupkg 用例如本地开发构建Microsoft.WindowsAppSDK.WinUI.3.0.0-dev.nupkgCI/流水线构建形如Microsoft.WindowsAppSDK.WinUI.3.0.0-zmain.230101.1-CI.nupkg参见 building-sample-apps.md三、用 Visual Studio 创建临时测试应用启动 Visual Studio新建项目。选择Blank App, Packaged (WinUI in Desktop)模板语言可选C# 或 C。务必把项目创建在仓库之外的普通目录例如C:\Users\alias\source\repos\App17不要放进 WinUI 仓库。模板默认引用最新公开发布的 WinAppSDK 版本。先做一次验证构建确认这个应用能正常编译并启动再继续后续步骤。开启本机代码调试Enable Native Debugging在 Visual Studio 中确保你处于本机native代码调试模式对C 应用默认就是本机调试无需额外配置。对C# 应用需要手动修改项目设置——选择Debug → [应用名] Debug Settings → Enable Native Code Debugging。这一步在后面迭代调试时至关重要因为我们要在混合模式下打断点、看模块与符号。四、指向本地 WinUI 组件包4.1 添加 nuget.config关闭应用和 Visual Studio。在测试项目的根目录即.sln所在目录新建nuget.config写入以下内容configuration config clear / add keyglobalPackagesFolder value$\..\packages / add keyrepositoryPath value$\..\packages / /config packageSources add keypackagestore valuerepo-root\PackageStore / /packageSources /configuration其中repo-root\PackageStore要替换为你本地 WinUI 仓库中PackageStore目录的实际路径。这份配置做了两件事新增本地包源把 WinUI 仓库里的PackageStore目录加入 nuget 的包搜索列表使 Visual Studio 项目能够看到并使用这个本地构建产物。重定向全局包缓存让 nuget 把所有依赖包缓存到本项目目录下的packages子目录而不是机器级的全局缓存如C:\Users\alias\.nuget\packages。这一点很关键本地 WinUI 组件包不该进入全局缓存否则会引发版本污染问题。代价是项目所有依赖包都会重复缓存一份在本地略显冗余但这是值得的权衡。注意上面的nuget.config并没有clear掉默认的包源nuget.org 必须保持可达。只有 WinUI 组件包来自本地PackageStore它自身的依赖Microsoft.WindowsAppSDK.Base、.Foundation、.InteractiveExperiences以及Microsoft.Web.WebView2仍然从 nuget.org 还原。4.2 把项目目标平台改为与本地构建一致例如 x64重新打开.sln把测试应用的构建平台从默认的 x86 改为x64。原因init.cmd默认构建 x64而本地 WinUI 组件包只支持单一目标平台——这与真实 WinAppSDK 包同时支持 x86、x64、arm64不同。应用的目标平台必须与本地构建 WinUI 的平台严格一致否则无法正确加载。4.3 替换包引用Package References在 Visual Studio 中通过Tools → NuGet Package Manager → Manage NuGet Packages for Solution管理包引用务必勾选Include prerelease包含预发行版复选框否则本地组件包不会出现在列表里。关键点本地构建产出的是名为Microsoft.WindowsAppSDK.WinUI的组件包component package它和模板默认引用的Microsoft.WindowsAppSDK元包meta-package是不同的包 ID。因此这不是一次简单的版本升级你必须移除Microsoft.WindowsAppSDK引用添加Microsoft.WindowsAppSDK.WinUI引用。也可以直接编辑.csproj。把模板生成的PackageReference IncludeMicrosoft.WindowsAppSDK Versiontemplate-version /替换为本地构建产出的版本本文示例统一使用3.0.0-devPackageReference IncludeMicrosoft.WindowsAppSDK.WinUI Version3.0.0-dev /绝对不要同时引用两个包。如果两个都引用restore依然会成功但构建会失败并报错Microsoft.WindowsAppSDK.ComponentReference.targets(123,9): error : One or more referenced Windows App SDK components are newer than the versions expected by the Microsoft.WindowsAppSDK.Runtime package: Microsoft.WindowsAppSDK.WinUI: Microsoft.WindowsAppSDK.Runtime expected version version, but version 3.0.0-dev was referenced..该报错给出的两个修复建议在这里都不适用本地包的版本是固定的改不了而设置WindowsAppSDKSelfContained只是掩盖了症状、并未修正包图package graph。正确做法就是移除元包引用。完成替换后重新构建并按F5启动。此时你的测试应用已经运行在本地构建的 WinUI之上了可以在测试应用里编写、验证你的场景了。五、内循环Inner Loop秒级迭代工作流前文搭好了一次性的指向接下来是日常高频迭代的核心循环。5.1 找到你的应用实际加载的 Microsoft.UI.Xaml.dll 路径按F5启动并调试应用。打开模块窗口Debug → Windows → Modules。找到Microsoft.UI.Xaml右键 →Copy Value → Copy Path记下 DLL 完整路径。形如C:\Users\alias\source\repos\App17\App17\bin\x64\Debug\net8.0-windows10.0.19041.0\win-x64\AppX\Microsoft.ui.xaml.dll两个值得注意的点本地 WinUI 组件包默认是 Self-Contained自包含而真实包默认是 Framework-Dependent框架依赖。自包含对调试更友好因为 DLL 就在应用的 AppX 输出目录里方便直接替换。如果你在迭代的是Microsoft.UI.Xaml.Controls.dll则记下该 DLL 的路径方法相同。同时请验证 Visual Studio 是否已为这个 DLL 加载符号PDB。正确的 PDB 路径形如repo-root\BuildOutput\obj\amd64chk\dxaml\xcp\dxaml\dllsrv\winrt\native\Microsoft.ui.xaml.pdb如果符号没有加载、或加载自其他位置说明哪里出了问题例如平台/配置不匹配需要先排查。5.2 在 WinUI 仓库中构建你的改动在仓库中做出代码修改。开始构建前务必先在 Visual Studio 中停止调试你的应用否则 DLL 被占用拷贝会失败。然后按改动对象选择最快的重建命令改动的是Microsoft.UI.Xaml.dll最快方式msb dxaml\xcp\dxaml\dllsrv\winrt\native\Microsoft.ui.xaml.vcxproj改动的是Microsoft.UI.Xaml.Controls.dll使用msb controls\dev\dll\Microsoft.UI.Xaml.Controls.vcxproj关于msb别名源码见 tools/msb.cmd它是仓库提供的 msbuild 便捷包装行为等价于多进程 生成 .binlog地构建当前目录的项目及其依赖并会设置SkipSigningtrue跳过签名从而加速本地迭代同类别名还有bz只构建当前项目、不构建依赖可能失败和msb /t:Rebuild。这两条命令只重建对应 DLL。因为是增量编译只重编改动的.cpp/.h通常只需几秒钟但如果你改动了一个公共头文件common header可能触发更大范围的重新编译。这套流程最适合纯代码改动。如果你在改 API 面例如更新 IDL 接口就需要更完整的构建例如在仓库根目录重跑build.cmd详见下文更广泛的改动。记录新构建出的 DLL 路径形如repo-root\BuildOutput\bin\amd64chk\Product\Microsoft.ui.xaml.dll5.3 把新 DLL 拷贝进你的应用用新构建的 DLL 替换应用构建输出目录中的旧 DLL。示例Windows CMDcopy /y repo-root\BuildOutput\bin\amd64chk\Product\Microsoft.ui.xaml.dll C:\Users\alias\source\repos\App17\App17\bin\x64\Debug\net8.0-windows10.0.19041.0\win-x64\AppX\Microsoft.ui.xaml.dll注意我们这里并不是重新打包本地 WinUI 组件包只是替换应用里的 DLL。因此如果你对应用做了一次 clean 构建这个更新过的 DLL 会丢失需要再拷贝一次。5.4 重新启动并调试应用再次在 Visual Studio 中按F5启动应用验证它加载了更新后的 DLL并确认 Visual Studio仍然在为更新后的 DLL 加载符号观察模块窗口或断点命中情况。5.5 迭代此后你可以在测试应用与产品代码之间持续往返改产品代码 →msb增量编译 →copy替换 DLL → F5 调试 → 验证效果。这个循环覆盖了日常开发中最常见的 90% 场景。六、更广泛的改动Broader Changes当改动超出替换单个 DLL 就能生效的范畴例如修改 API 面、跨模块依赖变更、更新 XAML 资源等你需要退回到完整构建在仓库根目录运行build.cmd——它会构建全部内容并重新创建本地 WinUI 组件包。如果你只想手工构建必要部件、但仍要更新本地组件包可以使用pack.component.cmd重新打包。6.1 更新本地 WinUI 组件包后的关键一步清理包缓存你可能以为重跑build.cmd生成了新组件包回到 Visual Studio 按 F5 应用就能自动拾取新版本。这不会生效。原因是 nuget 假定同一版本的包是不可变的immutable——而本地包版本是固定的3.0.0-dev不会随每次构建而递增。nuget 会把包内容缓存在包缓存目录中构建实际使用的是缓存里的文件。因此每次重新打包本地组件包后都需要从缓存中删除它强制 Visual Studio 拾取新版本找到前文nuget.config中配置的本地包缓存目录即$\..\packages指向的目录。在资源管理器中删除其中的microsoft.windowsappsdk.winui\version文件夹。注意事项文件夹名对应的是你引用的组件包Microsoft.WindowsAppSDK.WinUI而不是Microsoft.WindowsAppSDK元包version是你本地构建产出的版本号——也就是PackageReference里写的那个版本可以在repo-root\PackageStore目录的.nupkg文件名中确认例如Microsoft.WindowsAppSDK.WinUI.3.0.0-dev.nupkg对应版本3.0.0-dev只删除该子文件夹即可其他已缓存的包版本不受影响。删除后重新构建Visual Studio 会从本地仓库的PackageStore再次解包新组件包到本地缓存你就可以继续基于最新构建进行测试了。6.2 关于 pack.component.cmd 的补充pack.component.cmd源码见 pack.component.cmd是只打包、不构建的入口它调用build-nupkg.ps1把BuildOutput\packaging\Configuration目录中已构建好的架构产物打成Microsoft.WindowsAppSDK.WinUI组件包并安装进PackageStore目录。其用法要点要求先通过init.cmd设置好BuildPlatform与Configuration环境变量否则命令会提示用法并退出默认打包版本为3.0.0-dev可用/version ver覆盖例如/version 3.0.0-zmain.230101.1-CI。从源码结构看pack.component.cmd在存在.azuredevops目录CI 环境与本地环境时使用不同的依赖覆盖参数-UseDependencyOverrides但产物与流程一致。七、工作流速查与常见陷阱阶段关键动作常见陷阱初始构建init.cmd→build.cmd或build.cmd product构建环境默认 x64 Debuggit pull后需重跑init.cmd创建应用Blank App, Packaged (WinUI in Desktop)建在仓库外C# 项目记得开启 Native Code Debugging指向本地包写nuget.config本地源 本地缓存nuget.org 仍须可达依赖包从官方源还原平台匹配测试应用改为 x64本地组件包仅支持单一平台必须与init.cmd一致包引用删Microsoft.WindowsAppSDK加Microsoft.WindowsAppSDK.WinUI3.0.0-dev同时引用两个包会导致ComponentReference.targets报错内循环msb增量编译 →copy替换 DLL → F5构建前先停止调试clean 构建会丢替换的 DLL重打包build.cmd或pack.component.cmd必须删除本地缓存中的microsoft.windowsappsdk.winui\version才生效这套工作流把改产品代码 → 验证效果的周期压缩到几秒钟级别是 WinUI 仓库本地开发中性价比最高的迭代方式而当你需要确认某次改动对整个仓库、对所有依赖模块的影响时再回到build.cmd全量构建两者互为补充。【免费下载链接】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），仅供参考
