The Azure DevOps Handbook

How To Replace App Config Settings With The Replace Tokens Extension In Azure DevOps

I’ll explain how to use the Replace Tokens extension for Azure DevOps to dynamically change config variables in your app during a pipeline run.

3 min readNov 29, 2022

Some applications require different configurations for a test stage and a production stage for example. When using Azure DevOps, we can dynamically change configuration variables in a build pipeline using the Replace Tokens extension. I’ll show you how to set it up and the needed configuration steps.

Defining placeholders in the config file

Let’s assume, we have a .NET application with an appsettings.json file containing some configuration values. Here is a small example:

There are 4 keys and their values already contain placeholders enclosed with #{…}. These values will be replaced by our pipeline during each run.

Installing the extension

The Replace Tokens extension adds a task that you can include in your pipeline. Click on Get it free, sign in with your Azure DevOps account and wait for the installation process to finish. It will be available in all of your projects of your organization.

Screenshot of installed extensions in an organization by author

🔔 The code examples are from my Medium newsletter app. Join the subscriber list and get a short and sweet overview of my published content once a month.

Click HERE to subscribe for free!

Defining the variables

There are two ways to define variables. We can define them inside the YAML file or we can create a variable group and reference it in the YAML file.

variables:
  - group: configGroup
  - name: CollectArticles
    value: true
  - name: SendNewsletter
    value: false
  - name: UseProdMode
    value: false
  - name: FeedUrl
    value: https://xeladu.medium.com/feed

The code above needs to be inserted into your pipeline file at the root level (more details on variable scopes can be found HERE). It contains a group definition and individual variable definitions. In that case, the last set value wins if identical variable names are used. You can find more details about setting variables in pipelines HERE.

To define a variable group, go to Library → Variable groups and click on + Variable group. An editor will appear that allows defining key-value pairs. The name of the group needs to be referenced in the YAML file. Here is an example screenshot:

Screenshot of variable group editor in Azure DevOps by author

Enhancing the build pipeline

Add the following code to the beginning of your pipeline:

- task: replacetokens@5
  displayName: Replace tokens in configuration file
  inputs:
    targetFiles: 'PATH-TO-YOUR-FILE(S)'
    encoding: 'auto'
    tokenPattern: 'octopus'
    writeBOM: true
    actionOnMissing: 'fail'
    keepToken: false
    actionOnNoFiles: 'fail'
    enableTransforms: false
    enableRecursion: false
    useLegacyPattern: false
    enableTelemetry: true

This task will look for all target files (you can use a fixed path or work with wildcards to match multiple files), search for the defined token pattern in them, and replace the values with our custom ones.

There are multiple token patterns available to choose from. You can also use different patterns in different files so that each Replace Tokens task only transforms one file at a time. See the image below for pattern examples:

Screenshot of available token patterns in Replace Tokens extension for Azure DevOps by author

Result

When the pipeline runs, the tokens will be replaced with the defined values. Your appsettings.json that is used by the application will look like this:

🔔 The value of SendNewsletter is false because the inline setting in the YAML file overrides the group setting. Always watch your variables to prevent surprises!

Conclusion

I showed you how you can replace configuration variables to support multiple environments like test and production. The steps are easy to implement and the Replace Tokens extension is free to use.

Find more tips for Azure DevOps here: