Azure DevOps发布管道File-transform-task变量未替换问题

核心检查点与解决方案 #

1. 严格匹配变量名与配置节点层级（大小写敏感） #

变量组中的变量名必须完全匹配配置文件里的节点层级，包括大小写。举个实际示例：
如果你的Webservice.settings（最终合并到.exe.config）结构如下：

<configuration>
  <applicationSettings>
    <MyFancyProgram.App.Properties.Webservice>
      <setting name="LoginName" serializeAs="String">
        <value></value>
      </setting>
      <setting name="ApiEndpoint" serializeAs="String">
        <value></value>
      </setting>
    </MyFancyProgram.App.Properties.Webservice>
  </applicationSettings>
</configuration>

那么变量组里的变量名必须是：

• MyFancyProgram.App.Properties.Webservice.LoginName
• MyFancyProgram.App.Properties.Webservice.ApiEndpoint

注意：命名空间、setting名称的大小写必须和XML节点完全一致，哪怕一个字母大小写错了，都匹配不到节点。

2. 检查File Transform任务的配置细节 #

• 文件路径正确性：确保Transform files字段指向的是最终要部署的.exe.config文件（如果Webservice.settings是嵌入生成的，要指向生成后的.exe.config，而不是源文件）
• 执行顺序：File Transform任务必须放在复制文件到目标服务器/发布位置的任务之前，否则替换的是本地构建文件，不会同步到部署包
• 转换规则验证：对于applicationSettings类型的节点，不需要额外配置转换规则，只要变量名格式正确，任务会自动匹配。如果是自定义节点，才需要添加XDT转换规则，但你的场景用默认规则即可。

3. 排除变量覆盖与范围问题 #

• 确认变量组的范围是Release，且没有其他同名称的变量（比如管道级、阶段级变量）覆盖了变量组的值
• 如果是保密变量，确保在管道设置中允许保密变量被用于文件转换（默认是允许的，但可以检查任务的Enable variable substitution选项是否开启）

4. 查看管道日志定位问题 #

执行发布后，查看File Transform任务的日志输出，里面会明确显示：

• 找到了哪些配置文件
• 匹配到了哪些变量
• 哪些变量没有找到对应的节点

比如日志里如果出现No matches found for variable 'XXX'，直接说明变量名和节点不匹配，需要修正变量名或配置节点。

内容的提问来源于stack exchange，提问作者Nepomuk