简介一份面向C#开发者的Avalonia跨平台上位机开发资源包聚焦桌面端界面与业务逻辑分离的工程实践适合需要将WinForm/WPF知识迁移到跨平台场景的学员。包体包含270个文件核心为155个DLL运行库、22个CS源码文件及AXAML界面描述文件并附带BLL与DAL数据库分层模块压缩包约56.61MB。资源不仅提供Avalonia框架的NuGet安装与项目生成指引还给出完整解决方案示例可直接作为主框架功能块引用同时兼容Console、WinForm、WPF、Web等主流C#程序结构便于对比学习。已有1101人浏览学习对于想快速上手Avalonia的开发者可从中获得界面布局、数据绑定、模块划分及多项目协作的实用参考减少环境搭建和工程组织上的弯路。 干这行这么多年上位机开发最让人头疼的从来不是逻辑多复杂而是甲方一句“能不能在Linux上跑”。以前听到这种需求基本就是两条路要么劝客户加一台Windows工控机要么捏着鼻子用Qt/C重写界面。直到我完整把一个基于C# .NET的上位机项目用Avalonia迁移过去才意识到这条路不仅能走而且能走得很顺。这篇就围绕这个标题把我从选型到落地的完整过程、踩过的坑和实测有效的做法梳理出来给同样在做上位机跨平台开发的朋友一个参考。1. 为什么选Avalonia而不是其他方案1.1 上位机跨平台的现实需求先说需求背景。这两年我接触到的项目里要求上位机跑在Linux上的比例越来越高大致有几种情况现场用国产化工控机的系统预装的是麒麟或统信UOS工厂现有服务器是Linux希望监控站直接复用还有一些边缘计算盒子本身就是ARM Linux架构。这些场景下上位机如果只支持Windows交付就很被动。界面还只是一方面更要命的是通讯层。工控现场涉及的设备五花八门串口仪表、PLC、扫码枪、工业相机、MQTT网关都需要上位机去对接。所以一个合格的跨平台方案必须同时解决界面跨平台和设备通讯跨平台两个问题。Avalonia恰好在两边都有还不错的支持这也是我最终选它的核心原因。1.2 Avalonia与其他跨平台框架的对比选型的时候我主要对比了四类方案Avalonia、Qt、Electron还有MAUI。我用一个表格列出实测感受方案界面表现力Linux支持与C#/.NET生态结合资源占用团队上手成本Avalonia强类WPF的XAML成熟稳定原生可直接引用现有C#代码低原生渲染低有WPF基础很快Qt/QML强成熟一般需要通过C/CLI桥接低中高需要学C或QMLElectron强前端生态成熟中等通过Node.js桥接高内存占用明显中需要前端基础MAUI中等官方支持弱不够成熟原生中中这里说说我的实际感受。Electron确实界面做得漂亮但工控机配置普遍不高Electron打包出来动辄两三百兆运行内存轻松上500M现场机器带不动。Qt本身很强但大多数做上位机的团队主力是C#为了跨平台突然转C业务代码要重写成本太高。MAUI在Windows和移动端还行但Linux桌面支持一直不算稳定工控场景不推荐。Avalonia这半年来我用下来的体验是XAML语法跟WPF几乎一个模子出来的原项目里的View层逻辑迁移成本极低渲染是自绘的不依赖系统WebView和特定图形库Linux下跑得很稳包括树莓派上的ARM Linux我也试过没有大问题。还有一个额外好处它和.NET生态完全打通原有的依赖注入、通讯线程、日志框架、序列化库全都能直接复用不用搞两套体系。2. 项目整体架构设计2.1 分层设计通讯层必须独立出来跨平台迁移最容易翻车的地方就是把界面和通讯逻辑耦合在一起。我在迁移前就强制把项目拆成了四层这个习惯在Avalonia项目里帮我省了很多事Models层定义设备数据模型、协议报文结构。Infrastructure层所有通讯实现包括串口、TCP、UDP、MQTT、Modbus协议解析。Application层流程控制、状态机管理、数据缓冲、指令队列。UI层只负责展示和用户交互。这样当我把UI从WPF换成Avalonia时下面三层一个文件都没动。反过来如果当初通讯逻辑到处new在主窗体的按钮事件里迁移时就是一场灾难。2.2 关键技术选型项目里我最终选用的核心库如下都是全面测试过能在Avalonia .NET 8下正常工作的UI框架Avalonia 11.x支持XAML、样式、绑定、动画。MVVM工具包CommunityToolkit.Mvvm轻量好用源生成器减少大量样板代码。串口通讯System.IO.Ports.NET官方库Linux下用包管理器装好libicu后就很稳定。MQTTMQTTnet纯C#实现异步API设计合理跨平台无压力。ModbusNModbus支持RTU和TCP。JSON序列化System.Text.Json性能和兼容性都不错。日志Serilog配合File和Console输出。这些库的选择背后其实都有考量比如MQTTnet没有用官方MQTT库是因为它更活跃、跨平台处理更好日志用Serilog是本项目现场排障需要滚动文件输出不用控制台堆日志。核心原则只有一个通讯库尽量选纯托管实现的避免那些依赖Windows原生API或需要单独安装驱动的组件。3. 核心通讯模块的实现3.1 串口通讯封装串口是上位机绕不开的一类通讯。现场最常见的设备就是各种485传感器、仪表。我封装了一个SerialPortService核心代码如下:public sealed class SerialPortService : IDisposable { private SerialPort _port; private readonly object _writeLock new object(); public event EventHandlerbyte[] DataReceived; public bool Open(string portName, int baudRate, Parity parity Parity.None, int dataBits 8, StopBits stopBits StopBits.One) { _port new SerialPort(portName, baudRate, parity, dataBits, stopBits) { ReadTimeout 500, WriteTimeout 500 }; _port.DataReceived OnDataReceived; _port.Open(); return _port.IsOpen; } private void OnDataReceived(object sender, SerialDataReceivedEventArgs e) { int bytesToRead _port.BytesToRead; byte[] buffer new byte[bytesToRead]; _port.Read(buffer, 0, bytesToRead); DataReceived?.Invoke(this, buffer); } public void Send(byte[] data) { lock (_writeLock) { if (_port ! null _port.IsOpen) { _port.Write(data, 0, data.Length); } } } public void Dispose() { _port?.Dispose(); } }这里我特别加了一个_writeLock因为现场串口设备多多线程下如果同时写容易把数据帧弄碎。写操作必须原子化这是很多初学者容易漏的地方。另一个坑是数据分包。串口底层是按字节到达的一次发送的一帧数据可能被拆成多段接收事件。我在项目里又加了一层“帧缓存”按照设备的帧头、帧尾或超时时间把零散字节拼成完整报文。真正解析逻辑只处理完整帧不然数据解析会时好时坏。3.2 TCP/IP与Modbus对接TCP/IP算是现代上位的标配。很多PLC如三菱Q系列J71E71模块都支持以太网通信。与这类设备对接时除了TCP连接外还要注意协议封装。比如三菱MC协议用的是二进制/ASCII格式的帧结构有子头部、请求数据长度、命令、PLC编号等字段。用C#实现时要特别注意大小端转换和位拼接。比如读取D寄存器请求数据区就要按高字节在后的规则拼。为此我封装了一个统一的TcpClientServicepublic sealed class TcpClientService : IDisposable { private TcpClient _client; private NetworkStream _stream; private readonly CancellationTokenSource _cts new(); public event EventHandlerbyte[] DataReceived; public event EventHandler Connected; public event EventHandler Disconnected; public async Task ConnectAsync(string ip, int port) { _client new TcpClient(); await _client.ConnectAsync(ip, port); _stream _client.GetStream(); _ Task.Run(ReceiveLoop); Connected?.Invoke(this, EventArgs.Empty); } private async Task ReceiveLoop() { byte[] buffer new byte[4096]; while (!_cts.IsCancellationRequested _client.Connected) { try { int read await _stream.ReadAsync(buffer, 0, buffer.Length); if (read 0) break; DataReceived?.Invoke(this, buffer[..read]); } catch { break; } } Disconnected?.Invoke(this, EventArgs.Empty); } public async Task SendAsync(byte[] data) { if (_stream ! null) { await _stream.WriteAsync(data); } } public void Dispose() { _cts.Cancel(); _stream?.Dispose(); _client?.Close(); } }这里我加了断线重连的机制因为现场网络波动是常态。重连逻辑用状态机断线后等待5秒自动重连连续失败10次后降级为手动重连避免现场无人值守时无限重连刷屏日志。还有心跳检测每3秒发一个心跳包连续三次无响应判定为断线这个在现场实测很有效能把故障时间从小时级压缩到分钟级。Modbus协议这块我的建议是别自己造轮子直接引入NModbus。但要注意NModbus的异步方法在Linux上偶尔有超时问题我实测后统一在调用处包了CancellationToken和Task.WhenAny做超时控制稳定性明显提升。3.3 MQTT与设备数据上送很多现场并不需要上位机直接连所有设备而是通过串口服务器或网关把数据先汇总到MQTT上位机再订阅。Avalonia项目里我用MQTTnet做客户端接入代码非常简洁public sealed class MqttClientService { private readonly IMqttClient _client; public MqttClientService() { _client new MqttFactory().CreateMqttClient(); } public async Task ConnectAsync(string host, int port, string clientId) { var options new MqttClientOptionsBuilder() .WithTcpServer(host, port) .WithClientId(clientId) .WithCleanSession() .WithKeepAlivePeriod(TimeSpan.FromSeconds(30)) .Build(); await _client.ConnectAsync(options); _client.ConnectedAsync async e await Task.CompletedTask; } public async Task SubscribeAsync(string topic) { var options new MqttClientSubscribeOptionsBuilder() .WithTopicFilter(e e.WithTopic(topic).WithQualityOfServiceLevel(Protocol.MqttQualityOfServiceLevel.AtLeastOnce)) .Build(); await _client.SubscribeAsync(options); } public async Task PublishAsync(string topic, string payload) { var message new MqttApplicationMessageBuilder() .WithTopic(topic) .WithPayload(payload) .WithQualityOfServiceLevel(Protocol.MqttQualityOfServiceLevel.AtLeastOnce) .Build(); await _client.PublishAsync(message); } }MQTT在工控场景的价值在于解耦和缓冲。即使上位机软件崩溃重启网关里的数据也不会丢上位机起来后拉取历史就能补回数据空窗。我在项目里把“回放补偿”做成了一个功能重启后检测到与服务器时间差超过阈值自动从MQTT留存主题拉最近5分钟数据补点效果很好。3.4 扫码枪等外设接入工控现场最常见的扫码枪其实分两类一类是USB模拟键盘输入的接收端就是普通键盘输入跟串口无关。对这类设备我处理办法是全局键盘钩子或被动监听但Avalonia在Linux下监听全局键盘要借助输入库比较麻烦所以我绕了一下让扫码枪进入“串口模式”配置或者用带串口输出的扫码枪统一走串口接收。串口扫码枪的数据特点是一帧数据以0x0D回车结尾帧内容就是条码字符串。接收逻辑这样写private readonly StringBuilder _buffer new(); private void OnScannerDataReceived(object sender, byte[] data) { foreach (byte b in data) { if (b 0x0D) { string barcode _buffer.ToString(); _buffer.Clear(); OnBarcodeScanned?.Invoke(this, barcode); } else if (b 0x20 b 0x7E) { _buffer.Append((char)b); } } }之所以严格过滤0x20~0x7E是因为现场经常出现扫码枪乱码或附带控制字符不加过滤容易把垃圾数据带到业务层。处理扫码枪触发事件时我推荐做成异步事件驱动不要阻塞扫码线程否则连续扫码速度快时UI会掉帧或漏码。4. 视觉设备对接与视觉结果处理4.1 海康VisionMaster与上位机的通讯方式这个热词榜上也有“海康相机软件VisionMaster与C#上位机通讯用什么协议比较好”我实际做下来有两种主流方式第一种是SDK集成模式。VisionMaster本身提供.NET SDK上位机进程内直接调用它的API加载方案、触发采图、获取结果都通过SDK完成。这种方式集成度最高结果实时性好但耦合也重SDK版本升级容易影响主程序而且SDK对Linux支持没有Windows完美。第二种是独立方案 通讯协议模式。VisionMaster独立跑在工控机上上位机通过TCP/UDP发送触发指令和接收检测结果数据量小的时候也用ModbusTCP。我实际项目里用的是TCP JSON协议JSON结构里包含OK/NG判定、缺陷坐标、测量数值。这种方式最灵活上位机和视觉模块可以分开部署在不同机器上也方便以后替换视觉方案。4.2 数据解析与图像展示技巧处理视觉结果时解码是一个细节活。VisionMaster返回的坐标或灰度图通常要转换成BitmapSource给界面显示。Avalonia里图源和WPF不一样不能直接用System.Drawing.Bitmap我封装了一个转换函数public static Bitmap ToAvaloniaBitmap(byte[] rawImage, int width, int height) { var writeableBitmap new WriteableBitmap( new PixelSize(width, height), new Vector(96, 96), PixelFormats.Bgra8888, AlphaFormat.Opaque); using var framebuffer writeableBitmap.Lock(); Marshal.Copy(rawImage, 0, framebuffer.Address, rawImage.Length); return writeableBitmap; }图像数据是Bgra8888格式的裸字节数组用WriteableBitmap直接操作内存性能比逐像素Copy快一个数量级。实时显示相机的预览流50万像素30帧在Avalonia下跑起来完全流畅CPU占用可以接受。另外还有一个经验图像界面别用图片控件直接绑定大图Avalonia渲染大图会有卡顿我一般在显示之前把图像缩放到合适分辨率比如显示区域只有300x300就先把原始图按比例缩到500x500再绑定肉眼几乎无差异性能提升明显。5. UI界面细节与大数据量展示优化5.1 Avalonia数据绑定与跨线程更新Avalonia的数据绑定模式和WPF几乎一样MVVM模式下直接在ViewModel里用[ObservableProperty]标记属性就行。但有一个大坑从通讯线程直接修改绑定的集合或属性在Avalonia里不会自动封送UI线程会出异常或者界面不刷新。正确做法是用Dispatcher// 例如在ViewModel中从TCP接收线程更新状态 private async void OnTcpDataReceived(object sender, byte[] data) { var result _parser.Parse(data); await Dispatcher.UIThread.InvokeAsync(() { CurrentValue result.Value; IsDeviceOnline true; }); }我在做串口数据曲线刷新时刚开始直接在线程里给ObservableCollection加数据结果曲线卡成PPT。后来改成批量提交UI线程接收线程先把数据放进一个并发队列UI线程每100ms统一取一次批处理界面刷新一下就非常流畅。这个方法在处理高频采集数据时特别管用。5.2 大量数据展示的实测经验热词里有“csv net 10万数据”说明很多人在做大数据量的表格展示。Avalonia的DataGrid如果用普通的ObservableCollectionT绑定10万行记录滚动时会非常卡内存也会暴涨。我实测的解决方案是使用DataGridCollectionView开启分页或延迟加载。用虚拟化模式只渲染可见区域的行。实际数据存入List后按需切片暴露给视图。我建议直接把DataGrid的EnableRowVirtualization设为True并将ItemsSource绑到一个支持分页集合的ReadOnlyObservableCollection。如果数据还要做实时刷新就限定只更新当前页显示的行不全局替换整个集合。这样处理10万行CSV导入实时追加曲线数据界面上操作依然跟手。6. 跨平台部署与发布6.1 单文件发布与自包含运行时Avalonia项目发布比想象中简单。我常用的是单文件自包含发布这样目标机器上不用预装.NET运行时一个exe或可执行文件拷过去就能跑。Windows发布命令dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFiletrue -o ./publish/win-x64Linux发布命令dotnet publish -c Release -r linux-x64 --self-contained true -p:PublishSingleFiletrue -o ./publish/linux-x64ARM平台树莓派或ARM工控机dotnet publish -c Release -r linux-arm64 --self-contained true -p:PublishSingleFiletrue -o ./publish/linux-arm64这里特别提醒跨平台发布一定要指定RID不能直接用通用的dotnet publish否则Avalonia自带的SkiaSharp原生库不会被打进去发布出来的程序放到目标机器上会直接报找不到libSkiaSharp。还有一点单文件发布会把原生库嵌入进去启动时释放到临时目录这就要注意杀毒软件误报问题我遇到过Windows Defender误拦截的需要在杀毒软件加白名单或改用非单文件模式。6.2 Linux系统下的部署细节Linux部署的最大坑是串口权限。普通用户访问/dev/ttyUSB0或/dev/ttyS0默认没有权限处理方式是把当前用户加入dialout组sudo usermod -aG dialout $USER如果你用的是ARM盒子还有个更省事的方法写udev规则让程序以root方式运行时自动授权或者直接用服务方式启动服务配成root用户也行。但工控机上我建议还是建专用普通用户加入dialout组安全性更好。另一个坑是Avalonia在Linux下依赖特定图形库。如果工控机用的是精简版Linux可能缺libX11、libICE、libSM等我踩过几次后现在发布包时直接把部署脚本一起打进去脚本里用apt或yum自动安装这些依赖sudo apt install -y libx11-6 libice6 libsm6 libfontconfig1 libfreetype6如果目标系统是CentOS或Rocky对应包名是sudo yum install -y libX11 libICE libSM fontconfig freetypeLinux下手动debug时可以用DISPLAY:0 ./YourApp来指定显示输出如果跑不起来先看是缺库还是缺权限这个经验能省很多排查时间。7. 常见问题排查实录7.1 问题排查速查表我列一个实际踩坑记录方便大家对照排查现象可能原因解决办法Linux下程序启动即崩溃缺少SkiaSharp原生库确认RID是否正确用自包含单文件发布串口打不开报Access denied无权限访问/dev/ttyUSB0加入dialout组或调整udev规则Linux下界面显示得很小或模糊高分屏缩放未配置设置环境变量AVALONIA_SCREEN_SCALE_FACTORSMQTT连接不稳定经常断线心跳周期太长或网络不稳KeepAlive设为30秒并开启自动重连大量数据刷新时界面卡顿每帧数据都直接UI线程绑定批量合并提交100ms一个周期刷新Modbus TCP偶尔超时NModbus默认超时在Linux下不准用Task.WhenAny包一层自定义超时Windows打包后被杀毒拦截单文件嵌入原生库触发误报加白名单或改用文件夹发布模式读取CSV 10万行卡死DataGrid未开启虚拟化开启EnableRowVirtualization7.2 几个值得说的深坑再补充几个没那么容易定位的深坑。第一个是Linux下System.IO.Ports的包冲突问题。默认Project里引用System.IO.Ports时如果目标框架是net8.0尽量使用8.0.x版本包别用老的5.0版本。曾经遇到过一个包版本不正确导致Linux串口数据读取错乱的情况排查了好久最后换成官方版本就好了。第二个是Avalonia的焦点问题。上位机界面往往需要键盘输入但Avalonia在Linux下对无边框窗口的焦点获取有兼容性问题。我为了做出一个工业风格的黑色无边框主窗体试了很半天最后发现需要设置WindowState为Normal并手动管理窗口的Activated事件才保证扫码输入能正常工作。第三个是关于跨线程日志的坑。Serilog我在多线程下往同一个文件写日志偶尔会出现日志丢失。后来开启Serilog的SyncRoot同步机制并把文件滚动周期调成按天按大小双重滚动就再没丢过日志。日志这件事看似小在现场排查问题时没有完整日志真的会被折腾死。第四个是Avalonia性能监控。如果你发现界面莫名卡顿先用自带的Diagnostics工具查看Visual Tree的布局耗时很多时候是某个容器的背景画刷用了大量渐变或阴影工控机上会拖慢渲染。我在项目里直接把所有阴影效果和动画都砍掉界面风格偏朴素但流畅度提升巨大。对于上位机这种长期运行的软件稳定性优先于花哨效果是一条硬道理。最后分享一点实际体会从WinForms时代一路做上位机做到现在我的切身体会是跨平台不是终点而是起点。真正决定项目成败的是底层通讯模块抽得够不够干净、异常边界考虑得够不够全、现场部署方案是否简单可靠。Avalonia这套方案我的结论是值得投入它让C# .NET在上位机领域真正做到了一次编写、多平台交付而且迁移成本比想象中低很多。如果你手头正好有WPF或WinForms老项目面临Linux需求不妨先抽一个通讯模块简单、UI不复杂的子模块用Avalonia做一次验证性迁移跑通后再规模化推进。这条路我已经替你走通了。本文还有配套的精品资源点击获取