用途:winui-dev-workflow 用于指导和自动化 WinUI 3 桌面应用的构建与运行流程,适合在需要创建、编译、启动和排查 WinUI 3 项目时使用。\n\n项目创建:新应用可用 dotnet new winui-mvvm -n <AppName> 生成,模板包含 CommunityToolkit.Mvvm、TitleBar、MicaBackdrop 与 Frame 导航;注意不要先手动 mkdir,-n 会自动创建目录。对已有应用,应先阅读 .csproj,了解 TargetFramework、PackageReference 版本、项目结构与既有模式。\n\n安装包:使用 dotnet add package <Name>,且不要指定 --version,以获取最新稳定版并避免过时 API 不匹配。\n\n构建与运行:推荐调用随技能提供的 BuildAndRun.ps1。该脚本会自动检查开发者模式、查找 .csproj、检测平台(x64 或 ARM64)、用 MSBuild 构建(失败时回退到 dotnet build)、定位输出目录,并以 winapp run --debug-output 启动,输出中包含运行进程 PID。脚本支持显式指定项目、-Detach 分离模式、-SkipRun 仅构建以及传入 MSBuild 参数覆盖默认配置。调用时应使用 async 模式,因为脚本会一直附着在运行中的应用上;sync 调用会阻塞整个应用生命周期。若构建失败,应读取全部错误并一次性批量修复后重跑;若启动崩溃,可读取 shell 输出以查看首次机会异常。\n\n常见错误速查:开发者模式未开启、缺少类型、需要指定平台、XAML 类型未找到、绑定路径缺失、启动后空白窗口(x:Bind 默认 OneTime,需 Mode=OneWay)、应用静默退出(应使用 winapp run 而非直接运行 exe)、XAML 编译器静默崩溃(移除 PresentationCore.dll/System.Windows 引用)、包安装失败(运行 winapp init 并核对清单发布者与证书)、坏映像格式(平台目标应为 x64 或 ARM64,而非 AnyCPU)。\n\n前置条件:Windows 10 v1903 及以上、启用开发者模式、.NET SDK 8.0 起(新装推荐 10.0)、winapp CLI 0.3 起、安装 WinUI 模板。若缺少 winapp、dotnet、模板或开发者模式未开启,不应自行安装或绕过,而应停止并提示用户运行 /winui-setup 完成安装与验证后再重试。\n\n硬性规则:不要直接运行打包后的 .exe;不要添加 <WindowsPackageType>None 来绕过启动问题;不要删除 Package.appxmanifest;不要使用 AnyCPU,始终使用 x64 或 ARM64。
winui-dev-workflow
编程与开发
更新于 11-12 06:46