PLM.ArasUtils 1.0.10

PLM.ArasUtils

PLM.ArasUtils 是面向 Aras Innovator 的 .NET Standard 扩展库，用于简化 Aras IOM (Item Object Model) 的查询、属性访问、关系处理、批量操作和 JSON 转换。

项目源码中的扩展方法位于 PLM.ArasUtils 命名空间，主要实现文件为 PlmItem.cs。

项目信息

安装

.NET CLI

dotnet add package PLM.ArasUtils --version 1.0.10

Package Manager Console

Install-Package PLM.ArasUtils -Version 1.0.10

项目文件

<ItemGroup>
  <PackageReference Include="PLM.ArasUtils" Version="1.0.10" />
</ItemGroup>

安装后引入命名空间：

using Aras.IOM;
using PLM.ArasUtils;

依赖与构建配置

项目支持四种构建配置。Debug 和 Release 使用 NuGet 的 Aras IOM， 另外两个配置使用本机 Aras 安装目录中的 IOM.dll。

兼容配置中的 IOM.dll 路径写在 PLM.ArasUtils.csproj 中，路径只适用于对应的开发机。 在另一台机器上构建 11sp12Released 或 12sp9Released 前，请先修改项目文件中的 HintPath 元素。

dotnet restore PLM.ArasUtils.csproj
dotnet build PLM.ArasUtils.csproj -c Release

生成 NuGet 包：

dotnet pack PLM.ArasUtils.csproj -c Release --no-restore

打包时会把本文件作为 NuGet 包的 README（由项目文件中的 PackageReadmeFile 配置）。

快速开始

下面的示例假设 inn 已经创建，并且连接已经成功登录。

查询、读取和检查错误

Innovator inn = /* 已登录的 Innovator 实例 */;

Item result = inn.newItem("Part", "get")
    .setProperty("item_number", "PART-001")
    .apply();

result.CheckError();

if (result.getItemCount() > 0)
{
    Item part = result.getItemByIndex(0);

    // Aras ID 和字符串属性使用原生 IOM 方法读取
    string id = part.getID();
    string number = part.getProperty("item_number", "");
    string name = part.getProperty("name", "");

    // 值类型属性可以使用泛型扩展方法转换
    DateTime createdOn = part.CreatedOn<DateTime>();

    Console.WriteLine($"Part: {number}, {name}, {id}");
    Console.WriteLine($"Created: {createdOn}");
}

CheckError() 检查 Aras Item 的错误状态，发现错误时抛出异常。 集合也支持 CheckError()、HasErrors()、GetValidItems() 和 GetErrorItems()。

Item 集合与 LINQ

var parts = inn.newItem("Part", "get")
    .apply()
    .ToList();

var makeParts = parts
    .WhereProperty("make_buy", "Make")
    .WherePropertyContains("name", "Gear", ignoreCase: true)
    .DistinctByProperty("classification")
    .ToList();

var itemNumbers = makeParts.SelectProperty("item_number").ToList();
var byId = makeParts.ToDictionary();

批量更新

var parts = inn.newItem("Part", "get").apply().ToList();

parts
    .SetProperty("review_status", "pending")
    .setAction("update")
    .apply()
    .CheckError();

集合扩展方法会逐个调用 IOM 方法，因此仍需遵循 Aras 服务器的权限、 锁定和事务规则。

关系项

Item part = inn.newItem("Part", "get")
    .setProperty("item_number", "PART-001")
    .apply()
    .CheckError();

Item bom = part.FetchRelationships("Part BOM");

foreach (Item relationship in bom.Enumerator())
{
    Item relatedPart = relationship.getItemRelatedItem();

    if (relatedPart != null)
    {
        Console.WriteLine(relatedPart.getProperty("item_number", ""));
    }
}

关系扩展包括：

• FetchRelationships() 和 FetchRelationships(string type)
• getItemSourceItem() 和 getItemSourceItem(string type)
• getItemRelatedItem() 和 getItemRelatedItem(string type)
• getItemPropertyItem(string property)
• getItemById(string type, string id)

JSON 转换

var properties = part.getPropertys();
string json = part.ToJson();

