Windows App SDK and WinUI 3
Use this stack when the product is Windows-first and native Windows integration matters more than cross-platform reach.
Good fits:
- Windows desktop apps that need native UI, system integration, notifications, windowing, file associations, startup tasks, or Store distribution.
- Public Windows apps where MSIX plus Microsoft Store is acceptable. The lab owner already has a Store account, so account setup is not the blocker.
- Existing WPF, WinForms, or Win32 apps that need incremental access to modern Windows APIs without a rewrite.
- Apps that need a small amount of embedded web UI through WebView2 while keeping native shell, packaging, and deployment.
Weak fits:
- Web-first SaaS, admin tools, or content surfaces that can ship faster as Astro, Next.js, or a PWA.
- Products that must launch on macOS, Linux, iOS, and Android with one UI codebase.
- Teams that cannot test on a Windows dev machine with Visual Studio, MSIX tooling, and the Windows App Certification Kit.
- Apps that only need a tray utility or simple scriptable tool and do not benefit from WinUI, MSIX, or Store distribution.
Stack Shape
| Layer | Default | Why |
|---|---|---|
| Platform | Windows App SDK stable channel | Modern Windows APIs through NuGet and runtime packages, independent of OS feature cadence |
| UI | WinUI 3 | Microsoft’s recommended native UI framework for new Windows desktop apps |
| Language | C# first, C++ when needed | C# is fastest for solo app work; C++ is for native interop or performance-sensitive existing codebases |
| Project model | Packaged WinUI 3 app | Package identity unlocks Windows features and keeps Store/MSIX paths open |
| Packaging | MSIX | Clean install, uninstall, updates, package identity, and Store alignment |
| Distribution | Microsoft Store MSIX by default | Store signs and hosts MSIX packages and handles updates after certification |
| Runtime | Framework-dependent for Store/MSIX, self-contained for direct/xcopy edge cases | Store can install runtime dependencies; direct download needs explicit runtime planning |
| Web content | WebView2 only when needed | Useful for embedded web workflows, but it adds runtime, security, and testing concerns |
| Quality | Build, launch, tests, MSIX, WACK, signing path, runtime check | Windows desktop bugs hide in packaging, activation, runtime, identity, and UI automation |
Minimum Done Criteria
Do not call a Windows App SDK feature done until these are true:
| Area | Proof |
|---|---|
| Build | Debug and release builds complete on a Windows dev machine |
| Launch | App launches from Visual Studio or dotnet run and from the packaged artifact path |
| Tests | Non-XAML tests run; WinUI/XAML tests use a WinUI Unit Test App or documented manual smoke path |
| Packaging | MSIX package or explicit unpackaged artifact path is produced |
| Runtime | Framework-dependent runtime dependency or self-contained output is verified |
| Store | Store readiness is a dry run unless Partner Center submission actually happened |
| Signing | Signing path is documented; no certs, passwords, or Store credentials are committed |
| Accessibility | Accessibility Insights or UI Automation smoke is run for meaningful UI changes |
| Agent safety | Stale UWP patterns are rejected before code review passes |
First Pages To Read
- Docs index
- Decision guide
- Starter architecture
- Commands
- Quality gates
- Pitfalls
- Agent guardrails
- Platform map
- Deployment models
- Packaging and identity
- Runtime deployment
- Store and signing
- Stale UWP patterns
Recommended Default
Start with a packaged C# WinUI 3 app, one app project, one testable core library, simple manual services, MSIX packaging, and Microsoft Store MSIX as the default public release path.
Add WebView2 only when native controls do not fit the product. Add unpackaged, sparse package, custom installer, self-contained, or Store MSI/EXE paths only when the product has a concrete distribution constraint.
Gotcha: A Microsoft Store account is not release evidence. Each app still needs package identity, a listing, screenshots, privacy policy when personal data is collected or transmitted, certification, versioning, restricted capability review when used, and package/runtime validation.