Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Este artigo descreve as alterações necessárias para migrar do SDK do Bot Framework para .NET para o SDK de Agentes do Microsoft 365 para .NET.
Dica
Trate esse trabalho como um esforço de modernização, e não apenas uma troca de pacote. O SDK de Agentes favorece padrões mais simples e sem opiniões (APIs mínimas, DI, registro em log padrão) e substitui recursos herdados como artefatos LUIS/QnA e Composer. Mantenha apenas aquilo de que seu bot realmente precisa e evite levar adiante a complexidade do modelo antigo.
Recursos do Azure
Os recursos de Azure existentes permanecem inalterados durante essa migração. Continue usando o registro atual do bot no Azure (ID do aplicativo e segredo); você fará referência a esses valores nas novas seções de configuração TokenValidation e Connections descritas posteriormente. Muitas soluções também incluem configurações de aplicativo herdadas, como MicrosoftAppType, MicrosoftAppId e MicrosoftAppPasswordMicrosoftAppTenantId. Essas entradas são inofensivas durante a migração, mas não são mais usadas pelo SDK de Agentes do Microsoft 365, portanto, você pode removê-las depois de validar a nova configuração.
Primeiras etapas
Comece atualizando as dependências de pacote. As alterações a seguir não abrangem todos os namespaces que talvez seja necessário tocar, mas elas lidam com a maioria das substituições do pacote.
Se o bot se integrar ao Microsoft Teams, inclua o pacote de extensão do Teams Microsoft.Agents.Extensions.Teams para os principais recursos do Teams.
Remova a dependência do NewtonSoft.Json. O SDK de Agentes usa System.Text.Json para serialização.
Reserve um momento para limpar as fontes do NuGet e fixar as versões do pacote. Remova todos os feeds de versão preliminar preteridos do Bot Framework, como fontes anteriores do MyGet, de NuGet.config para evitar falhas de restauração. Prefira os pacotes estáveis Microsoft.Agents.* mais recentes e considere a fixação de versão central (por exemplo, por meio de Directory.Packages.props) para que você possa atualizar intencionalmente.
Em seguida, atualize namespaces. A abordagem mais fácil é uma localização e substituição em toda a solução do texto exato.
| Namespace do Bot Framework | Namespace do SDK de agentes |
|---|---|
using Microsoft.Bot.Builder.Integration.AspNet.Core; |
using Microsoft.Agents.Hosting.AspNetCore; |
using Microsoft.Bot.Builder; |
using Microsoft.Agents.Builder; |
Microsoft.Bot.Builder.Dialogs |
Microsoft.Agents.Builder.Dialogs |
using Microsoft.Bot.Schema; |
using Microsoft.Agents.Core.Models; |
Microsoft.Bot.Connector.Authentication |
Microsoft.Agents.Connector |
using Microsoft.Bot.Builder.Teams; |
using Microsoft.Agents.Extensions.Teams.Compat; |
using Microsoft.Bot.Schema.Teams; |
using Microsoft.Agents.Extensions.Teams.Models; |
using Newtonsoft.Json; |
using System.Text.Json; |
using Newtonsoft.Json.Linq; |
Remover totalmente |
| O namespace do Bot Framework Teams | Namespace do SDK de agentes |
|---|---|
| Microsoft.Bot.Builder.Teams | Microsoft.Agents.Extensions.Teams.Compat |
| Microsoft.Bot.Schema.Teams | Microsoft.Agents.Extensions.Teams.Models |
Alguns tipos e propriedades foram renomeados no SDK de Agentes. Use os mapeamentos a seguir para orientar as alterações.
Atualize referências TurnState comuns. Substitua devidamente os usos a seguir.
| Namespace do Bot Framework | Namespace do SDK de agentes |
|---|---|
TurnState.Get<ConnectorClient> |
.Services.Get<IConnectorClient> |
.TurnState.Get<IUserTokenClient> |
.Services.Get<IUserTokenClient> |
.TurnState. |
.Services. |
A inicialização difere ligeiramente no SDK de Agentes. Muitos exemplos do Bot Framework registram a injeção de dependência no Startup.cs e a referenciam no Program.cs. Com o SDK de Agentes, consolide essa configuração Program.cs para uma configuração de estilo de API mínima mais simples.
A autenticação também muda. O SDK para Bot Framework incluiu a autenticação de entrada via JWT (JSON Web Token) na sua estrutura de hospedagem, mas o SDK para Agentes deixa a autenticação HTTP para o ASP.NET. Copie AspNetExtensions em seu projeto para habilitar ASP.NET autenticação para solicitações de entrada.
Observações de arquitetura e compatibilidade
Remova serviços e artefatos preteridos como parte da migração. O LUIS e o QnA Maker estão desativados, portanto, substitua os usos restantes por abordagens suportadas, como Azure OpenAI com recuperação de informações. O SDK de Agentes não dá suporte a diálogos adaptativos/Composer e expressões LG/Adaptive, logo, você deve remover os ativos relacionados.
As caixas de diálogo permanecem disponíveis em Microsoft.Agents.Builder.Dialogs para compatibilidade. Elas continuam funcionando e são uma ponte prática durante a migração, mas o plano refatora para padrões de orquestração mais modernos quando isso faz sentido.
Ainda há suporte para middleware; no entanto, o SDK também expõe ganchos do ciclo de vida de turno. Prefira a lógica pequena antes/depois da curva quando possível. Se não estiver pronto para refatorar, você poderá continuar registrando implementações existentes IMiddleware por meio da injeção de dependência.
Cole o código a seguir em seu Program.cs, substituindo o conteúdo atual.
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.State;
using Microsoft.Agents.Hosting.AspNetCore;
using Microsoft.Agents.Storage;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using System.Threading;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient();
// Register your bot.
// A Dialog based bot would look something like:
// builder.AddAgent<MyBot<MainDialog>>();
//
// If you used custom (CloudAdapter subclass):
// builder.AddAgent<MyBot, MyAdapter>();
builder.AddAgent<MyBot>();
// This is the same as in BF SDK and can be replaced with what you had in Startup.cs
builder.Services.AddSingleton<IStorage, MemoryStorage>();
builder.Services.AddSingleton<ConversationState>();
builder.Services.AddSingleton<UserState>();
// If you are using dialogs, copy your equivalent from Startup.cs
builder.Services.AddSingleton<MainDialog>();
// Perform any other DI included in your Startup.cs
// Do not include:
// services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();
// services.AddSingleton<IBotFrameworkHttpAdapter, ???>();
// services.AddTransient<IBot, ???>();
// services.AddSingleton<ServiceClientCredentialsFactory>(...)
// services.AddHttpClient().AddControllers().AddNewtonsoftJson
// Configure the HTTP request pipeline.
// Add AspNet token validation for Azure Bot Service and Entra. Authentication is
// configured in the appsettings.json "TokenValidation" section.
builder.Services.AddControllers();
builder.Services.AddAgentAspNetAuthentication(builder.Configuration);
var app = builder.Build();
// Enable AspNet authentication and authorization
app.UseAuthentication();
app.UseAuthorization();
app.MapPost("/api/messages",
async (HttpRequest request,
HttpResponse response,
IAgentHttpAdapter adapter,
IAgent agent,
CancellationToken cancellationToken) =>
{
await adapter.ProcessAsync(request, response, agent, cancellationToken);
}).RequireAuthorization(); ;
app.Run();
appsettings
Referencie as configurações de aplicativos existentes e adicione as seções a seguir. Primeiro, configure TokenValidation para que ASP.NET possa validar solicitações de entrada.
"TokenValidation": {
"Enabled": true,
"Audiences": [
"{{MicrosoftAppId-value}}"
],
"TenantId": "{{MicrosoftTenantId-value}}"
},
Consulte os comentários em AspNetExtensions para obter detalhes sobre todas as configurações disponíveis.
Em seguida, defina Conexões. O exemplo a seguir mostra uma configuração de locatário único usando segredos do cliente.
"Connections": {
"ServiceConnection": {
"Settings": {
"AuthType": "ClientSecret",
"AuthorityEndpoint": "https://login.microsoftonline.com/{{MicrosoftTenantId-value}}",
"ClientId": "{{MicrosoftAppId-value}}",
"ClientSecret": "{{MicrosoftAppPassword-value}}",
"Scopes": [
"https://api.botframework.com/.default"
]
}
}
},
"ConnectionsMap": [
{
"ServiceUrl": "*",
"Connection": "ServiceConnection"
}
],
Consulte Configurar a autenticação em um agente .NET para obter detalhes sobre diferentes configurações de autenticação.
Alterações de serialização
Alguns TeamsActivityHandler métodos que antes eram necessários JObject agora esperam JsonElement. Também remova builder.Services.AddControllers().AddNewtonsoftJson(); de Program.cs, a menos que você precise explicitamente dele para caminhos de código não relacionados; o SDK de Agentes não exige isso.
Anexos e esquemas do Teams movidos para Microsoft.Agents.Core.Models e Microsoft.Agents.Extensions.Teams.Models. Se você tiver analisado JSON bruto com Newtonsoft no passado, atualize essa lógica para usar System.Text.Json equivalentes.
Estadual
ConversationState, UserState e PrivateConversationState são compatíveis com algumas diferenças.
IStatePropertyAccessor é preterido, embora ainda funcional, logo, prefira os métodos IAgentState daqui para frente.
Dialog.RunAsync continua aceitando um IStatePropertyAccessor, mas também dá suporte a tipos de passagem AgentState ou derivados, como ConversationState, UserState e PrivateConversationState. É recomendável passar diretamente um desses objetos de estado.
AutoSaveStateMiddleware são aprimorados para carregar e salvar automaticamente o estado. Não o use com agentes baseados em AgentApplication. Para agentes baseados em ActivityHandler, você pode adicioná-lo ao adaptador para carregar/salvar automaticamente todos os estados:
adapter.Use(new AutoSaveStateMiddleware(true, conversationState, userState));
Solução de problemas e dicas
As dicas a seguir podem ajudar você a ser mais bem-sucedido.
Falhas na restauração do NuGet
Se a restauração do NuGet falhar, remova os feeds de versão preliminar preteridos do Bot Framework de NuGet.config e verifique se apenas nuget.org (ou o feed de artefatos aprovado) está configurado.
Interfaces ambíguas
Se você encontrar interfaces ambíguas – como IMiddleware ou IStorage– qualificam totalmente os tipos de SDK de Agentes (por exemplo, use Microsoft.Agents.Storage.IStorage).
Acesso a serviços com escopo de turno
Ao acessar serviços com escopo de turno, substitua TurnContext.TurnState os usos por TurnContext.Services. Por exemplo, recupere IConnectorClient ou IUserTokenClient por meio de .Services.Get<T>().
Migração do JSON (System.Text.Json)
Para migração do JSON, substitua qualquer JObject/JToken lógica por JsonDocument/JsonElement em System.Text.Json.
401s locais durante a depuração
Se você vir 401s durante a depuração local, forneça sua ID do aplicativo e o segredo no Emulador ou remova temporariamente .RequireAuthorization() enquanto você realiza o diagnóstico da autenticação.
Lista de verificação de migração
✓ Analisar e planejar: identifique recursos não compatíveis (Composer, LUIS/QnA) e opte por migrar X recriar escopo.
✓ Atualizar alvo do .NET: mover para o net6.0 ou net8.0 nos projetos.
✓ Substituir pacotes: remova Microsoft.Bot.*; adicione Microsoft.Agents.* (Builder, Core, Hosting.AspNetCore, Authentication.Msal, provedores de armazenamento, Teams/Teams.Compat).
✓ Atualizar namespaces e tipos: aplique localizar/substituir de acordo com as tabelas acima; corrija APIs renomeadas.
✓ Program.cs: registrar o agente por meio de builder.AddAgent<T>(), estado/armazenamento e chamar AddAgentAspNetAuthentication; mapear /api/messages com autorização.
✓ Middleware: prefira eventos de turno; se necessário, registre-se existente IMiddleware via DI.
✓ Compilar e testar localmente: use o Emulador com credenciais; validar cenários principais e comportamentos do Teams.
✓ Implantar e monitorar: atualize as configurações do aplicativo no Azure para corresponder à nova configuração e monitorar os logs após a distribuição.