Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Cet article décrit les modifications requises pour migrer du Kit de développement logiciel (SDK) Bot Framework pour .NET vers le Kit de développement logiciel (SDK) Microsoft 365 Agents pour .NET.
Conseil
Traitez ce travail comme un effort de modernisation, pas seulement un échange de packages. Agents SDK favorise les modèles simples et non épinglé (API minimales, DI, journalisation standard) et déprécie les fonctionnalités héritées telles que LUIS/QnA et les artefacts Composer. Ne conservez que ce dont votre bot a réellement besoin et évitez d’emporter avec vous la complexité inutile des anciens modèles.
Ressources Azure
Vos ressources Azure existantes restent inchangées pendant cette migration. Continuez à utiliser votre inscription de bot Azure actuelle (ID d’application et secret) ; vous référencez ces valeurs dans les nouvelles sections de configuration TokenValidation et Connections décrites ultérieurement. De nombreuses solutions incluent également des paramètres d’application hérités tels que MicrosoftAppType, MicrosoftAppId, MicrosoftAppPassword, et MicrosoftAppTenantId. Ces entrées sont inoffensives lors de la migration, mais ne sont plus utilisées par le Microsoft 365 Agents SDK. Vous pouvez donc les supprimer après avoir validé la nouvelle configuration.
Premières étapes
Commencez par mettre à jour les dépendances de package. Les modifications suivantes ne couvrent pas tous les espaces de noms que vous pourriez avoir à modifier, mais elles gèrent la plupart des remplacements de packages.
| Kit de développement logiciel (SDK) Bot Framework | Kit de développement logiciel (SDK) Agents |
|---|---|
| Microsoft.Bot.Builder.Integration.AspNet.Core | Microsoft.Agents.Hosting.AspNetCore et 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 |
Si votre bot s’intègre à Microsoft Teams, incluez le package d’extension Teams Microsoft.Agents.Extensions.Teams pour les fonctionnalités principales de Teams.
Supprimez votre dépendance sur NewtonSoft.Json. Agents SDK utilise System.Text.Json pour la sérialisation.
Prenez un moment pour nettoyer les sources NuGet et épingler les versions du package. Supprimez tous les flux d’aperçu Bot Framework déconseillés, tels que les anciennes sources MyGet, de NuGet.config pour éviter les échecs de restauration. Préférez les packages stables Microsoft.Agents.* les plus récents et envisagez l’épinglage de version centrale (par exemple, via Directory.Packages.props) afin de pouvoir effectuer une mise à niveau intentionnelle.
Ensuite, mettez à jour les espaces de noms. La méthode la plus simple consiste à effectuer une recherche et un remplacement dans l’ensemble de la solution pour le texte exact.
| Espace de noms Bot Framework | Espace de noms Agents SDK |
|---|---|
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; |
Supprimer entièrement |
| Espace de noms Bot Framework Teams | Espace de noms Agents SDK |
|---|---|
| Microsoft.Bot.Builder.Teams | Microsoft.Agents.Extensions.Teams.Compat |
| Microsoft.Bot.Schema.Teams | Microsoft.Agents.Extensions.Teams.Models |
Certains types et propriétés ont été renommés dans Agents SDK. Utilisez les mappages suivants pour guider les modifications.
Mettez à jour les références courantes TurnState. Remplacez les utilisations suivantes en conséquence.
| Espace de noms Bot Framework | Espace de noms Agents SDK |
|---|---|
TurnState.Get<ConnectorClient> |
.Services.Get<IConnectorClient> |
.TurnState.Get<IUserTokenClient> |
.Services.Get<IUserTokenClient> |
.TurnState. |
.Services. |
L’initialisation diffère légèrement dans Agents SDK. De nombreux exemples Bot Framework inscrivent l’injection de dépendances et Startup.cs les référencent à partir de Program.cs. Avec Agents SDK, consolidez cette configuration Program.cs pour une configuration de style d’API minimale plus simple.
L’authentification change également. Le Kit de développement logiciel (SDK) Bot Framework incluait l’authentification JWT (JSON Web Token) entrante dans sa pile d’hébergement, mais le Kit de développement logiciel (SDK) Agents laisse l’authentification HTTP à ASP.NET. Copiez AspNetExtensions dans votre projet pour activer l’authentification ASP.NET pour les demandes entrantes.
Notes architecturales et compatibilité
Supprimez les services et artefacts déconseillés dans le cadre de la migration. LUIS et QnA Maker sont supprimés. Remplacez donc toute utilisation restante par des approches prises en charge telles que Azure OpenAI avec récupération. Agents SDK ne prend pas en charge les dialogues Composer/Adaptif et les expressions LG/Adaptives. Vous devez donc supprimer les ressources associées.
Les boîtes de dialogue restent disponibles sous Microsoft.Agents.Builder.Dialogs la compatibilité. Elles continuent de fonctionner et constituent une solution intermédiaire pratique pendant la migration, mais prévoyez des refontes vers des modèles d’orchestration plus modernes lorsque cela est pertinent.
Le middleware est toujours pris en charge ; toutefois, le SDK expose également des points d’ancrage dans le cycle de vie des tours. Préférez la logique avant/après le tour quand c’est possible. Si vous n’êtes pas prêt à refactoriser, vous pouvez continuer à inscrire des implémentations existantes IMiddleware via l’injection de dépendances.
Collez le code suivant dans votre Program.cs, en remplaçant le contenu actuel.
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
Référencez vos appsettings existantes et ajoutez les sections suivantes. Tout d’abord, configurez TokenValidation afin que ASP.NET puisse valider les demandes entrantes.
"TokenValidation": {
"Enabled": true,
"Audiences": [
"{{MicrosoftAppId-value}}"
],
"TenantId": "{{MicrosoftTenantId-value}}"
},
Pour plus d’informations sur tous les paramètres disponibles, consultez les commentaires dans AspNetExtensions.
Ensuite, définissez Connexions. L’exemple suivant montre une configuration monolocataire à l’aide de clés secrètes clients.
"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"
}
],
Consultez Configure authentication in a .NET agent pour plus d’informations sur les différents paramètres d’authentification.
Modifications de sérialisation
Certaines TeamsActivityHandler méthodes précédemment requises JObject attendent JsonElementmaintenant. Supprimez builder.Services.AddControllers().AddNewtonsoftJson(); également de Program.cs, sauf si vous en avez explicitement besoin pour des chemins de code non liés ; Agents SDK n'en a pas besoin.
Pièces jointes et Schémas Teams déplacés vers Microsoft.Agents.Core.Models et Microsoft.Agents.Extensions.Teams.Models. Si vous analysiez du JSON brut avec Newtonsoft auparavant, mettez à jour cette logique pour utiliser des équivalents System.Text.Json.
Statut
ConversationState, UserStateet PrivateConversationState sont compatibles avec quelques différences.
IStatePropertyAccessor est déconseillé, même s'il est toujours fonctionnel, préférez donc les méthodes IAgentState à l’avenir.
Dialog.RunAsync continue d’accepter un IStatePropertyAccessor mais prend également en charge la transmission AgentState ou les types dérivés tels que ConversationState, UserStateet PrivateConversationState. La transmission directe de l’un de ces objets d’état est recommandée.
AutoSaveStateMiddleware sont améliorés pour charger et enregistrer automatiquement l’état. Ne l’utilisez pas avec des assistants AgentApplication basés sur les données. Pour les assistants ActivityHandler basés sur les données, vous pouvez l’ajouter à votre adaptateur pour charger/enregistrer automatiquement tout l’état :
adapter.Use(new AutoSaveStateMiddleware(true, conversationState, userState));
Résolution des problèmes et conseils
Les conseils suivants peuvent vous aider à mieux réussir.
Échecs de restauration NuGet
Si la restauration NuGet échoue, supprimez les flux d’aperçu Bot Framework déconseillés de NuGet.config et vérifiez que seul nuget.org (ou votre flux d’artefact approuvé) est configuré.
Interfaces ambiguës
Si vous rencontrez des interfaces ambiguës, telles que IMiddleware ou IStorage, qualifiez totalement les types Agents SDK (par exemple, utilisez Microsoft.Agents.Storage.IStorage).
Accès aux services à portée de tour
Lors de l’accès aux services à portée de tour, remplacez les utilisations TurnContext.TurnState par TurnContext.Services. Par exemple, récupérez IConnectorClient ou IUserTokenClient via .Services.Get<T>().
Migration JSON (System.Text.Json)
Pour la migration JSON, remplacez n’importe quelle logique JObject/JToken parJsonDocument/JsonElement de System.Text.Json.
Erreurs 401 locales lors du débogage
Si vous voyez des erreurs 401 lors du débogage local, fournissez votre ID et secret d’application dans l’Émulateur, ou supprimez temporairement .RequireAuthorization() pendant le diagnostic de l’authentification.
Liste des éléments à vérifier pour la migration
• Analyser et planifier : identifiez les fonctionnalités non prises en charge (Composer, LUIS/QnA) et décidez de migrer ou bien de reconstruire la portée.
✓ Mettre à jour la cible .NET : passer à net6.0 ou net8.0 dans les projets.
• Remplacer les packages : supprimez Microsoft.Bot.*; ajoutez Microsoft.Agents.* (Builder, Core, Hosting.AspNetCore, Authentication.Msal, Fournisseurs de stockage, Teams/Teams.Compat).
• Mettre à jour les espaces de noms et les types : appliquez rechercher/remplacer par les tables ci-dessus ; corrigez les API renommées.
✓ Program.cs: Inscrivez votre assistant via builder.AddAgent<T>(), état/stockage et appelez AddAgentAspNetAuthentication; mappez /api/messages avec autorisation.
✓ Intergiciel : préférez les événements de tour ; si nécessaire, inscrivez-vous d'un IMiddleware existant via DI.
• Générer et tester localement : utilisez l’émulateur avec des informations d’identification ; validez les principaux scénarios et les comportements Teams.
✓ Déployer et surveiller : Mettez à jour les paramètres de l’application dans Azure pour qu’ils correspondent à la nouvelle configuration et regardent les journaux après le déploiement.