SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场teams-sdk-to-agents-sdk-dotnet-migration

teams-sdk-to-agents-sdk-dotnet-migration

编程与开发

查看项目

更新于 10-16 11:33

技能介绍

用途

该技能用于把客户的 Teams SDK（teams.net）机器人迁移到 .NET 版的 Microsoft 365 Agents SDK。仅适用于 teams.net 项目，即依赖 Microsoft.Teams.Plugins.AspNetCore、Microsoft.Teams.Apps、Microsoft.Teams.Api 的项目。若项目依赖 Microsoft.Bot.Builder*，应改用 bf-to-agents-sdk-dotnet-migration 技能，这不是 Bot Framework 迁移。Teams SDK 在 IContext<T> 上注册流式事件委托（如 teamsApp.OnMessage(async context => ...)），而 Agents SDK 通过 AgentApplication 子类上的处理程序方法、使用 ITurnContext 来路由活动。相关仓库：Agents SDK 为 https://github.com/microsoft/agents-for-net，Teams SDK 为 https://github.com/microsoft/teams.net。

主要能力

技能定义了一整套迁移流程：

  • 生成迁移后的项目副本，目录形如 agentsdk-<name>/dotnet/agentsdk-<name>/，包含 csproj、Program.cs、代理类、AspNetExtensions.cs、appsettings.json、launchSettings.json 和 README.md。
  • 将 Teams SDK 的 On* 注册映射为 Teams 路由特性，代理类始终是一个 [TeamsExtension] partial 类。
  • 将 Program.cs 引导从 builder.AddTeams()/UseTeams() 改为 AddAgentDefaults().AddAgent<MyAgent>().AddAgentAuthorization(...)/UseAgents()/MapDefaultAgentEndpoints()。
  • 将内联委托转换为带路由特性的处理程序方法，处理程序接收 ITeamsTurnContext。
  • 配置 application settings，从 Teams SDK 的扁平 Teams:ClientId/ClientSecret/TenantId 迁移到 Agents SDK 的 Connections + TokenValidation（可选 AgentApplication）。
  • 使用独立的 teams-app-manifest 技能生成、补全或审计 Teams 应用清单。
  • 执行构建与启动验证。

关键迁移规则

保留行为，除面向用户的运行时称谓由 bot 改为 agent 外，保持相同的命令、文本匹配与响应。README、目录描述和面向用户消息中将迁移后的运行时描述为 agent，同时保留 Azure Bot、bot ID、清单 bots[] 等平台术语。

使用稳定的 Agents SDK 包。调用方给出的最低版本是下限而非复制版本；在允许的主版本内选择最新的稳定版本，并为 Microsoft.Agents.Hosting.AspNetCore、Microsoft.Agents.Authentication.Msal、Microsoft.Agents.Extensions.MSTeams 三者确认一个共同的 major.minor 发布线。不要在没有明确策略时选择预发布版或新主版本。

包替换（示例用 RESOLVED_VERSION 替换为所选发布线的浮点版本，如 major.minor.*）：

  • 移除 Microsoft.Teams.Plugins.AspNetCore，加入 Microsoft.Agents.Hosting.AspNetCore + Microsoft.Agents.Authentication.Msal
  • 加入 Microsoft.Agents.Extensions.MSTeams
  • Microsoft.Teams.Cards（若使用）保留，Agents MSTeams 扩展复用该包

Microsoft.Agents.Hosting.AspNetCore 会传递引入 Microsoft.Agents.Builder、Microsoft.Agents.Core、Microsoft.Agents.Connector 和 Microsoft.Agents.Storage；[TeamsExtension] 源生成器随 Microsoft.Agents.Core 分发，无需显式引用分析器。

目标框架使用仓库配置的目标框架，当前为 net10.0，并将 <ImplicitUsings> 设为 disable，添加显式 using 指令。

命名空间替换（Teams SDK → Agents SDK）：

  • Microsoft.Teams.Plugins.AspNetCore.Extensions → Microsoft.Agents.Hosting.AspNetCore
  • Microsoft.Teams.Apps → Microsoft.Agents.Builder, Microsoft.Agents.Builder.App
  • Microsoft.Teams.Apps.Activities → Microsoft.Agents.Builder.App（路由）
  • Microsoft.Teams.Api.Activities → Microsoft.Agents.Core.Models
  • Microsoft.Teams.Api（模型）→ Microsoft.Agents.Core.Models
  • Teams 特有命名空间 → Microsoft.Agents.Extensions.MSTeams.*

