版本声明全系列统一口径本系列基线为AVEVA E3D Design 3.1。程序集、文档与产品版本必须一一对应跨版本引用接口会直接踩空。AVEVA PDMS 自 2024 年 4 月 1 日起不再销售、不再提供支持因此本系列不把 PDMS 作为新开发目标只在讲迁移时回到它。凡官方口径正文给出help.aveva.com的静态文档链接该站为静态 HTML正文可抓取、可核对凡来自 AVEVA Community 论坛或第三方博客的内容正文一律标注为社区来源/第三方来源不代表官方结论凡按官方 API 签名构造、但未在任何本机环境跑通的代码一律标注**“按官方 API 签名构造需在本地 E3D Design 环境验证”**。官方未公开的项官方示例下载页、独立的 Core / Core3D API 参考站、官方 GitHub 仓库等在正文中只写官方未公开不做任何推测性补全。一句话结论四条路不是同一件事的四种写法而是四层成本阶梯——PML1 宏最快几分钟出结果、PML2 最像做应用表单与对象、PML.NET 最擅长算法与外部库、.NET Addin 才能改界面并接进企业系统选型第一刀砍在要不要动界面第二刀砍在要不要复杂算法与外部依赖。〇认知问题AVEVA PDMS 已经停售停支持那我手上的 PDMS 定制代码还有意义吗新开发该对着哪个版本写PML1 和 PML2 是两种不同的语言吗新人应该先学哪一个我想在 E3D 界面上加一个自己的菜单和停靠窗口只用 PML 能做到吗我是 C# 程序员不懂管道业务能不能完全绕开 PML网上有人说E3D 15.x这是不是更新的版本我该不该追四条路可以混用吗混用时最容易踩的坑是什么一机制解析1.1 先把产品和版本钉死做二次开发第一条纪律是版本对齐。写错版本的接口名报错信息往往指向类型不存在而不是版本不对排查会非常耗时。产品层面的事实AVEVA E3D Design是当前在售的三维工厂设计产品官方产品页为 https://www.aveva.com/en/products/e3d-design/。它取代 AVEVA PDMS。AVEVA PDMS官方产品页已只剩退市通告——自 2024 年 4 月 1 日起PDMS 不再销售、不再提供支持研发投入全部转向 E3D Designhttps://www.aveva.com/en/products/aveva-pdms/。官方同时说明 E3D Design 仍与 PDMS 后续版本保持兼容客户可以两平台并行但 PDMS 最终会被淘汰。版本线帮助站上实测存在1.1 / 2.1 / 3.1三代 E3D Design 文档docs.aveva.com的版本索引把当前版本列为E3D Design 3.1。本系列统一以 3.1 为准遇到历史差异会显式标注。一个常见误解必须纠正15.x 不是 E3D Design 的版本而是 AVEVA Engineering 的版本。文档站会同时列出 “E3D Design 3.1” 与 “Engineering 15.8” 这类条目容易让人误以为 E3D 也走到了 15 版。实际在 E3D Design 上没有发现 15.x 的命名https://docs.aveva.com/bundle/system-platform-2023-r2-sp1。近年可核实的重大变更官方发布页 https://www.aveva.com/en/info/e3d-design-releases/**3.1.5.02022-04**引入Graphical Explorer只读三维导航视图并引入通过PMLNETCALLABLE对象把 Microsoft ML.NET 训练好的机器学习模型导入 AVEVA PML的能力Model 模块 Developer 标签页**3.1.4.02022-02**引入MultiCAD30 余种 CAD 格式导入可由命令行或 PML 对象调用支持批处理、Work Packs含 Visual Queries、Space Management以及 Rule Manager 扩展。需要留意的是该发布页只回溯到 2022 年 2 月2023–2026 的发布条目在公开页面上未找到——这意味着最新版有什么新 API这件事不能靠这个页面下结论。一句话基线认 E3D Design 3.1PDMS 只当历史15.x 与 E3D 无关。1.2 四条路各自是什么官方文档体系里有四本与二次开发直接相关的手册教程里会反复引用它们文档代号入口.NET Customisation User GuideNCUGhttps://help.aveva.com/AVEVA_Everything3D/3.1/NCUG/NCUG_FP.htmlPML Customisation User GuidePMLCGhttps://help.aveva.com/AVEVA_Everything3D/3.1/PMLPUG/PMLCG_FP.htmlSoftware Customisation对象/成员/方法总参考SCRMhttps://help.aveva.com/AVEVA_Everything3D/3.1/SCRM/SCRM_FP.htmlAVEVA CAF API 参考唯一公开的独立 API 参考站—https://help.aveva.com/API/CAF/index.html四条路的技术定位如下。路一PML1。PML 是AVEVA Programmable Macro Language。官方对 PML1 与 PML2 的关系有明确表述当前版本常称PML2可以视为对PML1能力的扩展但**“许多编程任务的做法不同”而有些任务用 PML1 更高效**https://help.aveva.com/AVEVA_Everything3D/3.1/PMLPUG/PMLCG2.02.1.html。PML1 的表达方式是命令 变量注入最典型的就是把宏当作一排按键回放。PML1 的表达式包在数据库手册DBRM里单独成章官方口径是一般来说这些设施与 PML 2 兼容https://help.aveva.com/AVEVA_Everything3D/1.1/DBRM/DBRM9.10.01.html。路二PML2。官方定义很清楚PML2 是面向对象语言专为定制 AVEVA 产品的 Forms and Menus 而设计窗体本身就是对象用全局变量表示例如!!EntryForm因此窗体名不能与其他对象、全局变量或窗体重名https://help.aveva.com/AVEVA_Everything3D/3.1/PMLPUG/PMLCG14.14.1.html、https://help.aveva.com/AVEVA_Everything3D/3.1/PMLPUG/PMLCG2.02.3.html。PML2 的文件类型按官方培训材料口径为.pmlfnc函数、.pmlfrm表单、.pmlobj对象依赖环境变量PMLLIB。路三PML.NET。官方原文的定位是“Through the use of PML.NET, an enhancement to PML which allows the PML programmer to call .NET code, customisation which utilizes the strengths of .NET compiled code and PML can be achieved.”也就是说PML.NET 是让 PML 调用 .NET 代码的增强机制而不是让 C# 反过来指挥 PML。它的价值点在于PML 负责熟悉模型数据C# 负责算法与外部库。路四.NET Addin。NCUG 把 .NET 定制分成两条路径.NET Addin与PML.NET官方强调两者都提供了一种在运行时把 .NET 程序集dll动态载入模块的机制并且定位是与既有的 PML 定制并存https://help.aveva.com/AVEVA_Everything3D/3.1/NCUG/NCUG1.02.02.html。.NET Addin 的判定标准是程序集内必须含有一个实现IAddin接口的类CAFCommon Application Framework加载时用反射找到该类、实例化它并调用IAddin.Starthttps://help.aveva.com/AVEVA_Everything3D/3.1/NCUG/NCUG2.03.02.html。1.3 四条路的对照表选型主表维度PML1PML2PML.NET.NET Addin本质上是什么命令语法的宏语言面向对象扩展为 Forms and Menus 设计PML 调 .NET 代码的桥运行时载入 dll 并接入 CAF编译成本零改文件即生效零需要 C# 编译需要 C# 编译能否加表单/界面基本不能无 PML2 对象体系能setup form、gadget不能它只负责被 PML 调用能Command UIC 文件 停靠窗口能否改 E3D 主界面菜单/工具栏不推荐不推荐不能能官方推荐做法复杂算法/外部库弱弱强.NET 全生态强数据访问方式命令与元素属性同 PML1C# 侧DbElement等C# 侧DbElement等主要风险命名冲突、写库不可逆窗体名与全局变量冲突命名空间必须写全版本与程序集引用推荐定位一次性宏、批处理回放内部小工具界面计算密集型任务交付级工具、企业系统对接1.4 官方写明的限制这些是选型的硬约束不要等踩了才回头改架构。官方文档里已经写死的限制有四条C# 不能直接调用 PML。NCUG 明确无法从 C# 直接调用 PML只能通过事件机制反向通知https://help.aveva.com/AVEVA_Everything3D/3.1/NCUG/NCUG5.07.1.html。这直接决定了架构方向PML 是主动方C# 是被调用方。如果你设想的方案是C# 主程序去驱动 E3D 干活按官方机制这条路是走不通的。只有标注PMLNetCallable的类与方法才会被 PML.NET 加载可见https://help.aveva.com/AVEVA_Everything3D/3.1/NCUG/NCUG5.07.2.html。代码写了却调不到十有八九是这个原因。USING NAMESPACE必须写完整命名空间不允许写部分命名空间该语法大小写不敏感。官方举例说明写USING NAMESPACE Aveva.Core之后再去object namespace.NETObject()会报错https://help.aveva.com/AVEVA_Everything3D/3.1/NCUG/NCUG5.07.3.html。不能把DIRECTION、ORIENTATION这类 PML 对象传给 .NET但数据库引用DB 引用可以以数组或字符串形式传递同上。另外官方还指出模块切换不保持 .NET 对象。还有一条与界面相关的官方态度必须记住PMLCG 的 Commands 章写明命令可以实现为PML command object或core command object通过.uic文件把工具与命令对象关联并且官方明确不建议从标签页按钮直接调用 PML 宏https://help.aveva.com/AVEVA_Everything3D/3.1/PMLPUG/PMLCG24.27.01.html。原因在于这与 command ribbon 的机制不兼容——旧式事件/工具栏方式虽然仍受支持但官方标注为不推荐NCUG 2.03.05 / 2.03.06。1.5 决策树按顺序问自己四个问题答案会直接落到某一条路上这一步是一次性的吗是 → 直接写 PML1 宏用完即弃不要去建工程。需要用户输入/选择/预览吗需要 → 上 PML2表单 对象但记住 gadget 有硬限制见 1.4 与后续表单篇。需要复杂算法、正则、外部库、机器学习模型吗需要 → 上 PML.NET把 C# 写成库用IMPORTUSING NAMESPACE调注意 C# 侧不能反向调 PML。需要出现在 E3D 界面菜单、工具栏、停靠窗口或与公司系统交互吗需要 → 上.NET Addin Command UIC 文件这是官方推荐做法。经验法则本系列一致口径纯数据搬运与格式整理优先用 PML需要复杂算法或外部库时再上 PML.NET 或 .NET Addin界面级功能一定走Command UIC。二完整代码与逐行剖析下面四段代码的目的是看见路的样子不追求功能完整。前三段出自官方培训材料/官方文档原文摘录第四段按官方 API 签名构造并已标注验证要求。2.1 路一PML1 宏官方培训材料原样NEW EQUIP /ABCD NEW BOX XLEN 300 YLEN 400 ZLEN 600 NEW CYL DIA 400 HEI 600 CONN P1 TO P2 OF PREV逐行剖析NEW EQUIP /ABCD在当前层级下新建一个名为ABCD的设备Equipment。注意名称以/开头这是给出元素名的写法。NEW BOX XLEN 300 YLEN 400 ZLEN 600在上一步创建的元素即当前元素之下新建一个长方体三个方向的长度分别是 300 / 400 / 600。这条命令的隐含前提是当前元素已经切到位——宏本质上就是命令回放谁当前命令就作用在谁身上。NEW CYL DIA 400 HEI 600新建圆柱直径 400、高 600。CONN P1 TO P2 OF PREV按官方培训材料的原样这是把连接点P1连到PREV上一个元素的P2上。这一行的教学价值在于让人看见PREV这类相对定位词是 PML1 宏的常用手法。运行方式官方培训材料口径$M/%PDMSUI%\examples\simpleMac.mac或更通用的$m/FILENAME。2.2 路二PML2 表单片段官方文档原文摘录setup form !!nameCE !this.formTitle |Name CE| button .button |Print Name Of CE| call |!this.print()| exit define method .print() q var !!ce.flnn endmethod逐行剖析setup form !!nameCE定义一个名为nameCE的窗体。窗体是对象用全局变量表示所以这里写的是!!nameCE——这也是窗体名不能与既有全局变量重名这条规则的技术根源。!this.formTitle |Name CE|!this指窗体自身formTitle是窗体标题属性|Name CE|是 PML 的字符串定界写法竖线包裹。button .button |Print Name Of CE| call |!this.print()| exit放一个按钮 gadget按钮上的文字是Print Name Of CEcall |...|后面是回调——官方原文说回调是以文本字符串形式提供的“可以是任何合法的 PML 表达式、PML 函数或方法调用包括任何窗体、gadget 或用户定义对象的方法”。exit表示这个按钮行为结束后关闭窗体。define method .print()…endmethod为窗体对象定义方法。方法体里q var !!ce.flnn是查询当前元素的flnn属性并把变量形式打印出来属于 PML 的调试型输出。注意方法体里操作的是!!ce全局当前元素而回调里写的是!this.print()窗体自身的方法。这一段最值得记住的是回调是字符串不是函数指针字符串里写什么就会被当作 PML 代码执行。2.3 路三PML.NET 的入口官方语法摘录IMPORT MyCompany.E3DExt USING NAMESPACE Aveva.Core.Samples -- 官方在说明不允许部分命名空间时给出的调用形式 -- object namespace.NETObject()逐行剖析IMPORT ...PML.NET 装载程序集的语法。装配件由 **PMLNetEngine** 用反射加载查找路径为 **%AVEVA_DESIGN_EXE% 目录、其子目录、映射驱动器或 UNC 路径**。USING NAMESPACE Aveva.Core.Samples指定命名空间大小写不敏感但必须写完整。写父级再去点取子对象官方明说会报错。object namespace.NETObject()官方文档里出现的调用形式用于说明命名空间解析规则。真正可调用的类与方法必须是被你自己的程序集里标注了PMLNetCallable的类与方法——程序集名与类名请替换成你自己的本段只示范语法骨架按官方 API 签名构造需在本地 E3D Design 环境验证。2.4 路四.NET Addin 骨架按官方 API 签名构造需在本地 E3D Design 环境验证usingAveva.ApplicationFramework;// AddinManager / ServiceManager / SettingsManagerusingAveva.ApplicationFramework.Presentation;// CommandManager 等// CAF 的判定标准程序集内必须有一个实现 IAddin 接口的类// 加载时由 CAF 反射查找、实例化并调用 IAddin.Start。// Start 的确切签名请以本地 NCUG 2.03.02 页与安装目录 Samples.zip 中的官方工程// ExamplesAddin / AttributeBrowserAddin 等为准此处按官方结构构造骨架。publicclassMyFirstAddin:IAddin{publicvoidStart(){// 1) 从服务容器取到 CAF 服务官方示例用 serviceManager.GetService(typeof(Xxx))// 2) 在这里注册自定义 Command、停靠窗口、UIC 文件// 3) 具体写法见官方 NCUG 的 Addin 与 Command 章节}}逐行剖析using Aveva.ApplicationFramework;CAF 的核心命名空间。官方文档给出的命名空间清单包含Aveva.ApplicationFramework含AddinManager、ServiceManager、SettingsManager与Aveva.ApplicationFramework.Presentation含CommandBarManager、CommandManager。public class MyFirstAddin : IAddin实现IAddin是 Addin 的准入条件。注意官方描述是反射找一个实现IAddin的类——不是靠配置文件里声明类名所以一个程序集里通常只放一个实现类避免歧义。Start()CAF 调用它一切初始化都发生在这里。装配件层面官方文档逐页实测存在的程序集名为Aveva.ApplicationFramework.dll、Aveva.ApplicationFramework.Presentation.dllCAF 两件套Aveva.Core.Database.dll、Aveva.Core.Database.Filters.dll数据访问Aveva.Core.Geometry.dll、Aveva.Core.Maths.Geometry.dll、Aveva.Core.Shared.dll、Aveva.Core.Utilities*.dll、Aveva.Core3D.Graphics.dll以及Aveva.Engineering.Tags.Pml.dll。AVEVA Standalone 专用的是Aveva.Core3D.Standalone、Aveva.E3D.Standalone。需要特别提醒的是代际陷阱历史版本文档PDMS 12.0 时代中出现的程序集名是Pdms.Database.dll、PDMSFilters.dll。官方未给旧→新的命名空间迁移对照表社区帖里流传的Aveva.Pdms.PMLNet→Aveva.Core.PMLNet、Aveva.Pdms.Presentation→Aveva.Core.Presentation、Aveva.Pdms.Presentation.PDMSCommands→Aveva.Core.Commands等映射仅为社区来源只能当线索不能当结论必须逐个在目标环境验证。三常见报错与排查下面三条都是选型选错导致的典型症状都按现象 / 原因 / 处置三段式给出。症状一C# 侧写完方法PML 侧IMPORT之后看不到它。现象PML 里IMPORT成功但调用时报找不到对象/方法。原因类或方法没有标注PMLNetCallable。官方规则是只有标注为 PMLNetCallable 的类与方法才会被考虑。处置给目标类与目标方法补标注重新编译确认 dll 落在%AVEVA_DESIGN_EXE%目录或其子目录也可以是映射驱动器或 UNC 路径。症状二USING NAMESPACE Aveva.Core之后取object namespace.NETObject()报错。现象与官方文档里不允许部分命名空间的描述完全一致的报错。原因把命名空间当成了可点取的层级。官方明确写不允许书写部分命名空间。处置一次写全例如USING NAMESPACE Aveva.Core.Samples大小写可以随意但层级不能省。症状三自定义菜单点下去没有任何反应。现象.uic里菜单项显示正常点击无响应。原因命令类没有设置Command基类的Key或者 UIC 里的引用与Key不一致。CAF 是用Key把 UI 与逻辑解耦关联的。处置在命令类构造函数里设置this.Key ...官方示例写法如this.Key Aveva.ShowAttributeBrowserCommand;并让 UIC 文件里的引用与之严格一致同时确认 dll 已注册到CommandManager.Commands。症状四思路性错误最容易返工架构设计成C# 主程序驱动 E3D。现象设计阶段就卡住——找不到从 C# 调 PML的接口。原因官方明确列出限制——无法从 C# 直接调用 PML只能通过事件机制反向通知。处置把主控方改成 PML或 PML.NET 触发C# 只做被调用的库与事件响应者。四动手练习练习 110 分钟判定标准可量化打开帮助站 https://help.aveva.com/AVEVA_Everything3D/3.1/PMLPUG/PMLCG_FP.html在目录里数出与对象/方法/表单/命令/Add-in相关的章节标题至少 5 个并抄写下来。合格判定抄下的标题能在 SHELL 对应章节中一一找到其中应当包含Form Concepts、Form and Gadget Callbacks、Commands、PML Add-ins这几个真实章节名。练习 220 分钟用手上的 E3D Design 环境打开Command Window官方路径Tools 标签 → Display 组 → 点击 Commands把本篇文章 2.1 节的四行宏逐行粘贴执行务必在测试 MDB 上做写库操作不可逆。合格判定NEW EQUIP /ABCD之后NEW BOX ...能挂到该设备下失败时记下完整报错文本。练习 315 分钟纯纸面用 1.5 的决策树给你手上的三个真实需求各选一条路并写出理由。合格判定三个需求中至少有一个落在.NET Addin一个落在PML1 宏且理由能引用本篇 1.3 表里的至少两个维度。练习 410 分钟在帮助站检索 “Console”记录命中数量再检索 “Command Window”。合格判定能复现检索 Console 零命中这一事实并在自己的笔记里写清官方入口名是Command Window。五小结与下一篇预告本篇钉死了三件事版本基线是 E3D Design 3.1PDMS 已停售停支持15.x 是 AVEVA Engineering 而非 E3D四条路的定位是宏 / 表单对象 / 让 PML 调 .NET / 改界面并接系统官方限制是不可绕的架构约束C# 不能直接调 PML、命名空间必须写全、只有PMLNetCallable可见、界面走Command UIC。下一篇《环境盘点与开发前自检》会把动手之前必须确认的东西一次列完Command Window 的确切打开路径、PMLLIB与四个 CAF 环境变量、安装目录里的Samples.zip、四本手册的入口以及一份可执行的自检清单——因为绝大多数代码没问题但就是跑不通根因都在环境。文末 FAQQ1AVEVA PDMS 已经停售停支持那我手上的 PDMS 定制代码还有意义吗新开发该对着哪个版本写有意义。官方说明 E3D Design 仍与 PDMS 后续版本兼容客户可以两平台并行PDMS 最终被淘汰所以存量 PDMS 定制代码是可以迁移的资产。但新开发应当对着AVEVA E3D Design 3.1写程序集、文档与产品版本必须一一对应。PDMS 两侧的关键差异是程序集与命名空间换代——PDMS 12.0 时代文档里是Pdms.Database.dll、PDMSFilters.dllE3D 侧是Aveva.Core.Database.dll、Aveva.Core.Database.Filters.dll而官方没有给出旧→新命名空间迁移对照表只能逐个验证社区帖里的映射只能当线索。Q2PML1 和 PML2 是两种不同的语言吗新人应该先学哪一个官方口径是当前版本常称 PML2可以视为对 PML1 能力的扩展但许多编程任务的做法不同而且某些任务用 PML1 更高效。所以它们不是两个互不相干的语言而是同一语言体系的两代风格PML1 偏命令 变量注入PML2 是面向对象、专为 Forms and Menus 设计。新人建议先学 PML1因为它是所有 PML 的地基且表达式包在 DBRM 手册里单独成章、官方称与 PML2 兼容再学 PML2 的对象与表单。文件扩展名按官方培训材料口径是.pmlfnc/.pmlfrm/.pmlobj依赖环境变量PMLLIB。Q3我想在 E3D 界面上加一个自己的菜单和停靠窗口只用 PML 能做到吗按官方推荐做法界面级定制应当走.NET Addin Command UIC 文件命令类继承 CAF 的抽象基类Command在构造函数里设置Key用 XML 格式的 UIC 文件定义菜单/工具栏并通过Key关联模块级配置文件是模块名Customisation.xml其UICustomizationFiles按顺序列出要加载的 UIC其中$1会被当前工程名替换。PML 侧也有 Command 机制PML command object .uic但官方明确不建议从标签页按钮直接调用 PML 宏因为与 command ribbon 不兼容旧式事件/工具栏方式仍受支持但不推荐。Q4我是 C# 程序员不懂管道业务能不能完全绕开 PML不能完全绕开但可以把 PML 压到最薄。官方为 .NET 提供了两条路径——.NET Addin与PML.NET——两者都通过在运行时把 dll 动态载入模块来实现并且定位是与既有 PML 定制并存。关键约束是无法从 C# 直接调用 PML只能通过事件机制反向通知。因此哪怕你只写 C#PML 仍然会是那条触发链路的入口一行IMPORT 一行USING NAMESPACE或一个命令对象。另外还有两条限制要设计进去模块切换不保持 .NET 对象DIRECTION、ORIENTATION等 PML 对象不能传给 .NET但数据库引用可以以数组或字符串形式传递。Q5网上有人说E3D 15.x这是不是更新的版本我该不该追不必追因为这个说法本身有误15.x 是 AVEVA Engineering 的版本不是 E3D Design 的版本。文档站的版本索引会同时列出 “E3D Design 3.1” 与 “Engineering 15.8” 这类条目容易混。E3D Design 上未发现 15.x 命名已确认的文档版本线是 1.1 / 2.1 / 3.1当前版本为 3.1。追新时请以 3.1 为主线遇到历史版本差异显式标注。Q6四条路可以混用吗混用时最容易踩的坑是什么可以混用而且是官方鼓励的形态——NCUG 明确 .NET 定制的定位就是与既有 PML 定制并存。典型组合是PML/PML2 负责界面触发与数据巡检PML.NET 负责被调用的计算库.NET Addin 负责把入口挂到界面上。最容易踩的坑有三个一是把主控方设计成 C#方向反了官方不支持二是类或方法忘了PMLNetCallable标注导致写了却调不到三是USING NAMESPACE写了部分命名空间直接报错。此外还要注意PML 的集合collection与界面上看到的 “My Collections” 不是同一回事——后者实为 GPWL/GPSET/GPITEMS 体系这一条在做数据访问时会显著影响你的设计。