企业官网建设流程全解析

WinUI 构建失败排查指南：在 microsoft-ui-xaml 中捕获与分析 MSBuild binlog 文件

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

本文基于 docs/external/debugging_buildfailures.md 整理，讲解 WinUI 3 构建与打包（packaging）失败时的标准取证手段：如何分别通过 Visual Studio 与 MSBuild 命令行捕获 binlog 二进制日志，以及在基于 WinUI 源码排查构建失败时如何用devcmd.cmd初始化正确的开发环境。读完本文，你可以独立完成“复现失败 → 收集 binlog → 附带日志提交问题”的完整流程。

binlog 是 MSBuild 生成的二进制构建日志，完整记录了构建过程中每个目标的调度、参数、输入输出与错误信息。相比控制台文本日志，binlog 可以用日志查看器打开、检索和筛选，因此官方文档明确指出：捕获并提供 binlog 文件是调试构建与打包问题的有效方式，并且一般更推荐通过 MSBuild 的 CLI 收集 binlog，因为这样更容易诊断（两种方法都可以接受）。

方法一：通过 Visual Studio 收集 binlog

在 VS 中收集 binlog 需要借助VS Project System Tools扩展（VS 2019 与 VS 2022 各有对应版本），并调整项目构建日志的文件详细程度。完整步骤如下：

1. 安装VS Project System Tools扩展（VS 2019 与 VS 2022 分别有对应版本）。

2. 将Build Log File的详细程度设置为Diagnostics。入口在Tools -> Options -> Projects and Solutions -> MSBuild project build log file verbosity：

3. 打开日志窗口：View -> Other Windows -> Build Logging：

4. 按下 Build Logging 窗口中的播放（play）按钮开始记录：

5. 执行导致错误的操作（例如构建你的项目）。失败的步骤会显示为 "Failed"，对应的文件扩展名为.binlog，将这些文件分享出去即可帮助定位构建与打包问题。

从源码结构看，WinUI 仓库的初始化脚本 scripts/dev/OneTimeSetup.ps1 中的Install-LogViewer函数会安装 MSBuildStructuredLog 查看器，并将.binlog文件扩展名与该查看器关联——也就是说，仓库的官方环境初始化流程本身就预设了“拿到 binlog 后用专用查看器打开”这一排查链路。

方法二：通过命令行收集 binlog

在Visual Studio 开发人员命令行（Developer Command Prompt）中运行 MSBuild 时，追加-bl开关即可生成 binlog。注意：这些命令应当在 VS 命令行环境中使用，以便msbuild命令及 MSVC 工具链环境变量可用。

文档给出的两个典型命令如下：

• 以 x86 Release 构建解决方案并收集 binlog：

  msbuild /p:Platform=x86 /p:Configuration=Release /bl

• 如果遇到**创建应用包（app package）**的问题，可以用下面这条命令模拟打包流程并收集 binlog：

  msbuild /p:AppxBundlePlatforms=x86 /p:Platform=x86 /p:Configuration=Release /p:BuildAppxUploadPackageForUap=true /bl

其中AppxBundlePlatforms指定 Appx 打包目标平台，BuildAppxUploadPackageForUap触发 UAP 上传包的打包目标——第二条命令的价值在于：即使没有实际走到打包 UI，也能在命令行复现并记录打包阶段（packaging）的完整构建轨迹。

排查 WinUI 源码构建失败：先运行 devcmd.cmd

原文档强调：如果在基于 WinUI 源码（source code）的场景下调查构建失败，请先在仓库根目录运行devcmd.cmd。

查看根目录的 DevCmd.cmd，可以确认它做的事情：

• 通过vswhere定位 MSBuild 安装位置，要求VS 2019（16.x）或更高版本（见 DevCmd.cmd 中set VsVersion=16.0）。查找顺序是：先找 BuildTools 产品（Microsoft.VisualStudio.Product.BuildTools），找不到再找包含Microsoft.Component.MSBuild组件的完整 VS 安装（DevCmd.cmd）；
• 如果仓库根目录存在.buildtools目录（通常意味着 CI 流水线在该次运行中安装了 VS Build Tools），则优先使用该目录中的 MSBuild（DevCmd.cmd）；
• 最终调用<MSBuildInstallPath>\Common7\Tools\VsDevCmd.bat /no_logo完成开发环境初始化，并重新导出VCToolsInstallDir、VCToolsRedistDir、ExtensionSdkDir等变量（DevCmd.cmd）。

此外，devcmd.cmd支持两个参数：

• /Prerelease：让vswhere搜索预发布版本的 VS 安装（对应PrereleaseArg=-prerelease，DevCmd.cmd）；
• /PreserveContext：跳过最后的cmd /k新会话启动，保留当前窗口上下文（DevCmd.cmd），主要用于自动化场景。

如果你的机器还没有安装 MSBuild，仓库提供了 OneTimeSetup.cmd，它转发到 scripts/dev/OneTimeSetup.ps1：-Install MSBuild会安装 Visual Studio Build Tools 并加载 MSBuildTools 工作负载（scripts/dev/OneTimeSetup.ps1），-Install LogViewer则安装 binlog 查看器（上一节提到）。

补充：Build.cmd 本身就会产出 binlog

如果你在本地用仓库自带的构建脚本 Build.cmd 构建 WinUI 源码，其实每次构建都已自动开启 binlog 记录。在 Build.cmd 的:buildSolution子例程中：

set _binlog=%RepoRoot%\BuildOutput\%_title%.%_BuildArch%%_BuildType%.binlog set _options=/bl:!_binlog! !_verbosity! ...

即每个解决方案构建都会把/bl指向BuildOutput\<解决方案名>.<架构><构建类型>.binlog（例如BuildOutput\MUXControls.x64chk.binlog）。当构建失败时，脚本会直接打印日志文件位置（Build.cmd）：

--- ERROR: buildSolution for !_solution! FAILED. Binlog is here: !_binlog!

配合 Build.cmd 的用法说明，排查构建失败时常用的选项包括：

因此，本地Build.cmd构建失败时，最快的取证路径是：查看错误输出中给出的BuildOutput\*.binlog路径 → 用日志查看器打开 → 将 binlog 与复现步骤（目标、选项、flavor）一并附在问题报告中。

小结：提交构建/打包问题时的 binlog 清单

1. 复现失败的具体操作（构建目标、平台、配置，或打包命令）；
2. 按方法一（VS + Build Logging 窗口）或方法二（VS 命令行 +/bl）生成的.binlog文件；
3. 若是 WinUI 源码构建失败，说明已先运行devcmd.cmd初始化环境，并可提供Build.cmd报错时打印的BuildOutput\*.binlog；
4. 若是打包（app package）问题，附上带BuildAppxUploadPackageForUap=true参数收集的 binlog。

按上述流程收集的 binlog 完整保留了 MSBuild 的调度与错误上下文，是 WinUI 社区定位构建与打包问题最可靠的证据形式。

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