Panduan migrasi Azure Bot Framework SDK ke Agen SDK Microsoft 365 untuk .NET

Artikel ini menjelaskan perubahan yang diperlukan untuk bermigrasi dari Bot Framework SDK untuk .NET ke Agen SDK Microsoft 365 untuk .NET.

Tip

Perlakukan pekerjaan ini sebagai upaya modernisasi, tidak hanya pertukaran paket. SDK Agen mendukung pola yang lebih sederhana dan tidak diopinisiasi (API minimal, DI, pengelogan standar) dan fitur lama yang tidak digunakan lagi seperti LUIS/QnA dan Composer. Simpan hanya apa yang sebenarnya dibutuhkan bot Anda dan hindari membawa kompleksitas templat lama ke depan.

Sumber daya Azure

Sumber daya Azure Anda yang ada tetap tidak berubah selama migrasi ini. Lanjutkan menggunakan pendaftaran Bot Azure Anda saat ini (ID Aplikasi dan rahasia); Anda mereferensikan nilai tersebut di bagian konfigurasi TokenValidation dan Connections baru yang dijelaskan nanti. Banyak solusi juga mencakup pengaturan aplikasi lama seperti MicrosoftAppType, MicrosoftAppId, MicrosoftAppPassword, dan MicrosoftAppTenantId. Entri ini tidak berbahaya selama migrasi tetapi tidak lagi digunakan oleh Agen SDK Microsoft 365, sehingga Anda dapat menghapusnya setelah memvalidasi konfigurasi baru.

Langkah pertama

Mulailah dengan memperbarui dependensi paket. Perubahan berikut tidak mencakup setiap namespace yang mungkin perlu Anda sentuh, tetapi menangani sebagian besar pengganti paket.

SDK Bot Framework Agen SDK
Microsoft.Bot.Builder.Integration.AspNet.Core Microsoft.Agents.Hosting.AspNetCore dan 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

Jika bot Anda terintegrasi dengan Microsoft Teams, sertakan paket Ekstensi Teams Microsoft.Agents.Extensions.Teams untuk fitur Teams inti.

Hapus dependensi Anda pada NewtonSoft.Json. SDK Agen menggunakan System.Text.Json untuk serialisasi.

Luangkan waktu sejenak untuk membersihkan sumber NuGet dan menyematkan versi paket. Hapus umpan pratinjau Bot Framework yang tidak digunakan lagi—seperti mantan sumber MyGet—dari NuGet.config untuk menghindari kegagalan pemulihan. Lebih baik paket Microsoft.Agents.* stabil terbaru dan pertimbangkan penyematan versi pusat (misalnya, melalui Directory.Packages.props) sehingga Anda dapat meningkatkan dengan sengaja.

Selanjutnya, perbarui namespace layanan. Pendekatan termudah adalah menemukan dan mengganti teks yang tepat di seluruh solusi.

Ruang nama Bot Framework Namespace SDK Agen
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; Hapus seluruhnya
Namespace Bot Framework Teams Namespace SDK Agen
Microsoft.Bot.Builder.Teams Microsoft.Agents.Extensions.Teams.Compat
Microsoft.Bot.Schema.Teams Microsoft.Agents.Extensions.Teams.Models

Beberapa jenis dan properti diganti namanya di SDK Agen. Gunakan pemetaan berikut untuk memandu perubahan.

Kerangka Kerja Bot Agen SDK
BotState AgentState
OAuthPromptSettings.ConnectionName OAuthPromptSettings.AzureBotOAuthConnectionName
IAttachments.GetAttachmentInfoWithHttpMessagesAsync IAttachments.GetAttachmentInfoAsync
IBotFrameworkHttpAdapter IAgentHttpAdapter
BotAdapter ChannelAdapter
CloudAdapterBase ChannelServiceAdapterBase

Perbarui referensi TurnState umum. Ganti penggunaan berikut sebagaimana mestinya.

Ruang nama Bot Framework Namespace SDK Agen
TurnState.Get<ConnectorClient> .Services.Get<IConnectorClient>
.TurnState.Get<IUserTokenClient> .Services.Get<IUserTokenClient>
.TurnState. .Services.

Inisialisasi sedikit berbeda dalam SDK Agen. Banyak sampel Bot Framework mendaftarkan injeksi dependensi di Startup.cs dan mereferensikannya dari Program.cs. Dengan SDK Agen, konsolidasikan pengaturan ini di Program.cs untuk konfigurasi gaya API minimal yang lebih sederhana.

Autentikasi juga berubah. SDK Bot Framework menyertakan autentikasi JSON Web Token (JWT) masuk di tumpukan hosting-nya, tetapi Agen SDK membiarkan autentikasi HTTP ke ASP.NET. Salin AspNetExtensions ke dalam proyek Anda untuk mengaktifkan autentikasi ASP.NET untuk permintaan masuk.

Catatan arsitektur dan kompatibilitas

Hapus layanan dan artefak yang tidak digunakan lagi sebagai bagian dari migrasi. Pembuat LUIS dan QnA dihentikan, jadi ganti penggunaan yang tersisa dengan pendekatan yang didukung seperti Azure OpenAI dengan pengambilan. SDK Agen tidak mendukung Dialog Komposer/Adaptif dan Ekspresi LG/Adaptif, jadi Anda harus menghapus aset terkait.

