Manage multiple environments

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

You can perform the following with multiple environments:

  1. 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.

  2. Manage app behaviors in different environments: You can set up different app behaviors for multiple environments such as enable telemetry in production environment.

    Note

    Ensure that telemetry is disabled in development environment.

    Tip

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

Create new environment

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

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

Note

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

Add remote environment:

  1. Select the Teams Toolkit From the activity bar from the activity bar.

  2. Select +Teams: Create new environment under the ENVIRONMENT section as shown in the following image:

    create new environment

Note

If you have more than one environments, then you need to select an existing environment to create the same. 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

You can select the 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: Configures the files that user can customize for Teams app.
    • config.<envName>.json: Configuration file per-environment.
    • azure.parameters.<envName>.json: Parameters file for Azure bicep provision per-environment.
    • projectSettings.json: Global project settings that apply to all environments.
  • .fx/states: Provision result that is generated by the Teams Toolkit.
    • state.<envName>.json: Provision output file per-environment.
    • <env>.userdata: User data for the provision output per-environment.
  • templates
    • appPackage: App manifest template files.
    • azure: Bicep template files.

Customize resource provision

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

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 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 templates/manifest.template.json file under manifest section in .fx/config.<envName>.json Preview app manifest in Toolkit

Scenarios

You can see the following scenarios to customize the resources provision in different environments.


Scenario 1: Customize Teams app name for different environment

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:

  1. Open config file .fx/configs/config.dev.json.
  2. 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)"
            ...
        }
    }
    ...
}
  1. You can create a new environment and name it staging if it doesn't exist.
  2. Open config file .fx/configs/config.staging.json.
  3. Update the same property myapp(staging).
  4. Now you can run provision command on dev and staging environment to update the app name in remote environments. To run provision command with Teams Toolkit, see provision.
Scenario 2: Customize Teams app description for different environment

You can set different Teams app description 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.

Steps for customization:

  1. Open config file .fx/configs/config.dev.json.
  2. Add 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"
            ...
        }
    }
    ...
}
  1. Create a new environment and name it staging if it doesn't exist.
  2. Open config file .fx/configs/config.staging.json.
  3. Add the same property to my app description for staging.
  4. Open Teams app manifest template templates/appPackage/manifest.template.json.
  5. Update the property description > short to use the variable defined in configure files with mustache 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}}", 
    ...
  },
  ...
}
  1. You can now 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, we can update the description value in it for our target:

  1. Open Teams app manifest template templates/appPackage/manifest.template.json.
  2. Update the property description > short with hard-coded 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",
    ...
  },
  ...
}

  1. You can now 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 provision cloud resources.


See also