JObject obj = json.ToJObject();
JArray array = "[{\"name\":\"Part\"}]".ToJArrary();

string itemsJson = makeParts.ToJson("id", "item_number", "name");

需要引用：

using Newtonsoft.Json.Linq;

ToJArrary() 是现有 API 的方法名（拼写保持兼容）；它返回 JArray。

API 概览

Extend

针对单个 Item 的常用方法：

针对 IEnumerable<Item> 的批量方法：

• apply(string action = default)
• setAction(string action)
• SetProperty(string property, string value, string lang = default)
• setAttribute(string name, string value)
• setPropertyItem(string property, Item value)
• setType(string itemTypeName)
• setId()、setId(List<string> ids)、setNewID()
• getID()、getResult()、getErrorString()
• removeAttribute(string attributeName)
• Clone(bool cloneRelationships)

IEnumerableItemExtensions

分页示例：

int pageIndex = 0; // 从 0 开始
int pageSize = 50;

IEnumerable<Item> page = makeParts.Page(pageIndex, pageSize);
(int totalCount, int totalPages) = makeParts.GetPageInfo(pageSize);

ItemPropertyExtend

该类为常见 Aras 系统属性提供泛型访问器：

• CreatedById<T>、CreatedOn<T>、ModifiedById<T>、ModifiedOn<T>
• Classification<T>、KeyedName<T>、Id<T>、OwnedById<T>、ManagedById<T>
• LockedById<T>、CurrentState<T>、State<T>
• IsCurrent<T>、IsReleased<T>、MajorRev<T>、MinorRev<T>、Generation<T>
• NotLockable<T>、Css<T>、NewVersion<T>、ConfigId<T>
• PermissionId<T>、TeamId<T>

这些方法的泛型参数约束为 struct。Aras 的 ID、KeyedName、 Classification 等通常是字符串，读取这类属性时请使用 item.getProperty("id", "") 等原生 IOM 方法；不要写 item.Id<string>()。

类型转换约束

• getProperty<T> 和 SelectProperty<T> 要求 T : struct，底层使用 Convert.ChangeType。
• getValue<T> 使用库内置的转换逻辑，支持 int、double、decimal 和 DateTime。
• 转换失败时不要依赖默认值静默掩盖数据问题，建议在业务边界捕获并记录异常。

本地化

string zhLabel = part.GetListLabelByLang("make_buy", "zc");
string enLabel = part.GetListLabelByLang("make_buy", "en");
string filterLabel = part.GetFilterListLabel("status", "en");

语言代码由 Aras 服务器配置决定，常见值包括 zc、en 和 ja。 如果未传语言参数，列表标签扩展默认使用 zc。

使用注意事项

1. 调用扩展方法前，先通过 HttpServerConnection.Login() 完成登录并检查登录结果。
2. 不要在源代码中硬编码密码；使用安全配置、密钥存储或环境变量。
3. HttpServerConnection 及同一 Item 的并发访问应由业务代码自行同步。
4. 大数据查询应设置合理的 select、page_size，并优先使用分页。
5. 批量扩展方法是对每个 Item 逐个执行 IOM 操作；需要原子事务时请使用 Aras 服务器端事务或一次性 AML。
6. 使用文件流上传和下载大文件，并确保连接、流和检入/检出管理器正确释放。
7. 11sp12Released 和 12sp9Released 的 IOM.dll 路径属于本机配置， 发布前请确认目标环境中的 Aras 版本与 DLL 匹配。

登录示例：

HttpServerConnection connection =
    IomFactory.CreateHttpServerConnection(
        "https://server/InnovatorServer.aspx",
        "Database",
        "username",
        "password");

Item login = connection.Login();
login.CheckError();

Innovator innovator = IomFactory.CreateInnovator(connection);

try
{
    // 使用 innovator 和 PLM.ArasUtils 扩展方法
}
finally
{
    connection.Logout();
}

许可证

本项目使用 MIT 许可证，详见 LICENSE。

贡献

欢迎通过 Issue 报告问题， 或提交 Pull Request。

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/<name>
3. 提交更改
4. 推送分支并创建 Pull Request