Manage multiple environments

Article
12/21/2022
5 minutes to read

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

You can perform the following activities with multiple 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.

Tip

Ensure that you have Teams app project opened in Microsoft Visual Studio code.

Create new environment

After you create a project, Teams Toolkit by default configures:

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

Note

Each project can have one local environment but multiple remote environments.

Perform the following steps to create a new environment:

Select the Teams Toolkit from the Visual Studio Code activity bar.
Select + Create new environment under ENVIRONMENT.

Note

If you have 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 existing environment you've selected to the new environment created.

Target environment

Teams Toolkit prompts you to select a target environment when you have 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 user can customize for the Teams app.
- config.<envName>.json: Configuration file for every environment.
- 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: Provision output that is generated by Teams Toolkit. Teams Toolkit creates this folder after you provision resources for your app.
- state.<envName>.json: Provision output file for every environment.
- <env>.userdata: User data for the provision output for every environment.
templates
- appPackage: 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

You can see the following scenarios 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.

Steps for customization:

Open config file .fx\configs\config.dev.json.
Update the property of 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 it doesn't exist.
Open config file .fx\configs\config.staging.json.
Update the same property myapp(staging).
Run provision command on dev and staging environment to update the app name in remote environments. To run 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 set different Teams app descriptions for the different environments:

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 for customization:

Open config file .fx\configs\config.dev.json.
Add a new property of manifest > description > short with value 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 it doesn't exist.
Open config file .fx\configs\config.staging.json.
Add the same property to my app description for staging.
Open Teams app manifest template templates\appPackage\manifest.template.json.
Update the property description > short to use the variable defined in configure files with braces 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 environment to update the app name in remote environments.

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.

As the Teams app manifest template is shared across all environments, you can update the description value in it for your target:

Open Teams app manifest template templates\appPackage\manifest.template.json.
Update the property description > short with 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 environment to update the app name in remote environments.

Scenario 4: Customize Azure resources for different environment

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

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