代码树无侵入式定制 (XDT/JDT 变换)

在 Aras Innovator 开发中，除了向数据库导入元数据配置包以及编写 Method 代码之外，有时我们必须对服务器的**代码树（Code Tree，即安装在 IIS 物理磁盘下的物理文件和文件夹）**进行改造。例如：

• 更改登录界面的闪屏（Splash Screen）和系统 Logo。
• 修改 Web.config 开启高安全性传输。
• 在 OAuthServer.config 中配置企业单点登录（SSO）或者注册第三方集成 App 的 Client。

传统的做法是直接编辑这些 .config 或图片文件。但这会带来严重的升级维护灾难：当 PLM 进行版本更新或打补丁时，官方的安装包会强行覆盖这些物理文件，导致所有的定制成果瞬间化为乌有，且极难排查。

为了实现零侵入、高安全性的部署，Aras 推荐使用 Document Transformation（文档变换） 技术。

---

1. 物理代码树架构

Aras Innovator 的 IIS 安装路径下，代码树具有极其固定的层级结构：

Innovator/
├── Client/                         # 前端 HTML/JS/CSS 静态资源物理目录
│   └── images/                     # 存放系统图标与闪屏图片
│       └── splash.gif              # 默认加载闪屏
├── Server/
│   ├── web.config                  # 服务端主 IIS 配置文件
│   └── bin/                        # 服务端物理 DLL 程序集
└── OAuthServer/
    └── OAuthServer.config          # 身份验证及 SSO 核心配置文件

---

2. 变换（Transformation）技术原理：XDT 与 JDT

为了不直接在官方原版物理文件上涂抹修改，我们在版本控制系统（Git）中，只保留原版文件与包含修改差异的变换文件（Transform File）。

在自动化构建部署（CI/CD）或本地沙箱初始化时，打包工具会自动读取变换文件，在原版文件的基础之上，动态地插入、替换或删除特定的配置节点，生成最终上线运行的物理文件。

变换类型

• XDT (XML Document Transformation)：专门用于 XML 格式配置文件（如 .config, .xml）的变换规范。
• JDT (JSON Document Transformation)：专门用于修改配置文件（如 .json）的变换规范。

---

3. XDT 变换配置示例

以下演示如何通过 XDT 机制，无侵入式地向 OAuthServer.config 文件的客户注册节点下，插入一个名为 MyERPIntegration 的第三方 API 认证客户端：

3.1 变换规则文件定义 (OAuthServer.config.xdt)

在 Git 仓库中创建该文件，内容定义了我们需要定位到 <client> 节点，并采用 Insert（插入）行为添加定制内容：

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <oauth>
    <clients>
      <!-- xdt:Locator 负责定位父级，xdt:Transform 负责执行动作 -->
      <client id="MyERPIntegration" 
              secret="7F3B8F89C6F4..." 
              allowed_scopes="IOMAPI" 
              xdt:Transform="Insert" />
    </clients>
  </oauth>
</configuration>

3.2 常用 XDT 变换指令

指令 (Transform Action)	作用	说明
Insert	插入新节点。	将变换文件定义的节点追加到匹配的父节点内。
Replace	替换现有节点。	替换整个目标 XML 节点及其所有子元素。
Remove	删除指定节点。	从物理配置文件中将该标签彻底移除。
SetAttributes	修改特定属性值。	仅修改某节点的某个键值，如将 debug="false" 改为 true。

---

4. 闪屏定制与静态资源规范

对于登录闪屏（Splash Screen）或前台系统界面的微调，推荐做法如下：

1. 资源隔离：不要直接覆盖官方的 splash.gif。
2. 重定向配置：在 CUI 或 Client 目录的定制配置中，通过转换文件定位到加载资源的配置节点，将其路径指向你放在 Git 中的专属资源目录，如 /Client/customer_custom/images/my_splash.png。
3. 这样做能保证即使 Aras 执行了小版本补丁升级，你的定制图片也安全地躺在自定义独立目录下，并且路由配置在合并后会自动生效。