avalonia-performance

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

1. Measure first: overlay FPS/layout/render graphs, then DevTools visual tree, then dotnet-counters/dotnet-trace.
2. 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.
3. 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