Pitfalls
These are the traps that repeatedly break Windows App SDK and WinUI 3 work.
Deployment Confusion
| Pitfall | Symptom | Fix |
|---|---|---|
| Mixing packaged and unpackaged guidance | App builds in one mode but notifications, settings, startup tasks, or Store packaging fail | Choose deployment model before writing feature code |
| Assuming all WinUI apps are Store-ready | Debug app launches but no Store artifact exists | Produce MSIX and run Store/WACK checks |
| Treating self-contained as magic | Output still needs additional runtime/service packages for some APIs | Read self-contained docs and test target-machine launch |
| Forgetting bootstrapper in unpackaged/external-location apps | Runtime APIs fail at startup | Initialize runtime before Windows App SDK APIs |
Stale UWP APIs
| Wrong pattern | Use instead |
|---|---|
Windows.UI.Xaml.* | Microsoft.UI.Xaml.* |
Window.Current | Track MainWindow or window instances explicitly |
CoreDispatcher.RunAsync | DispatcherQueue.TryEnqueue |
ApplicationView or CoreWindow | Microsoft.UI.Windowing.AppWindow plus HWND interop |
MessageDialog | ContentDialog with XamlRoot set |
UWP IBackgroundTask | Windows App SDK app lifecycle/activation or another desktop background model |
| UWP XAML Islands guidance | Treat as separate legacy modernization path, not WinUI 3 guidance |
Store And Signing Misunderstandings
- Store MSIX submissions are re-signed by Microsoft after certification, but Store MSI/EXE submissions require publisher signing.
- Non-Store MSIX and direct downloads require a trusted signing path or users hit trust and SmartScreen friction.
- Self-signed certificates are for local testing or managed enterprise trust, not broad public distribution.
- A privacy policy is required when the app collects or transmits personal information.
- Restricted capabilities need justification and may need certification notes.
WebView2 Runtime Gaps
- The WebView2 SDK/control is not the same thing as the WebView2 Runtime on user machines.
- Evergreen runtime is the default recommendation for security and updates.
- Fixed runtime is an explicit compatibility/offline decision and needs an update plan.
- Host object/script injection is a trust boundary, not a shortcut for arbitrary app access.
Testing Mistakes
- XAML code cannot be treated like pure .NET code. Use a WinUI Unit Test App for XAML runtime tests.
- Non-XAML logic should move into a library so it can use normal test projects.
- Appium and Accessibility Insights need stable automation IDs and a real UI Automation tree.
- Playwright only covers web content inside WebView2, not the native WinUI shell.
Linux/Mac Workspace Trap
This pack can be written and reviewed on Linux, but real validation needs Windows. Do not convert a docs-only pass into a release claim.
Gotcha: Most AI-generated WinUI mistakes come from stale UWP training data. Reject UWP namespaces and lifecycle/windowing patterns before debugging runtime errors.