yang827/aveva-dev-skills / skills/aveva-dev-dotnet
aveva-dev-dotnet
VerifiedComprehensive developer knowledge base for AVEVA Marine and AVEVA PDMS .NET secondary development (part of the aveva-dev-skills suite). Covers Common Application Framework (CAF), Dabacon DbElement access, PMLNet interop, MarAPI, and Planar structural modeling.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.5 KB |
| chapters/ch01-architecture-and-caf-addin.md | markdown | 11.4 KB |
| chapters/ch02-database-access-and-elements.md | markdown | 19.9 KB |
| chapters/ch03-pmlnet-interop-and-controls.md | markdown | 9.6 KB |
| chapters/ch04-ui-controls-grid-mydata.md | markdown | 13.0 KB |
| chapters/ch05-marine-utility-and-objects.md | markdown | 9.3 KB |
| chapters/ch06-marine-ui-and-vitesse.md | markdown | 7.6 KB |
| chapters/ch07-marine-welding-and-production.md | markdown | 6.8 KB |
| chapters/ch08-planar-fundamentals-and-panels.md | markdown | 8.7 KB |
| chapters/ch09-planar-plates-stiffeners-brackets.md | markdown | 7.7 KB |
| chapters/ch10-planar-features-cuts-holes-welds.md | markdown | 12.8 KB |
| cheatsheet.md | markdown | 6.6 KB |
| glossary.md | markdown | 7.3 KB |
| patterns.md | markdown | 7.0 KB |
| references/core-api-reference.md | markdown | 46.4 KB |
| references/marine-api-reference.md | markdown | 69.0 KB |
| references/planar-api-reference.md | markdown | 76.8 KB |
| references/planar-enums-reference.md | markdown | 13.8 KB |
chapters/ch01-architecture-and-caf-addin.md
View on GitHub# Chapter 1: AVEVA .NET Customisation Architecture & CAF Addin Framework
## Core Idea
AVEVA .NET 二次开发采用通用应用程序框架(Common Application Framework, CAF),通过实现 `IAddin` 接口并注册到模块配置文件(`*Addins.xml`),开发者可以在同一进程内与宿主程序共享数据库会话,利用 `WindowManager`、`CommandManager` 与 UIC 机制无缝扩充 AVEVA Plant / Marine 的用户界面与业务逻辑。
## Frameworks Introduced
- **CAF 插件生命周期模型 (CAF Addin Lifecycle Framework)**:
- When to use: 任何为 AVEVA Marine/Plant(如 Design、Draft、Outfitting)开发独立功能模块、工具窗体或菜单命令时。
- How:
1. 引用 `Aveva.ApplicationFramework.dll` 与 `Aveva.ApplicationFramework.Presentation.dll`。
2. 实现 `Aveva.ApplicationFramework.IAddin` 接口(`Name`, `Description`, `Start(ServiceManager)`, `Stop()`)。
3. 在 `Start` 中通过 `ServiceManager.GetService(typeof(...))` 获取 `WindowManager` 与 `CommandManager`。
4. 注册命令与创建停靠窗口(`DockedWindow`)。
5. 在 `Stop` 中释放非托管资源与解绑事件。
- **命令与界面分离模式 (Command-UI Decoupling Pattern)**:
- When to use: 管理界面控件(工具栏按钮、菜单项)与执行逻辑的解耦绑定。
- How: 继承 `Aveva.ApplicationFramework.Presentation.Command`,指定全局唯一 `Key`,重写 `Execute()`,通过 UIC 界面配置文件将该 `Key` 绑定到界面工具(Tool)。
## Key Concepts
- **CAF (Common Application Framework)**: AVEVA 的 .NET 核心应用程序框架,提供服务发现、插件加载、窗口停靠与菜单命令管理。
- **ServiceManager**: central service locator,负责注册并向 Addin 提供核心服务(如 WindowManager、CommandManager、SettingsManager)。
- **IAddin**: 所有 CAF Addin 的入口接口,定义插件启动和停止生命周期方法。
- **WindowManager**: 负责管理宿主程序中的浮动窗体(FloatingWindow)和停靠窗体(DockedWindow)。
- **DockedWindow**: 宿主 MDI 架构下的停靠面板,可吸附在左、右、顶、底或作为标签页停靠。
- **Command**: 抽象命令基类,包含 `Key`、`Checked`、`Enabled` 状态及 `Execute()` 动作。
- **UIC 文件 (User Interface Customisation, .uic)**: 基于 XML 的界面定制文件,定义命令栏(CommandBar)、菜单与工具按钮的层次结构。
- **Addins.xml**: 模块启动时扫描的 XML 配置文件,指定需加载的 Addin 程序集路径与全类名。
## Mental Models
- **Think of ServiceManager as a Service Bus**: 插件不要自己创建核心基础设施,而是通过 `ServiceManager.GetService` 索取宿主提供的服务。
- **Think of Command as State + Action**: 命令是单一真理来源(Single Source of Truth),界面的按钮只是命令状态(Checked/Enabled)与动作(Execute)的投影。
- **Use UIC for Layout, C# for Logic**: 界面布局在 UIC 文件中声明,交互与业务在 C# Command 中实现,切勿在窗体构造中硬编码菜单栏。
## Anti-patterns
- **跨线程直接操作 AVEVA 数据库**: AVEVA 内核是单线程单元模型,在后台工作线程(如 `Task.Run` 或 `Thread`)中直接调用 `DbElement` 会导致 Dabacon 数据库锁死或崩溃,必须通过 UI 调度器派发到主线程。
- **在 IAddin.Start 中执行重型阻塞任务**: `Start` 方法在宿主模块启动的主事件循环中同步执行,若执行耗时查询会导致启动卡死;应将重型加载延后至窗体首次打开或异步调度。
- **忽略 Stop() 中的事件注销**: 未在 `Stop` 中解绑事件委托或注销命令,会导致模块切换或二次加载时产生内存泄漏和重复回调。
## Code Examples
```csharp
using System;
using Aveva.ApplicationFramework;
using Aveva.ApplicationFramework.Presentation;
namespace Aveva.CustomAddins
{
public class MarineToolsAddin : IAddin
{
private WindowManager _windowManager;
private CommandManager _commandManager;
private DockedWindow _dockedWindow;
public string Name => "MarineToolsAddin";
public string Description => "Custom tools and automation addin for AVEVA Marine";
public void Start(ServiceManager serviceManager)
{
// 1. 获取核心管理服务
_windowManager = (WindowManager)serviceManager.GetService(typeof(WindowManager));
_commandManager = (CommandManager)serviceManager.GetService(typeof(CommandManager));
// 2. 创建并配置用户自定义控件
var userControl = new MyCustomMarinePanel();
_dockedWindow = _windowManager.CreateDockedWindow(
"Aveva.MarineTools.Window",
"Marine Automation Tools",
userControl,
DockedPosition.Right
);
_dockedWindow.SaveLayout = true;
// 3. 注册命令并绑定窗口控制
var toggleCmd = new ToggleToolsWindowCommand(_dockedWindow);
_commandManager.Commands.Add(toggleCmd);
}
public void Stop()
{
// 4. 清理资源与引用
if (_dockedWindow != null)
{
_dockedWindow.Dispose();
_dockedWindow = null;
}
}
}
public class ToggleToolsWindowCommand : Command
{
private readonly DockedWindow _window;
public ToggleToolsWindowCommand(DockedWindow window)
{
Key = "Aveva.MarineTools.ToggleWindowCommand";
_window = window;
}
public override void Execute()
{
if (_window.Visible)
{
_window.Hide();
Checked = false;
}
else
{
_window.Show();
Checked = true;
}
}
}
}
```
- **What it demonstrates**: 标准 CAF Addin 实现,展示服务注入、DockedWindow 创建及 Command 双向状态绑定。
## Reference Tables
| 核心接口 / 类 | 所在程序集 | 核心职责 |
|---|---|---|
| `IAddin` | `Aveva.ApplicationFramework.dll` | 插件入口生命周期定义 (`Name`, `Description`, `Start`, `Stop`) |
| `ServiceManager` | `Aveva.ApplicationFramework.dll` | 基础服务注册中心,提供 `GetService(Type)` |
| `WindowManager` | `Aveva.ApplicationFramework.Presentation.dll` | 窗体管理器,提供 `CreateDockedWindow`, `CreateFloatingWindow` |
| `CommandManager` | `Aveva.ApplicationFramework.Presentation.dll` | 命令注册表管理器,维护 `Commands` 集合 |
| `Command` | `Aveva.ApplicationFramework.Presentation.dll` | 抽象命令基类,包含 `Key`, `Checked`, `Enabled`, `Execute()` |
| `DockedWindow` | `Aveva.ApplicationFramework.Presentation.dll` | 停靠窗口封装,提供 `Show()`, `Hide()`, `DockedPosition` |
### 模块 Addin 配置文件路径表 (`%AVEVA_DESIGN_USER%` 或模块根目录)
| 模块名称 | 默认配置文件名 |
|---|---|
| Design | `DesignAddins.xml` |
| Marine Outfitting | `MarineOutfittingAddins.xml` |
| Draft | `DraftAddins.xml` |
## Worked Example: 完整加载与 UIC 关联步骤
1. **编译程序集**: 将包含 `MarineToolsAddin` 的 C# 项目编译为 `MarineToolsAddin.dll`,拷贝到 `%PDMSEXE%` 或自定义插件目录。
2. **编辑 `DesignAddins.xml`**:
```xml
<AddinList>
<Addin>
<Name>MarineToolsAddin</Name>
<Assembly>MarineToolsAddin.dll</Assembly>
<Class>Aveva.CustomAddins.MarineToolsAddin</Class>
</Addin>
</AddinList>
```
3. **编辑 UIC 界面配置文件 (`Custom.uic`)**:
在 `<Tools>` 节点中声明所需控件工具(支持通过 Property Grid 进行视觉定制):
```xml
<Tools>
<!-- 1. 普通操作按钮 -->
<ButtonTool Key="Aveva.MarineTools.RunReport" Caption="Run Report" Tooltip="Generate hull report" Image="Report_16x16" />
<!-- 2. 状态切换按钮 (双向同步 Command.Checked) -->
<StateButtonTool Key="Aveva.MarineTools.ToggleWindowCommand" Caption="Marine Tools" Tooltip="Show/Hide Tools Window" BeginGroup="true" />
<!-- 3. 下拉多级子菜单 -->
<PopupMenuTool Key="Aveva.MarineTools.WeldMenu" Caption="Welding Utilities">
<Tools>
<ButtonTool Key="Aveva.MarineTools.CalculateWeld" Caption="Calculate Welds" />
<ButtonTool Key="Aveva.MarineTools.ExportWeld" Caption="Export Weld Table" />
</Tools>
</PopupMenuTool>
<!-- 4. 下拉组合框与单行输入 -->
<ComboBoxTool Key="Aveva.MarineTools.BlockSelector" Caption="Current Block" />
<TextBoxTool Key="Aveva.MarineTools.SearchKeyword" Caption="Search" />
</Tools>
```
并在目标菜单栏(`<MenuBar>`)或工具栏(`<ToolBar>`)中引用对应的 `Key`。
4. **启动 Design 模块**: 宿主解析 XML,实例化 Addin,执行 `Start()`,工具栏显示 "Marine Tools" 图标,点击即可呼出停靠窗体。
---
## 5. 插件性能诊断、CPU Profiling 与 UIC 生产部署
### 5.1 底层诊断与 CPU 耗时追踪 (`PdmsTrace` & `TraceEntry`)
在大型工程中,Addin 启动或高频事件处理可能导致界面卡顿,官方提供了微秒级诊断工具:
```csharp
using Aveva.ApplicationFramework.Diagnostics;
// 1. 设置跟踪标志位
PdmsTrace.SetTraceFlag((TraceNumber)101, 1);
// 2. 使用 using 作用域自动记录耗时
using (TraceEntry tr = TraceEntry.Enter("InitAddinLayout", (TraceNumber)101))
{
// 初始化窗体或拉取数据...
}
// 3. 宿主 CPU Profiling 测速
PdmsTrace.StartCPUTrace();
// 待测代码...
PdmsTrace.StopCPUTrace(true); // 输出 CPU 时钟周期与耗时报表
```
### 5.2 企业级 UIC 部署与环境重定向 (`CAF_UIC_PATH` & `$1.uic`)
在企业网络中,主程序目录通常被锁定为只读权限,不能直接修改安装目录下的 Customisation XML:
1. **环境变量 `CAF_UIC_PATH`**: 将其指向本地开发目录或网络集中共享目录,宿主将优先从该路径检索并加载 UIC。
2. **项目专属配置 `$1.uic`**: 在 UICCustomizationFiles 节点中配置 `Path="$1.uic"`,启动时 `$1` 会自动解析替换为当前进入的项目代码(如 `SAM.uic`)。
3. **运行时动态加载 UIC**:
```csharp
CommandBarManager cmdBarMgr = (CommandBarManager)serviceManager.GetService(typeof(CommandBarManager));
cmdBarMgr.AddUICustomizationFile("DepartmentTools.uic", "DepartmentTools");
```
## Key Takeaways
1. 始终使用 `IAddin` + `ServiceManager` 作为 .NET 插件主入口,不要使用非托管钩子注入。
2. 每一个窗体交互逻辑必须封装为继承自 `Command` 的子类,并通过唯一 `Key` 与 UIC 工具映射。
3. 停靠窗口使用 `WindowManager.CreateDockedWindow`,并设置 `SaveLayout = true` 以便保留用户窗体停靠习惯。
4. 严格遵守单线程 UI 约束,任何涉及 AVEVA 数据模型(Dabacon)的操作必须在主线程中进行。
5. 善用 `PdmsTrace` 进行 CPU 性能剖析,生产部署时利用 `CAF_UIC_PATH` 环境变量解耦只读安装目录。
## Connects To
- **Ch 02**: [ch02-database-access-and-elements.md](ch02-database-access-and-elements.md)(在 Addin 中使用 `Aveva.Core.Database` 存取模型数据)
- **Ch 03**: [ch03-pmlnet-interop-and-controls.md](ch03-pmlnet-interop-and-controls.md)(与传统 PML 界面体系交互混合编程)
- **Ch 04**: [ch04-ui-controls-grid-mydata.md](ch04-ui-controls-grid-mydata.md)(在 Addin 窗体中使用 AVEVA 官方 C# Grid Control)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |