自定义应用清单

项目
10/28/2024

应用清单 (以前称为 Teams 应用清单) 介绍了应用如何集成到 Microsoft Teams 中。搭建基架后，默认应用清单文件在中可用 appPackage/manifest.json。应用清单文件包含一些格式为的 ${{XX_XX}}环境变量，实际值使用 Microsoft Teams 工具包和 env 文件（如 env/.env.dev 和 env/.env.local）解析。

若要使用实际内容预览应用清单，Teams 工具包会在文件夹下 appPackage/build 生成预览应用清单文件，如以下文件夹结构所示：

└───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

可以在本地和远程环境中预览应用清单文件。

在本地环境中预览应用清单文件

若要在本地环境中预览应用清单文件，请选择 F5 键以运行本地调试。在中 env/.env.local生成环境变量后，将在文件夹下 appPackage/build 生成应用包和预览应用清单。

还可以从树视图触发 Zip Teams 应用包 ，或者从命令面板触发 Teams：Zip Teams 应用包 ，以生成预览应用清单和应用包。

屏幕截图显示了 Zip Teams 应用包的选择。

在远程环境中预览应用清单文件

若要在远程环境中预览应用清单文件，可以触发“从树视图 预配” 或 “Teams： 从命令面板预配”。它为远程 Teams 应用、生成应用包和文件夹下的 appPackage/build 预览应用清单生成环境变量。

还可以从树视图触发 Zip Teams 应用包 ，或者从命令面板触发 Teams：Zip Teams 应用包 ，以生成预览应用清单和应用包。

屏幕截图显示用于压缩 Teams 应用包的选项。

在 Visual Studio Code 中自定义应用清单

在本地调试或预配期间，Teams 工具包从 appPackage/manifest.json 加载应用清单，并按中 env/.env.xx定义的环境变量解析应用清单，然后在适用于 Teams 的开发人员门户中创建或更新 Teams 应用。

可以在和 teamsapp.local.yml中teamsapp.yml定义自己的manifest.json文件。例如，可以将 manifest.json 文件放在中 test/test.json，并更新 manifestPath yaml 文件中的参数。

- 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

可以定义自己的环境变量。默认manifest.json包含一些格式为 ${{xx_xx}} 的占位符。可以定义自己的环境变量，并在 manifest.json 文件中添加占位符。例如，可以通过在 env/.env.xx 文件中定义新的环境变量来自定义应用说明，并使用相应的占位符更新manifest.json。

.env.dev
```
TEAMS_APP_DESCRIPTION=This is an amazing app
```
manifest.json
```
 {
     "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
     "manifestVersion": "1.17",
     "description": {
         "short": "${{TEAMS_APP_DESCRIPTION}}",
         "full": "Full description of tab0418"
     },
 }
```
从 Teams 工具包 5.10 开始，使用 file 函数，可以将字段的值（如冗长或多行应用说明）存储在单独的文本文件中。例如，在的父文件夹中manifest.json创建一个description.txt文件来存储应用的完整说明。然后，将中的 manifest.json 值description.full设置为 $[file('description.txt')]。 Teams 工具包从文本文件中读取内容，并在生成应用包时将其用作完整说明。

description.txt
```
 This is the full description.
```
manifest.json
```
 {
     "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
     "manifestVersion": "1.17",
     "description": {
         "short": "Short description of tab",
         "full": "$[file('./description.txt')]"
     },
 }
```
还可以在中添加 env/.env.xx文件路径。然后，将的参数 file() 修改为格式的 ${{xx_xx}} 占位符。

.env.dev
```
 DESCRIPTION_PATH=./description.txt
```
manifest.json
```
{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
    "manifestVersion": "1.17",
    "description": {
        "short": "Short description of tab",
        "full": "$[file(${{DESCRIPTION_PATH}})]"
    },
}
```

验证你的应用

自定义后，可能需要验证应用清单或应用包。可以从树视图触发 验证应用程序 ，也可以从命令面板触发 Teams：验证应用程序 。有两个选项： 使用清单架构进行验证 或使用 验证规则验证应用包。

屏幕截图显示了在实用工具下选择的验证应用程序。

使用应用清单架构进行验证

此选项使用环境变量呈现 appPackage/manifest.json ，然后验证应用清单及其架构。

屏幕截图显示了使用清单架构选择的验证。

或者，使用以下Microsoft Teams 工具包命令行接口 (Teams 工具包 CLI) 命令：

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

如果遇到 MissingEnvironmentVariablesError，则表示 Teams 工具包找不到在 manifest.json 中定义的相应环境变量。可能需要运行 “预配” 或选择“F5”以生成环境变量，或手动更新 .env.xx 文件来实现该值。

屏幕截图显示缺少环境变量错误。

使用验证规则验证应用包

此选项使用验证规则验证压缩的应用包。

屏幕截图显示了使用验证规则验证应用包的选择。

或者，使用以下 Teams 工具包 CLI 命令：

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

它具有除应用清单架构以外的其他验证规则。例如，如果静态选项卡部分具有 entityId conversations 和名称，则会出现以下错误：

更新 Teams 应用

预览并验证应用清单文件后，可以通过从命令面板触发 Teams：更新 Teams 应用 命令，将本地更改同步到 Teams 开发人员门户。

屏幕截图显示了 Teams 更新应用的选择。

或者，使用以下 Teams 工具包 CLI 命令：

teamsfx update teams-app

注意

更改反映在开发人员门户中。将覆盖开发人员门户中的任何手动更新。
若要更改已发布应用的名称，必须同时修改 local.manifest 和 manifest.json 文件。

如果应用清单文件因配置文件更改或模板更改而过时，请选择以下任一操作：

仅预览版：根据当前配置覆盖本地应用清单文件。
预览和更新：根据当前配置覆盖本地应用清单文件，并更新到 Teams 平台。
取消：不执行任何操作。

预览本地和开发环境的值

在 appPackage/manifest.json中，可以转到 CodeLens 预览和 dev 环境的值local。

显示 CodeLens v5 的屏幕截图。

注意

预配环境或执行本地调试以生成环境变量。

可以通过选择“CodeLens”转到 .env 文件，其中提供了包含所有环境名称的下拉列表。选择环境后，将打开相应的 .env 文件。

显示开发环境的选择的屏幕截图。

若要预览所有环境的值，可以将鼠标悬停在占位符上。它显示环境名称和相应值的列表。如果未预配环境或执行本地调试，则环境变量可能不存在。在本地预配或调试应用以查看占位符值。

屏幕截图显示将鼠标悬停时占位符显示具有环境名称和相应值的列表。

通过