Azure Bot Framework SDK:sta Microsoft 365 -agenttien SDK siirto-ohjeet .NET

Tässä artikkelissa kuvataan tarvittavat muutokset siirtymiseksi Bot Framework SDK:sta .NET .NET Microsoft 365 -agenttien SDK.

Vinkki

Käsittele tätä työtä modernisointityönä, ei vain pakettivaihtona. Agenttien SDK suosii yksinkertaisempia, itsenäisiä kuvioita (minimaaliset ohjelmointirajapinnat, DI, vakiokirjaus) ja poistaa käytöstä vanhoja ominaisuuksia, kuten LUIS/QnA ja Composer-artefaktit. Säilytä vain botin tarpeet ja vältä vanhan mallin monimutkaisuuden viemistä eteenpäin.

Azure-resurssit

Olemassa olevat Azure resurssit pysyvät muuttumattomina tämän siirron aikana. Jatka nykyisen Azure Botin rekisteröinnin (sovellustunnus ja salauskoodi) käyttöä. Viittaat näihin arvoihin myöhemmin kuvatuissa uusissa TokenValidation- ja Connections-määritysosioissa. Monet ratkaisut sisältävät myös vanhoja sovellusasetuksia, kuten MicrosoftAppType, MicrosoftAppId, MicrosoftAppPassword ja MicrosoftAppTenantId. Nämä merkinnät ovat haitattomia siirron aikana, mutta ne eivät ole enää Microsoft 365 -agenttien SDK käytössä, joten voit poistaa ne, kun olet vahvistanut uuden määrityksen.

Ensimmäiset vaiheet

Aloita päivittämällä pakettien riippuvuudet. Seuraavat muutokset eivät kata kaikkia nimitiloja, joihin saatat joutua koskemaan, mutta ne käsittelevät useimmat pakettikorvaukset.

Bot Framework SDK Agentit SDK
Microsoft.Bot.Builder.Integration.AspNet.Core Microsoft.Agents.Hosting.AspNetCore ja Microsoft.Agents.Authentication.Msal
Microsoft.Bot.Builder Microsoft.Agents.Builder
Microsoft.Bot.Builder.Dialogs Microsoft.Agents.Builder.Dialogs
Microsoft.Bot.Builder.Azure.Blobs Microsoft.Agents.Storage.Blobs
Microsoft.Bot.Builder. Azure Microsoft.Agents.Storage.CosmosDb
Microsoft.Bot.Schema Microsoft.Agents.Core

Jos bottisi integroituu Microsoft Teams kanssa, sisällytä Teams-laajennuspakettiin Microsoft.Agents.Extensions.Teams Teamsin ydinominaisuuksille.

Poista riippuvuussuhteesi NewtonSoft.Json-tiedostoon. Agenttien SDK käyttää System.Text.Json-tiedostoa sarjoittamiseen.

Siisti NuGet-lähteet ja kiinnitä pakettiversiot. Poista kaikki vanhentuneet Bot Framework -esiversiosyötteet, kuten aiemmat MyGet-lähteet NuGet.configista palautusvirheiden välttämiseksi. Käytä mieluummin uusimpia vakaita Microsoft.Agents.*-paketteja ja harkitse keskitettyä versiokiinnittämistä (esimerkiksi Directory.Packages.propsin kautta), jotta voit päivittää tarkoituksellisesti.

Päivitä seuraavaksi nimitilat. Helpoin tapa on koko ratkaisun laajuinen tarkan tekstin etsiminen ja korvaaminen.

Bot Framework -nimitila Agenttien SDK -nimitila
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; Poista kokonaan
Bot Framework Teams -nimitila Agenttien SDK -nimitila
Microsoft.Bot.Builder.Teams Microsoft.Agents.Extensions.Teams.Compat
Microsoft.Bot.Schema.Teams Microsoft.Agents.Extensions.Teams.Models

Jotkin tyypit ja ominaisuudet nimettiin uudelleen Agenttien SDK:ssa. Seuraavien yhdistämismääritysten avulla voit ohjata muutoksia.

