EPLAN API 插件开发实战：从脚本到插件，电气设计自动化避坑指南

简介这份资源是面向电气设计自动化开发者的 EPLAN API 插件开发实例包适合具备 C# 与 .NET 基础、希望基于 Eplanapi 接口库扩展 EPLAN 电气设计软件功能的工程师参考。项目围绕 EPLAN.EplAddin.JMC 插件展开涉及工程数据访问、元器件与接线图操作、自动生成报告、批量修改项目、外部数据库集成以及图形绘制、自定义缩放逻辑与界面资源美化等方向可帮助读者理解插件从项目结构到功能实现的完整思路。压缩包共 137 个文件约 8.72MB以 72 个 dll 动态库、22 个 cs 源码、11 个 xml 配置、6 个 resx 与 6 个 resources 资源文件为主另含 bmp、ico 等界面素材及 sln、csproj 工程文件目录结构便于按模块查阅。目前已有 370 人学习下载适合作为 EPLAN 二次开发与插件定制的实践参考。1. 从一份 EPLAN API 插件包说起电气设计自动化到底能省下多少重复劳动如果你做过成套电气柜的图纸大概率经历过这种循环项目里新增了三十个同型号的断路器你得一个个改设备标识符、一个个填部件编号、一个个对齐端子排连接点。改完发现客户临时换了品牌于是全部推倒重来。EPLAN API 存在的意义就是把这套循环交给脚本。标题里的drawny2t、scalezj2这类命名通常是插件作者自己的模块缩写eplanapi指向的是 EPLAN 平台对外暴露的二次开发接口而eplan项目插件说明它不是一个独立工具是挂在 EPLAN 里跑的扩展。这篇文章不讲空泛的自动化趋势只讲一件事拿到一份 EPLAN API 插件工程怎么读懂它、跑起来、改出自己要的功能以及哪些地方最容易翻车。适合已经会用 EPLAN 画图、但没写过插件的电气工程师也适合想接 EPLAN 二次开发单子的程序员。2. EPLAN API 的开发模型先搞清楚你在跟谁打交道2.1 三种扩展形态选错了后面全是坑EPLAN 的二次开发不是只有一条路。常见做法有三种选型直接决定你后面写代码的手感。第一种是脚本Script用 C# 或 VB.NET 写成通过 EPLAN 的脚本对话框直接执行。它适合一次性任务比如批量改属性、导出报表。优点是启动快、调试简单缺点是没法做复杂界面也没法常驻。第二种是插件Add-in编译成 DLL注册到 EPLAN 的Add-ins目录启动时加载。它能挂菜单、开窗口、监听事件标题里说的eplan项目插件基本指这一类。插件适合做长期使用的工具比如自动生成端子图表、批量校验部件库。第三种是外部程序通过 API 远程调用EPLAN 提供了一套基于 COM 或 .NET Remoting 的接口外部进程可以连上去操作项目。这种模式适合做批处理服务器但配置复杂权限和版本匹配问题多。我一般建议先写脚本验证逻辑逻辑稳定了再包成插件。直接上插件调试成本会让你怀疑人生。2.2 核心对象模型项目、页、设备、属性不管用哪种形态你操作的都是同一套对象模型。理解这四个层级API 就懂了一半。Project一个.elk项目文件所有操作的根。Page图纸页按页类型分比如原理图页、总览页、端子图页。Function / Device页上的设备一个断路器、一个端子、一个 PLC 点都是设备。Property设备上的属性比如设备标识符、部件编号、连接点数量。API 里大量操作本质是找到对象 → 读属性 → 改属性 → 写回。难点不在改在怎么高效地找到对象。用SelectionSet拿当前选中的用Project.Pages遍历所有页用过滤器按页类型或属性筛选。遍历全项目在大型项目里很慢能缩小范围就缩小。2.3 最小可运行脚本批量给选中设备加前缀下面这段 C# 脚本演示最核心的流程拿选中集、遍历、改属性、刷新。这是所有插件的骨架。// 引入 EPLAN 命名空间版本号按你本机安装的 EPLAN 版本调整 using Eplan.EplApi.ApplicationFramework; using Eplan.EplApi.DataModel; using Eplan.EplApi.Base; public class AddPrefixAction : IEplAction { public bool Execute(ActionCallingContext ctx) { // 1. 拿到当前项目 Project oProject new ProjectManager().CurrentProject; if (oProject null) return false; // 2. 拿当前选中的对象集合 SelectionSet oSel new SelectionSet(); if (oSel.SelectionSetSize 0) return false; // 3. 遍历选中对象只处理 Function 类型 foreach (StorableObject oObj in oSel) { Function oFunc oObj as Function; if (oFunc null) continue; // 4. 读原标识符加前缀后写回 string oldName oFunc.Name; oFunc.Name PREFIX_ oldName; // 5. 锁定属性防止被后续操作覆盖 oFunc.LockObject(); } // 6. 刷新项目显示 oProject.Refresh(); return true; } public void GetActionName(ref string strActionName) { strActionName AddPrefixAction; } }逻辑说明SelectionSet是插件和用户交互最自然的入口用户选什么你处理什么避免全项目遍历。Function是设备在 API 里的基类Name属性对应界面上的设备标识符。LockObject()这一步很多人省掉结果发现改完又被 EPLAN 的自动编号覆盖回去这是血泪经验。参数说明CurrentProject在没打开项目时返回 null必须判空。SelectionSetSize为 0 时直接返回避免空遍历。前缀字符串建议从配置文件读硬编码在代码里后期改起来要重新编译。2.4 插件注册让 EPLAN 启动时认识你的 DLL脚本能跑通后包成插件需要多两步编译成 DLL写注册信息。!-- 放在 EPLAN 安装目录的 Add-ins 文件夹下文件名与 DLL 同名 -- Addin NameMyEplanPlugin/Name AssemblyMyEplanPlugin.dll/Assembly ActionAddPrefixAction/Action MenuText批量加前缀/MenuText MenuPath工具/我的插件/MenuPath /Addin逻辑说明EPLAN 启动时扫描Add-ins目录下的 XML按Assembly加载 DLL按Action找到入口类按MenuPath挂到菜单栏。MenuText是用户看到的菜单名。参数说明MenuPath用斜杠分层路径不存在 EPLAN 会自动创建。DLL 的编译目标框架必须和 EPLAN 版本匹配EPLAN 2022 之后基本是 .NET Framework 4.8用错框架会加载失败且报错信息很模糊。3. 从零跑通一个 EPLAN 项目插件环境、编译、调试3.1 环境准备版本匹配是第一道坎EPLAN API 最大的坑不是代码是版本。API 的 DLL 随 EPLAN 安装路径通常在C:\Program Files\EPLAN\Platform\版本\Bin。你的工程必须引用这个目录下的Eplan.EplApi.*.dll而不是从 NuGet 随便拉一个。常见做法是在 Visual Studio 里新建类库项目目标框架选 .NET Framework 4.8然后手动添加对以下 DLL 的引用DLL 名称作用Eplan.EplApi.ApplicationFramework动作、菜单、命令入口Eplan.EplApi.DataModel项目、页、设备、属性对象Eplan.EplApi.Base基础类型、路径、设置Eplan.EplApi.HEServices导出、打印、报表等高层服务引用时把Copy Local设为 False因为这些 DLL 运行时由 EPLAN 提供复制到输出目录反而会引起版本冲突。3.2 编译与部署DLL 放哪、XML 怎么写编译成功后把 DLL 和同名 XML 一起放到 EPLAN 的Add-ins目录。这个目录的位置取决于安装方式常见路径是C:\Program Files\EPLAN\Platform\版本\Add-ins\如果 EPLAN 装在非系统盘或者用了多用户配置路径可能不同。稳妥的办法是在 EPLAN 里点选项 → 设置 → 用户 → 显示 → 目录看 Add-ins 的实际路径。部署后重启 EPLAN菜单栏应该出现你配置的菜单项。没出现的话按顺序排查XML 文件名是否和 DLL 一致、Assembly字段是否只写文件名不写路径、DLL 是否被系统锁定。3.3 调试附加到进程比断点更可靠插件调试不能直接 F5因为宿主是 EPLAN。正确姿势是在 Visual Studio 里打开你的插件工程设好断点。启动 EPLAN打开一个测试项目。在 VS 里点调试 → 附加到进程找到EPLAN.exe附加。在 EPLAN 里点你的菜单项断点命中。注意如果 EPLAN 启动时已经加载了旧版 DLL你重新编译后必须重启 EPLAN 才能加载新版。热替换在 EPLAN 插件里基本不可行别浪费时间。3.4 一个实用例子批量导出端子图表下面这段代码演示用HEServices导出当前项目的端子图表为 PDF。这是电气设计里高频需求。using Eplan.EplApi.ApplicationFramework; using Eplan.EplApi.DataModel; using Eplan.EplApi.HEServices; public class ExportTerminalAction : IEplAction { public bool Execute(ActionCallingContext ctx) { Project oProject new ProjectManager().CurrentProject; if (oProject null) return false; // 1. 创建导出服务实例 Export oExport new Export(); // 2. 设置导出格式为 PDF oExport.Format Export.FormatType.PDF; // 3. 设置输出路径建议从项目属性读不要硬编码 string outputPath D:\Export\Terminal.pdf; // 4. 设置导出范围只导端子图页 oExport.PageFilter PAGE_TYPE TERMINAL; // 5. 执行导出 oExport.DoExport(oProject, outputPath); return true; } public void GetActionName(ref string strActionName) { strActionName ExportTerminalAction; } }逻辑说明Export类封装了 EPLAN 的导出能力Format决定输出格式PageFilter用 EPLAN 自己的过滤语法筛选页。DoExport是同步调用大项目会卡界面生产环境建议放后台线程。参数说明PageFilter的语法参考 EPLAN 帮助里的过滤器章节常用字段有PAGE_TYPE、PAGE_NAME、PROPERTY_xxx。输出路径如果目录不存在DoExport会抛异常提前用Directory.CreateDirectory建好。4. 避坑与排查EPLAN API 开发里最容易翻车的五件事4.1 现象插件加载后菜单不出现日志也没报错原因XML 里的Assembly字段写了完整路径或者 DLL 的目标框架和 EPLAN 不匹配。EPLAN 加载失败时经常静默跳过不弹错误框。解决Assembly只写文件名。用corflags工具检查 DLL 的框架版本确保是 .NET Framework 而非 .NET Core。在 EPLAN 启动参数里加/Debug可以看到加载日志。4.2 现象改了属性界面上没变化切页后才刷新原因API 改的是数据层界面层需要显式刷新。很多人以为改完自动同步结果以为代码没生效。解决改完属性后调用oProject.Refresh()或者对单个对象调oFunc.Refresh()。批量操作时在循环外调一次项目级刷新别在循环里调性能差十倍。4.3 现象遍历全项目设备时卡死大项目直接无响应原因Project.Pages返回所有页每页再遍历设备嵌套循环在几千页的项目里是灾难。解决用过滤器缩小范围。比如只处理原理图页oProject.Pages.Where(p p.PageType PageType.Schematic)。能用SelectionSet就用选中集让用户先选再处理。实在要全遍历放后台线程并加进度提示。4.4 现象设备标识符改完又被自动改回去原因EPLAN 的自动编号功能在后台运行你改完它按自己的规则重排。这是最隐蔽的坑。解决改之前调oFunc.LockObject()锁定对象或者临时关闭自动编号oProject.Settings.SetBool(USER.AUTONUMBERING.ACTIVE, false)改完再恢复。锁定更安全不影响其他操作。4.5 现象导出 PDF 时中文乱码或字体丢失原因EPLAN 导出用的字体依赖系统字体库服务器环境往往缺字体。另外导出路径含中文时某些版本会出问题。解决服务器上装全常用中文字体。导出路径用纯英文或者确认 EPLAN 版本支持 Unicode 路径。导出前在 EPLAN 里手动导一次确认字体正常再写代码。5. 进阶把插件做成可配置、可复用的工具5.1 配置外置别把参数写死在代码里前面几段代码里前缀字符串、导出路径都是硬编码。实际项目里这些必须外置。常见做法是读 EPLAN 项目属性或者读一个同目录的 XML/JSON 配置文件。// 从项目属性读配置属性名在 EPLAN 里预先定义好 string prefix oProject.Properties[MyPlugin.Prefix].ToString(); if (string.IsNullOrEmpty(prefix)) prefix DEFAULT_;逻辑说明EPLAN 项目属性支持自定义字段在项目属性对话框里可以手动加也可以用 API 写。这样配置跟着项目走换项目自动换配置比外部文件更省心。参数说明属性名建议加命名空间前缀避免和 EPLAN 内置属性冲突。读之前判空给默认值防止属性不存在时抛异常。5.2 用事件监听做自动化项目保存时自动校验插件的高级用法是监听 EPLAN 事件在特定时机自动执行。比如项目保存时自动校验设备标识符是否重复。// 在插件初始化时注册事件 oProject.OnSave new Project.SaveEventHandler(OnProjectSave); private void OnProjectSave(Project oProject) { // 遍历所有设备检查标识符重复 var duplicates oProject.Pages .SelectMany(p p.Functions) .GroupBy(f f.Name) .Where(g g.Count() 1); foreach (var group in duplicates) { // 把重复项写进项目备注或弹窗提示 new Decider().Decide( Decider.DecisionType.OK, $发现重复标识符{group.Key}共 {group.Count()} 处); } }逻辑说明OnSave是项目级事件保存前触发。GroupBy加Where是找重复项的标准写法。Decider是 EPLAN 的弹窗服务比MessageBox更贴合 EPLAN 界面风格。参数说明事件处理里不要做耗时操作否则保存会卡住。校验逻辑复杂的话只做轻量检查详细报告异步生成。5.3 验证插件是否真的生效三个检查点写完插件别急着交付按这三个点验证第一功能验证拿一个真实项目跑一遍对比操作前后的数据。比如批量改前缀导出设备清单对比。第二边界验证空项目、单页项目、超大项目各跑一次。空项目不崩大项目不卡死才算合格。第三回滚验证改错了能不能撤销。EPLAN 的撤销栈对 API 操作支持有限重要操作前建议先备份项目文件。我一般会在插件里加一个操作前自动备份的选项默认开启。5.4 一个我踩过的坑别在循环里创建对象早期写插件时我在遍历设备的循环里new了一堆临时对象结果大项目跑到一半内存爆了。EPLAN 的 API 对象很多是非托管资源new出来不释放会累积。后来改成在循环外创建可复用的对象循环内只改变量内存曲线立刻平稳。这个教训让我养成了一个习惯写 EPLAN 插件时先想清楚哪些对象能复用再动手。希望帮到你。本文还有配套的精品资源点击获取