诊断、版本与数据库

诊断的目标是先取得证据，再做最小修复。不要把“能在数据库里改掉症状”误认为修复完成；Aras 的元数据、权限、缓存、文件系统与服务配置通常共同参与一次请求。

适用版本： 诊断流程可跨版本使用；运行时、配置文件、内部 helper 和 SQL 架构必须以目标 Release 为准。

执行层： LDE 调试、服务端 XML/AML、IIS 运维与授权 DBA；普通业务代码不得直接操作数据库。

主要依据： 各 Release 官方 Platform Specifications / Programmer's Guide、2025 Aras DevOps Unit 14-18、11.0 SP9 旧手册的调试与 AML 章节，以及本项目提供的 SQL、XML 和故障笔记。

核验 Release 与运行时

标注：Stable（核验流程）

不存在可靠的“Aras 年份 → 唯一 .NET 版本”速查表。一个 Release 可能同时依赖 .NET Framework 与 ASP.NET Core/.NET Runtime，而且 Innovator Server、Client、OAuth Server、Conversion Server 的要求可能不同。

按下面顺序确认：

1. 在登录页、About 或部署清单确认精确 Release、Service Pack 和 Hotfix。
2. 打开该 Release 的官方 Platform Specifications 与 Installation Guide。
3. 分组件检查 web.config、*.runtimeconfig.json 和已部署程序集的 Target Framework。
4. 核对服务器实际安装的 Runtime/Hosting Bundle，而不是只看开发机 SDK。
5. 把结果写进项目 baseline 和运维清单。

官方资料例证

Aras 2024 的平台规格同时列出 .NET Framework 4.7.2 与 ASP.NET Core/.NET Runtime and Hosting Bundle 6.0.6；Aras 2025 同时列出 .NET Framework 4.7.2 与 Runtime and Hosting Bundle 8.0.1。因此“2023+ 已完全迁移到某一个 .NET”并不准确。

参考入口：

• Aras Innovator Platform Documentation Library
• Aras Innovator 2024 Platform Specifications
• Aras Innovator 2025 Platform Specifications

服务端调试

标注：Classic client compatibility / 本地环境专用

旧资料通过 Debugger.Launch() 触发 JIT 调试。这种方式只允许在隔离 LDE 使用：

• Visual Studio 与目标进程位于受控开发机；
• 当前请求不是生产流量；
• 应用池超时和调试中断已知；
• 调试代码不会进入部署 Package；
• 完成后恢复配置并重新运行集成测试。

优先使用与目标 Release 匹配的 Visual Studio Aras Innovator Method Plugin。2025 年 Aras DevOps 培训资料明确要求选择对应 Release 的 Method Template，并把 Method 保存到数据库或 AML Package。

生产环境禁止

JIT 调试会暂停工作线程，可能挂起所有使用同一应用池的请求。生产问题应使用结构化日志、关联 ID、可控 trace 和可重放的 LDE 数据来诊断。

客户端动态脚本命名

标注：Classic client compatibility

开发环境里，可以用 sourceURL 让动态 Method 在浏览器 Sources 面板中更容易识别：

//# sourceURL=aras-method-example-form-onload.js

每个 Method 使用唯一、可搜索的名称。生产包可以移除这行；它不能替代 source map，也不应包含客户名或敏感标识。

安全读取 XML 配置属性

标注：Stable

读取 class_structure 之类的 XML 时，要处理空值、格式错误、缺少属性和查询错误。

Innovator inn = this.getInnovator();

Item query = inn.newItem("ItemType", "get");
query.setAttribute("select", "id,class_structure");
query.setProperty("name", "Example Document");
query = query.apply();

if (query.isError() || query.getItemCount() != 1)
{
    return inn.newError("无法唯一取得 ItemType 配置。");
}

string classStructure = query.getProperty("class_structure", "");
if (string.IsNullOrWhiteSpace(classStructure))
{
    return inn.newResult("该 ItemType 没有 class_structure。");
}

var xml = new System.Xml.XmlDocument();

try
{
    xml.LoadXml(classStructure);
}
catch (System.Xml.XmlException)
{
    return inn.newError("class_structure 不是有效 XML。");
}

var names = new System.Collections.Generic.List<string>();
foreach (System.Xml.XmlNode node in xml.SelectNodes("/class/class"))
{
    System.Xml.XmlAttribute name = node.Attributes?["name"];
    if (name != null && !string.IsNullOrWhiteSpace(name.Value))
    {
        names.Add(name.Value);
    }
}

return inn.newResult(string.Join(", ", names));

不要用固定索引取第 4 个节点，也不要把 Console.WriteLine 当作 Server Method 的用户返回或生产日志。

递归 AML 查询

标注：Stable

GetItemRepeatConfig 可用于沿关系递归读取配置。官方 Programmer's Guide 也用它演示 BOM 查询。通用示例必须限制深度和字段：

<Item
  type="Part"
  action="GetItemRepeatConfig"
  id="{VALIDATED_PART_ID}"
  select="id,item_number,name">
  <Relationships>
    <Item
      type="Part BOM"
      select="id,quantity,related_id"
      repeatProp="related_id"
      repeatTimes="6" />
  </Relationships>
</Item>

{VALIDATED_PART_ID} 是文档占位符，不是 AML 自带表达式。代码中应使用 IOM 设置 ID。

性能边界

