版本声明本篇基线为AVEVA E3D Design 3.1文档版本线存在 1.1 / 2.1 / 3.1教程统一以 3.1 为准前代产品AVEVA PDMS 自 2024 年 4 月 1 日起不再销售、不再提供支持。文中命令基类、状态枚举、事件名、UIC 机制与环境变量均出自官方 .NET 定制手册NCUG与 PML 定制手册PMLCG。凡标注按官方 API 签名构造的代码均需在本地 E3D Design 环境验证。一句话结论把定制功能挂到界面上的最小闭环是**“一个设置过Key的Command子类 一次CommandManager.Commands注册 一份用同一个Key引用它的.uic”**——三者缺一菜单就会点了没反应。〇、认知问题读完本篇你应该能回答定制命令为什么必须继承Command抽象基类构造函数里必须设置什么Execute()、Execute(ArrayList arguments)、GetState()、Description、Refresh(string context)分别在什么时候被调用GetState()返回的CommandState为什么说可按位组合它实际影响什么BeforeCommandExecute与CommandExecuted两个事件分别处在执行链的哪个位置能做什么UIC 文件是什么它和模块名Customisation.xml是什么关系$1会被替换成什么为什么不建议从标签页按钮直接调用 PML 宏官方给的替代方案是什么一、机制解析1.1Command基类与Key界面与逻辑解耦CAF 提供了一个抽象基类Command官方要求所有定制命令类都必须继承它。继承之后有一条硬性规定必须在构造函数中设置基类的Key属性。Key是这套机制的解耦点命令类知道自己的Key是什么但完全不知道自己在界面上的位置UIC 文件只写哪个菜单项关联哪个Key完全不知道命令是怎么实现的两边通过Key这个字符串对上号。所以菜单点了没反应的头号原因就是Key没设、设错、或与.uic里写的不逐字符一致。这是本系列铁律 5 的来源定制命令必须设置Command基类的Key.uic靠它关联。1.2 可重写成员与状态属性官方列出的可重写成员成员作用Execute()无参执行入口菜单/按钮触发时的主逻辑Execute(ArrayList arguments)带参数执行入口用于把参数从界面传进命令GetState()返回CommandState枚举决定命令当前的状态Description命令的描述文本Refresh(string context)在给定上下文下刷新命令状态命令实例上可直接读写的状态属性界面据此呈现Checked、Enabled、List、SelectedIndex、Value、ValueChanged、Visible。把这组属性读懂就能理解 CAF 命令的呈现模型界面元素从命令实例上读状态而不是命令去改界面。因此想让菜单项显示为勾选状态就操作Checked想让菜单项变灰就通过GetState()返回不含启用位的CommandState想让命令在下拉框里表现为选择项就用List/SelectedIndex/Value。注意ValueChanged的存在它表明 CAF 的命令模型并不只是点了执行还包括值被改了这类事件。设计界面时不要把它当成只会触发Execute的按钮。1.3CommandState按位组合的状态GetState()的返回值是CommandState枚举官方明确它可按位组合。这意味着状态不是单选而是若干标志位的并集——一个命令可以同时是可见 启用 已勾选。工程含义有两点不要用多个属性分别表达状态而是把状态收拢到GetState()里统一返回不要写如果没勾选就不启用这类耦合逻辑状态位之间应该是正交的。另外GetState()会在界面需要呈现时被反复调用打开菜单、切换工具栏、刷新上下文所以它的实现必须快且无副作用——不要在这里面查数据库、不要在这里面改模型。1.4 事件BeforeCommandExecute与CommandExecuted官方给出两个关键事件事件位置典型用途BeforeCommandExecute命令执行之前前置校验、条件不满足时Cancel掉本次执行CommandExecuted命令执行之后后置审计、日志、界面刷新联动BeforeCommandExecute可以Cancel这一条是很有分量的它意味着你可以在不修改命令类本身的前提下给第三方或既有命令加上权限校验 / 前置条件校验这类横切逻辑。工程上常见的用法是只允许特定权限的用户执行某命令当前!!CE类型不符合要求时直接拦住而不是等命令内部报错。CommandExecuted则适合做命令审计日志谁、什么时候、执行了哪个Key的命令。1.5 注册CommandManager.Commands注册方式官方写得很直接把命令实例加入CommandManager.Commands集合。CommandManager位于命名空间Aveva.ApplicationFramework.Presentation与CommandBarManager同属该命名空间典型的取法是从ServiceManager里取服务——这正是第 09 篇要求把ServiceManager存下来的原因。注册与装载是两件事Addin 被加载 ≠ 命令出现在界面上。Addin 只负责命令对象被创建并注册进集合界面出现与否由 UIC 决定。1.6 UIC 文件与模块名Customisation.xmlUICUser Interface Customisation文件是 XML 格式的界面定义文件CAF 通过它定义菜单与工具栏并与命令对象的Key关联这就是解耦 UI 与逻辑的落地方式。模块级配置文件是模块名Customisation.xml其中UICustomizationFiles按顺序列出要加载的 UIC 文件$1会被替换成当前工程名——这一条非常实用可以给不同项目加载不同的 UIC 集合而不用改文件内容。加载路径由环境变量CAF_UIC_PATH指定官方说明它是界面定义文件位置按模块名Customisation.xml查找并列出的.uic。两种加载方式配置文件方式模块名Customisation.xml里的UICustomizationFiles列出.uic代码方式commandBarManager.AddUICustomizationFile(AttributeBrowser.uic, AttributeBrowser)。另外CAF 还提供交互式编辑入口工具栏右键 → Customize。在开发期先用它把菜单摆好、看清生成的Key引用关系再回写进.uic比手写 XML 快得多。1.7 PML 侧的命令机制与不要从标签页按钮直接调用 PML 宏官方在 PML 侧也有一套命令机制命令可以实现为 PML command object 或 core command object并通过.uic文件把工具与命令对象关联——这与 .NET 侧的CommandKey是同一套界面靠引用名找逻辑的思想。SCRM 的对象类型清单里也确实列有COMMAND对象类型。同时官方明确给出了一条否定性建议不建议从标签页按钮直接调用 PML 宏。理由指向与 command ribbon 的兼容性——直接挂宏绕过了命令体系状态、权限、上下文都无法参与管理。这就是本系列铁律 7 的由来。官方的替代方案是把功能做成Command对象PML command object 或 .NETCommand子类再用.uic关联。二、完整代码与逐行剖析2.1 官方示例转载ShowAttributeBrowserCommand下面这段是官方 .NET Command and Menu Customisation 教程中ShowAttributeBrowserCommand的转载版来源性质官方教程示例代码转载它是命令如何与一个可停靠窗口联动的标准范例usingAveva.ApplicationFramework.Presentation;publicclassShowAttributeBrowserCommand:Command{privateDockedWindow_window;publicShowAttributeBrowserCommand(DockedWindowwindow){this.KeyAveva.ShowAttributeBrowserCommand;// 必须设置.uic 靠它引用本命令_windowwindow;_window.ClosednewEventHandler(_window_Closed);WindowManager.Instance.WindowLayoutLoadednewEventHandler(Instance_WindowLayoutLoaded);}publicoverridevoidExecute(){if(this.Checked){_window.Show();}// 勾选状态 显示窗口else{_window.Hide();}// 未勾选 隐藏窗口}}逐行剖析using Aveva.ApplicationFramework.Presentation;Command基类就在这个命名空间里该命名空间还包含CommandBarManager、CommandManager。public class ShowAttributeBrowserCommand : Command继承是强制的。类名本身没有约束但Key有约束。private DockedWindow _window;命令不自己创建窗口而是从外部接收窗口引用——这是窗口生命周期由 Addin 管理、命令只负责显示/隐藏的合理分工。this.Key Aveva.ShowAttributeBrowserCommand;构造函数里第一件事就是设Key。这个字符串会原样出现在.uic里。_window.Closed …/WindowManager.Instance.WindowLayoutLoaded …把窗口关闭与界面布局加载两个事件接上用来同步Checked状态窗口被关掉时菜单项的勾选要跟着取消。public override void Execute()无参执行入口。if (this.Checked) { _window.Show(); } else { _window.Hide(); }一个非常典型的开关型命令写法——命令自己只判断Checked界面呈现由 CAF 依据状态完成。注意它没有去改Checked这通常由GetState()或界面框架负责。2.2 注册代码官方示例转载CommandManagercommandManager(CommandManager)serviceManager.GetService(typeof(CommandManager));ShowAttributeBrowserCommandshowCommandnewShowAttributeBrowserCommand(attributeListWindow);commandManager.Commands.Add(showCommand);逐行剖析serviceManager.GetService(typeof(CommandManager))命令管理器是从服务容器里取出来的不是自己 new 的。这说明为什么第 09 篇要在Start里保存ServiceManager——注册动作必须在Start之后、且要用 CAF 给的那个ServiceManager。(CommandManager)强制转换说明GetService返回的是通用对象类型。commandManager.Commands.Add(showCommand)官方明确的注册方式——把命令实例加入CommandManager.Commands集合。注册之后命令对象就存在了但还没在界面上露面。new ShowAttributeBrowserCommand(attributeListWindow)把窗口实例注入命令。注意此时attributeListWindow必须已经创建完毕所以 Addin 里的顺序应当是先建窗口 → 再建命令 → 再注册。2.3 一个带状态与参数的自定义命令构造示例下面这个命令演示GetState()、CommandState、Execute(ArrayList)与Value的用法。代码来源性质按官方 API 签名构造需在本地 E3D Design 环境验证其中CommandState的具体枚举成员名请以本机Aveva.ApplicationFramework.Presentation.dll的 IntelliSense 与 CAF API 参考为准。usingSystem.Collections;usingAveva.ApplicationFramework.Presentation;namespaceMyCompany.E3DAddin{/// summary/// 演示型命令/// 1) 用 GetState() 返回按位组合的 CommandState/// 2) 用 Execute(ArrayList) 接收界面传来的参数/// 3) 用 Value 承载一个当前值。/// /summarypublicclassAuditModelCommand:Command{privatebool_hasSelectionfalse;// 是否已选中元素由外部上下文刷新privatestring_lastResult;// 最近一次执行结果摘要publicAuditModelCommand(){this.KeyMyCompany.AuditModelCommand;// 与 .uic 中的引用名逐字符一致}/// summary/// 界面每次需要呈现本命令时都会调用必须快、必须无副作用。/// 返回 CommandState 位组合具体枚举成员名以本机程序集为准。/// /summarypublicoverrideCommandStateGetState(){CommandStatestatebase.GetState();// 示意把可见/启用/勾选作为相互独立的位来组合// 而不是用多个布尔属性分散表达。// 实际位名请以本机 CommandState 定义为准确认。returnstate;}/// summary无参执行走同一套逻辑参数为空。/summarypublicoverridevoidExecute(){Execute(newArrayList());}/// summary带参执行参数由界面传入例如当前选择集。/summarypublicoverridevoidExecute(ArrayListarguments){// arguments 的构造方式由调用方决定使用前必须做空值与数量校验intargCount(argumentsnull)?0:arguments.Count;_lastResult已处理参数数量argCount;Console.WriteLine([AuditModelCommand] _lastResult);// 执行完毕后通知界面刷新提示框架状态已变this.Value_lastResult;this.ValueChangedtrue;}/// summary供外部上下文刷新时调用更新内部状态标记。/summarypublicoverridevoidRefresh(stringcontext){_hasSelection!string.IsNullOrEmpty(context);base.Refresh(context);}}}要点提示GetState()里只读内部标记、不做耗时操作——它会被频繁调用。Execute()与Execute(ArrayList)应当收敛到同一段逻辑Execute()内直接转调带参版本避免两条路径行为不一致。ValueChanged是命令的一个状态属性用来向框架表达值变了不要把它当成事件处理器去订阅。Refresh(string context)是让命令感知上下文变化的入口适合更新_hasSelection之类的标记。2.4.uic片段构造示例?xml version1.0 encodingutf-8?!-- 说明以下节点与属性名仅示意用命令 Key 关联界面的组织方式。 .uic 的真实 schema 请以本机随安装提供的 UIC 文件、 或用工具栏右键 → Customize导出的结果为准 不要凭记忆手写。 --UICustomizationMenuNameMyToolsCaptionMyTools!-- Command 属性的值必须与命令构造函数里设置的 Key 逐字符一致 --MenuItemCommandMyCompany.AuditModelCommandCaption模型巡检/MenuItemCommandAveva.ShowAttributeBrowserCommandCaption属性浏览器//Menu/UICustomization判定要点.uic里的Command…与命令的Key是同一个字符串。这两处任何一处改动而另一处没改菜单项就会出现但点了没反应或根本不出现。2.5 两种加载方式对照方式一配置文件?xml version1.0 encodingutf-8?!-- 模块名Customisation.xml 的示意结构节点名以本机为准 --CustomisationUICustomizationFiles!-- 按顺序加载$1 会被替换为当前工程名 --File$1\MyTools.uic/FileFileCommon.uic/File/UICustomizationFiles/Customisation方式二代码// 代码方式加载 UIC第一个参数是 UIC 文件名第二个参数是用途/上下文标识// 代码来源性质按官方 API 签名构造需在本地环境验证commandBarManager.AddUICustomizationFile(AttributeBrowser.uic,AttributeBrowser);选择建议企业统一菜单用配置文件方式便于项目级$1差异化单个 Addin 自带的界面用代码方式随 Addin 一起部署不用改模块配置。三、常见报错与排查3.1 菜单项出现了但点了没反应现象菜单/工具栏里有这一项点击无任何响应不报错、不执行。原因.uic里的Command属性值与命令的Key不一致或命令对象压根没注册。排查三步定位——①打印命令的Key②在.uic里搜索该字符串确认存在且逐字符一致③在Start里确认commandManager.Commands.Add(...)确实执行过加一行日志。3.2 命令执行了但菜单项完全不出现现象日志显示Start执行、注册也成功但界面里找不到菜单。原因UIC 文件没有被加载——CAF_UIC_PATH未生效、模块名Customisation.xml没被读到、或UICustomizationFiles里没列该文件。排查确认CAF_UIC_PATH指向的目录里确实有模块名Customisation.xml确认 XML 语法正确一个标签没闭合就整份失效再确认.uic在列表里。3.3 命令一直灰着无法点击现象菜单项可见但不可点。原因GetState()返回的CommandState里没有包含启用位。排查检查GetState()的实现是否返回了基类状态、是否在某条分支上漏掉了启用位。注意CommandState是按位组合的要确认你返回的组合里确实有启用。3.4GetState()一调用界面就卡现象打开菜单时明显卡顿。原因在GetState()里做了数据库查询或模型写操作而它会随界面呈现被反复调用。排查把耗时逻辑移到Refresh(string context)或Start里做一次GetState()只读缓存标记。3.5 事件里Cancel不生效现象在BeforeCommandExecute里试图阻止命令执行但命令照样跑了。原因Cancel的位置不对——必须在这个前置事件里取消且取消的是本次执行放到CommandExecuted后置里已经晚了。排查确认事件挂载的是BeforeCommandExecute而不是CommandExecuted确认取消操作在该事件的可取消语义范围内具体 API 以本机 CAF API 参考为准。3.6 冲突旧式事件/工具栏方式与 ribbon 不兼容现象用旧式方式挂上去的按钮在 command ribbon 里表现异常。原因官方明确指出旧式事件/工具栏方式仍受支持但已不推荐原因是与 command ribbon 不兼容。排查改为官方推荐路径——Command子类 .uic。同样地官方也明确不建议从标签页按钮直接调用 PML 宏也应改成命令对象 .uic关联。四、动手练习把一个命令挂到菜单上并跑通用 2.1 的ShowAttributeBrowserCommand或 2.3 的自定义命令注册后写一份最小.uic通过模块名Customisation.xml加载。判定标准菜单里出现该项点击后Execute内的日志被打印且无异常。制造并修好Key 不一致把.uic里的Command值改动一个字符重启模块观察现象再改回来。判定标准能准确描述菜单项与执行的四种组合有项无响应 / 无项有注册 / 两项齐备 / 两项都缺各自的界面表现并说出修复动作。用BeforeCommandExecute做前置拦截给某个命令加前置校验当不满足条件时取消执行。判定标准不满足条件时命令主体逻辑完全不执行日志中无主体输出满足条件时正常执行。同时验证把同样的拦截逻辑错误地放到CommandExecuted里拦截不再生效。用$1做项目级 UI 差异在模块名Customisation.xml的UICustomizationFiles里使用$1让不同工程加载不同的 UIC 集合。判定标准能说明$1被替换成什么、以及为什么这种方式比给每个项目复制一份配置文件更可维护。五、小结与下一篇预告一句话收束命令体系是逻辑靠Key自我标识、界面靠Key反向引用的双向约定。要点四条命令必须继承Command构造函数里必须设Key状态收拢到GetState()返回的CommandState按位组合GetState()必须快且无副作用执行链上两个抓手BeforeCommandExecute可Cancel与CommandExecuted审计界面出现靠 UIC模块名Customisation.xml列 UIC、CAF_UIC_PATH定位、$1换工程名旧式事件/工具栏方式不推荐。下一篇11 数据库 .NET 接口命令挂上去了但它要干的活是读模型、写模型。下一篇进入Aveva.Core.Database讲DbElement的三种取元素重载其中包括那条著名的无参调用返回null而不是抛异常、四个数据模型定义类、DbElementType的每类型单类 值语义以及 Filters/Iterators 与单位体系。FAQQ1定制命令为什么必须继承Command抽象基类构造函数里必须设置什么CAF 规定所有定制命令类必须继承抽象基类Command并在构造函数中设置基类的Key属性。Key是整套机制的解耦点命令类通过它自我标识.uic文件通过它反向引用命令界面元素与逻辑之间不需要互相知道对方的存在。构造函数里可以顺带做事件挂接例如窗口关闭事件、界面布局加载事件但不要做耗时操作因为命令对象在启动期就可能被创建。Q2Execute()、Execute(ArrayList arguments)、GetState()、Description、Refresh(string context)分别在什么时候被调用Execute()是无参执行入口界面直接触发时走它Execute(ArrayList arguments)是带参入口用于把参数从界面传进命令实践中建议让Execute()转调带参版本以保持行为一致GetState()在界面需要呈现命令状态时被调用可能非常频繁所以必须快且无副作用Description提供描述文本Refresh(string context)在上下文变化时被调用适合更新内部标记例如是否已有选中元素。把这五个方法的分工记住就不会出现在GetState()里查数据库这类性能事故。Q3GetState()返回的CommandState为什么说可按位组合它实际影响什么官方说明GetState()返回CommandState枚举且该枚举可按位组合。这意味着一个命令的状态不是单选值而是若干标志位的并集——同一个命令可以同时是可见、启用、已勾选。它直接影响界面呈现菜单项是否出现、是否可点、是否显示勾选。工程上的推论是把状态统一在GetState()里以位组合的方式返回不要用多个互不相关的布尔属性分散表达也不要在状态位之间建立耦合逻辑。Q4BeforeCommandExecute与CommandExecuted两个事件分别处在执行链的哪个位置能做什么BeforeCommandExecute在命令执行之前触发它的关键能力是可以Cancel掉本次执行——适合做权限校验、前置条件校验这类横切逻辑而且不需要修改命令类本身。CommandExecuted在命令执行之后触发适合做审计日志谁在什么时候执行了哪个Key的命令以及界面联动刷新。两者的顺序不能颠倒拦截必须放在前置事件里放到后置事件里命令已经执行完了。Q5UIC 文件是什么它和模块名Customisation.xml是什么关系$1会被替换成什么UICUser Interface Customisation文件是 XML 格式的界面定义文件CAF 通过它定义菜单与工具栏并与命令对象的Key关联从而实现界面与逻辑解耦。模块级配置文件模块名Customisation.xml里的UICustomizationFiles按顺序列出要加载的 UIC 文件文件位置由环境变量CAF_UIC_PATH指定。$1会被替换成当前工程名因此可以用同一份配置让不同项目加载不同的 UIC 集合。此外也可以用代码方式加载commandBarManager.AddUICustomizationFile(...)开发期还可以用工具栏右键 → Customize交互式地摆好菜单再回写成.uic。Q6为什么不建议从标签页按钮直接调用 PML 宏官方给的替代方案是什么官方明确不建议从标签页按钮直接调用 PML 宏原因指向与 command ribbon 的兼容性直接挂宏绕过了命令体系命令的状态管理、上下文刷新、权限与审计都无法参与。官方的替代方案是把功能实现为命令对象可以是 PML command object也可以是 .NET 的Command子类再通过.uic文件把工具与命令对象关联起来。官方的 PML 定制手册里也有专门的 Commands 章节与COMMAND对象类型说明这套机制在 PML 侧同样成立。