winui 3项目必须使用visual studio 2022 17.0+创建，需启用uwp和c++桌面开发工作负载，模板选“blank app, packaged (winui 3 in desktop)”，依赖microsoft.windowsappsdk运行时与正确配置package.appxmanifest。
WinUI 3项目必须用 Visual Studio 2022 创建
Visual Studio 2019 不支持 WinUI 3 桌面模板（WinUI 3 in Desktop），哪怕装了最新 SDK 也会缺模板。VS 2022 17.0+ 是硬性门槛，且需启用 Universal Windows Platform development 和 Desktop development with C++ 两个工作负载——后者常被忽略，但 WinUI 3 桌面应用依赖 C++/WinRT 运行时，没它会编译失败或 WindowsAppSDK 初始化报错。
创建时选模板要认准：Blank App, Packaged (WinUI 3 in Desktop)。别选 Blank App (WinUI 3 in UWP)，那是沙盒环境，不能访问文件系统、注册表或调用大多数桌面 API。
项目结构里关键的三个文件夹和一个 NuGet 包
新建后你会看到 App.xaml、MainWindow.xaml、Package.appxmanifest 和 Microsoft.WindowsAppSDK NuGet 引用。前两者是 UI 入口，后者是运行时核心——版本必须与项目目标匹配：
-
Microsoft.WindowsAppSDK版本不能手动降级，否则Windows.System.Launcher等 API 会提示“找不到类型” -
Package.appxmanifest里的TargetDeviceFamily Name="Desktop"必须存在，删掉会导致打包失败或安装后闪退 -
winui3\Microsoft.UI.Xaml的资源字典默认在App.xaml中合并，若手动删了MergedDictionaries，控件样式会回退成 Win32 默认灰框
调试阶段常见启动失败原因
按 F5 启动黑屏或直接退出，多数不是代码问题，而是环境或配置卡点：
- Windows 版本低于 18362（1903）会报错
0x80073D54，因为 WinUI 3 依赖 OS 层的AppModel改进 - 没安装
Windows App SDK Runtime（非 SDK），即使开发机有 VS 也不代表已部署运行时；需单独下载Microsoft.WindowsAppRuntime.1.5.x-x64.appinstaller安装 -
MainWindow.xaml.cs中误调用Window.Activate()在OnLaunched外触发，会导致窗口未初始化就激活，抛出System.Runtime.InteropServices.COMException: 0x802A0001
首次写逻辑时绕不开的线程和生命周期
WinUI 3 的 UI 线程模型和 WPF/WinForms 不同：所有 UI 操作必须在主线程（DispatcherQueue），但 DispatcherQueue.TryEnqueue 不再是唯一方式，推荐用 DispatcherQueue.GetForCurrentThread() 获取实例后调用 EnqueueAsync：
await DispatcherQueue.GetForCurrentThread().EnqueueAsync(() =>
{
myButton.Content = "Done";
});
另外，OnLaunched 里不要假设窗口一定存在——多实例模式下可能复用已有窗口，args.PreviousExecutionState == ApplicationExecutionState.Terminated 才适合恢复状态；而 Suspending 事件里不能做耗时 IO，否则系统会强制终止进程。
真正麻烦的是调试时热重载不生效，或者 XAML 更改后没反应——这通常是因为项目属性中 Enable XAML Hot Reload 没勾选，或者你正在用 Release 配置运行。这些细节不报错，但会让开发节奏卡住很久。