• repeatTimes="0" 是否代表无限展开以及具体行为必须按 Release 验证；文档示例不使用无界递归。
• 只返回使用中的属性。
• 对循环引用、共享子件和深层 BOM 建立测试数据。
• 超大结构使用分页、Query Definition/TGV 或专用报表方案。
• 不要根据一次测试推断递归结果的所有深层节点都会以相同方式执行 Permission；应使用有权、仅 Discover、无权三类账号，在目标 Release 对根、关系行和深层 related Item 分别验证。

参考：Aras Innovator 12 Programmer's Guide。该链接是旧版编程手册，语法概念可参考，客户端实现仍须按目标 Release 核验。

向上反查 BOM

标注：Stable（查询目标） / DBA only（SQL 实现）

SQL Server recursive CTE 可以在只读诊断或报表库里向上查父件，但不应成为绕过 Aras 权限的客户端 API。若确实由 DBA 执行，至少需要：

• 参数化起始 Part ID；
• 明确最大递归层数；
• 处理循环；
• 在每层定义版本和 is_current 语义，而不是只过滤最终结果；
• 只授予只读账号；
• 不把查询结果重新直写 Aras 表。

应用功能优先考虑 AML、Query Definition、TGV 或经过权限设计的 Server Method。

参数化 SQL 的边界

标注：Private API / DBA only

某些目标 Release 提供参数化 SQL helper。即使参数化避免了字符串注入，它仍然绕过 Item Permission、Server Event、版本和历史。因此：

• 只用于无法通过 IOM 表达、并经过架构审查的只读诊断或集成查询；
• 禁止 SELECT *，限制列、行数和执行时间；
• 所有参数显式给出类型；
• 不把它作为普通业务写入方式；
• helper 名称和参数格式必须按目标 Release 验证。

数据库恢复后的用户映射

标注：DBA only

数据库附加或恢复后出现 orphaned database user，属于 SQL Server 身份映射问题，不是 Aras Method。旧资料使用已经过时的存储过程。正确流程是：

1. 备份并确认恢复目标。
2. 只读检查登录与数据库用户 SID 是否匹配。
3. 按当前 SQL Server 官方文档重新映射既有用户到正确 login。
4. 用最小权限账号验证 Aras 连接。
5. 记录变更、回滚方法和数据库所有者。

具体 DDL 由 DBA 根据 SQL Server 版本和组织策略生成；Cookbook 不提供可盲目执行的生产命令。

阻塞与锁诊断

标注：DBA only

把“查阻塞”“查看请求”“终止会话”混在同一个脚本里非常危险。分为三个阶段：

1. 观察：记录 blocking session、被阻塞 session、数据库、对象、等待类型、事务开始时间与正在执行的语句。
2. 判断：确认是否为正常长事务、维护作业、Aras 请求或外部集成，并评估回滚代价。
3. 处置：只有获授权 DBA 才能终止精确确认的 session；处置后检查回滚进度与应用健康。

不要运行未初始化 session 变量、占位符或“终止所有阻塞者”的动态脚本。生产操作必须进入变更或事故记录。

TOC 图标缺失

标注：Reject 先改配置的做法

“管理员看到的 TOC 多，所以 URL 太长”只是一个待验证假设。不要直接覆盖 Client web.config，更不要把 URL/QueryString 上限放大到极端值。

证据驱动的排查顺序

1. 浏览器 Network 面板记录失败请求的 URL、状态码、响应体和 request ID。
2. 对比普通用户与管理员请求：失败的是图标、数据、bundle 还是授权响应。
3. 查 IIS access log、Failed Request Tracing、ASP.NET Core stdout/应用日志。
4. 测量实际 URL 和 QueryString 长度，再与当前 IIS、ASP.NET/ASP.NET Core 配置比较。
5. 检查静态资源路径、MIME、缓存、CUI/TOC metadata 与反向代理限制。
6. 在 LDE 用相同 TOC 数据复现。
7. 如果证据确实指向长度限制，只通过项目的 config transform 做最小增量，并设置业务可接受的上限、回归测试和回滚。

修改整份 web.config 还可能意外改变 authentication、handler、environment variables 和安全过滤规则，所以应保留厂商原文件，仅部署受版本控制的 transform。

数据库列表与内部端点

标注：Reject

不要把数据库枚举页面、内网 IP、服务器别名或数据库名称写进公开文档。需要列出可用数据库时，应由管理员读取受保护的部署配置或资产清单，并限制给授权人员。

为什么不要这样做

原始模式	标注	风险
固定的 Aras → .NET 对应表	Reject	忽略同一 Release 的多组件、多运行时要求
生产请求触发 JIT debugger	Reject	阻塞应用线程与用户请求
XML 节点固定取 [3]	Reject	配置稍变即越界或读取错误分类
无界递归并返回大量属性	Reject	响应爆炸、超时、内存压力
SQL 反查作为普通用户接口	Reject	绕过 Aras Permission
诊断脚本自动终止数据库会话	Reject	可能误杀生产事务并触发大回滚
覆盖完整 web.config	Reject	破坏版本配置、安全策略和升级路径
发布数据库枚举端点	Reject	信息泄露与环境耦合

验证清单

• [ ] Release、Service Pack、Hotfix 和每个组件 Runtime 均有证据。
• [ ] 调试只在 LDE 进行，调试代码不会进入 Package。
• [ ] XML 解析处理空值、无效格式和缺失属性。
• [ ] 递归查询限制层数、字段和结果规模。
• [ ] SQL 仅由授权 DBA 用于只读诊断或明确审批的维护。
• [ ] IIS 配置修改来自已复现证据，并通过 transform、测试和回滚管理。
• [ ] 日志与文档不包含内网地址、凭据、真实 GUID 或客户业务名称。