What This Reference Is For
Use this file when the user reports sluggish WinUI behavior, dropped frames, long startup, or laggy scrolling and layout.
Prefer
- Keeping the UI thread free for layout, rendering, and input.
- Simpler visual trees and lighter templates.
- Virtualization-friendly controls and item layouts.
- Measurement before optimization when the issue is not obvious.
Avoid
- Doing expensive I/O or CPU work directly on the UI thread.
- Deeply nested XAML trees without a concrete benefit.
- Re-templating controls in ways that dramatically increase layout work.
- Guessing at performance causes without profiling.
Guidance
- Favor platform controls and layouts that virtualize well for long lists.
- Defer or background heavy work when it does not need to block interaction.
- Reduce unnecessary layout invalidation and repeated measure/arrange churn.
- Use WPR and WPA with the XAML Frame Analysis plugin for frame-level investigations.
- Treat slow-frame findings as a clue to UI-thread overload, not as a reason to micro-optimize blindly.
Sample and Source Anchors
- Learn
winui-perf.md - WinUI Gallery pages that demonstrate adaptive UI and complex controls without excessive custom infrastructure
Review Checklist
- Is heavy work running off the UI thread where possible?
- Are large collections using an appropriate items control?
- Is the visual tree no more complex than it needs to be?
- Has profiling been used before claiming a fix?