avalonia-performance
Use when diagnosing or improving Avalonia performance — slow scrolling or large lists (virtualization, TableView), FPS/layout/render profiling with DevTools and RendererDiagnostics overlays, compiled vs reflection bindings, image decode size, visual-tree depth, startup time and size (ReadyToRun, trimming, NativeAOT), and memory leaks (event handlers, DataContext, images).
linuxdevel · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add linuxdevel/Avalonia-skills --skill avalonia-performanceAbout this skill
name: avalonia-performance description: Use when diagnosing or improving Avalonia performance — slow scrolling or large lists (virtualization, TableView), FPS/layout/render profiling with DevTools and RendererDiagnostics overlays, compiled vs reflection bindings, image decode size, visual-tree depth, startup time and size (ReadyToRun, trimming, NativeAOT), and memory leaks (event handlers, DataContext, images).
Avalonia Performance & Diagnostics
Version labels follow avalonia-versions: (12.0+), (12.1+), (11.x), no label = 11.3/12.0/12.1. For publish steps (RIDs, single file, installers) see avalonia-deployment; this skill covers only the performance-relevant flags.
Workflow
- Measure first: overlay FPS/layout/render graphs, then DevTools visual tree, then
dotnet-counters/dotnet-trace. - Fix the biggest cost: usually (a) non-virtualized big list, (b) reflection bindings, (c) full-size image decode, (d) deep/huge visual tree, (e) work on the UI thread.
- Re-measure in Release (
dotnet run -c Release); Debug builds and an attached debugger distort results.
Diagnosing
DevTools
| Package | Call | |
|---|---|---|
| (12.0+) | AvaloniaUI.DiagnosticsSupport (+ AvaloniaUI.DeveloperTools global tool avdt, Avalonia Plus tooling) | this.AttachDeveloperTools(); in Application.Initialize() |
| (11.x) | Avalonia.Diagnostics | this.AttachDevTools(); (or window.AttachDevTools()) |
public override void Initialize()
{
AvaloniaXamlLoader.Load(this);
#if DEBUG
this.AttachDeveloperTools(); // (12.0+) — AppBuilder equivalent: .WithDeveloperTools()
#endif
}
Avalonia.Diagnostics has no 12.x release; never reference both. Options (DeveloperToolsOptions): ConnectOnStartup, Runner, Protocol (HTTP default port 29414, or named pipes), AutoConnectFromDesignMode, DiagnosticLogger. Docs: https://docs.avaloniaui.net/tools/developer-tools/installation
Renderer overlays (all versions)
TopLevel.RendererDiagnostics.DebugOverlays is a [Flags] enum RendererDebugOverlays (namespace Avalonia.Rendering):
| Flag | Shows |
|---|---|
Fps | frames per second |
DirtyRects | invalidated rectangles per frame |
LayoutTimeGraph | recent layout pass times |
RenderTimeGraph | recent render times |
var top = TopLevel.GetTopLevel(this)!;
top.RendererDiagnostics.DebugOverlays =
RendererDebugOverlays.Fps | RendererDebugOverlays.LayoutTimeGraph | RendererDebugOverlays.RenderTimeGraph;
// toggle off: RendererDebugOverlays.None
How to read: large dirty rects every frame on a static screen means something is animating or invalidating continuously; tall layout graph means layout thrash (see below); tall render graph means heavy drawing (shadows, big images, effects).
.NET tooling (run against the app process)
dotnet-counters monitor --process-id <pid> System.Runtime # GC heap, alloc rate, gen0/1/2 counts, threadpool
dotnet-trace collect --process-id <pid> --profile cpu-sampling # open .nettrace in PerfView / VS / Speedscope
dotnet-gcdump collect --process-id <pid> # heap snapshot to find leaked controls/VMs
Install these tools yourself from nuget.org (dotnet tool install --global dotnet-counters); verify package ids before installing. Rising gen2 heap after closing windows/views means a leak (see Memory).
UI Performance
Virtualization
| Control | Virtualizes by default? |
|---|---|
ListBox, ComboBox dropdown, TreeView-style items hosts | Yes (VirtualizingStackPanel) |
ItemsControl | No; ItemsPanel defaults to StackPanel |
TableView (12.1+) | Yes, recycles rows and cells |
DataGrid | Yes (rows); maintenance mode in 12.1, prefer TableView/TreeDataGrid |
ItemsRepeater | Retired, not supported as of 12. Migrate to ItemsControl/ListBox |
<!-- ItemsControl with virtualization -->
<ScrollViewer>
<ItemsControl ItemsSource="{Binding Items}">
<ItemsControl.ItemsPanel>
<ItemsPanelTemplate><VirtualizingStackPanel/></ItemsPanelTemplate>
</ItemsControl.ItemsPanel>
</ItemsControl>
</ScrollViewer>
<!-- Simpler: use ListBox; style it if you do not want selection visuals -->
VirtualizingStackPanel members: Orientation, CacheLength (extra space realized above/below viewport; raising it trades memory for smoother scrolling), FirstRealizedIndex / LastRealizedIndex (-1 when nothing realized; handy in a diagnostic to confirm virtualization is active).
What breaks virtualization (the panel gets unlimited space, realizes every item):
- Putting the list inside an unconstrained-height parent:
StackPanel,ScrollViewerwithVerticalScrollBarVisibility="Auto"wrapping aListBox, orGridrow withHeight="Auto". Give the list a bounded height (*row,DockPanelfill) and let the list own its scrolling. - Nesting a
ListBoxinside aScrollViewerjust to "scroll the page". - Replacing
ItemsPanelwith a non-virtualizing panel (StackPanel,WrapPanel,UniformGrid). - Variable-size, very heavy
ItemTemplates (virtualization works, but each realization is expensive; flatten the template). - Realizing everything in code (
ItemsPanelRoot.Childrenloops,ContainerFromIndexover the whole range).
Also: bind ItemsSource to an ObservableCollection<T> and mutate incrementally; replacing the whole collection reference rebuilds every container. For bulk loads, build the list then assign once.
Bindings
| Cost | |
|---|---|
Compiled (x:DataType set) | fastest, build-time checked, trim/AOT safe. Default in 12.0+ |
{ReflectionBinding} / (11.x) default {Binding} | reflection at runtime, slower, trimmer-unsafe |
- (12.0+)
{Binding}withoutx:DataTypefails to compile; setx:DataTypeon the view root and onDataTemplates. - (11.x) Opt in project-wide: `true</AvaloniaU