avalonia-threading

Avalonia Threading

Version labels per avalonia-versions: (12.0+), (11.x), no label = 11.3/12.0/12.1.

Core Rules

1. AvaloniaObjects (controls, styled properties) may only be touched from the thread that owns them — normally the UI thread. Violations throw InvalidOperationException: Call from invalid thread.
2. Avalonia installs an AvaloniaSynchronizationContext on the UI thread, so await in UI-thread code resumes on the UI thread automatically.
3. Do CPU/IO work off-thread (Task.Run, async IO); marshal only the result back.
4. Never block the UI thread (.Result, .Wait(), .GetAwaiter().GetResult()) — deadlocks and frozen UI.
5. Multiple UI threads are not supported, even in 12. One dispatcher per thread exists, but apps use one UI thread.

Dispatcher.UIThread

using Avalonia.Threading;

// Fire-and-forget (non-blocking, from any thread)
Dispatcher.UIThread.Post(() => StatusText.Text = "Done");
Dispatcher.UIThread.Post(() => StatusText.Text = "Idle", DispatcherPriority.Background);

// Await completion / get a value back
await Dispatcher.UIThread.InvokeAsync(() => StatusText.Text = "Done");
var text = await Dispatcher.UIThread.InvokeAsync(() => SearchBox.Text);

// Async callback overload (returns Task, awaits inner work)
await Dispatcher.UIThread.InvokeAsync(async () => { await LoadAsync(); });

// Blocking — avoid from UI-bound flows; fine for rare sync handoffs from a worker
Dispatcher.UIThread.Invoke(() => StatusText.Text = "Done");

// Access checks
if (Dispatcher.UIThread.CheckAccess()) { /* on UI thread */ }
Dispatcher.UIThread.VerifyAccess();      // throws if not on UI thread