使用 Bot Framework Rich Cards 构建富卡片交互机器人：BotUsingCards 示例深度解析

示例工程【免费下载链接】ailabExperience, Learn and Code the latest breakthrough innovations with Microsoft AI项目地址https://gitcode.com/gh_mirrors/ai/ailab点击查看免费下载本指南围绕 Microsoft AI Lab 仓库中的GoogleAssistantConnector/DemoBot/BotUsingCards示例系统讲解 Bot Frameworkv4中八种 Rich Cards富卡片的创建、发送与选择交互机制并给出本地运行、模拟器测试与 Azure 部署的完整实操路径。读完本文你将理解卡片在对话机器人中的角色掌握 Hero、Thumbnail、Receipt、Signin、Animation、Video、Audio 与 Adaptive Card 的代码级构造方法并能在自己的机器人中复用这套对话框编排模式。一、概念基础什么是 Bot什么是 Rich Cards原 README 开篇定义了本示例的两个核心概念Bot机器人一个让用户通过文本、图形卡片或语音进行对话式交互的应用。它既可以是简单的问答对话框也可以是基于模式匹配、状态跟踪与人工智能技术、与现有业务服务深度集成的智能服务入口。Bot Framework 将对话式交互作为一等公民机器人通过 Activity活动与用户交换消息。Rich Cards富卡片大多数消息通道Channel都支持富内容。卡片正是把纯文本对话升级为结构化视觉交互的载体——一条消息里可以附带图片、按钮、媒体与结构化信息而不是仅仅一行文字。本示例的目标就是逐一探索机器人可以使用的不同卡片类型。在 CardsBot.cs 的类注释中明确写道Microsoft Bot Framework currently supports eight types of rich cards. We will demonstrate the use of each of these types in this project.——即本工程完整演示了框架支持的八种富卡片这也是整个示例的灵魂。二、示例工程结构速览在动手运行之前先理解示例的工程布局以下路径均相对仓库根目录文件/目录作用CardsBot.cs机器人主逻辑负责八种卡片的生成与发送Startup.csASP.NET Core 启动配置注册 Bot、状态存储与访问器CardsBotAccessors.cs会话状态访问器暴露对话框状态属性appsettings.json应用配置.bot 文件路径与加密密钥using-cards.botBot 配置文件声明开发/生产两个端点Resources/adaptiveCard.jsonAdaptive Card 的 JSON 模板航班信息卡片DeploymentScripts/msbotClone/bot.recipeMSBot 克隆部署所需的资源清单wwwroot/default.htm本地运行时的欢迎主页CardsBot.csproj工程文件声明依赖AdaptiveCards 1.0.3、Microsoft.Bot.Builder 4.2.2 等从 CardsBot.csproj 可以看到示例基于netcoreapp2.1核心依赖为Microsoft.Bot.Builder、Microsoft.Bot.Builder.Dialogs、Microsoft.Bot.Builder.Integration.AspNet.Core、Microsoft.Bot.Configuration均为 4.2.2以及AdaptiveCards1.0.3——这决定了运行环境需要支持 .NET Core 2.1 及以上 SDK。三、八种富卡片逐一拆解源码级机器人入口在 CardsBot.cs 的OnTurnAsync方法当收到ActivityTypes.Message消息时创建对话框上下文并继续/启动对话框当收到ConversationUpdate新成员加入时发送欢迎语其他类型活动则原样回显。所有卡片最终都以Attachment附件的形式挂在回复消息上发出这是 Bot Framework 发送卡片的统一机制。3.1 Hero Card英雄卡片Hero Card 是一张大图 标题/副标题/文本 按钮的经典营销式卡片。源码中的GetHeroCard()构造了标题 BotFramework Hero Card、副标题、宣传文本、图片与一个 Get Started 打开链接按钮ActionTypes.OpenUrl并通过GetHeroCard().ToAttachment()转为附件var heroCard new HeroCard { Title BotFramework Hero Card, Subtitle Microsoft Bot Framework, Text Build and connect intelligent bots to interact with your users naturally..., Images new ListCardImage { new CardImage(https://sec.ch9.ms/.../buildreactionbotframework_960.jpg) }, Buttons new ListCardAction { new CardAction(ActionTypes.OpenUrl, Get Started, value: https://docs.microsoft.com/bot-framework) }, };3.2 Thumbnail Card缩略图卡片与 Hero Card 结构几乎一致区别在于图片尺寸更小、以缩略图形式呈现适合列表式的多条目信息展示。源码GetThumbnailCard()的字段集合同 Hero CardTitle、Subtitle、Text、Images、Buttons。3.3 Receipt Card收据卡片Receipt Card 专为订单/支付场景设计包含Title、Facts键值对信息如订单号、支付方式、Items商品明细每项含名称、单价、数量、图片、Tax、Total和按钮。源码示例模拟了一笔 90.95 美元的订单Data Transfer 与 App Service 两项按钮跳转到 Azure 定价页。这是八种卡片中字段最丰富、最适合电商类机器人的类型。3.4 Signin Card登录卡片Signin Card 只有一个核心用途触发 OAuth 登录流程。它通过ActionTypes.Signin类型的按钮引导用户完成身份认证按钮 value 指向登录地址var signinCard new SigninCard { Text BotFramework Sign-in Card, Buttons new ListCardAction { new CardAction(ActionTypes.Signin, Sign-in, value: https://login.microsoftonline.com/) }, };3.5 Animation Card动画卡片Animation Card 用于播放 GIF 等动画媒体包含Title、Subtitle、缩略图Image与Media列表。源码示例指向一张 GIF 动图MediaUrl即为媒体地址。3.6 Video Card视频卡片Video Card 内嵌视频播放器字段包含Title、Subtitle、Text、封面图Image、Media视频地址与Buttons。源码示例使用了 Blender 基金会开源影片《Big Buck Bunny》并附带 Learn More 按钮。注意视频能否内联播放取决于具体通道是否支持。3.7 Audio Card音频卡片Audio Card 用于嵌入音频文件如 wav、mp3结构与 Video Card 类似Title、Subtitle、Text、封面Image、Media与按钮。源码示例引用了《星球大战》台词音频 I am your father 并附 Read More 按钮。3.8 Adaptive Card自适应卡片Adaptive Card 是最强大、也是本示例唯一以 JSON 形式组织的卡片类型——它不依赖特定语言构造器而是由跨平台标准化的 JSON Schema 描述可在各平台自适应渲染。示例将模板存放在 Resources/adaptiveCard.json代码通过文件读取 JSON 反序列化生成附件string[] paths { ., Resources, adaptiveCard.json }; var adaptiveCardJson File.ReadAllText(Path.Combine(paths)); var adaptiveCardAttachment new Attachment() { ContentType application/vnd.microsoft.card.adaptive, Content JsonConvert.DeserializeObject(adaptiveCardJson), };模板本身是一张航班确认卡片旧金山 SFO ⇄ 阿姆斯特丹 AMS 往返行程展示了 Adaptive Card 的核心元素TextBlock文本块支持weight/isSubtle/spacing/size/color等样式属性、ColumnSet/Column多列布局、Image图片、speak语音朗读文本与$schema/version版本声明。读透这份 JSON你就掌握了 Adaptive Card 最基本的文本 列 图片排版范式。四、卡片选择交互WaterfallDialog ChoicePrompt 编排卡片不是孤立的展示本示例还演示了如何让用户点选想看哪张卡片——这是对话框Dialogs机制的标准用法。在 CardsBot.cs 的构造函数中注册了两类对话框组件this._dialogs new DialogSet(accessors.ConversationDialogState); this._dialogs.Add(new WaterfallDialog(cardSelector, new WaterfallStep[] { ChoiceCardStepAsync, ShowCardStepAsync })); this._dialogs.Add(new ChoicePrompt(cardPrompt));WaterfallDialog瀑布对话框把一次对话拆成多个按顺序执行的步骤Step。cardSelector由两个步骤组成——先询问用户想看哪张卡片再根据回答展示对应卡片。ChoicePrompt选择提示以选项列表形式向用户发问。GenerateOptions方法为它注入了九个选项Adaptive card、Animation card、Audio card、Hero card、Receipt card、Signin card、Thumbnail card、Video card以及一个 All cards一次看全部。交互链路如下用户发消息 →OnTurnAsync检测到ActivityTypes.Message创建对话框上下文并ContinueDialogAsync首次进入DialogTurnStatus.Empty时通过BeginDialogAsync(cardSelector)启动瀑布对话框第一步ChoiceCardStepAsync调用PromptAsync(cardPrompt, ...)弹出选项用户选择后进入第二步ShowCardStepAsync把输入文本ToLowerInvariant().Split( )[0]取首词与 hero、thumb、receipt、sign、animation、video、audio、adaptive 前缀匹配命中则回复对应卡片否则进入else分支——以Carousel轮播布局一次展示全部八张卡片reply.AttachmentLayout AttachmentLayoutTypes.Carousel; reply.Attachments.Add(CreateAdaptiveCardAttachment()); reply.Attachments.Add(GetHeroCard().ToAttachment()); // ... 其余六张卡片依次加入最后EndDialogAsync结束本轮并提示 Type anything to see another card.。这一提示 → 选择 → 分发 → 展示的编排是从 BotUsingCards 中可以直接借鉴到任意机器人里的通用模式。五、状态与配置.bot 文件、存储与访问器5.1 配置三件套示例的配置由三个文件协同完成appsettings.json仅两个键——botFilePath.bot 文件路径默认using-cards.bot与botFileSecret.bot 文件加密密钥默认空字符串。关键提示如果你把 .bot 文件用 MSBot 工具加密过必须在此填入 botFileSecret否则 Startup.cs 中BotConfiguration.Load会因无法解密而加载失败Azure Bot Service 的机器人可在应用设置Application Settings中找到该密钥。若未加密则留空即可。using-cards.bot声明两个端点服务——developmenthttp://localhost:3978/api/messages本地调试用与productionhttps://yourbotname.azurewebsites.net/api/messages部署后替换为真实域名每个端点含appId/appPassword本地调试时留空生产环境填入注册信息。Startup.cs启动时加载 .bot 文件文件不存在则抛FileNotFoundException按环境名development/production挑选端点并用其AppId/AppPassword构造SimpleCredentialProvider作为机器人的凭据提供者同时注册OnTurnError错误处理器把对话轮次内的异常记录日志并向用户回复兜底文案。5.2 存储与状态访问器Startup.cs 默认使用MemoryStorage构建ConversationState会话级状态。注释明确指出MemoryStorage 仅用于本地调试机器人重启后内存数据全部丢失生产环境应改用 Azure Blob Storage 或 Cosmos DB代码中以注释形式给出了 AzureBlobStorage 的接入示例需引入Microsoft.Bot.Builder.Azure包并配合 .bot 文件中的存储配置。状态访问器 CardsBotAccessors.cs 封装了唯一的属性访问器ConversationDialogState内部名称CardsBotAccessors.DialogState用于读写对话框状态。整个运行链路可以概括为配置.bot appsettings→ 凭证CredentialProvider→ 存储MemoryStorage→ 会话状态ConversationState→ 访问器Accessors→ 对话框DialogSet→ 卡片发送每一环都对应着 Startup.cs 与 CardsBot.cs 中的具体实现。六、本地运行指南原 README 提供了两条本地运行路径均可直接照做6.1 方式一Visual Studio打开解决方案 DemoBot.sln或直接打开 CardsBot.csproj按F5运行项目。程序入口在 Program.csWebHost.CreateDefaultBuilder创建主机启用AddAzureWebAppDiagnostics日志另预留了 Debug/Console 与 Application Insights 的接入注释随后UseStartupStartup()拉起 Bot 服务。运行成功后访问http://localhost:3978会看到 wwwroot/default.htm 提供的欢迎页页面提示通过 Emulator 打开 .bot 文件测试而机器人消息端点即http://localhost:3978/api/messages。6.2 方式二.NET Core CLI# 在示例目录下执行路径相对于仓库根目录 cd GoogleAssistantConnector/DemoBot/BotUsingCards dotnet run前置条件安装 .NET Core CLI 工具本示例目标框架为netcoreapp2.1需要对应 SDK。运行时若 Startup.cs 报 The .bot configuration file was not found请确认appsettings.json中的botFilePath与 .bot 文件实际位置一致。七、用 Bot Framework Emulator 测试EmulatorBot Framework Emulator是微软官方的桌面调试工具支持在 localhost 或通过隧道远程调试机器人这也是验证卡片效果最快的方式安装 Bot Framework Emulator本地运行后浏览器欢迎页中也有下载入口启动 Emulator选择File → Open bot导航到GoogleAssistantConnector/DemoBot/BotUsingCards目录选中using-cards.bot文件打开。连接后发送任意消息即可触发卡片选择流程机器人先以选项形式询问 What card would you like to see?你点击或输入卡片名称后对应类型的富卡片就会以附件形式渲染在会话窗口中选择 All cards 则会看到八种卡片以轮播Carousel形式横向排列。Emulator 也支持通过隧道工具如 ngrok把本地机器人暴露到公网供远程通道联调。八、部署到 Azure原 README 推荐使用 MSBotBot Builder CLI 工具一键克隆并配置示例依赖的 Azure 服务核心命令如下msbot clone services -f deploymentScripts/msbotClone -n BOT-NAME -l Azure-location --subscriptionId Azure-subscription-id --appId YOUR APP ID --appSecret YOUR APP SECRET PASSWORD参数说明-f deploymentScripts/msbotClone指向资源清单目录本仓库中对应 DeploymentScripts/msbotClone/bot.recipe-n BOT-NAME机器人名称-l Azure-locationAzure 区域--subscriptionIdAzure 订阅 ID--appId/--appSecret机器人在 Microsoft 应用注册门户中注册得到的应用 ID 与密码即 Bot App ID/Secret部署后需回填到 using-cards.bot 的 production 端点与 Startup.cs 的凭证配置中。本仓库携带的 bot.recipe 声明了克隆时需要创建的资源development/production两个端点对应本地 3978 端口与 Azure Web App 消息端点以及一个名为cards-Insights的 Application Insights 资源——MSBot 会依据这份清单在 Azure 上创建并关联这些服务随后把生成的连接信息写回 .bot 文件。部署完成并填充 appId/appSecret 后即可把 production 端点替换为https://your-bot-name.azurewebsites.net/api/messages。九、延伸阅读与仓库内参考资料围绕本示例你还可以在仓库中继续深挖以下关联内容GoogleAssistantConnector/README.md展示如何通过 Google Assistant Proxy 把本例这类 Bot Framework 机器人接入 Google AssistantDirect Line 通道以及完整的 actions.json 模板与部署脚本说明GoogleAssistantConnector/DemoBot/DemoBot.sln示例所属的解决方案文件CardsBot.cs八种卡片的全部构造代码含 Receipt Card 的 Fact/ReceiptItem 明细与各类卡片按钮的ActionTypes用法是最完整的可直接复用的卡片代码库。小结从概念上看本示例回答了机器人如何用富卡片与用户对话从实现上看它覆盖了八种卡片的构造、Adaptive Card 的 JSON 模板、基于 WaterfallDialog 的选择式交互以及从本地运行、模拟器调试到 Azure 部署的完整链路。无论你是要在电商场景复刻 Receipt Card还是想用 Adaptive Card 做跨平台动态界面这个示例都是一份开箱即用的参照实现。赞分享示例工程【免费下载链接】ailabExperience, Learn and Code the latest breakthrough innovations with Microsoft AI项目地址https://gitcode.com/gh_mirrors/ai/ailab点击查看免费下载相关推荐Windows-universal-samples 联系人卡片Contact Cards示例全解析迷你卡片、延迟加载与全尺寸卡片实战Windows universal samples 联系人卡片Contact Cards示例全解析迷你卡片、延迟加载与全尺寸卡片实战 本文以 Window示例工程使用 Webview View API 在资源管理器中构建交互式视图Calico Colors 示例深度解析使用 Webview View API 在资源管理器中构建交互式视图Calico Colors 示例深度解析 导读 本文以 webview view samp示例工程WeChat Bot Xposed深度解析构建无需Root的微信机器人WeChat Bot Xposed深度解析构建无需Root的微信机器人 微信机器人开发一直是Android自动化领域的热门话题而基于Xposed框架的实现方上一篇Cosign 贡献指南从本地构建、单元测试、一致性测试到文档生成的全流程实战下一篇10分钟定位N1查询瓶颈Awesome Django性能优化工具箱与排查清单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考