Bot Framework Agentit SDK
BotState AgentState
OAuthPromptSettings.ConnectionName OAuthPromptSettings.AzureBotOAuthConnectionName
IAttachments.GetAttachmentInfoWithHttpMessagesAsync IAttachments.GetAttachmentInfoAsync
IBotFrameworkHttpAdapter IAgentHttpAdapter
BotAdapter ChannelAdapter
CloudAdapterBase ChannelServiceAdapterBase

Päivitä yleiset TurnState-viittaukset. Korvaa seuraavat käytöt vastaavasti.

Bot Framework -nimitila Agenttien SDK -nimitila
TurnState.Get<ConnectorClient> .Services.Get<IConnectorClient>
.TurnState.Get<IUserTokenClient> .Services.Get<IUserTokenClient>
.TurnState. .Services.

Alustaminen eroaa hieman Agenttien SDK:ssa. Monet Bot Framework -mallit rekisteröivät riippuvuussuhteen kohteeseen Startup.cs ja viittaavat siihen kohteesta Program.cs. Yhdistä Agenttien SDK:n avulla nämä asetukset sisään Program.cs yksinkertaisemman ja mahdollisimman vähäisen ohjelmointirajapintatyylin määrittämiseksi.

Myös todentaminen muuttuu. Bot Framework SDK sisällytti saapuvan JSON Web Token (JWT) -todennuksen isännöintipinoon, mutta Agents SDK jättää HTTP-todennuksen ASP.NET. Kopioi AspNetExtensions projektiisi, jotta ASP.NET todennus otetaan käyttöön saapuville pyynnöille.

Arkkitehtoniset huomautukset ja yhteensopivuus

Poista vanhentuneet palvelut ja artefaktit osana siirtoa. LUIS ja QnA Maker on poistettu käytöstä, joten korvaa jäljellä olevat käyttötavat tuetuilla tavoilla, kuten Azure OpenAI noudetulla menetelmällä. Agenttien SDK ei tue Composer/Adaptive Dialogs- ja LG/Adaptive Expressions -funktioita, joten sinun on poistettava aiheeseen liittyvät resurssit.

Dialogit ovat edelleen käytettävissä kohteessa Microsoft.Agents.Builder.Dialogs yhteensopivuuden vuoksi. Ne jatkavat toimintaansa ja ovat käytännöllinen silta muuttoliikkeen aikana, mutta suunnittelevat refaktoreita kohti modernimpia orkestrointimalleja, joissa se on järkevää.

Väliohjelmistoja tuetaan edelleen; SDK näyttää kuitenkin myös elinkaarikoukut. Käytä mieluummin pientä ennen tai jälkeen kääntämisen logiikkaa, kun se on mahdollista. Jos et ole valmis muodostamaan tiedostoa uudelleen, voit jatkaa olemassa olevien IMiddleware -toteutusten rekisteröintiä riippuvuuslisäyksellä.

Liitä seuraava koodi kohteeseen Program.cs ja korvaa nykyinen sisältö.

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

Viittaa olemassa oleviin sovellusasetuksiisi ja lisää seuraavat osiot. Määritä ensin TunnusValidaatio, jotta ASP.NET voivat vahvistaa saapuvat pyynnöt.

"TokenValidation": {
  "Enabled": true,
  "Audiences": [
    "{{MicrosoftAppId-value}}"
  ],
  "TenantId": "{{MicrosoftTenantId-value}}"
},

Katso lisätietoja kaikista käytettävissä olevista asetuksista AspNetExtensions-kommenteista.

Määritä seuraavaksi Yhteydet. Seuraavassa esimerkissä näytetään yhden vuokraajan määritys asiakassalaisuuksien avulla.

"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"
  }
],

Katso lisätietoja eri todennusasetuksista artikkelista Todennuksen määrittäminen .NET agentissa.

Sarjoitus muuttuu

Jotkin TeamsActivityHandler menetelmistä, jotka vaadittiin aiemmin JObject odottavat nyt JsonElement. Poista myös builder.Services.AddControllers().AddNewtonsoftJson(); Program.cs:sta, ellet nimenomaisesti tarvitse sitä liittymättömiin koodipolkuihin; Agenttien SDK ei vaadi sitä.

