用途
Avalonia Threading 是一份面向 Avalonia UI 开发者的线程模型参考文档,用于解决在后台线程与 UI 线程之间安全交互的问题。Avalonia 的控件和样式属性(AvaloniaObject)只能由创建它们的线程访问,通常是 UI 线程;违反此规则会抛出 InvalidOperationException: Call from invalid thread。该文档说明如何正确地把后台计算结果封送回 UI 线程,避免死锁、界面冻结和跨线程异常。
主要能力
文档围绕以下主题展开:
-
核心规则:AvaloniaObject 只能在所属线程访问;UI 线程自动安装 AvaloniaSynchronizationContext,因此 UI 线程代码中的 await 会自动回到 UI 线程;CPU/IO 工作应放到线程外(Task.Run、异步 IO),只把结果封送回来;禁止阻塞 UI 线程(.Result、.Wait()、GetAwaiter().GetResult());即使 12.0 也不支持多个 UI 线程。
-
Dispatcher.UIThread API:Post(即发即忘,最安全,不会死锁)、InvokeAsync(可 await、可取消、可中止)、Invoke(同步阻塞)、CheckAccess、VerifyAccess、ToTaskScheduler。文档以表格列出各成员返回值、默认优先级和适用场景,并说明 DispatcherOperation 的 Status、Priority、Abort()、Wait()、GetTask()、GetAwaiter() 及事件。
-
DispatcherPriority:从低到高列出 SystemIdle、ApplicationIdle、ContextIdle、Background、Input、Default、Loaded、UiThreadRender、Render、BeforeRender、AsyncRenderTargetResize、Normal、Send 等优先级,并给出选择建议(普通更新用 Default,批量低优先级用 Background,空闲清理用 ApplicationIdle/SystemIdle)。
-
ViewModel 中的 async/await:命令在 UI 线程启动,await 后的续体也回到 UI 线程;推荐使用真正异步的 API 而非 Task.Run 包装;async void 仅用于事件处理器并需 try/catch;后台线程上设置绑定属性会抛异常。
-
ConfigureAwait:ViewModel/View/代码后置中不要用 ConfigureAwait(false);库/服务/仓储代码可用;混用方法中 ConfigureAwait(false) 之后需用 Dispatcher.UIThread.Post/InvokeAsync 封送。
-
后台工作与进度:Progress<T> 在 UI 线程构造,Report 回调才会在 UI 线程执行;也可用 Dispatcher.UIThread.Post 替代;高频报告需节流。
-
ObservableCollection 跨线程:集合非线程安全,CollectionChanged 在变更线程触发;正确做法是后台计算、UI 线程变更,或通过 Dispatcher 变更;大批量数据分块处理以保持响应;大替换优先整体替换集合属性;DynamicData、Rx ObserveOn、ReactiveUI.Avalonia 可作为替代方案(需按包版本验证)。
-
DispatcherTimer:Tick 在计时器所属调度器上运行;视图卸载时必须 Stop;提供 RunOnce 和 Run 辅助方法;Tick 中长时间工作会冻结 UI;异步 Tick 可能重叠需加标志;非 UI 周期任务用 PeriodicTimer 或 System.Threading.Timer。
-
取消:每个操作一个 CancellationTokenSource,启动新操作前取消旧的;把 token 传给异步 API 和 Task.Run;单独捕获 OperationCanceledException;替换时 Dispose;视图/ViewModel 销毁时取消;InvokeAsync 的 CancellationToken 只能取消排队中的操作,不能中断正在执行的委托。
-
AvaloniaSynchronizationContext:UI 线程自动安装(AutoInstall 默认 true);Post 排队不阻塞,Send 同步执行;池线程没有上下文;12.0 中 new AvaloniaSynchronizationContext() 使用 Dispatcher.CurrentDispatcher 而非 Dispatcher.UIThread。
-
Avalonia 12 线程变更:每线程一个 Dispatcher;Dispatcher.CurrentDispatcher、Dispatcher.FromThread、AvaloniaObject.Dispatcher;Dispatcher.UIThread 仍推荐用于应用代码;AvaloniaObject.CheckAccess/VerifyAccess 委托给对象自己的 Dispatcher;DispatcherTimer 和 AvaloniaSynchronizationContext 默认使用当前调度器;InvokeAsync 捕获 ExecutionContext;新增 Dispatcher.Yield()/Resume();Android 调度器基于 Looper/MessageQueue 重建;托管调度器获得显式后台处理支持。
-
测试:无头测试在测试 UI 线程上运行 Avalonia 调度器,应 await 调度器工作而非 Thread.Sleep;ViewModel 异步逻辑应可注入(TimeProvider、返回 Task 的服务)。
-
常见错误:从 Task.Run 或 System.Threading.Timer 回调更新控件/绑定属性;UI 线程上 .Result/.Wait();ViewModel 中用 ConfigureAwait(false) 后设置属性;工作线程 Invoke 而 UI 线程等待工作线程导致死锁;Task.Run 中修改 ObservableCollection;紧循环中高优先级逐项 Post;事件处理器外使用 async void;视图销毁时不停止 DispatcherTimer;12 中在工作线程创建 DispatcherTimer/AvaloniaSynchronizationContext;假设 InvokeAsync 回调看不到环境上下文;在工作线程构造 Progress<T>;忘记取消被取代的工作;期望 12 支持多 UI 线程。
使用方式
该文档为参考性技能说明,本身不包含安装命令或可执行代码。开发者按文档中的代码示例在 C# 项目中编写线程相关逻辑,例如使用 Dispatcher.UIThread.Post 从后台线程更新界面、在 ViewModel 中编写 async 命令、使用 DispatcherTimer 做周期更新等。文档中给出的代码片段可直接参考,但需结合具体项目调整。
适用场景
适用于使用 Avalonia UI 构建桌面应用的 C# 开发者,尤其是需要从后台线程更新界面、处理异步命令、管理定时器、处理大数据集合绑定、进行取消控制或迁移到 Avalonia 12 的场景。
限制
文档明确说明 Avalonia 不支持多个 UI 线程,即使 12.0 存在多调度器也不支持多线程 UI。部分替代方案(如 DynamicData、ReactiveUI.Avalonia)需按包版本验证。文档未提供安装命令、收费信息或平台支持细节,这些内容暂未提供。