Code Tree 与 XDT/JDT 配置变换

Aras 解决方案通常同时包含数据库元数据和服务器文件。AML package 管理 ItemType、Form、Method 等元数据； Code Tree 管理部署文件；XDT/JDT transformation 则把环境差异应用到 XML/JSON 配置。

适用版本

本文以 Aras DevOps 1.3.1～1.6 User Guide 的 TransformationsOfConfigFiles 机制为基线。 目标文件、目录和转换工具会随 Innovator/DevOps Release 变化，不能把旧版 OAuthServer.config 路径复制到 R39。

---

1. 先给变化分类

变化	正确载体	示例
Innovator 元数据	AML package	ItemType、Form、CUI、Method Item
新增静态或程序集文件	Code Tree 定制目录	自定义图片、受支持的扩展 DLL
XML 配置差异	XDT	method-config.xml 的增量节点
JSON 配置差异	JDT	JSON 中新增或合并环境配置
密码、证书私钥、client secret	Secret store / 部署注入	不进入 Git

不要为了方便把所有内容都复制成一棵“修改后的完整 Innovator 目录”。完整副本会把官方文件、环境值和定制混在一起，升级时难以审查。

---

2. 变换工作流

变换文件描述“需要改变什么”，官方基线仍是输入。 升级时用新 Release 的原始文件重新应用变换，而不是在旧的最终文件上继续打补丁。

---

3. 仓库边界

Aras DevOps 文档把配置变换放在 TransformationsOfConfigFiles 下。 其相对目录与文件名应按当前 DevOps Guide 和 Work repository 模板组织。

Work repository/
├── AML-packages/
├── CodeTree/
└── TransformationsOfConfigFiles/
    └── Innovator/
        └── Server/
            └── method-config.xml

这只是官方应用安装文档中可见的一类布局，不是所有 Release 的完整目录清单。 创建文件前先从 SDE baseline artifact 或当前 Work repository 模板确认目标相对路径。

---

4. XDT：修改 XML

XDT 使用 xdt:Locator 找目标节点，使用 xdt:Transform 执行动作。

下面示例只展示语法：为自有测试配置增加一个可重复节点。

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <appSettings>
    <add key="Company.Feature.Enabled"
         value="true"
         xdt:Locator="Match(key)"
         xdt:Transform="InsertIfMissing" />
  </appSettings>
</configuration>

常用意图包括：

• InsertIfMissing：目标不存在时插入，重复应用不继续复制。
• SetAttributes：修改已定位节点的属性。
• Replace：替换整个目标节点。
• Remove：移除明确定位的节点。

实际可用动作和定位写法以 Aras DevOps 随附 transformation 引擎为准。

Insert 不天然幂等

每次运行都插入的规则可能产生重复配置。优先使用 *IfMissing 变体或明确 Locator，并执行双次应用测试。

---

5. JDT：修改 JSON

JDT 用于 JSON 配置。官方 DevOps 指南推荐在需要可重复合并时采用 Merge 等合适操作。

设计 JDT 时检查：

• Object 是合并还是整体替换。
• Array 是追加、按键匹配还是替换。
• 第二次应用是否产生重复元素。
• null、缺失键和空数组的语义。
• 输出是否仍是合法 JSON。

不同 JDT 实现的操作格式并不统一，本文不提供脱离目标 DevOps Release 的伪通用 JSON 语法。

---

6. 环境值与秘密

仓库只保存结构和非秘密默认值。

• URL、数据库名等环境值通过部署变量提供。
• 密码、token、证书私钥通过 secret store 提供。
• Pipeline 日志对秘密做屏蔽。
• 变换输出与制品权限受控。
• 生产配置不得从开发配置复制后手工改密码。

OAuth client 的注册方式也有版本边界。R14+ REST 文档使用现代 OAuth 2.0 端点；R39 应使用当期 OAuth Registry/认证文档， 不要向一个假定存在的旧 OAuthServer.config 手工插入自制 <client> 节点。

---

7. 自定义 DLL 与静态文件

新增文件应放到官方支持的扩展位置，并在包中记录来源、版本和校验和。

自定义服务端 DLL 还要满足：

1. 按目标 Innovator Release 的 .NET 运行时编译。
2. 引用与目标服务器兼容的 IOM。
3. 按 Programmer's Guide 配置 method-config.xml。
4. 不覆盖 OOTB 同名程序集。
5. 在干净 Code Tree 上验证启动和 Method 加载。

R35 服务器组件运行 .NET 8.0.1；R39 迁移到 .NET 10。一个旧 Framework DLL 能复制进 bin，不代表能成功加载。

---

8. 可复现实验：双次应用

对每个 transformation 执行以下实验：

1. 从目标 Release baseline 复制一份测试配置。
2. 记录原文件哈希。
3. 运行官方 DevOps transformation 流程一次。
4. 验证目标节点、XML/JSON 语法和应用启动。
5. 对结果再次运行同一 transformation。
6. 比较第一次与第二次输出哈希。
7. 如果不同，检查重复节点、数组追加或不稳定排序。
8. 把命令、工具版本、输入和输出哈希保存为证据。

升级实验

1. 取下一目标 Release 的干净 baseline。
2. 应用同一 transformation。
3. 如果 Locator 找不到目标，视为升级阻断，不自动忽略。
4. 阅读新 Release 安装/迁移文档后更新规则。
5. 重跑双次应用和启动 smoke test。

---

9. Code Tree 发布检查

• 仓库没有完整 OOTB Code Tree 的无意义副本。
• 所有新增文件都有来源、许可证和哈希。
• 所有 XML/JSON 能通过解析。
• Transformation 双次应用结果稳定。
• 没有 secret 出现在 Git diff 和构建日志。
• DLL 的 Target Framework 与目标 Release 匹配。
• Pipeline 在干净 baseline 上完成，而不是依赖旧环境残留。
• 失败时能恢复原 Code Tree 与配置。

---

10. 常见错误

直接改官方配置并提交最终文件

这会掩盖真实差异。应保留基线，提交 transformation。

假定所有转换自动幂等

XDT Insert 和 JDT 数组追加可能重复。必须做双次应用实验。

发明固定 Code Tree 路径

目录和配置随 Release 变化；从当期 baseline 与 DevOps 文档获取。

在 transformation 中保存 secret

变换文件进入版本控制，秘密应由部署系统注入。

用 XDT 修改 AML 元数据

ItemType、Form、CUI、Method Item 应放 AML package，不放 Code Tree 配置转换。

---

11. 官方依据

• Utilizing Transformation — Aras DevOps 1.6
• Aras DevOps Documentation Library
• Aras DevOps 1.3.1 User Guide
• R34 Programmer's Guide — Custom DLL
• Migration to .NET 10
• Aras Innovator 2024 RESTful API

文档最后核验：2026-08-13。