Liite- ja Teams-rakenteet, jotka on siirretty kohteeseen Microsoft.Agents.Core.Models ja Microsoft.Agents.Extensions.Teams.Models. Jos olet aiemmin jäsentänyt raa'an JSON:n Newtonsoftin kanssa, päivitä tämä logiikka käyttämään System.Text.Json vastaavia.

Osavaltio

ConversationState, UserState ja PrivateConversationState ovat yhteensopivia muutamien eroavaisuuksien kanssa. IStatePropertyAccessor on vanhentunut – vaikkakin silti toiminnallinen – joten suosi IAgentState menetelmiä jatkossa.

Dialog.RunAsync hyväksyy edelleen IStatePropertyAccessor, mutta tukee myös välitys- AgentState tai johdettuja tyyppejä, kuten ConversationState, UserState ja PrivateConversationState. Yhden näistä tilan objekteista välittämistä suoraan suositellaan.

AutoSaveStateMiddleware on parannettu lataamaan ja tallentamaan tilan automaattisesti. Älä käytä sitä kohteeseen AgentApplication perustuvien agenttien kanssa. ActivityHandler-pohjaisia agentteja varten voit lisätä sen sovittimeen, jos haluat ladata tai tallentaa koko tilan automaattisesti:

adapter.Use(new AutoSaveStateMiddleware(true, conversationState, userState));

Vianmääritys ja vihjeet

Seuraavat vihjeet saattavat auttaa sinua menestymään paremmin.

NuGet-palautusvirheet

Jos NuGet-palauttaminen epäonnistuu, poista vanhentuneet Bot Framework -esiversiosyötteet NuGet.config ja varmista, että vain nuget.org (tai hyväksytty artefaktin syöte) on määritetty.

Moniselitteiset käyttöliittymät

Jos kohtaat moniselitteisiä liittymiä, kuten IMiddleware tai IStorage, hyväksyt agenttien SDK-tyypit täydellisesti (esimerkiksi käytä Microsoft.Agents.Storage.IStorage).

Vuorokohtaisten palveluiden käyttäminen

Kun käytät käyttäessäsi käytettävien alueiden palveluja, korvaa TurnContext.TurnState käyttö arvolla TurnContext.Services. Voit esimerkiksi noutaa kohteen IConnectorClient tai IUserTokenClient kautta kohteen .Services.Get<T>().

JSON-siirto (System.Text.Json)

Jos kyseessä on JSON-siirto, korvaa mikä tahansa JObject/JToken logiikka arvolla JsonDocument/JsonElement kohteesta System.Text.Json

Paikallinen 401-luku virheenkorjauksen aikana

Jos näet 401-lukua paikallisen virheenkorjauksen aikana, anna sovellustunnus ja salasana emulaattorissa tai poista se tilapäisesti .RequireAuthorization() todentamisen diagnosoinnin aikana.

Siirron tarkistusluettelo

✓ Analysoi ja suunnittele: Tunnista ominaisuudet, joita ei tueta (Säveltäjä, LUIS/QnA) ja päätä siirtyä tai rakentaa uudelleen.
( Upgrade .NET target: Siirry projekteissa net6.0:aan tai net8.0:aan.
✓ Korvaa paketit: Poista Microsoft.Bot.*; lisää Microsoft.Agents.* (Builder, Core, Hosting.AspNetCore, Authentication.Msal, Storage providers, Teams/Teams.Compat).
✓ Päivitä nimitilat ja tyypit: Käytä hakua/korvaamista yllä olevissa taulukoissa; korjaus, jonka nimet on nimetty uudelleen ohjelmointirajapinnoille.
✓ Program.cs: Rekisteröi agenttisi -palvelun kautta builder.AddAgent<T>() tilan/tallennustilan kautta ja kutsu AddAgentAspNetAuthentication; kartta /api/messages valtuutuksella.
✓ Väliohjelmisto: Käännöstapahtumien suosiminen; tarvittaessa rekisteröidy aiemman IMiddleware DI:n kautta.
✓ Luo ja testaa paikallisesti: käytä emulaattoria tunnistetiedoilla; vahvistetaan tärkeimmät skenaariot ja Teamsin toiminta.
( Deploy ja monitor: Päivitä Azure sovellusasetukset vastaamaan uutta kokoonpanoa ja katso lokit käyttöönoton jälkeen.

Liittyvä sisältö

  • Last updated on