简介MarcusW.VncClient是一份采用C#编写的高性能跨平台VNC客户端库面向需要远程控制、远程桌面功能的.NET开发者。它完整实现了RFB协议以完全托管方式运行可在.NET Core或.NET 5支持的所有平台上使用目前仍处Alpha阶段但稳定性较高适合日常集成与二次开发。资源包为zip格式大小约931KB内容紧凑便于快速下载部署。该库在性能上颇下功夫采用Tight、ZRLE等图像编码技术在慢速网络下也能保持流畅画面同时抽象了平台相关组件方便移植兼容TigerVNC、LibVNCServer、RealVNC、Vino等主流服务端实用性很强。已有662人学习浏览对于希望为自有应用增添VNC远程访问能力的开发者这份源码能帮助避开底层协议细节大幅缩短开发周期是一份值得保存的参考与基础组件。 做运维类桌面工具那几年我最烦的事其实不是告警风暴也不是面板布局而是“怎么把远端机器的屏幕干净利落地挪到自己的程序里”。最早用的办法很土主程序直接拉起VncViewer进程再用窗口句柄把它的画面嵌进来两台机器之间靠共享内存搬运图像数据画面稍大一点就卡焦点切来切去还会闪。后来有个需求必须在C#程序内部直接渲染远程桌面还要跨平台跑我才认真把整个生态翻了一遍最后留下来的方案是MarcusW.VncClient这个高性能跨平台VNC客户端库。如果你也在做远程运维工具、多节点屏幕巡检、自动化测试的屏幕采集或者想给自家软件加一个“远程协助”入口这篇文章应该能帮你少走不少弯路。我会从一个C#开发者的视角把选型逻辑、核心概念、最小集成、性能调优和跨平台落地这几个环节拆开讲代码给到能直接抄的程度。1. 翻遍C#生态之后我为什么锁定了这个库先回答一个最基本的疑问远程桌面方案那么多为什么偏偏是VNC又为什么是MarcusW.VncClient1.1 RDP、VNC、自绘协议到底该选谁微软的RDP在Windows平台集成度确实高但如果你的程序要跑在Linux、macOS甚至ARM设备上想用一套C#代码通吃所有端RDP那条路基本走不通。官方SDK绑定Windows第三方封装要么收费要么半死不活。自绘协议倒是能完全控制可服务端和客户端都要自己写画布压缩、差分传输、输入回传全得从零造轮子为了一个远程画面投入这么多研发成本对绝大多数团队都是亏的。VNC走的是RFB协议天生平台无关服务端生态极其丰富Windows有TightVNC、UltraVNCLinux有TigerVNC、x11vnc还有一些嵌入式设备自带VNC服务端。客户端只需要实现RFB协议的握手、帧缓冲更新、键盘鼠标事件、剪贴板同步这几件事就能连上绝大多数机器。对C#来说只要有个库把这些协议细节封装好跨平台就只是.NET运行时本身的问题。1.2 老实说C#这边能打的VNC库并不多我当时的排查列表打开之后心情挺复杂的。老牌库像VncSharpWinForms年代的东西同步Socket阻塞式收发跑一次握手操作UI线程就卡一下帧缓冲更新来了直接往PictureBox上DrawImage代码风格停留在二十年前。还有几个从Java VNC Viewer移植过来的库界面控件和协议逻辑耦合在一起想拆掉它的画布换成自己的渲染组件得动手术。再就是有些个人作者写了一半的Demo级项目连TLS握手都没处理压根不敢用在生产环境。MarcusW.VncClient是少数几个让我觉得“这是按现代C#工程标准写的库”。它基于.NET Standard异步API贯穿始终帧缓冲、输入事件、剪贴板、TLS都拆成了独立模块跟具体UI框架完全解耦。这意味着你可以在WPF里用WriteableBitmap渲染到了Linux换成SkiaSharp渲染层想怎么换就怎么换。1.3 选型时我列的四项硬指标当时我做技术评估列得比较苛刻异步API必须贯穿到底连接握手、帧缓冲请求、事件发送都不能阻塞否则UI线程迟早出事渲染层必须可替换不能把PictureBox或者某个Control硬编码在库内部协议支持要完整至少覆盖帧缓冲更新、键盘事件、指针事件、剪贴板最好支持TLS能跑在非Windows平台至少Linux要能跑移动端可以后续再看MarcusW.VncClient当时全部满足。也正因如此后面踩坑时我才觉得这库值得写一篇长文展开。2. 先画清楚三个核心概念用法自然就通了很多人拿到库直接看API文档容易被一堆方法名绕晕。我的建议是先理解它背后的RFB协议模型因为整个库的API就是照着协议消息设计的。2.1 连接层一次ConnectAsync背后发生了什么VNC连接不是单纯建立一个TCP通道就算完事它要经历协议版本协商、安全类型协商、安全握手比如VNC Password认证或者TLS然后才是初始化消息、像素格式协商、编码类型协商。MarcusW.VncClient把这一整套都收进了ConnectAsync方法里你看到的是一个await它内部其实完成了一轮完整的RFB握手。var client new VncClient(); var settings new VncConnectionSettings { Password your-password }; await using var connection await client.ConnectAsync(192.168.1.10, 5900, settings);这里有个容易被忽略的细节ConnectAsync返回的connection对象实现了IAsyncDisposable。在C# 8.0以上的代码里用await using包裹连接关闭时能保证异步释放底层Socket和缓冲资源而不是像老库那样直接同步Close。这个设计差异在高频连接场景下体感很明显。2.2 帧缓冲所谓“远程桌面”的本质就是它帧缓冲就是远端屏幕的像素集合VNC服务端把屏幕变化封装成FramebufferUpdate消息推给客户端。你不需要主动去“拉”每一帧而是订阅更新事件等数据到了再处理。MarcusW.VncClient里的核心事件就是FrameBufferUpdated。connection.FrameBufferUpdated OnFrameBufferUpdated; private void OnFrameBufferUpdated(object? sender, FrameBufferUpdatedEventArgs e) { // e.FrameBuffer 包含当前的帧缓冲数据 // 拿到数据后写入渲染控件 }理解帧缓冲更新机制是个分水岭。它不是整屏重新推一整张JPG而是带区域坐标的编码块。服务端只发送变化的那块矩形区域用指定的编码方式压缩。所以你订阅到的事件每次可能只对应屏幕上一个矩形区域的变化而不是完整的一帧画面。不理解这一点很容易在渲染循环里写出“每次更新都全量拷贝整块缓冲”的低效代码。2.3 事件通道客户端不只是看还得会操作远程画面能看之后下一步就是操作。键盘、鼠标、剪贴板这些从客户端发往服务端的消息在RFB协议里各自独立。MarcusW.VncClient把这些封装成了SendKeyEvent、SendPointerEvent、SendCutText之类的方法。await connection.SendPointerEventAsync(PointerButton.Left, isPressed: true, x, y); await connection.SendPointerEventAsync(PointerButton.Left, isPressed: false, x, y); await connection.SendKeyEventAsync(KeySymbols.Return, isPressed: true); await connection.SendKeyEventAsync(KeySymbols.Return, isPressed: false);鼠标事件尤其要注意现代UI里大家习惯直接监听MouseMove但在远程桌面场景下你要自己维护左键是否按下的状态因为拖动操作必须拆成一串“按下-移动-抬起”事件序列发送给远端。这个细节我后面在触摸设备落地时又踩了一遍。3. 跑通第一个最小可见的远程桌面理论概念过完之后直接上代码。我以一个WPF应用为例因为Windows下这个组合最典型。Linux、macOS的渲染层我会在后面的跨平台章节单独说。3.1 从NuGet引用到创建连接首先安装包dotnet add package MarcusW.VncClient然后创建客户端实例并建立连接。需要说明的是不同版本的方法签名可能略有差异有的版本用Uri传入连接地址有的版本直接传Host和Port以你实际拉到的NuGet包版本对应为准。var client new VncClient(); var settings new VncConnectionSettings { Password password, // 如果服务端支持TLS可以配置加密参数 }; await using var connection await client.ConnectAsync(192.168.1.10, 5900, settings);3.2 把帧缓冲写到WPF控件上WPF里渲染连续图像推荐用WriteableBitmap而不是每次创建新的BitmapSource。WriteableBitmap可以复用像素缓冲区避免频繁分配托管对象造成GC压力。WriteableBitmap? bitmap null; private void OnFrameBufferUpdated(object? sender, FrameBufferUpdatedEventArgs e) { var fb e.FrameBuffer; Dispatcher.Invoke(() { // 第一次更新时根据帧缓冲尺寸创建位图 if (bitmap null || bitmap.PixelWidth ! fb.Width || bitmap.PixelHeight ! fb.Height) { bitmap new WriteableBitmap(fb.Width, fb.Height, 96, 96, PixelFormats.Bgra32, null); RemoteImage.Source bitmap; } // 帧缓冲数据写入位图 bitmap.Lock(); // 这里将fb的像素数据复制到bitmap.BackBuffer // 注意处理Stride和像素格式转换 bitmap.AddDirtyRect(new Int32Rect(e.X, e.Y, e.Width, e.Height)); bitmap.Unlock(); }); }有一个坑必须提醒FrameBufferUpdated事件大概率不是UI线程触发的所以在WPF里更新控件必须用Dispatcher跳线程。你要是图省事直接在事件里操作控件程序会随机性抛异常而且只在画面刷新量大的时候复现非常难查。3.3 别忽略帧缓冲更新请求RFB协议的主动方在客户端你不发送FramebufferUpdateRequest服务端默认不会持续推画面。MarcusW.VncClient内部有自动请求逻辑多数情况下你不用管。但如果你要做手动控制比如只在界面可见时才请求画面需要关掉自动请求然后自己周期性调用请求方法。var request new FramebufferUpdateRequest { IsIncremental true, X 0, Y 0, Width (ushort)fb.Width, Height (ushort)fb.Height }; await connection.RequestFrameBufferUpdateAsync(request);这里有个“为什么”值得展开Incremental为true的意思是“只发送相对于上次的变化区域”适合静态画面居多的场景为false则是强制全屏刷新。如果你无脑用false高频请求远程桌面的流畅度会急剧下降因为服务端每次都要重新编码整个屏幕。正确做法是常规刷新用增量只在窗口尺寸变化、画面花屏等场景下强制发一次全量请求。4. 性能调优实测远不只是把像素拷出来画面能出来是一回事跑得流畅是另一回事。远程桌面的性能瓶颈往往不在库本身而在你接入渲染层和转发像素数据的那条链路上。下面这几个调优点我都是拿实际项目测过对比过的。4.1 编码器和色彩深度决定带宽下限RFB协议支持多种编码方式常见的包括Raw、Tight、Zlib、Hextile等。MarcusW.VncClient会和服务端协商可用的编码器但你可以通过设置影响协商结果。我实测过三种典型场景场景Raw编码Tight编码结论局域网内画面变化少流畅CPU占用低同样流畅但远程端CPU略高Raw够用局域网内高频滚动/视频带宽占用高可能卡画面流畅压缩率优势明显选Tight跨网络/弱网基本不可用勉强可用延迟可感知必须压缩编码直观感受是局域网里Raw编码足够快牺牲一点带宽换最低的CPU开销但只要跨公网或者WiFi环境一般Tight这种带压缩的编码几乎是必须的。Tight编码的代价是服务端和客户端都要花CPU做压缩解压如果远端机器性能很弱反而会拖慢整体响应。色彩深度也要重视。默认32位真彩画质最好但对带宽不友好。如果只是看终端窗口、文本界面改成16位甚至8位带宽能降一半以上。这个在弱网场景下效果立竿见影画面肉眼看得出渐变色的色阶断层但看代码和终端毫无压力。4.2 从帧缓冲到UI控件拷贝次数是性能大头我见过最典型的性能事故每次FrameBufferUpdated事件里都new一个Bitmap然后再画到界面上。这会导致两个问题一是触发大量托管对象分配GC频繁二是WPF的BitmapSource在UI线程上创建跨线程和频繁创建都会拖慢渲染。MarcusW.VncClient本身在底层用了缓冲池和Span来降低拷贝但数据交到你手上之后链路就归你管了。我的经验是复用一个WriteableBitmap只在分辨率变化时重建用bitmap.Lock/Unlock直接写BackBuffer而不是走BitmapConverter转换帧缓冲数据到位后只在DirtyRect区域标记失效别整屏重绘这里还牵涉到像素格式转换。VNC服务端推过来的可能是24位RGB而WPF WriteableBitmap要的是32位BGRA这个转换没法避免但要用高效的指针拷贝或SIMD优化类库不要用逐像素的Bitmap.GetPixel/SetPixel——那种写法慢到想砸键盘。4.3 把GC压力控制住画面才不抖远程桌面是典型的“高频次、大对象”场景。一帧1080p的帧缓冲就按MB算如果每次更新都产生大块堆内存LOH大对象堆很快就会涨起来。MarcusW.VncClient内部用的缓冲池能挡掉一部分但你自己接到数据后如果又复制一份做转换GC压力就全回来了。我后来调整了几个习惯事件参数里的帧缓冲对象不长期持有引用需要保留的数据尽快拷贝到自己的缓冲区渲染层的像素缓冲区用数组池或者自行管理的内存块复用而不是每次new byte[width * height * channels]避免在更新事件里大量使用LINQ产生临时对象这些调整做完同样一条链路GC频率肉眼可见地降下来画面刷新也稳了。5. 跨平台落地时真正扎手的地方这库卖点是跨平台但“库跨平台”和“你的完整方案跨平台”是两码事。我先后在Windows、Linux、部分ARM设备上折腾过有几处坑很值得记录下来。5.1 Linux下的渲染层和输入坐标系Windows有WPF、WinFormsUI框架成熟接入WriteableBitmap几乎无障碍。到了Linux第一个要决定的就是渲染用GTK还是SkiaSharp。GTK#在.NET生态里维护状态一般SkiaSharp更省心回退方案也多。我的做法是封装一个IImageRenderer接口Windows实现用WriteableBitmapLinux实现用SKSurface上层业务代码完全不用改。Linux下另一个容易被忽略的坑是Wayland。现在很多发行版默认用Wayland窗口管理器对子窗口嵌入、光标位置、缓冲区交换策略的处理和X11差异很大。当时我在Wayland会话里远程画面能显示但鼠标位置总是偏移最后定位到是分辨率缩放和坐标系转换问题。如果条件允许生产环境我建议先用X11等Wayland周边生态彻底成熟了再切。5.2 触摸设备上的鼠标事件映射前面提过拖动事件序列的问题在手机上这个问题会被放大。手机上用户手指滑动系统给的是触摸点坐标和触摸状态但VNC服务端只认鼠标按键。所以需要自己维护状态机手指按下时发送左键按下手指移动时持续发送移动事件手指抬起时发送左键抬起。MarcusW.VncClient的SendPointerEvent方法参数和这套逻辑刚好能对上但转换逻辑得自己写。还有一个很实际的需求把手指移动解释成鼠标移动还是鼠标滚轮不同场景需求不一样。看代码列表时要精细移动看网页时希望上下滚动。这个我在应用里做了一个切换开关用户体验比自动判断靠谱得多。5.3 键盘映射和中文输入的琐碎问题跨平台键盘映射也是个坑。RFB协议里传的是X11 KeySym值C#里要正确转换Windows虚拟键和KeySym就需要对照表。字母数字键没问题到了CtrlAltDel、Win键、甚至中文输入法组合键问题就来了。我当时的处理方案是本地先处理IME组合最终只把实际的字符结果发往远端而不是把用户的每个按键原封不动转发。不然中文输入法候选框在本地弹出来了远端也会收到一串莫名其妙的键码。剪贴板同步同样有回环风险你从远程窗口复制内容同步到本地剪贴板之后监听本地剪贴板变化再发回远端一个不小心就形成“复制-再复制”的循环。MarcusW.VncClient暴露的剪贴板事件本身没问题但应用层接入时必须加一个标志位判断当前剪贴板变化是不是自己写进去的。6. 集成到真实系统半年后的几点体会代码能跑通、性能也达标这只是开始。真正把远程画面功能集成进生产系统后还有一堆“离文档很远”的事情我觉得比API用法更值得分享。6.1 断线重连策略要提前设计VNC连接极其容易断远端机器重启、网络波动、服务端重启、长时间空闲被杀。MarcusW.VncClient在连接断开时会把连接对象标记为Disconnected状态并触发相应事件但不会帮你自动重连。我建议从一开始就实现指数退避的重连机制不然真到运维现场你会被“用户问为什么画面黑了”这类问题淹没。private async Task ReconnectWithRetryAsync(VncClient client, string host, int port, VncConnectionSettings settings) { var delay TimeSpan.FromSeconds(1); while (!_cancellationToken.IsCancellationRequested) { try { _connection?.Dispose(); _connection await client.ConnectAsync(host, port, settings); return; } catch (Exception ex) { _logger.LogWarning(ex, Reconnect failed, retry after {Delay}, delay); await Task.Delay(delay, _cancellationToken); if (delay TimeSpan.FromSeconds(30)) delay delay.Add(delay); // 指数退避 } } }6.2 安全配置密码和TLS都不能省VNC默认走VNC Password认证密码是明文或者弱混淆在网络上传输的只要有人抓包就能还原。MarcusW.VncClient支持TLS加密连接前提是服务端也开启对应的安全类型。我的建议是只要服务端支持TLS就一定要开启密码不要硬编码在配置文件里用环境变量或者密钥管理服务去读。尤其当你做的工具要连接公网机器时明文VNC密码意味着任何人都能截获你的远程画面这个风险不值得冒。6.3 日志和版本更新的经验排查握手阶段的疑难杂症时日志是最有力的武器。MarcusW.VncClient支持把内部日志接到ILogger上这个能力关键时刻能救命。有一次对方的环境怎么都连不上安全类型协商总是失败靠库的日志一步步看最后定位到对方TightVNC版本太老对TLS安全类型的扩展支持不完整换回VNC Password认证立刻就好了。没有日志这种跨协议版本的诡异问题排查起来就是大海捞针。另外提醒一句这库迭代速度不慢升级版本时建议看下Release Notes再动。我有一次从旧版本升上来某些方法签名变了编译期直接报错倒是好事最怕的是行为上的调整比如自动请求策略、剪贴板同步默认开关这种不仔细看文档根本发现不了线上才会出问题。做了大半年之后我最大的后悔是没早点把帧缓冲更新的日志统计加上。当时被弱网卡顿问题折腾了两天加了日志才发现问题根本不在协议层而是远端服务器用了一块很旧的网卡带宽被其他业务吃满了。远程桌面这东西链路越长越要提前把观测手段做全库本身性能再好应用层也要有随时能排查问题的抓手。本文还有配套的精品资源点击获取