Customize app manifest

App manifest (previously called Teams app manifest) describes how your app integrates into Microsoft Teams. After scaffolding, the default app manifest file is available at appPackage/manifest.json. The app manifest file contains some environment variables with format of ${{XX_XX}}, and the actual values are resolved using Microsoft Teams Toolkit with env files like env/.env.dev and env/.env.local.

To preview app manifest with actual content, Teams Toolkit generates the preview app manifest files under appPackage/build folder:

└───appPackage
    └───build
        ├───appPackage.{env}.zip - Zipped app package of remote Teams app
        ├───appPackage.local.zip - Zipped app package of local Teams app
        ├───manifest.{env}.json  - Previewed manifest of remote Teams app
        └───manifest.local.json  - Previewed manifest of local Teams app

You can preview the app manifest file in local and remove environments.

Preview the app manifest file in local environment

To preview the app manifest file in local environment, you can press F5 to run local debug. After you generate the environment variables in env/.env.local, the app package and the preview app manifest are built under appPackage/build folder.

You can also trigger Zip Teams App Package from tree view or Teams: Zip Teams app Package from command palette to generate the previewed app manifest and app package.

Preview the app manifest file in remote environment

To preview the app manifest file in remote environment, you can trigger Provision from tree view or Teams: Provision in the cloud from command palette. It generates environment variables for remote Teams app, build app package and the preview app manifest under appPackage/build folder.

You can also trigger Zip Teams App Package from tree view or Teams: Zip Teams app Package from command palette to generate the preview app manifest and app package.

Customize the app manifest for Visual Studio Code

During local debug or provision, Teams Toolkit loads app manifest from appPackage/manifest.json and resolves app manifest by environment variables defined in env/.env.xx, then creates or updates Teams app in Teams Developer Portal.

1. You can define your own manifest.json file in teamsapp.yml and teamsapp.local.yml. For example, you can put your manifest.json file in test/test.json, and update the manifestPath parameters in yaml files.

   - uses: teamsApp/zipAppPackage # Build Teams app package with latest env value
     with:
     manifestPath: ./test/test.json # Path to manifest template
     outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
     outputJsonPath: ./appPackage/build/manifest.${{TEAMSFX_ENV}}.json
   

2. You can define your own environment variables. The default manifest.json contains some placeholders with format of ${{xx_xx}}. You can define your own environment variables and add placeholders in the manifest.json file. For example, you can customize app description by defining a new environment variable in env/.env.xx file, and update manifest.json with corresponding placeholder.

   .env.dev

   TEAMS_APP_DESCRIPTION=This is an amazing app
   

   manifest.json

   {
       "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
       "manifestVersion": "1.16",
       "description": {
           "short": "${{TEAMS_APP_DESCRIPTION}}",
           "full": "Full description of tab0418"
       },
   }
   

Validate Application

After customization, you may want to validate your app manifest or app package. You can trigger Validate Application from tree view, or Teams: ValidateApplication from command palette. There are two options, Validate using manifest schema or Validate app package using validation rules.

Validate using the app manifest schema

This option renders appPackage/manifest.json with environment variables, and then validates your app manifest with its schema.

CLI command:

teamsfx validate --manifest-path YOUR-PATH-TO-MANIFEST

If you meet MissingEnvironmentVariablesError, it means that Teams Toolkit can't find corresponding environment variables defined in manifest.json. You may need to run Provision or F5 to generate environment variables, or manually update .env.xx file to fulfill the value.

Validate app package using validation rules

This option validates the zipped app package with validation rules.

CLI command:

teamsfx validate --app-package-file-path YOUR-PATH-TO-APP-PACKAGE

It has another validation rules than the app manifest schema. For example, if static tab section has entityId "conversations" and name, the following error appears:

Update Teams app

After you've previewed and validated the app manifest file, you can sync your local changes to Teams Developer Portal by triggering Teams: Update Teams app command from command palette:

CLI command:

teamsfx update teams-app

Note

The change is reflected in Developer Portal. Any manual updates in Developer Portal are overwritten.

If the app manifest file is outdated due to configuration file change or template change, select any one of the following actions:

• Preview only: Local app manifest file is overwritten according to current configuration.
• Preview and update: Local app manifest file is overwritten according to current configuration and also updated to Teams platform.
• Cancel: No action is taken.

To preview values for local and dev environment

In appPackage/manifest.json, you can go to CodeLens to preview the values for local and dev environment.

Note

Provision the environment or execute local debug to generate environment variables.

You can go to .env file by selecting the CodeLens, which provide a dropdown list with all the environment names. After selecting one environment, the corresponding .env file opens.

To preview values for all the environment, you can hover over the placeholder. It shows a list of environment names and corresponding values. If you haven't provisioned the environment or executed the local debug, the environment variable may not exist. Select Trigger Teams: Provision in the cloud command to see placeholder value or Trigger local debug to see placeholder value.

See also

• Teams Toolkit Overview.
• App manifest schema
• Developer Portal for Teams
• Manage multiple environments
• Public developer preview for Microsoft Teams
• Provision cloud resources using Visual Studio Code