FileTransform@2 - 文件转换 v2 任务

项目
11/21/2024

使用此任务可将令牌替换为 XML 或 JSON 配置文件中的变量值。

语法

# File transform v2
# Replace tokens with variable values in XML or JSON configuration files.
- task: FileTransform@2
  inputs:
    folderPath: '$(System.DefaultWorkingDirectory)/**/*.zip' # string. Required. Package or folder. Default: $(System.DefaultWorkingDirectory)/**/*.zip.
    #enableXmlTransform: true # boolean. XML transformation. Default: true.
    #xmlTransformationRules: '-transform **\*.Release.config -xml **\*.config' # string. Optional. Use when enableXmlTransform == true. XML Transformation rules. Default: -transform **\*.Release.config -xml **\*.config.
  # Variable Substitution
    #jsonTargetFiles: # string. JSON target files. 
    #xmlTargetFiles: # string. XML target files.

# File transform v2
# Replace tokens with variable values in XML or JSON configuration files.
- task: FileTransform@2
  inputs:
    folderPath: '$(System.DefaultWorkingDirectory)/**/*.zip' # string. Required. Package or folder. Default: $(System.DefaultWorkingDirectory)/**/*.zip.
    #xmlTransformationRules: '-transform **\*.Release.config -xml **\*.config' # string. XML Transformation rules. Default: -transform **\*.Release.config -xml **\*.config.
  # Variable Substitution
    #jsonTargetFiles: # string. JSON target files. 
    #xmlTargetFiles: # string. XML target files.

输入

folderPath - 包或文件夹
string。必填。默认值：$(System.DefaultWorkingDirectory)/**/*.zip。

包或文件夹的文件路径。

变量生成和发布。支持通配符。

例如，$(System.DefaultWorkingDirectory)/**/*.zip。对于压缩文件夹，内容将提取到 TEMP 位置、执行转换以及原始项目位置压缩的结果。

enableXmlTransform - XML 转换
boolean。默认值：true。

配置转换将在变量替换之前运行。

XML 转换仅适用于 Windows 平台。

xmlTransformationRules - XML 转换规则
string。自选。当 enableXmlTransform == true时使用。默认值：-transform **\*.Release.config -xml **\*.config。

使用语法提供换行符分隔的转换文件规则列表：-transform <pathToTransformFile> -xml <pathToSourceConfigurationFile>。结果文件路径是可选的，如果未指定，则源配置文件将替换为转换后的结果文件。

xmlTransformationRules - XML 转换规则
string。默认值：-transform **\*.Release.config -xml **\*.config。

jsonTargetFiles - JSON 目标文件
string。

提供换行分隔的文件列表，以替换变量值。文件名相对于根文件夹提供。

例如，若要替换以下示例中 ConnectionString 的值，需要在生成或发布管道（或发布管道的环境）中将变量定义为 Data.DefaultConnection.ConnectionString。

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Server=(localdb)\SQLEXPRESS;Database=MyDB;Trusted_Connection=True"
    }
  }
}

变量替换在配置转换后运行。

注意：仅在生成/发布管道中定义的自定义变量用于替换。排除默认/系统定义的管道变量。如果在发布管道和阶段中定义了相同的变量，则阶段变量将取代发布管道变量。

xmlTargetFiles - XML 目标文件
string。

提供换行分隔的文件列表，以替换变量值。文件名相对于根文件夹提供。

对于 XML，生成或发布管道中定义的变量将与任何配置文件和 parameters.xmlappSettings、applicationSettings和 connectionStrings 节中的 key 或 name 项匹配。

变量替换在配置转换后运行。

任务控制选项

除任务输入之外，所有任务都具有控制选项。有关详细信息，请参阅控件选项和常见任务属性。

输出变量

没有。

言论

文件转换版本 2 中的新增功能：

更优化的任务字段，允许用户在单个任务实例中启用任何/所有转换（XML）、变量替换（JSON 和 XML）功能。
当未应用任何配置的转换/替换或任务 no-op时，任务将失败。

使用此任务可对配置和参数文件应用文件转换和变量替换。有关如何处理翻译的详细信息，请参阅文件转换和变量替换引用。

重要

此任务适用于 Web 包，需要 Web 包文件。它不适用于独立 JSON 文件。

文件转换

目前，仅 XML 文件支持文件转换。
若要将 XML 转换应用于配置文件（*.config），必须使用语法指定换行分隔的转换文件规则列表：-t ransform <path to the transform file> -xml <path to the source file> -result <path to the result file>
在很多方案中，文件转换非常有用，尤其是在部署到应用服务并且想要添加、删除或修改不同环境（如开发、测试或 Prod）的配置时，请遵循标准 Web.config 转换语法。
还可以使用此功能转换其他文件，包括控制台或 Windows 服务应用程序配置文件（例如，FabrikamService.exe.config）。
配置文件转换在变量替换之前运行。

变量替换

目前，变量替换仅支持 XML 和 JSON 文件格式。
目标配置文件中定义的令牌将更新，然后替换为变量值。
变量替换在配置文件转换后运行。
变量替换仅适用于对象层次结构中预定义的 JSON 键。它不会创建新密钥。

注意

仅在生成和发布管道中定义的自定义变量用于替换。将排除默认和系统管道变量。

下面是当前排除的前缀的列表：

agent.
azure_http_user_agent
build.
common.
release.
system.
tf_

如果在发布管道和阶段中定义了相同的变量，则阶段定义的变量取代了管道定义的变量。

另请参阅：文件转换和变量替换引用。

例子

如果需要在模式 .Production.config命名的所有配置文件上运行 XML 转换，则应将转换规则指定为：

-transform **\*.Production.config -xml **\*.config

如果管道中有一个基于阶段名称命名的配置文件，可以使用：

-transform **\*.$(Release.EnvironmentName).config -xml **\*.config

若要替换嵌套或分层的 JSON 变量，请使用 JSONPath 表达式指定它们。例如，若要替换以下示例中 ConnectionString 的值，必须将变量定义为生成或发布管道（或发布管道中的阶段）中的 Data.DefaultConnection.ConnectionString。

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Server=(localdb)\SQLEXPRESS;Database=MyDB;Trusted_Connection=True"
    }
  }
}

要求

要求	描述
管道类型	YAML，经典版本，经典版本
运行时间	代理，DeploymentGroup
需求	没有
功能	此任务不满足作业中后续任务的任何要求。
命令限制	任何
Settable 变量	任何
代理版本	所有支持的代理版本。
任务类别	效用

另请参阅

文件转换和变量替换引用

通过