Manage multiple environments in Teams Toolkit v4

Article
05/17/2023

Important

We've introduced the Teams Toolkit v5 extension within Visual Studio Code. This version comes to you with many new app development features. We recommend that you use Teams Toolkit v5 for building your Teams app.

Teams Toolkit v4 extension will soon be deprecated.

Teams Toolkit provides a simple way for you to create and manage multiple environments. You can use environments to provision resources and deploy artifacts to the target environment for your Microsoft Teams app.

You can perform the following activities with environments:

Test before production: You can set up multiple environments, such as dev, test, and staging before publishing a Teams app to production environment in modern app development lifecycle.
Manage app behaviors in different environments: You can set up different app behaviors for multiple environments, such as enabling telemetry in the production environment.

Note

Ensure that telemetry is disabled in the development environment.

Create a new environment

Each project can have one local environment but multiple remote environments. After you create a project, Teams Toolkit configures the following default environments:

local environment to represent the local machine environment configuration.
dev environment to represent the remote or cloud environment configuration.

To create a new environment:

Open your Teams app project in Visual Studio Code.
Select the Teams Toolkit from the Visual Studio Code activity bar.
Select + Create new environment under ENVIRONMENT.

If you've more than one environment, you need to select an existing environment to create the new environment. The command copies the file contents of config.<newEnv>.json and azure.parameters.<newEnv>.json from the selected environment to the new environment that you’re creating.

Target environment

Teams Toolkit prompts you to select a target environment when you've multiple remote environments.

add env

Project folder structure

After creating the project, you can view the project folders and files under EXPLORER in Visual Studio Code. Besides the custom codes, Teams Toolkit uses some files to maintain the configs, states, and templates of the app. The following list provides files and outlines their relationship with multiple environments:

.fx\configs: Configuration files that the user can customize for the Teams app.
- config.<envName>.json: Configuration file for the environment. This file exists for every environment individually.
- azure.parameters.<envName>.json: Parameters file for Azure bicep provision for every environment.
- projectSettings.json: Global project settings that apply to all environments.
.fx\states: Teams Toolkit generates the provision output in this folder after you provision resources for your app.
- state.<envName>.json: Provision output file for the environment. This file exists for every environment individually.
- <env>.userdata: User data for the provision output for the environment. This file exists for every environment individually.
templates
- appPackage: App manifest (previously called Teams app manifest) template files.
- azure: bicep template files.

Customize resource provision

Teams Toolkit allows you to customize the resource provision in each environment by changing the configuration and template files.

The following table lists the common scenarios for customized resource provision:

Scenarios	Location	Description
Customize Azure Resource	`bicep` files under `templates\azure` `.fx\azure.parameters.<envName>.json`	Customize ARM parameters and templates
Reuse existing Microsoft Azure Active Directory (Azure AD) app for Teams app	`auth` section in`.fx\config.<envName>.json`	Use an existing Azure AD app for your Teams app
Reuse existing Azure AD app for bot	`bot` section in`.fx\config.<envName>.json`	Use an existing Azure AD app for your bot
Skip adding user while provisioning SQL	`skipAddingSqlUser` property in`.fx\config.<envName>.json`	Skip adding user for SQL database
Customize app manifest	`manifest.template.json` file is available under `templates\appPackage`	Preview app manifest in Toolkit

Scenarios

The following scenarios show how to customize the resource provision in different environments:

Scenario 1: Customize the Teams app name for different environments

You can set the Teams app name to myapp(dev) for the default environment dev and myapp(staging) for the staging environment, staging. Here, myapp denotes the name of your app project or app name.

Steps for customization:

Open the configuration file .fx\configs\config.dev.json.
Update the value of the property manifest > appName > short to myapp(dev).

The updates to .fx\configs\config.dev.json are:

{
    "$schema": "https://aka.ms/teamsfx-env-config-schema",
    "description": "You can customize the TeamsFx config for different environments.   Visit https://aka.ms/teamsfx-env-config to learn more about this.",
    "manifest": {
        "appName": {
            "short": "myapp(dev)"
            ...
        }
    }
    ...
}

Create a new environment and name it staging, if a staging environment doesn't exist.
Open the configuration file .fx\configs\config.staging.json.
Update the value of the property manifest > appname > short to myapp(staging).
Run provision command on dev and staging environments to update the app name in remote environments.

Note

For more information on running provision command with Teams Toolkit, see how to provision using Teams Toolkit in Microsoft Visual Studio Code.

Scenario 2: Customize the Teams app description for different environments

You can define Teams app description for each environment:

For the default environment dev, the description is my app description for dev.
For the staging environment staging, the description is my app description for staging.

Follow these steps customizing the environment description:

Open the configuration file .fx\configs\config.dev.json.
Add a new property for manifest > description > short and enter its value as my app description for dev.

The updates to .fx\configs\config.dev.json are:

{
    "$schema": "https://aka.ms/teamsfx-env-config-schema",
    "description": "You can customize the TeamsFx config for different environments.   Visit https://aka.ms/teamsfx-env-config to learn more about this.",
    "manifest": {
        ...
        "description": {
            "short": "`my app description for dev"
            ...
        }
    }
    ...
}

Create a new environment and name it staging, if a staging environment doesn’t exist.
Open the configuration file .fx\configs\config.staging.json.
Add a new property as you did in config.dev.json and enter its value as my app description for staging.
Open the app manifest template templates\appPackage\manifest.template.json.

Update the value of property description > short to use the variable defined in configure files with braces. Use the following syntax {{config.manifest.description.short}}.

The updates to manifest.template.json are:

{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.11/MicrosoftTeams.schema.json",
"manifestVersion": "1.11",
"version": "1.0.0",
...
"description": {
  "short": "{{config.manifest.description.short}}", 
  ...
},
...

}

Run provision command against dev and staging environments to update the app name in remote environments.

Note

For more information on running provision command with Teams Toolkit, see how to provision using Teams Toolkit in Microsoft Visual Studio Code.

Scenario 3: Customize Teams app description for all environments

You can set the description of Teams app to my app description for all the environments.

Teams Toolkit shares the same app manifest templates across all environments, you can update the description value in it for your target:

Open the app manifest template templates\appPackage\manifest.template.json.

Update the value of the property description > short with the permanent string my app description.

The updates to manifest.template.json are:

{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.11/MicrosoftTeams.schema.json",
"manifestVersion": "1.11",
"version": "1.0.0",
...
"description": {
  "short": "my app description",
  ...
},
...
}

Run the provision command against all environments to update the app name in remote environments.

Scenario 4: Customize Azure resources for different environments

You can customize Azure resources provisioned for each environment. For example, edit the environment corresponding to .fx\configs\azure.parameters.{env}.json file to specify an Azure Function name.

For more information on Bicep template and parameter files, see how to provision cloud resources.