这几年在 Windows 桌面办公生态里摸爬滚打我越来越觉得 C# 和 WPS 插件开发其实是一块被低估的宝地。很多人一提到 WPS 二次开发第一反应就是 VBA 宏或者只能等 WPS 开放更多 JS API但真正想要做带独立界面、能复用 .NET 生态、又能像正规软件一样安装部署的工具C# 走 COM 加载项这条路是最稳的也是投入产出比最高的。这篇文章我会从零开始把我实际踩过的坑、总结出来的流程以及一套可以直接改来用的完整代码结构全部拆给你看目标是让你看完就能动手把第一个正经的 WPS 插件跑起来。我打算用“给 WPS 文字加一个侧边栏批量水印工具”这个场景作为主线因为水印功能足够典型涉及 Ribbon 按钮、任务窗格、文档遍历、COM 注册这些核心环节麻雀虽小五脏俱全。你在实际项目中要做的批量签名、批注导出、格式检查套路完全一样把代码里的业务逻辑换掉就行。动手之前先看三条技术路线的底气与天花板WPS 二次开发目前常见的有三条路线VBA 宏、JS API 加载项、C# COM 加载项。很多人一上来就纠结选哪个其实不用纠结看清适用场景就行。VBA 宏适合个人自动化脚本比如录一段操作、写个宏批量改格式但它有两个硬伤一是 WPS 个人版对 VBA 的支持很有限必须装 WPS 专业版或者单独装 VBA 组件才能流畅跑二是 VBA 的 IDE 调试体验停留在“上古时代”变量跟踪、断点、异常信息都不友好稍微复杂的业务逻辑写起来特别费劲。你要是只在当前机器上用又不想折腾编译和发布VBA 可以但想做成工具分发给别人用VBA 就撑不住了。JS API 加载项是 WPS 2019 之后主推的跨平台路线本质上是用 HTML/CSS/JS 开发网页然后挂到 WPS 的 WebView 里跑。好处是界面漂亮、跨 Windows/Linux 平台坏处是它和 WPS 文档内核的交互深度有限很多操作要绕道而且对本地文件系统、硬件设备、外部进程的控制能力弱。适合开发那种“对外展示型”的辅助面板不适合做高强度的本地文档批处理工具。C# COM 加载项走的是 IDTExtensibility2 接口直接以进程内 DLL 的方式被 WPS 加载可以拿到完整的 Application 对象模型能弹原生的 WinForms 窗体能调用任何 .NET 库还能通过 System.Diagnostics 控制外部工具。这才是“外挂级”的插件方案的底气。缺点是注册表配置稍微敏感位数必须和 WPS 一致另外发布时要做强名称签名但这些问题都有成熟解法我在下面都会讲到。所以我的结论很明确如果你要做一个给多人使用的、带界面的、逻辑复杂的办公自动化工具C# COM 加载项是首选。这也是本文主讲的方案。环境搭建的四个关键准备项2.1 安装清单我先说一次完整的软件准备清单照着装就行Windows 10 或 Windows 1164 位系统为主WPS Office 2019 之后任意版本建议 64 位专业版Visual Studio 2022 Community勾选“.NET 桌面开发”工作负载.NET Framework 4.8 开发包VS 默认会带一个让你能随时查看注册表的工具系统自带的 regedit 就够了WPS 版本这里特别提醒一下个人版和专业版在插件接口层面没有本质区别但专业版更稳定而且对 VBA、宏权限、注册表加载项的兼容性更好。如果你在单位内部部署尽量申请专业版授权能省掉很多“为什么别人机器上跑不起来”的麻烦。另外装 WPS 的时候安装向导里有个“兼容第三方插件”之类的选项不同版本叫法不太一样尽量勾上。这个选项在部分版本里会影响 WPS 是否主动扫描 COM 加载项。2.2 一个必须提前建立的认知位数匹配WPS 有 32 位和 64 位两个分支你的插件 DLL 编译目标必须和 WPS 主程序位数一致。如果 WPS 装的是 32 位而你编译了一个 AnyCPU 或者 x64 的 DLLWPS 在加载时会直接忽略注册表里看似写好了实际就是没反应。反过来也一样。最稳妥的做法是让你的插件项目编译目标设为 x86因为很大比例的个人版 WPS 即使装在 64 位系统上默认也是 32 位安装版本x86 的 DLL 在 32 位和 64 位进程中都能通过 WOW64 机制被 32 位进程加载而 x64 DLL 只能在 64 位程序里跑。如果你明确知道自己装的是 64 位 WPS那编译目标就选 x64。我个人的习惯是统一推荐用户装 64 位 WPS插件也编译成 x64这样内存和性能都更省心。但为了兼容不确定的环境你可以同时产出 x86 和 x64 两个安装包。2.3 创建项目时的几个开关打开 Visual Studio新建项目时选“类库(.NET Framework)”注意不是 .NET Core/.NET 5 的类库因为 COM 加载项需要 .NET Framework 的注册表互操作机制.NET Core 走的是另一套 ComHostWPS 对这种加载方式的支持不如传统方案稳定。项目名称我建议起一个有意义的名字比如 WpsWatermarkAddin因为程序集名会和生成出来的 DLL 文件名挂钩后面注册时要引用。建好项目后需要把这几个配置打开项目属性 - 应用程序 - 程序集信息 - “使程序集对 COM 可见”勾上生成事件里加上强名称签名我会在项目属性 - 签名里直接新建一个 snk 文件目标框架选 .NET Framework 4.8如果 WPS 运行环境比较老旧可以降到 4.6.2强名称签名这一步很多新手会忽略但它很关键。WPS 加载 COM 加载项时会对程序集做完整性校验没有强名称的 DLL 在某些安全策略下会被直接拒绝。你只需要在“签名”选项卡里勾选“为程序集签名”然后新建一个密钥文件就行VS 会自动处理好。从零实现C# 水印插件完整开发实录3.1 插件启动的入口实现 IDTExtensibility2IDTExtensibility2 是 COM 加载项的标准入口接口WPS 在启动时发现你的 DLL 注册到加载项列表后会在合适时机调用这个接口的方法。核心方法就三个OnConnection、OnDisconnection、OnStartupComplete。OnConnection 代表 WPS 开始加载插件OnStartupComplete 代表 WPS 界面初始化完成通常在后者里面做界面相关的初始化更安全因为此时文档对象已经就绪。接口定义在微软的 Extensibility 类型库里但为了少引一个 COM 依赖我直接用自定义方式定义等效接口这样代码更干净不依赖 Office 的主互操作程序集。定义一个 IAddinInterface里面声明这五个方法然后让主类实现它。下面是核心的 Connect 类代码框架using System; using System.IO; using System.Runtime.InteropServices; using System.Windows.Forms; namespace WpsWatermarkAddin { [ComVisible(true)] [Guid(A1B2C3D4-E5F6-4A5B-9C8D-1E2F3A4B5C6D)] [ProgId(WpsWatermarkAddin.Connect)] public class Connect : IDTExtensibility2 { private object _application; private AddinRibbon _ribbon; private WatermarkTaskPane _taskPane; public void OnConnection(object application, ext_ConnectMode connectMode, object addInInst, ref Array custom) { _application application; WriteLog(OnConnection called); } public void OnDisconnection(ext_DisconnectMode removeMode, ref Array custom) { WriteLog(OnDisconnection called); _taskPane?.Dispose(); } public void OnStartupComplete(ref Array custom) { WriteLog(OnStartupComplete called); _ribbon new AddinRibbon(_application); _ribbon.ShowPane OnShowPane; } public void OnAddInsUpdate(ref Array custom) { } public void OnBeginShutdown(ref Array custom) { } private void OnShowPane() { if (_taskPane null) _taskPane new WatermarkTaskPane(_application); _taskPane.Show(); } internal static void WriteLog(string message) { try { string logPath Path.Combine( Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), WpsWatermarkAddin, log.txt); Directory.CreateDirectory(Path.GetDirectoryName(logPath)); File.AppendAllText(logPath, $[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] {message}{Environment.NewLine}); } catch { } } } }这段代码里我故意保留了日志方法这是插件开发非常重要的基本功。COM 加载项没有 Console 给你打印信息WPS 也不会把异常弹给你所有问题只能靠日志。后面我会专门讲日志怎么设计。3.2 在 WPS 里加一个按钮自定义功能区接下来要让 WPS 界面上出现我们自己的按钮。WPS 文字和 Word 一样支持 Ribbon 扩展接口是 IRibbonExtensibility其中最关键的方法是 GetCustomUI返回一段 XML描述功能区和控件的布局。这段 XML 对大小写和命名空间特别敏感我见过很多人因为一个属性拼错导致整个功能区加载失败。我的方案是新增一个 AddinRibbon 类实现 IRibbonExtensibility。它的职责只有两个提供 Ribbon XML以及处理按钮点击回调。using System; using System.Runtime.InteropServices; namespace WpsWatermarkAddin { [ComVisible(true)] public class AddinRibbon : IRibbonExtensibility { public event Action ShowPane; private readonly object _app; public AddinRibbon(object app) { _app app; } public string GetCustomUI(string ribonID) { if (ribonID WPS.Writer || ribonID WPS文字) { return customUI xmlnshttp://schemas.microsoft.com/office/2009/07/customui ribbon tabs tab idtabWatermark label我的工具 group idgrpWatermark label水印工具 button idbtnShowPane label打开侧边栏 onActionOnShowPaneAction sizelarge/ /group /tab /tabs /ribbon /customUI; } return null; } public void OnShowPaneAction(IRibbonControl control) { ShowPane?.Invoke(); } } }实际的 Ribbon XML 里 often 需要把 ribbonID 写成 WPS 启动时传入的实际字符串不同版本的 WPS 对文字组件的 ID 命名可能略有不同常见的就是 WPS.Writer。如果你的插件想支持表格和演示分别对 WPS.Writer、WPS.Sheet、WPS.Slide 分支返回不同的 XML 就行甚至可以用同一个 tab 同时在三个组件里显示。3.3 侧边栏窗口WinForms 和 WPS 的融合WPS 官方推荐用任务窗格承载自定义界面但 COM 加载项里做任务窗格的接口在各个版本之间有差异为了稳定性我更倾向于用一个无边框的自定义 WinForms 窗口停靠在 WPS 窗口右侧。这种方案不依赖 WPS 的 TaskPane API兼容性更好界面自由度也更高。WatermarkTaskPane 类继承 Form设置 FormBorderStyle 为 NoneTopMost 属性按照情况开在 Load 事件里计算 WPS 主窗口的位置然后把窗体定位到主窗口右侧。为了拿到 WPS 主窗口句柄我们通过 _application 的 Hwnd 属性获取窗口句柄再用 Win32 API 的 GetWindowRect 拿到位置这里要注意多显示器场景坐标是屏幕坐标系直接用屏幕坐标定位就行。public class WatermarkTaskPane : Form { private readonly object _app; private TextBox _watermarkText; private NumericUpDown _fontSize; private Button _applyButton; private Button _removeButton; public WatermarkTaskPane(object app) { _app app; InitializeComponent(); StartPosition FormStartPosition.Manual; FormBorderStyle FormBorderStyle.None; Width 300; Height 500; } private void InitializeComponent() { _watermarkText new TextBox { Location new System.Drawing.Point(20, 20), Width 250 }; _watermarkText.Text 机密文件; _fontSize new NumericUpDown { Location new System.Drawing.Point(20, 60), Width 120, Minimum 10, Maximum 200, Value 72 }; _applyButton new Button { Text 插入水印, Location new System.Drawing.Point(20, 100), Width 100 }; _removeButton new Button { Text 清除水印, Location new System.Drawing.Point(130, 100), Width 100 }; _applyButton.Click (s, e) ApplyWatermark(); _removeButton.Click (s, e) RemoveWatermark(); Controls.AddRange(new Control[] { _watermarkText, _fontSize, _applyButton, _removeButton }); } private void ApplyWatermark() { try { dynamic app _app; dynamic doc app.ActiveDocument; dynamic shape doc.Shapes.AddTextbox( 0, 100, 100, 450, 180, Type.Missing, Type.Missing, Type.Missing); shape.TextFrame.TextRange.Text _watermarkText.Text; shape.TextFrame.TextRange.Font.Size (int)_fontSize.Value; shape.TextFrame.TextRange.Font.Color 0xAAAAAA; shape.TextFrame.TextRange.Font.Bold 0; // 0False, -1True shape.Fill.Transparency 0.6f; // 设置为浮于文字上方并旋转 shape.Rotation 45; Connect.WriteLog(Watermark applied); } catch (Exception ex) { MessageBox.Show(插入水印失败 ex.Message); Connect.WriteLog(ApplyWatermark error: ex); } } private void RemoveWatermark() { try { dynamic app _app; dynamic doc app.ActiveDocument; for (int i doc.Shapes.Count; i 1; i--) { dynamic shape doc.Shapes.Item(i); string name shape.Name ! null ? shape.Name.ToString() : ; if (name.Contains(Watermark) || name.Contains(文本框) shape.TextFrame.TextRange.Text.ToString() _watermarkText.Text) { shape.Delete(); } } Connect.WriteLog(Watermark removed); } catch (Exception ex) { MessageBox.Show(清除水印失败 ex.Message); Connect.WriteLog(RemoveWatermark error: ex); } } }这里我用 dynamic 调用 WPS 的对象模型原因是 WPS 的 COM 类型库和微软 Office 的对象模型相似但不完全一致直接用 dynamic 可以避免在编译期绑定具体的 COM 类型让代码在不同版本的 WPS 上都有更强的兼容性。代价是少了智能提示解决办法是写一个针对 WPS API 的封装类把你常用的对象操作都集中起来有问题只改一处。3.4 强名称签名、编译与 COM 注册代码写完后重点就是注册。COM 加载项要被 WPS 找到需要两个层面的注册第一层是把程序集注册为 COM 组件也就是把 CLSID 写进注册表这样 WPS 才能通过 CLSID 创建我们的 Connect 类实例。这一步可以用 Visual Studio 的“工具 - 命令行 - 开发者命令提示”运行 RegAsm 程序集路径 /codebase 来实现。/codebase 参数会在注册表里记录 DLL 的物理路径避免每次都要把 DLL 拷贝到系统目录。开发阶段用 codebase 最方便发布阶段再用安装包把 DLL 放到固定目录并调用 RegAsm。第二层是告诉 WPS“这个 COM 组件是我的加载项”。WPS 会在注册表固定位置扫描加载项列表常见的位置是HKEY_CURRENT_USER\Software\Kingsoft\Office\WPS\AddinsWLHKEY_LOCAL_MACHINE\Software\Kingsoft\Office\WPS\AddinsWL另一种常见结构HKEY_CURRENT_USER\Software\Kingsoft\Office\WPS\Addins具体键名和 WPS 版本有关我开发时习惯写一个注册表脚本同时在两个候选路径都写入记录不影响启动速度。记录里包含 LoadBehavior 值1 表示启动时加载9 表示按需加载且启动时尝试加载通常设成 1 最直接。Windows Registry Editor Version 5.00 [HKEY_CURRENT_USER\Software\Kingsoft\Office\WPS\AddinsWL\A1B2C3D4-E5F6-4A5B-9C8D-1E2F3A4B5C6D] FriendlyNameWPS 水印工具 DescriptionC# 开发的 WPS 水印插件 LoadBehaviordword:00000001 Manifestfile:///C:\\WpsWatermarkAddin\\WpsWatermarkAddin.dll这个 .reg 文件和 RegAsm 配合基本就能完成注册。注意 Manifest 那行的路径反斜杠要写成双反斜杠否则注册表不会正确解析。注册完毕之后打开 WPS 文字正常情况下“我的工具”选项卡就会出现点击“打开侧边栏”右侧会弹出自定义窗口。如果没出现先别急绝大多数情况都是注册表路径或位数不匹配导致的我在第五节专门整理了排查清单。让调试不再折磨人进程外调试与日志体系COM 加载项最让人头疼的就是调试因为 DLL 被 WPS 进程加载你不能像普通程序一样直接按 F5 启动。我的做法是先在 Visual Studio 里把项目设为 Debug 配置然后启动 WPS确保 WPS 已经注册并能够加载这个 DLL再用“调试 - 附加到进程”选择 wps.exe代码类型选“托管”和“本机”都勾上然后在 C# 代码里打好断点等 WPS 调用到对应代码时断点就会命中。这里有个坑WPS 启动时加载插件很快如果你附加进程晚了OnConnection 早就执行完了。所以在调试阶段可以把 LoadBehavior 改成 9这样 WPS 启动时不会强行加载插件而是等你点击按钮时才按需加载你就有充足时间附加进程。等需要断点 OnConnection 时再临时改成 1并且先启动 WPS再快速附加。日志体系必须从第一天就建立。方法就是我在 Connect 类里放的 WriteLog它把日志写到 LocalApplicationData 下的固定目录。所有入口方法都打点包括 OnConnection、OnDisconnection、按钮点击、异常捕捉。生产环境下用户报“插件没反应”第一件事就是让他把这个日志文件发过来。没有日志体系就等于盲人摸象。需要注意 WPS 可能会限制插件 DLL 写文件的位置如果权限不足日志目录写不进去WriteLog 里的异常被我吞掉了导致你什么信息都看不到。所以日志目录我特意选在 LocalApplicationData这是当前用户目录权限问题最少。实战中常见的坑与排查技巧我把自己做 WPS 插件过程中遇到最多的几个问题整理成一个排查表按出现频率排序现象常见原因解决方案插件完全不加载功能区没有按钮插件 DLL 位数和 WPS 不匹配确认 WPS 位数用 regedit 看加载项注册路径重新编译对应位数LoadBehavior 已设为 1 但仍不加载注册表路径写到了 HKCU 但 WPS 以管理员权限运行改用 HKLM 路径或让用户以管理员权限启动 WPS点击按钮没有任何反应Ribbon XML 的按钮 onAction 方法没有正确实现在 GetCustomUI 里打日志确认返回的 XML 结构完整工具栏出现了但点击后弹 COM 错误Connect 类没有保持引用GC 回收导致对象失效在 Connect 中声明类字段保存 Ribbon 和 TaskPane 引用水印插入到文档后WPS 偶发崩溃没有在主线程操作 COM 对象确保所有对 Application/Document 的调用在 WPS 主线程执行64 位系统上注册成功但仍加载失败没有用 64 位 RegAsm打开 VS 的开发者命令行确认 cmd 环境是 x64我再补充几个很隐蔽的点。第一个是 COM 对象的生命周期。在 WPS 里做动态调用时dynamic 变量是 COM 对象的 RCW 包装如果局部变量被释放COM 对象可能被回收导致后续操作崩溃或报“对象被标记为释放”。解法是在插件类字段里长期保留 DApplication 和 DActiveDocument 的引用或至少保留 Application 的引用文档对象可以在每次需要时重新获取。第二个点尤其值得记住WPS 的 COM 调用的线程单元必须是 STA也就是 WPS 主线程。如果你在 TaskPane 里用 background worker 后台线程去遍历文档十有八九会报“RPC 服务器不可用”或者干脆没有响应。后台任务只做数据和计算所有 COM 操作都要通过 Invoke 回到 UI 线程来做。这个我吃了不少亏后来在日志里看到线程 ID 才发现问题。第三个点是要检查杀毒软件和系统的勒索软件防护。这类安全软件经常拦截 DLL 注入进程WPS 是办公软件属于重点监控目标。如果你发现自己的插件在开发机正常、发给同事就消失先让同事把杀毒软件日志看一眼很可能 DLL 被隔离了。解决方式是发布时做数字签名或者把安装目录加白。发布和分发的最后一步功能调通后分发阶段反而最容易翻车。不能直接把 DLL 发给用户让用户手动注册用户体验太差而且很容易因为权限问题失败。我建议用 Inno Setup 做安装包在安装脚本里调用 RegAsm 完成注册卸载时调用 RegAsm /u同时清理注册表加载项路径下的键值。Inno Setup 脚本大致逻辑如下[Run] Filename: {dotnet4032}\RegAsm.exe; Parameters: WpsWatermarkAddin.dll /codebase; \ WorkingDir: {app}; Flags: runhidden Filename: regedit.exe; Parameters: /s watermark_addin.reg; \ WorkingDir: {app}; Flags: runhidden [UninstallRun] Filename: {dotnet4032}\RegAsm.exe; Parameters: -u WpsWatermarkAddin.dll; \ WorkingDir: {app}; Flags: runhidden安装完成后插件对用户来说就是“装一个程序打开 WPS 就能用”。这才能叫一个合格的工具。发布之前再检查一下这三件事一是程序集版本号有没有 bump如果更新 DLL 但版本号没变WPS 可能因为缓存原因一直加载旧版本我通常每次发布都改 AssemblyVersion二是强名称密钥文件有没有让研发同事统一管理别每个人生成一个 snk否则后患无穷三是日志目录的清理机制长时间运行会产生大量日志文件建议按天滚动或保留最近 N 个文件。我的一些体会说实话C# 开发 WPS 插件这个方向在社区里资料不算多而且很多资料停留在 VBA 层面导致大家以为 WPS 二次开发只能写宏。但真正常态化办公工具的思路还是应该用 C# 来做一个能长期演进、代码可测试、界面可控的 COM 加载项。虽然学习曲线比 VBA 陡一点但只要把 IDTExtensibility2、IRibbonExtensibility、COMM 注册这几件事琢磨透后面做任何办公自动化功能都会顺畅很多。我个人的建议是第一版不要追求大而全从一个小功能开始比如文档批量改名、给全文档的图片加边框、或者像我这样加个批量水印跑通全链路之后再逐步加模块。开发过程中把日志和注册表脚本这些基础设施先做好了后面能省大量排查时间。最后再分享一个小技巧如果你不确定当前 WPS 版本到底用的是哪个加载项注册表路径可以在 WPS 的“工具 - 选项 - 兼容设置”里看看有没有“启用第三方插件”相关开关同时用 Process Monitor 监控 wps.exe 启动时的注册表访问直接看它读了哪个路径。这个办法能让你从“盲猜”直接进入“实证”排查定位的效率高一个量级。