How to use Replace Tokens in Azure Pipelines

9 min readApr 21, 2022

Replace Tokens is an extension that can be used in Azure DevOps, which provides the possibility to replace tokens in the code files with variables values (which can be configured in the Pipelines Library) during the execution of the CI/CD process.

It’s common in software projects that we have URLs that are used to make requests to other services, in .NET projects this is generally configured in “appsettings.json” files, and in Angular projects, this is generally configured in “environment.ts” files. When we have CI/CD process using Azure Pipelines, and we work with multiple stages (eg. development, test, acceptance, production, and so on), we need to be able to replace these URLs in an automatically way in order to use the correct values for each environment. In this article, I explain how to do this configuration by using an Azure DevOps extension named “Replace Tokens” from Guillaume Rouchon. For example purpose, I’m using a .NET 6 Web API and an Angular application.

In this article, the focus will be on the configuration for the Replace Tokens, but in case you want to know more about how to create Subscription in Azure, and services such as App Service, Databases, configuring Stages in the Pipeline, and other related topics, I recommend these articles in my blog where I explain about these subjects:

How Replace Tokens Extension Works

This extension provides the possibility to configure tokens in your project files, and these tokens can be replaced by some value when the pipeline is executed. For that, we can make use of Pipelines Library in Azure DevOps.

For example, in the case of a .NET app, in the “appsettings.json” file you can have the following configuration for the “ServiceA” and “ServiceB”:

Or the following configuration in an Angular app, in the “environment.prod.ts” file, for “ServiceA” and “ServiceB”:

And now you decided to deploy the app using Azure Pipeline with multiple stages, and for each stage, you need different URLs, for example:

// For development:
https://dev-other-service/api/// For production:
https://prd-other-service/api/