使用方式

迁移按以下步骤进行：

  1. 搭建副本：按客户源布局创建 agentsdk-<name>/dotnet/agentsdk-<name>/，其中 AspNetExtensions.cs 必须从 Agents SDK 示例（agents-for-net 的 src/samples/EmptyAgent/AspNetExtensions.cs）逐字复制，因为 AddAgentAspNetAuthentication() 不在任何 NuGet 包中。appsettings.json 保存非机密配置，本地凭据放在被忽略的 appsettings.Development.json 或环境变量中。
  2. 将表层映射到路由特性：扫描 On* 注册，将 OnMessage 映射为 [TeamsMessageRoute]，OnConversationUpdate 映射为 [TeamsMembersAddedRoute]/[TeamsMembersRemovedRoute]，以及其他 Teams 特有的 On*。
  3. 改写 Program.cs。
  4. 编写代理类：使用 [TeamsExtension] 的 partial AgentApplication 子类，用路由特性路由每个命令，处理程序接收 ITeamsTurnContext。文本调度语义：精确文本匹配不区分大小写；textRegex 用于复现 text.Contains 分发（加 (?i) 实现不区分大小写）；无参数的 [TeamsMessageRoute] 为 catch-all 且默认 RouteRank.Last。当多个 Contains 分支可能重叠时，设置 rank（值越小优先级越高）以保留原 if/else 优先级。
  5. 配置应用设置：将值迁移到 Connections + TokenValidation（默认是使用 ClientSecret 的 SingleTenant Azure Bot），保持 checked-in 的 appsettings.json 不含真实凭据，本地值放入被忽略的 appsettings.Development.json 或环境变量，并确保身份值在 TokenValidation、服务连接和 Graph 配置之间一致。其他 Azure Bot 类型（UserAssignedMSI、MultiTenant）参见 bf-to-agents-sdk-dotnet-migration 技能及 https://aka.ms/AgentsSDK-DotNetMSALAuth。
  6. 生成或审计 Teams 应用清单：使用 teams-app-manifest 技能，在无已验证能力需要变更时保留现有清单；仅在所有必需产品决策已知时生成清单。清单证据通过瞬态结构化 manifestReport 返回。
  7. 验证：运行 dotnet build 需 0 警告/0 错误，运行迁移后的应用确认监听 http://localhost:3978 且 GET / 返回 200。

API 映射（基础对话功能）

IContext<T> context → ITurnContext turnContext（加 ITurnState、CancellationToken）；context.Activity → turnContext.Activity；await context.Send("text") → await turnContext.SendActivityAsync("text", cancellationToken: ct)；await context.Send(adaptiveCard) → await turnContext.SendActivityAsync(MessageFactory.Attachment(new Attachment(ContentTypes.AdaptiveCard, card)), ct)；new MessageActivity().WithText("t") → Activity.CreateMessageActivity().WithText("t")；.AddMention(member, addText: false) → 构造 Mention 实体并赋予 activity.Entities；context.Api（Teams REST 客户端）→ ITeamsTurnContext.Client（首选）或 TeamsExtension.GetTeamsClient(turnContext)（需 [TeamsExtension]）。

优先使用 SendActivityAsync("text", cancellationToken: ct) 发送纯文本；当回复需要实体、附件或其他活动字段时，使用 Activity.CreateMessageActivity() 及 .WithText(...) 等流式方法构建活动，再设置额外字段。

适用场景

适用于需要把 teams.net 项目迁移到 Microsoft 365 Agents SDK 的开发场景，包括 .NET 机器人迁移、路由与事件模型改写、配置结构迁移以及 Teams 应用清单的生成或审计。

限制

不适用于 Bot Framework 迁移（依赖 Microsoft.Bot.Builder* 时应改用另一技能）。路由特性来自 Microsoft.Agents.Extensions.MSTeams.App；基础 Agents SDK 路由必须使用其文档化的委托签名，例如 [ActionExecuteRoute] 使用 ITurnContext 而非 ITeamsTurnContext。不要在 Program.cs 中添加 builder.Services.AddHttpClient()。不要从同名 Teams SDK API 推断 API 形态，而应依据已安装配置版本的 XML 文档或当前 Agents SDK 源码核对。不要猜测作用域、域名、身份值或权限，遇到 needs-input 时应停止。其他未在本资料中说明的功能、收费、价格、平台或效果暂未提供。