Bot Emulator v4.14.1中Adaptive Cards无法渲染的解决求助

问题场景 #

通过VS Code的Teams Toolkit扩展创建新Bot，在Bot Emulator中进行本地测试时，Adaptive Cards无法正常显示；即使使用默认生成的代码，卡片也无法渲染。

相关代码 #

teamsBot.js 核心逻辑 #

let txt = context.activity.text;
const removedMentionText = TurnContext.removeRecipientMention(context.activity);
if (removedMentionText) {
  // Remove the line break
  txt = removedMentionText.toLowerCase().replace(/\n|\r/g, "").trim();
}

// Trigger command by IM text
switch (txt) {
  case "welcome": {
    const card = cardTools.AdaptiveCards.declareWithoutData(rawWelcomeCard).render();
    await context.sendActivity({ attachments: [CardFactory.adaptiveCard(card)] });
    break;
  }
  case "learn": {
    this.likeCountObj.likeCount = 0;
    const card = cardTools.AdaptiveCards.declare(rawLearnCard).render(this.likeCountObj);
    await context.sendActivity({ attachments: [CardFactory.adaptiveCard(card)] });
    break;
  }
  /**
   * case "yourCommand": {
   *   await context.sendActivity(`Add your response here!`);
   *   break;
   * }
   */
}

learn.json Adaptive Card定义 #

{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "TextBlock",
      "size": "Medium",
      "weight": "Bolder",
      "text": "Learn Adaptive Card and Commands"
    },
    {
      "type": "TextBlock",
      "text": "Now you have triggered a command that sends this card! Go to documentations to learn more about Adaptive Card and Commands in Teams Bot. Click on \"I like this\" below if you think this is helpful.",
      "wrap": true
    },
    {
      "type": "FactSet",
      "facts": [
        {
          "title": "Like Count:",
          "value": "${likeCount}"
        }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.Execute",
      "title": "I Like This!",
      "verb": "userlike",
      "fallback": "Action.Submit"
    },
    {
      "type": "Action.OpenUrl",
      "title": "Adaptive Card Docs",
      "url": "https://learn.microsoft.com/en-us/adaptive-cards/"
    },
    {
      "type": "Action.OpenUrl",
      "title": "Bot Command Docs",
      "url": "https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/create-a-bot-commands-menu?tabs=desktop%2Cdotnet"
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.4"
}

截图 #

VS Code中卡片预览效果：

Bot Emulator中异常显示效果：

解决步骤 #

1. 更新Bot Emulator到最新版本 #

旧版本Bot Emulator对高版本Adaptive Card及Action.Execute的支持不完善，更新到最新版本可解决大部分兼容性问题。

2. 临时替换Action.Execute为Action.Submit（适配Emulator） #

Bot Emulator目前对Action.Execute支持有限，将learn.json中的Action.Execute替换为Action.Submit，即可正常渲染卡片：

{
  "type": "Action.Submit",
  "title": "I Like This!",
  "data": {
    "verb": "userlike"
  }
}

后续部署到Teams环境时，再改回Action.Execute即可（Teams原生支持该类型）。

3. 验证卡片渲染结果 #

在代码中添加日志，打印渲染后的卡片JSON内容，确认：

• 模板变量${likeCount}已被正确替换为数值0
• 生成的JSON符合Adaptive Card 1.4版本的Schema规范

同时检查CardFactory.adaptiveCard(card)生成的附件，确保contentType字段为application/vnd.microsoft.card.adaptive。

4. 确认本地Bot服务与Emulator的连接 #

先发送普通文本消息测试Bot是否能正常响应，排除端口占用、防火墙拦截等连接问题。确保Emulator正确配置了Bot的本地端点（如http://localhost:3978/api/messages）。

5. 校验卡片格式合法性 #

使用Adaptive Card官方验证工具检查learn.json的格式，确认无语法错误或不符合Schema的字段。

内容的提问来源于stack exchange，提问作者Dummy Cron