You can solve this problem by creating tokens, so this is an example of how it should be the files with tokens (in this example, you can see the token between #{…}#, but you can configure your tokens in the way you want — in case you use other pattern, just make sure to explicitly specify this configuration in the pipeline task):

appsettings.json file:

environment.prd.ts file:

Now we created tokens, instead of having the values in the configuration files. But where are the values of these tokens? They will come from Pipelines Library.

Creating the Variables in Pipelines Library

A library is a collection of build and release assets for an Azure DevOps project. Assets defined in a library can be used in multiple build and release pipelines of the project. The Library tab can be accessed directly in Azure Pipelines. (Microsoft Docs)

In Azure DevOps, it’s possible to make use of the Library to store a group of variables that we can use in the pipeline. In the Library, we can configure variables that we want to use in our pipelines, and it’s also possible to add sensitive data and hide the value. In order to use the variables in the Library in Azure DevOps, go to Pipelines > Library > click in “+ Variable group”:

Create the variables, add a name for the variables group and click in save:

Do the same for other environments (in this example I’m using only two, Development and Production, but you can have how many you want):

Installing Replace Tokens Extension

Now let’s install the Replace Tokens Extension in the Azure DevOps environment. Go to the marketplace and search for Replace Tokens, or access it by clicking here. Then click on “Get it free”:

Select your organization and click on “Install”:

Then you should see this page:

Now Replace Tokens extension is installed in your Azure DevOps environment. You can check the extensions you have by clicking on “Organization Settings” > “Extensions”:

Replace Tokens in Azure Pipelines

In this step, we are going to configure the pipeline to use the Replace Tokens task in order to replace the values with the values from the variables we created in the Pipelines Library.

I will show an example of how to do that in a back-end project using .NET 6 and a front-end project using Angular.

These are the App Services I created in Azure Portal:

For back-end project in development environment: dev-replace-tokens-api.

For back-end project in production environment:prd-replace-tokens-api.

For front-end project in development environment: dev-replace-tokens-spa.

For front-end project in production environment: prd-replace-tokens-spa.

Replace Tokens in Back-End Project

In this example, I’m using a .NET 6 Web API project. In the “azure-pipelines.yml” file we have the following main steps in this exact order:

1- Build Stage

1- The configuration to use .NET 6 will be added
2- The application will be build
3- The application will be zipped and published to the pipeline artifacts

2- Development Stage

1- The files will be extracted to a folder
2- The replace tokens task will replace the tokens
3- The old files will be deleted
3- The new files (with the new values in the tokens) will be zipped
4- The new files will be deployed with the new values in the tokens
5- The application will be deployed to an App Service

3- Production Stage (will only be executed if acceptance stage succeeds and if something is merged into the master branch)

In this stage, we have the same tasks as the Development stage and the acceptance stage, the only difference is that the tokens will be replaced with the values configured in the production group variables (from Pipelines Library)

To have an overview, you can see the complete yml file below. In this file there are three stages: Build, Deploy to Development and Deploy to Production. I will explain next the configuration for the Replace Tokens (you can see some commented code for unit tests, you can use it when you have unit test in your project):

The steps below are the steps necessary in order to make use of the Replace Tokens in the Pipelines:

First, we extract the files into a folder;
Second, we configure the root directory to the same location that the files were extracted in the previous task, and configure which files we want to replace the tokens, in this example, are the JSON files that starts with “appsettings”;
Third, we delete the old files;
Fourth, we archive the new files to be deployed;
Fifth, we deploy the app;

Result

Once the pipeline runs, the tokens will be replaced with the values in the Pipelines Library and will be deployed with the correct values:

For the API deployed in the development environment, as we can see, the URLs values from the “appsettings.json” file which we added the tokens, were replaced by the values in the development group variables (from Pipelines Library in Azure DevOps):

Development — ServiceA:

Development — ServiceB:

And in production environment, the values from the URLs were replaced by the values in the production group variables:

Production — ServiceA:

Production — ServiceB:

Replace Tokens in Front-End Project

In this example, I’m using an Angular project. In the “azure-pipelines.yml” file we have the following main steps in this exact order:

1- Build Stage

1- Node.js will be installed
2- The application will be build
3- The files will be zipped
4- The artifact will be created

2- Development Stage (this will only be executed if the build stage succeeds)

1- The files will be extracted to a folder
2- The replace tokens task will replace the tokens
3- The files will be zipped
4- The files will be deployed with the new values in the tokens

3- Production Stage (will only be executed if the development stage succeeds and if something is merged into the master branch)

In this stage, we have the same tasks as the Development stage, the only difference is that the tokens will be replaced with the values configured in the production group variables (from Pipelines Library)

The steps below are the steps necessary in order to make use of the Replace Tokens in the Pipelines:

First, we extract the files into a folder;
Second, we configure the root directory to the same location that the files were extracted in the previous task, and configure which files we want to replace the tokens, in this example, are the JavaScripts files that starts with “main”;
Third, we archive the new files to be deployed;
Fourth, we deploy the app;

Result

Once the pipeline runs, the tokens will be replaced with the values in the Pipelines Library and will be deployed with the correct values:

For the app in the development environment, as we can see, the URLs values from the “environment.prod.ts” file to which we added the tokens, were replaced by the values in the development group variables (from Pipelines Library in Azure DevOps):

And in production environment, the values from the URLs were replaced by the values in the production group variables:

Conclusion

In this article, we saw how to make use of the Replace Tokens extension, in a scenario where we need to deploy a .NET 6 Web API and an Angular application that makes use of services that have different URLs for the development and production environments. Making use of this extension is a great way to implement the deployment process to multiple stages in an automatically way with token substitution. With this extension, we can configure the tokens that must be replaced by some value, configure these values in the Azure DevOps Pipelines Library, and the values will be replaced when the CI/CD pipeline runs. You can check the code of these projects here:

https://github.com/henriquesd/ReplaceTokensExamples

If you like this solution, I kindly ask you to give a ⭐️ in the repository.

Thanks for reading!

References

Replace Token — Marketplace

How to use Angular environment files in your Azure DevOps multi-stage yml release pipeline — Kevin Boosten

Using TOKEN substitution in Azure DevOps — Seamus Brady

How to use Replace Tokens in Azure Pipelines

Written by Henrique Siebert Domareski