FileTransform@2 - File transform v2 task

Use this task to replace tokens with variable values in XML or JSON configuration files.

Syntax

# 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.
    #errorOnInvalidSubstitution: false # boolean. Error on empty files and invalid substitution. Default: false.
  # Variable Substitution
    #jsonTargetFiles: # string. JSON target files. 
    #xmlTargetFiles: # string. XML target files.

Inputs

folderPath - Package or folder
string. Required. Default value: $(System.DefaultWorkingDirectory)/**/*.zip.

File path to the package or a folder.

Variables are Build and Release. Wildcards are supported.

For example, $(System.DefaultWorkingDirectory)/**/*.zip. For zipped folders, the contents are extracted to the TEMP location, transformations executed, and the results zipped in original artifact location.

enableXmlTransform - XML transformation
boolean. Default value: true.

Config transforms will be run prior to the Variable Substitution.

XML transformations are supported only for Windows platform.

xmlTransformationRules - XML Transformation rules
string. Optional. Use when enableXmlTransform == true. Default value: -transform **\*.Release.config -xml **\*.config.

Provides a newline-separated list of transformation file rules using the syntax: -transform <pathToTransformFile> -xml <pathToSourceConfigurationFile>. The result file path is optional, and if not specified, the source configuration file will be replaced with the transformed result file.

jsonTargetFiles - JSON target files
string.

Provides a newline-separated list of files to substitute the variable values. File names are to be provided relative to the root folder.

For example, to replace the value of ConnectionString in the sample below, you need to define a variable as Data.DefaultConnection.ConnectionString in the build or release pipeline (or release pipeline's environment).

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

Variable Substitution is run after configuration transforms.

Note: Only custom variables that are defined in build/release pipelines are used in substitution. Default/system defined pipeline variables are excluded. If the same variables are defined in the release pipeline and in the stage, then the stage variables will supersede the release pipeline variables.

xmlTargetFiles - XML target files
string.

Provides a newline-separated list of files to substitute the variable values. File names are to be provided relative to the root folder.

For XML, Variables defined in the build or release pipelines will be matched against the key or name entries in the appSettings, applicationSettings, and connectionStrings sections of any config file and parameters.xml.

Variable Substitution is run after configuration transforms.

Note: Only custom variables defined in build/release pipelines are used in substitution. Default/system defined pipeline variables are excluded. If the same variables are defined in the release pipeline and in the stage, then the stage variables will supersede the release pipeline variables.

errorOnInvalidSubstitution - Error on empty files and invalid substitution.
boolean. Default value: false.

If selected, the pipeline fails if the target files are empty or if the substitution fails.

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

None.

Remarks

What's new in File Transform version 2:

• More optimized task fields that allow users to enable any/all of the transformation (XML), variable substitution (JSON and XML) features in a single task instance.
• Task fails when any of the configured transformation/substitution is NOT applied or when the task is no-op.

Use this task to apply file transformations and variable substitutions on configuration and parameters files. For details of how translations are processed, see File transforms and variable substitution reference.

Important

This task is intended for web packages and requires a web package file. It does not work on standalone JSON files.

File transformations

• At present, file transformations are supported for only XML files.
• To apply an XML transformation to configuration files (*.config) you must specify a newline-separated list of transformation file rules using the syntax:-transform <path to the transform file> -xml <path to the source file> -result <path to the result file>
• File transformations are useful in many scenarios, particularly when you are deploying to an App service and want to add, remove or modify configurations for different environments (such as Dev, Test, or Prod) by following the standard Web.config Transformation Syntax.
• You can also use this functionality to transform other files, including Console or Windows service application configuration files (for example, FabrikamService.exe.config).
• Config file transformations are run before variable substitutions.

Variable substitution

• At present only XML and JSON file formats are supported for variable substitution.
• Tokens defined in the target configuration files are updated and then replaced with variable values.
• Variable substitutions are run after config file transformations.
• Variable substitution is applied for only the JSON keys predefined in the object hierarchy. It does not create new keys.

Note

Only custom variables defined in build and release pipelines are used in substitution. Default and system pipeline variables are excluded.

Here's a list of currently excluded prefixes:

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

If the same variables are defined in both the release pipeline and in a stage, the stage-defined variables supersede the pipeline-defined variables.

See also: File transforms and variable substitution reference.

Examples

If you need XML transformation to run on all the configuration files named with pattern .Production.config, the transformation rule should be specified as:

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

If you have a configuration file named based on the stage name in your pipeline, you can use:

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

To substitute JSON variables that are nested or hierarchical, specify them using JSONPath expressions. For example, to replace the value of ConnectionString in the sample below, you must define a variable as Data.DefaultConnection.ConnectionString in the build or release pipeline (or in a stage within the release pipeline).

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

Requirements

Requirement	Description
Pipeline types	YAML, Classic build, Classic release
Runs on	Agent, DeploymentGroup
Demands	None
Capabilities	This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions	Any
Settable variables	Any
Agent version	All supported agent versions.
Task category	Utility

See also

• File transforms and variable substitution reference