Kommentar
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
I den här artikeln beskrivs nödvändiga ändringar för att migrera från Bot Framework SDK för .NET till Microsoft 365 Agents SDK för .NET.
Tips/Råd
Behandla det här arbetet som en moderniseringsinsats, inte bara ett paketbyte. SDK för agenter prioriterar enklare och mer flexibla mönster (minimala API:er, beroendeinjektion, standardloggning) och avvecklar äldre funktioner som LUIS/QnA och Composer-artifakter. Behåll bara det som din robot faktiskt behöver och undvik att föra vidare den gamla mallkomplexiteten.
Azure resurser
Dina befintliga Azure resurser förblir oförändrade under den här migreringen. Fortsätt att använda din aktuella Azure robotregistrering (app-ID och hemlighet). Du refererar till dessa värden i de nya konfigurationsavsnitten TokenValidation och Anslutningar som beskrivs senare. Många lösningar omfattar även äldre appinställningar som MicrosoftAppType, MicrosoftAppId, MicrosoftAppPassword och MicrosoftAppTenantId. Dessa poster är ofarliga under migreringen men används inte längre av Microsoft 365 Agents SDK, så du kan ta bort dem när du har verifierat den nya konfigurationen.
De första stegen
Börja med att uppdatera paketberoenden. Följande ändringar omfattar inte alla namnrymder du kan behöva uppdatera, men de hanterar de flesta paketersättningar.
Om roboten integreras med Microsoft Teams inkluderar du Teams-tilläggspaketet Microsoft.Agents.Extensions.Teams för grundläggande Teams-funktioner.
Ta bort ditt beroende av NewtonSoft.Json. SDK för agenter använder System.Text.Json för serialisering.
Ta en stund för att rensa upp NuGet-källor och låsa paketversioner. Ta bort alla föråldrade Bot Framework förhandsversionsflöden, till exempel tidigare MyGet-källor, från NuGet.config för att undvika återställningsfel. Föredra de senaste stabila Microsoft.Agents.* paketen och överväg att fästa den centrala versionen (till exempel via Directory.Packages.props) så att du kan uppgradera avsiktligt.
Uppdatera sedan namnrymder. Den enklaste metoden är en lösningsomfattande sökning och ersättning av den exakta texten.
| Bot Framework-namnområde | SDK-namnområde för agenter |
|---|---|
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; |
Ta bort helt |
| Bot Framework Teams-namnområde | SDK-namnområde för agenter |
|---|---|
| Microsoft.Bot.Builder.Teams | Microsoft.Agents.Extensions.Teams.Compat |
| Microsoft.Bot.Schema.Teams | Microsoft.Agents.Extensions.Teams.Models |
Vissa typer och egenskaper har bytt namn i SDK för agenter. Använd följande mappningar för att vägleda ändringar.
Uppdatera vanliga TurnState referenser. Ersätt följande användningar i enlighet med detta.
| Bot Framework-namnområde | SDK-namnområde för agenter |
|---|---|
TurnState.Get<ConnectorClient> |
.Services.Get<IConnectorClient> |
.TurnState.Get<IUserTokenClient> |
.Services.Get<IUserTokenClient> |
.TurnState. |
.Services. |
Initieringen skiljer sig något mellan SDK för agenter. Många Bot Framework-exempel registrerar beroendeinmatning i Startup.cs och refererar till den från Program.cs. Med SDK för agenter konsoliderar du den här konfigurationen Program.cs för en enklare konfiguration med minimal API-stil.
Autentiseringen ändras också. Bot Framework SDK inkluderade inkommande JSON-webbtokenautentisering (JWT) i värdstacken, men Agenternas SDK lämnar HTTP-autentisering till ASP.NET. Kopiera AspNetExtensions till projektet för att aktivera ASP.NET autentisering för inkommande begäranden.
Arkitektoniska anteckningar och kompatibilitet
Ta bort inaktuella tjänster och artefakter som en del av migreringen. LUIS och QnA Maker har dragits tillbaka, så ersätt eventuell återstående användning med metoder som stöds, till exempel Azure OpenAI med hämtning. SDK för agenter stöder inte Composer/adaptiva dialogrutor eller LG/adaptiva uttryck, så du bör ta bort de tillhörande resurserna.
Dialogrutor förblir tillgängliga under Microsoft.Agents.Builder.Dialogs för kompatibilitet. De fungerar fortfarande och är ett praktiskt steg under migreringen, men planera omstruktureringar mot mer moderna orkestreringsmönster där det är lämpligt.
Mellanprogram stöds fortfarande. SDK:et exponerar dock även svänglivscykelkrokar. Föredrar liten logik före/efter tur när det är möjligt. Om du inte är redo att omstrukturera kan du fortsätta att registrera befintliga IMiddleware implementeringar via beroendeinmatning.
Klistra in följande kod i din Program.cs, för att ersätta det aktuella innehållet.
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();
appinställningar
Referera till dina befintliga apparinställningar och lägg till följande avsnitt. Konfigurera först TokenValidation så att ASP.NET kan verifiera inkommande begäranden.
"TokenValidation": {
"Enabled": true,
"Audiences": [
"{{MicrosoftAppId-value}}"
],
"TenantId": "{{MicrosoftTenantId-value}}"
},
Mer information om alla tillgängliga inställningar finns i kommentarerna i AspNetExtensions .
Definiera sedan Anslutningar. Följande exempel visar en konfiguration med en enda klientorganisation med hjälp av klienthemligheter.
"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"
}
],
Mer information om olika autentiseringsinställningar finns i Konfigurera autentisering i en .NET-agent.
Serialiseringsändringar
Vissa TeamsActivityHandler-metoder som tidigare krävdes JObject förväntar sig nu JsonElement. Ta också bort builder.Services.AddControllers().AddNewtonsoftJson(); från Program.cs om du inte uttryckligen behöver det för orelaterade kodsökvägar. SDK för agenter kräver det inte.
Bifogade filer och Teams-scheman har flyttats till Microsoft.Agents.Core.Models och Microsoft.Agents.Extensions.Teams.Models. Om du tidigare har bearbetat rå JSON med Newtonsoft, uppdatera den logiken till att använda motsvarande System.Text.Json.
Stat/län
ConversationState, UserState och PrivateConversationState är kompatibla med några skillnader.
IStatePropertyAccessor är inaktuell – även om den fortfarande fungerar – så föredra metoderna IAgentState framöver.
Dialog.RunAsync fortsätter att acceptera en IStatePropertyAccessor men stöder även överförda AgentState eller härledda typer som ConversationState, UserState och PrivateConversationState. Vi rekommenderar att du skickar ett av dessa tillståndsobjekt direkt.
AutoSaveStateMiddleware utökas för att automatiskt läsa in och spara tillstånd. Använd den inte med AgentApplication-baserade agenter. För ActivityHandler-baserade agenter kan du lägga till det i adaptern för att automatiskt läsa in/spara allt tillstånd:
adapter.Use(new AutoSaveStateMiddleware(true, conversationState, userState));
Felsökning och tips
Följande tips kan hjälpa dig att bli mer framgångsrik.
NuGet-återställningsfel
Om NuGet-återställningen misslyckas tar du bort inaktuella Bot Framework-förhandsgranskningsflöden från NuGet.config och ser till att endast nuget.org (eller ditt godkända artefaktflöde) har konfigurerats.
Otydliga gränssnitt
Om du stöter på otydliga gränssnitt – till exempel IMiddleware eller IStorage– kvalificerar du helt SDK för agenter-typerna (till exempel använd Microsoft.Agents.Storage.IStorage).
Åtkomst till turn-scoped-tjänster
När du kommer åt tjänster med turn-scoped ersätter TurnContext.TurnState du användningarna med TurnContext.Services. Du kan till exempel hämta IConnectorClient eller IUserTokenClient via .Services.Get<T>().
JSON-migrering (System.Text.Json)
För JSON-migrering ersätter du all JObject/JToken logik med JsonDocument/JsonElement från System.Text.Json.
Lokala 401:or under felsökning
Om du ser 401 under lokal felsökning anger du antingen ditt app-ID och din hemlighet i emulatorn eller tar tillfälligt bort .RequireAuthorization() när du diagnostiserar autentisering.
Checklista för migrering
✓ Analysera och planera: Identifiera funktioner som inte stöds (Composer, LUIS/QnA) och bestämmer dig för att migrera kontra återskapa omfång.
√ Uppgradera .NET mål: Uppgradera till net6.0 eller net8.0 över projekt.
✓ Ersätt paket: Ta bort Microsoft.Bot.*, lägg till Microsoft.Agents.* (Builder, Core, Hosting.AspNetCore, Authentication.Msal, lagringsprovidrar, Teams/Teams.Compat).
✓ Uppdatera namnrymder och typer: Använd sök/ersätt enligt tabellerna ovan; korrigera omdöpta API:er.
✓ Program.cs: Registrera din agent via builder.AddAgent<T>(), tillstånd/lagring och anropa AddAgentAspNetAuthentication; mappa /api/messages med auktorisering.
✓ Mellanprogram: Föredrar turn-händelser. Vid behov bör du registrera befintlig IMiddleware via DI.
√ Skapa och testa lokalt: Använd emulatorn med autentiseringsuppgifter; validera kärnscenarier och Teams-beteenden.
√ Distribuera och övervaka: Uppdatera appinställningarna i Azure för att matcha den nya konfigurationen och titta på loggar efter distributionen.