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/ch05-marine-utility-and-objects.md
View on GitHub# Chapter 5: AVEVA Marine Utility API & Core Domain Objects
## Core Idea
`marAPI.dll` 中的 `Aveva.Marine.Utility` 命名空间是 AVEVA Marine 二次开发的基础底层框架;它提供了对 Marine 专有实体模型的对象化封装(如 `MarObject`、`MarDataBase`、`MarUtil`),并规范了命令注入、图纸与模型列表检索、二维几何轮廓以及基于 `IDisposable` 的非托管资源生命周期管理。
## Frameworks Introduced
- **Marine 非托管资源生命周期管理模式 (Marine Resource Disposal Pattern)**:
- When to use: 任何使用 `marAPI.dll` 中以 `Mar...` 开头的类(如 `MarObject`, `MarDataBase`, `MarUtil`)时。
- How:
1. 所有核心业务类均实现了 `System.IDisposable` 接口,底层紧密包装了 C/C++ 内存句柄与 Marine 内部数据块。
2. 必须在 C# 中采用 `using (...) { ... }` 语句块或在 `finally` 块中调用 `.Dispose()`。
3. 严禁放任垃圾回收器(GC)非确定性回收,否则可能导致底层 Marine 数据通信通道未正常释放或产生内存碎片。
- **MarDataBase 准则查询体系 (Criteria-Based Query Framework)**:
- When to use: 从 AVEVA Marine 工程中批量提取特定图纸(Dwg)或构件对象清单(ObjectList)时。
- How: 构建 `MarObjectCriteria` 准则过滤条件,传给 `MarDataBase.ObjectListGet` 获得目标集合。
## Key Concepts
- **MarObject**: AVEVA Marine 所有业务对象的通用基类,提供深浅复制 `Assign(that)` 与非托管指针清理逻辑。
- **MarUtil**: 通用工具服务类,提供应用程序类型检测(如 `AppCurvedHull`、`AppBasicDesign`)、宏命令动态注入(`AddCommand`)及坐标系变换。
- **MarDataBase**: 专门面向 Marine 结构模型的查询网关,提供 `ObjectListGet` 与 `DwgListGet` 方法。
- **MarObjectCriteria**: 查询过滤器描述类,用于设定构件名匹配模式、类型过滤器和模型状态掩码。
- **MarPoint2D / MarContour2D**: 二维空间坐标点与平面轮廓线段集合,是船体板缝、开孔轮廓的数学描述基础。
- **MarTbBaseException**: Marine 底层异常基类,所有来自 Marine 原生核心的错误均继承自此类。
## Mental Models
- **Think of MarObject as a Managed Handle to a Marine C++ Structure**: `MarObject` 并不包含全部数据副本,它是对 Marine 核心引擎中内存块的托管安全代理。
- **Think of MarUtil as the Command & Context Hub**: 当需要知道“当前是否在曲面外板模块”或“向控制台发送一行宏指令”时,第一选择是 `MarUtil`。
## Anti-patterns
- **忽略 Dispose() 导致连接泄露**: 在循环中大量 `new MarObject()` 或 `new MarDataBase()` 而不调用 `Dispose()`,极易耗尽底层 Marine IPC 通信套接字或内存句柄。
- **混淆 Aveva.Core.Database 与 Aveva.Marine.Utility**: `Aveva.Core.Database.DbElement` 偏向 Plant/Common Dabacon 树形层级,而 `MarObject` / `MarDataBase` 偏向船体造船工艺(Marine 业务逻辑),两者应结合使用而非相互混淆。
## Code Examples
```csharp
using System;
using Aveva.Marine.Utility;
namespace Aveva.CustomMarine.Utilities
{
public class MarineQueryExample
{
/// <summary>
/// 检查当前模块并使用 MarDataBase 查询符合条件的船体对象
/// </summary>
public void QueryMarineObjects()
{
// 1. 使用 using 严格管理非托管资源
using (MarUtil util = new MarUtil())
using (MarDataBase db = new MarDataBase())
using (MarObjectCriteria criteria = new MarObjectCriteria())
{
// 2. 检测当前所处的 Marine 业务模块
if (util.AppCurvedHull())
{
Console.WriteLine("Currently active in Curved Hull Modelling.");
}
else if (util.AppBasicDesign())
{
Console.WriteLine("Currently active in Basic Design.");
}
// 3. 配置查询准则(例如检索特定名称前缀的构件)
// criteria 提供了对构件类别、命名模式等筛选配置
try
{
// 4. 获取符合条件的构件列表
using (MarStringlist resultList = db.ObjectListGet(criteria))
{
if (resultList != null)
{
int count = resultList.Count;
Console.WriteLine($"Found {count} matching marine objects:");
for (int i = 0; i < count; i++)
{
Console.WriteLine($" [{i}] {resultList[i]}");
}
}
}
}
catch (MarTbBaseException tbEx)
{
// 5. 捕获 Marine 内核特定异常
Console.WriteLine($"Marine Core Error: {tbEx.Message}");
}
}
}
/// <summary>
/// 动态向 AVEVA 宿主注入命令行指令
/// </summary>
public void SendMacroCommand(string cmd)
{
using (MarUtil util = new MarUtil())
{
util.AddCommand(cmd);
}
}
}
}
```
- **What it demonstrates**: `MarUtil`、`MarDataBase` 和 `MarObjectCriteria` 的生命周期管控、环境检测、准则过滤及安全异常处理。
## Reference Tables
### `Aveva.Marine.Utility` 关键类型表
| 类型名称 | 接口 / 基类 | 核心功能 |
|---|---|---|
| `MarObject` | `IDisposable` | 基础模型包装,实现 `Assign(MarObject that)` |
| `MarUtil` | `IDisposable` | 工具函数库(环境判断、命令发送、坐标变换) |
| `MarDataBase` | `IDisposable` | 模型与图纸查询网关 (`ObjectListGet`, `DwgListGet`) |
| `MarObjectCriteria` | `IDisposable` | 查询过滤条件封装器 |
| `MarStringlist` | `IDisposable` | 专用的非托管安全字符串列表 |
| `MarPoint2D` | `IDisposable` | 二维几何点坐标 (`X`, `Y`) |
| `MarContour2D` | `IDisposable` | 二维轮廓,由有序的折线或圆弧构成 |
| `MarTbBaseException`| `System.Exception` | Marine 底层通用异常类型 |
### PMLNet 跨语言调用双重载规范 (Int32 与 Double 并存机制)
在 `marAPI.dll` 中,大量核心方法与属性提供成对的重载版本:
- **C# 原生版本**: 采用 `int` / `Int32` 参数(如 `int Layers`, `int GetNoSegments()`)。在纯 C# 插件开发中应优先使用,确保强类型与极致性能。
- **PML 兼容版本**: 带有 `PML` 后缀或入参为 `double`(如 `double LayersPML`, `double GetNoSegmentsPML()`)。由于 PML 解释器内部无整型概念,所有数值变量均为双精度浮点数(`double`),因此在 PML 脚本或 PMLNet 包装层中必须调用带 `PML` 后缀或 `double` 重载的方法。
### 跨语言专用字典集合类 (NCUG 与 marAPI Interop Dictionaries)
为了在无法直接传递 C# 复杂泛型字典的 PML 环境中完成键值对通信,`marAPI.dll` 封装了 5 大专用字典类:
| 字典类名 | 键类型 | 值类型 | PML 互操作方法 | 典型业务场景 |
|---|---|---|---|---|
| `StringStringDictionary` | `string` | `string` | `KeysPML()`, `ValuesPML()` | 构件元数据键值对映射 |
| `StringIntDictionary` | `string` | `int` | `KeysPML()`, `ValuesPML()` | 枚举名称与底层状态码映射 |
| `StringDoubleArrayDictionary`| `string` | `double[]` | `KeysPML()`, `ValuesPML()` | 构件名称对应坐标/尺寸数组 |
| `StringStringArrayDictionary`| `string` | `string[]` | `KeysPML()`, `ValuesPML()` | 分段归属的多个零件批次清单 |
| `IntStringArrayDictionary` | `int` | `string[]` | `KeysPML()`, `ValuesPML()` | 焊工技能代码对应的质量报表 |
在 PML 中调用字典对象的 `!dict.keyspml()` 与 `!dict.valuespml()`,会自动转化为 PML 原生 `Hashtable` 供脚本遍历。
## Worked Example: 构件检索与指令批量后处理
1. **构建准则**: 实例化 `MarObjectCriteria`,配置需检索的结构件范围。
2. **执行检索**: 调用 `MarDataBase.ObjectListGet(criteria)` 获得构件名单。
3. **后处理执行**: 遍历构件清单,拼接属性刷新或检查命令,使用 `MarUtil.AddCommand("...")` 依次发送给宿主交互引擎执行。
4. **资源释放**: 确保所有 `Mar...` 对象在退出当前作用域前被释放,杜绝非托管资源堆积。
## Key Takeaways
1. `marAPI.dll` 中绝大多数类继承自 `IDisposable`,务必遵循 `using` 块模式确保确定性析构。
2. `MarUtil` 是执行交互式命令(`AddCommand`)和识别当前子模块的统一入口。
3. 查询结果返回的 `MarStringlist` 也是非托管资源包装,必须及时 `Dispose()`。
4. 任何底层错误均抛出 `MarTbBaseException`,应在业务代码中针对性捕获以友好提示用户。
## Connects To
- **Ch 02**: [ch02-database-access-and-elements.md](ch02-database-access-and-elements.md)(与通用 `DbElement` 相互印证)
- **Ch 06**: [ch06-marine-ui-and-vitesse.md](ch06-marine-ui-and-vitesse.md)(结合 `MarUi` 进行交互提示)
- **Ch 07**: [ch07-marine-welding-and-production.md](ch07-marine-welding-and-production.md)(基于 Utility 支撑焊接与生产管线)
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: 471k | 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 |