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:

markdown

### 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.