Dialog tetap tersedia di bawah Microsoft.Agents.Builder.Dialogs untuk kompatibilitas. Mereka terus bekerja dan merupakan jembatan praktis selama migrasi, tetapi merencanakan refaktor menuju pola orkestrasi yang lebih modern di mana itu masuk akal.

Middleware masih didukung; namun, SDK juga mengekspos kait siklus hidup giliran. Lebih baik logika giliran sebelum/sesudah kecil jika memungkinkan. Jika Anda belum siap untuk merefaktor, Anda dapat terus mendaftarkan implementasi IMiddleware yang ada melalui injeksi dependensi.

Tempelkan kode berikut ke dalam Program.cs Anda, menggantikan konten saat ini.

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

Referensikan appsetting yang ada dan tambahkan bagian berikut. Pertama, konfigurasikan TokenValidation sehingga ASP.NET dapat memvalidasi permintaan masuk.

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

Lihat komentar di AspNetExtensions untuk detail tentang semua pengaturan yang tersedia.

Selanjutnya, tentukan Koneksi. Contoh berikut menunjukkan konfigurasi penyewa tunggal menggunakan rahasia klien.

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

Lihat Konfigurasi autentikasi di agen .NET untuk detail tentang pengaturan autentikasi yang berbeda.

Perubahan serialisasi

Beberapa metode TeamsActivityHandler yang sebelumnya diperlukan JObject sekarang mengharapkan JsonElement. Hapus juga builder.Services.AddControllers().AddNewtonsoftJson(); dari Program.cs kecuali Anda secara eksplisit membutuhkannya untuk jalur kode yang tidak terkait; SDK Agen tidak memerlukannya.

Skema Lampiran dan Teams dipindahkan ke Microsoft.Agents.Core.Models dan Microsoft.Agents.Extensions.Teams.Models. Jika Anda menguraikan JSON mentah dengan Newtonsoft di masa lalu, perbarui logika tersebut untuk menggunakan System.Text.Json yang setara.

State

ConversationState, UserState, dan PrivateConversationState kompatibel dengan beberapa perbedaan. IStatePropertyAccessor tidak digunakan lagi—meskipun masih berfungsi—jadi lebih baik metode IAgentState ke depannya.

Dialog.RunAsync terus menerima IStatePropertyAccessor tetapi juga mendukung jenis penerusan AgentState atau turunan seperti ConversationState, UserState, dan PrivateConversationState. Meneruskan salah satu objek status ini secara langsung disarankan.

AutoSaveStateMiddleware ditingkatkan untuk memuat dan menyimpan status secara otomatis. Jangan gunakan dengan agen berbasis AgentApplication. Untuk agen berbasis ActivityHandler, Anda dapat menambahkannya ke adapter Anda untuk melakukan pemuatan/penyimpanan otomatis semua status:

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

Pemecahan masalah dan tips

Kiat berikut mungkin membantu Anda menjadi lebih sukses.

Kegagalan pemulihan NuGet

Jika pemulihan NuGet gagal, hapus umpan pratinjau Bot Framework yang tidak digunakan lagi dari NuGet.config dan pastikan hanya nuget.org (atau umpan artefak yang disetujui) yang dikonfigurasi.

Antarmuka ambigu

Jika Anda menemukan antarmuka yang ambigu—seperti IMiddleware atau IStorage—sepenuhnya memenuhi syarat jenis SDK Agen (misalnya, gunakan Microsoft.Agents.Storage.IStorage).

Mengakses layanan cakupan giliran

Saat mengakses layanan cakupan giliran, ganti penggunaan TurnContext.TurnState dengan TurnContext.Services. Misalnya, ambil IConnectorClient atau IUserTokenClient hingga .Services.Get<T>().

Migrasi JSON (System.Text.Json)

Untuk migrasi JSON, ganti logika JObject/JToken apa pun dengan JsonDocument/JsonElement dari System.Text.Json.

401 lokal selama penelusuran kesalahan

Jika Anda melihat 401 selama penelusuran kesalahan lokal, berikan ID Aplikasi dan rahasia Anda di Emulator, atau hapus .RequireAuthorization() sementara saat Anda mendiagnosis autentikasi.

Daftar periksa migrasi

✓ Analisis dan rencana: Identifikasi fitur yang tidak didukung (Composer, LUIS/QnA) dan putuskan untuk bermigrasi vs. membangun kembali cakupan.
✓ Mutakhirkan target .NET: Pindah ke net6.0 atau net8.0 di seluruh proyek.
✓ Ganti paket: Hapus Microsoft.Bot.*; tambahkan Microsoft.Agents.* (Builder, Core, Hosting.AspNetCore, Authentication.Msal, Penyedia penyimpanan, Teams/Teams.Compat).
✓ Perbarui namespace layanan dan jenis: Terapkan temukan/ganti per tabel di atas; perbaiki API yang diganti namanya.
✓ Program.cs: Daftarkan agen Anda melalui builder.AddAgent<T>(), status/penyimpanan, dan panggil AddAgentAspNetAuthentication; petakan /api/messages dengan otorisasi.
✓ Middleware: Lebih baik aktivitas giliran; jika diperlukan, daftarkan IMiddleware yang ada melalui DI.
✓ Bangun dan uji secara lokal: Gunakan Emulator dengan kredensial; validasi skenario inti dan perilaku Teams.
✓ Deploy dan monitor: Perbarui pengaturan aplikasi di Azure agar sesuai dengan konfigurasi baru dan tonton log setelah peluncuran.

Isi Terkait

  • Last updated on