Auto provision variable values when using Teams Toolkit

Are you a developer who likes to develop applications for Microsoft Teams or wish to develop in the future? It could be Tabs, Bots, Messaging extensions, or, any extensibility points for Microsoft Teams. If you are, then you would have used Teams Toolkit to develop your application. If you have not, then you should try it out. It is a great tool that helps you to develop applications for Microsoft Teams.

While using the Teams Toolkit, you would typically use variables available in the .env file. These variables are used to store values that are used in your application. For example, if you are developing a bot, you would need to store the bot id, bot password, tenant id, etc. in the .env file. These values are then used in the application.

By default, if you add a new variable in the .env file, it will not be deployed automatically to the AppSettings section of your App Service. Any new entry which you make in your .env file, you will have to manually add that in the AppSettings. This would be a super difficult job and there are chances you may miss to add resulting in your application not working as expected, especially when you deploy a new version.

In this blog post, I am trying to mitigate that issue for your development scenarios. I will explain how to add a new variable in the .env file and how to deploy the values automatically to Azure. This will help you to avoid the manual steps of adding the values in the Azure portal.

Please note that in this blog post, I am using the Teams Toolkit version v5. This may not be applicable to older versions. I am building a bot in this example and the reference code and project will follow the structure used in the boilerplate project generated for the Bot. However, similar changes would apply to tabs as well.

Step 1: Add a new variable in .env file

This approach will be pretty straight forward and we will assume that you have already added a new value in all the .env file. Let us assume that the value you have added is MY_NEW_VARIABLE. Your environment file will look like below.

# New Custom Variable for your business process
MY_NEW_VARIABLE="Hello Teams Toolkit"

Step 2: Make the entry in the `config.ts` for referring in your code

Now since we have added the new value, in Teams Toolkit, if you would have noticed, there is a file called config.ts. This file is used to refer to the values in your code. For example, if you are trying to access the Bot ID in your code, you would typically use config.botId rather than directly using the value by process.env.MY_NEW_VARIABLE. This is a good practice to follow. So now we need to make sure that we add the new variable in the config.ts file. You can add the variable in the config enum as shown below.

const config = {
  botId: process.env.BOT_ID,
  botPassword: process.env.BOT_PASSWORD,
  myNewVariable: process.env.MY_NEW_VARIABLE,
};

Once you have added it, you can refer to the value in your code like config.myNewVariable and the value would be automatically picked up from the .env file.

Step 3: Add the variable in `teamsapp.local.yaml` file

In Teams Toolkit 5.0, you will find a new file called teamsapp.local.yaml. This file is used to prepare all the resources locally so that you can debug your application locally. Unlike the AppSettings in the Azure App Services which would typically be used to store the values, values will be temporarily saved in the file called .localconfigs. If you have a look into that file in your repo, by default you can see that there will be values called BOT_ID and BOT_PASSWORD. Local debug will use these values to run the application locally. Now for you to have your new environment values in the local file you have to make sure that you add the variable in the teamsapp.local.yaml file. You can add the variable in the file/createOrUpdateEnvironmentFile section of teamsapp.local.yaml file as shown below.

  # Generate runtime environment variables
  - uses: file/createOrUpdateEnvironmentFile
    with:
      target: ./.localConfigs
      envs:
        BOT_ID: ${{BOT_ID}}
        BOT_PASSWORD: ${{SECRET_BOT_PASSWORD}}
        MY_NEW_VARIABLE: ${{MY_NEW_VARIABLE}}

Step 3: Add the variable in `azure.bicep` file

Teams Toolkit uses Azure Bicep to deploy the resources in Azure. As mentioned before, I am using a bot in this example. So the azure.bicep file will have the section to create AppService for hosting the bot. Hence we would make the changes in the appSettings properties of the webApp creation section. After making the modifications, the section would look like below.

      appSettings: [
        {
          name: 'WEBSITE_RUN_FROM_PACKAGE'
          value: '1' // Run Azure APP Service from a package file
        }
        {
          name: 'WEBSITE_NODE_DEFAULT_VERSION'
          value: '~18' // Set NodeJS version to 18.x for your site
        }
        {
          name: 'RUNNING_ON_AZURE'
          value: '1'
        }
        {
          name: 'BOT_ID'
          value: botAadAppClientId
        }
        {
          name: 'BOT_PASSWORD'
          value: botAadAppClientSecret
        }
        {
          name: 'MY_NEW_VARIABLE'
          value: myNewVariable
        }
      ]

You can see that we now have added a new appSettings value called MY_NEW_VARIABLE and the value is referred from the variable called myNewVariable. Now you will need to add the variable at the top of the parameter initialization section. If you have not added any other values other than the default ones available, it will be after the line param location string = resourceGroup().location. Add the below line after that.

param myNewVariable string

Step 4: Add the parameter in `azure.parameters.json` file

Now the bicep file expects the parameter named myNewVariable, we will have to pass that along with the default value so that when Teams Toolkit provisions the services, appSettings will be added to the App Service along with the value defined for the variable. For doing that add a new parameter called myNewVariable in the azure.parameters.json file as shown below.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
      "resourceBaseName": {
        "value": "ttkrnd-${{RESOURCE_SUFFIX}}"
      },
      "botAadAppClientId": {
        "value": "${{BOT_ID}}"
      },
      "botAadAppClientSecret": {
        "value": "${{SECRET_BOT_PASSWORD}}"
      },
      "webAppSKU": {
        "value": "B1"
      },
      "botDisplayName": {
        "value": "${{TEAMS_APP_NAME}}"
      },
      "myNewVariable": {
        "value": "${{MY_NEW_VARIABLE}}"
      }
    }
  }

You can see above that, we have added a new parameter called myNewVariable, and the value is referred from the variable called MY_NEW_VARIABLE whose value would be taken from the right .env file depending on your deployment environment.

Conclusion

With the above step, you do not need to worry about manually adding the settings in the AppService. Teams Toolkit will take care of it for you.

Let me know your comments if you liked this post!

Photo by Yomex Owo on Unsplash

Auto provision variable values when using Teams Toolkit

Overall Process

Step 1: Add a new variable in .env file

Step 2: Make the entry in the config.ts for referring in your code

Step 3: Add the variable in teamsapp.local.yaml file

Step 3: Add the variable in azure.bicep file

Step 4: Add the parameter in azure.parameters.json file

Conclusion

Step 2: Make the entry in the `config.ts` for referring in your code

Step 3: Add the variable in `teamsapp.local.yaml` file

Step 3: Add the variable in `azure.bicep` file

Step 4: Add the parameter in `azure.parameters.json` file