WinUI 3 XAML Best Practices
Twelve categories of XAML best practices validated against WinUI 3 and Uno Platform, covering performance-critical patterns through polish optimizations.
Quick Reference - Top 10 Rules
- Never block the UI thread - Use async/await for all I/O and long operations
- Use x:Bind over Binding - Compile-time validation, 3x faster
- Use x:Load for conditional UI - Prevents element creation until needed
- Enable virtualization - ListView/ItemsRepeater for any list > 20 items
- Unsubscribe event handlers - Clean up in Unloaded to prevent leaks
- Keep visual tree shallow - Minimize nesting depth
- Use OneTime mode for static data - Avoid unnecessary change tracking
- Set AutomationProperties - Required for accessibility compliance
- Use x:Uid for all user-visible text - Enables localization
- Prefer Grid over nested StackPanels - Single layout pass vs multiple
Categories by Impact
| # | Category | Impact | Key Topics |
|---|---|---|---|
| 1 | Layout | HIGH | Panel selection, visual tree depth, AutoLayout, responsive design |
| 2 | Binding | HIGH | x:Bind vs Binding, modes, function binding |
| 3 | Async & Threading | CRITICAL | UI thread, DispatcherQueue, parallelization |
| 4 | Collections & Virtualization | CRITICAL | ListView, ItemsRepeater, incremental loading |
| 5 | Rendering & Composition | MEDIUM-HIGH | Composition APIs, animations, caching |
| 6 | Memory Management | HIGH | Event handlers, leaks, resource cleanup |
| 7 | Accessibility | HIGH | AutomationProperties, keyboard navigation |
| 8 | Localization | MEDIUM | x:Uid, .resw files, runtime switching |
| 9 | Styles & Theming | MEDIUM | ResourceDictionary, ThemeDictionaries, lightweight styling |
| 10 | XAML Loading | CRITICAL | x:Load, deferred loading, startup optimization |
| 11 | Navigation | MEDIUM-HIGH | Frame caching, page lifecycle |
| 12 | Input & Interaction | MEDIUM | Touch targets, gesture handling |
Impact Levels
- CRITICAL: Can cause app crashes, multi-second freezes, or memory leaks
- HIGH: Noticeable performance degradation (100ms+)
- MEDIUM-HIGH: Cumulative impact across many elements
- MEDIUM: Optimization for polish and responsiveness
Pattern Structure
Each reference file follows this format:
### Skill Name
**Rule**: Concise imperative statement
**Why**: Technical rationale with measurable impact
**Example (XAML/C#)**: Correct implementation
**Common Mistakes**: Anti-patterns to avoid
**Uno Platform Notes**: Platform-specific gaps/workarounds (if applicable)
**Reference**: Microsoft Learn link
WinUI 3 vs UWP Key Differences
| Feature | UWP | WinUI 3 |
|---|---|---|
| Namespace | Windows.UI.Xaml | Microsoft.UI.Xaml |
| Dispatcher | CoreDispatcher | DispatcherQueue |
| Deferred Loading | x:DeferLoadStrategy (deprecated) | x:Load |
| Window | CoreWindow | Microsoft.UI.Xaml.Window |
| App Model | UWP sandbox | Desktop (full trust) |
Uno Platform Compatibility
All patterns validated against Uno Platform with notes for:
- Platform-specific behavior differences
- Unsupported APIs and alternatives
- Skia renderer considerations
Using References
Consult the individual reference files listed in the table above, matched to the task at hand. Each file is self-contained with rules, code examples, common mistakes, and Uno Platform compatibility notes.