Variable Substitution Task

This task allows you to substitute variables in JSON files. It's particularly useful for replacing configuration values in settings files during deployment.

Features

• Replace JSON keys with values from pipeline variables
• Support for boolean, number, and string values
• Recursive file search
• Configurable error handling for missing variables
• Configurable logging levels

How to Use

1. Add the task to your pipeline
2. Configure the files to process
3. Define your replacements

Example

steps:
  - task: VariableSubstitution@1
    inputs:
      files: "**/appsettings.json"  # Process all appsettings.json files
      replacements: |
        EnvironmentSettings.Local: false
        TableSettings.TablePrefixEnv: TABLE_NAME_PREFIX
        Migrations.InitalizeTables: false
        Migrations.SeedDatabase: true
        Cors.AllowedOrigins.0: https://example.com
        Serilog.MinimumLevel: Information
      logLevel: info  # Optional: control logging verbosity

Input File Example

Your JSON file:

{
  "settings": {
    "EnvironmentSettings.Local": "environment",
    "TableSettings.TablePrefixEnv": "prefix"
  }
}

After substitution:

{
  "settings": {
    "EnvironmentSettings.Local": false,
    "TableSettings.TablePrefixEnv": "TABLE_NAME_PREFIX"
  }
}

Configuration Options

• files: Files to process (Required)

  • Supports minimatch patterns (e.g., "**/appsettings.json")
  • Multiple patterns can be specified on separate lines

• replacements: Variable replacements (Required)

  • Format: key: value
  • One replacement per line
  • Values are automatically parsed as JSON (booleans, numbers, strings)

• recursive: Search for files recursively

  • Default: true
  • Set to false to only search in the specified directory

• encoding: File encoding

  • Default: utf8
  • Other options: ascii, utf16le, etc.

• actionOnMissing: What to do when a variable is not found

  • warn: Log a warning (default)
  • fail: Fail the task
  • ignore: Continue silently

• logLevel: Control the verbosity of task output

  • error: Show only errors (default)
  • warn: Show warnings and errors
  • info: Show important operations
  • debug: Show detailed debugging information

Error Handling

The task will:

1. Warn if no files are found matching the pattern
2. Handle missing variables according to actionOnMissing setting
3. Skip files that aren't valid JSON
4. Preserve file formatting and indentation

Tips

• Use glob patterns to process multiple files
• Test your replacements with actionOnMissing: warn first
• Values are parsed as JSON, so you can use true/false for booleans
• Keys that aren't in the replacements list are left unchanged
• Set logLevel: debug when troubleshooting replacement issues