Configurer un bot .NET pour l’extension

À compter du 1er septembre 2023, il est fortement recommandé d’utiliser la méthode Étiquette de service Azure pour l’isolement réseau. L’utilisation de DL-ASE doit se limiter à des scénarios très spécifiques. Avant de mettre en œuvre cette solution dans un environnement de production, nous vous recommandons de demander conseil à votre équipe de support.

S’APPLIQUE À : SDK v4

Cet article explique comment mettre à jour un bot .NET pour qu’il fonctionne avec des canaux nommés et comment activer l’extension App Service Direct Line dans la ressource Azure App Service où le bot est hébergé.

Prérequis

• Un compte Azure. Si vous n’en avez pas encore, créez un compte gratuit avant de commencer.
• Bot .NET déployé dans Azure.
• SDK Bot Framework pour .NET 4.14.1 ou version ultérieure.

Activer l’extension App Service Direct Line

Cette section explique comment activer l’extension App Service Direct Line à l’aide de la clé d’extension App Service à partir de la configuration de canal Direct Line de votre bot.

Mettre à jour le code du bot

1. Dans Visual Studio, ouvrez votre projet de bot.
2. Autoriser votre application à utiliser des canaux nommés :

   1. Ouvrez le fichier Startup.cs.

   2. Ajoutez une référence au package NuGet Microsoft.Bot.Builder.Integration.AspNet.Core.

      using Microsoft.Bot.Builder.Integration.AspNet.Core;
      

   3. Dans la méthode Configure, ajoutez un appel à la méthode UseNamedPipes.

      public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
      {
          if (env.IsDevelopment())
          {
              app.UseDeveloperExceptionPage();
          }
      
          app.UseDefaultFiles()
              .UseStaticFiles()
              .UseWebSockets()
              // Allow the bot to use named pipes.
              .UseNamedPipes(System.Environment.GetEnvironmentVariable("APPSETTING_WEBSITE_SITE_NAME") + ".directline")
              .UseRouting()
              .UseAuthorization()
              .UseEndpoints(endpoints =>
              {
                  endpoints.MapControllers();
              });
      
          // app.UseHttpsRedirection();
      }
      

   4. Ouvrez le fichier Startup.cs.

3. Déployez votre bot mis à jour dans Azure.

Activez l’extension App Service Direct Line de votre bot

1. Dans le portail Azure, accédez à votre ressource Azure Bot.

   1. Sous Paramètres sélectionnez Canaux pour configurer les canaux à partir desquels votre bot accepte les messages.
   2. S’il n’est pas déjà activé, sélectionnez le canal Direct Line dans la liste des canaux disponibles pour activer le canal.
   3. Après avoir activé Direct Line, sélectionnez-le à nouveau dans la page Canaux.
   4. Sélectionnez l’onglet Extension App Service.
   5. Sous Clés d’extension App Service, sélectionnez l’icône d’œil en regard de la clé correspondante.

2. Accédez à la page d’accueil et sélectionnez App Services en haut de la page. Vous pouvez également afficher le menu du portail, puis sélectionner l’élément de menu App Services. Azure affiche la page App Services.

3. Dans la zone de recherche, saisissez le nom de votre ressource Azure Bot. Votre ressource est répertoriée.

   Notez que si vous passez votre curseur sur l’icône ou sur l’élément de menu, vous obtenez la liste de vos dernières ressources consultées. Votre ressource Azure Bot sera probablement répertoriée.

4. Sélectionnez votre lien de ressource.

   1. Dans la section Paramètres, sélectionnez l’élément de menu Configuration.

   2. Dans le volet de droite, ajoutez les paramètres suivants :

      Nom	Valeur
      DirectLineExtensionKey	Valeur de la clé d’extension App Service que vous avez copiée précédemment.
      DIRECTLINE_EXTENSION_VERSION	latest

   3. Si votre bot est hébergé dans un cloud Azure souverain ou restreint, où vous n’avez pas accès à Azure via le portail public, vous devez également ajouter le paramètre suivant :

      Nom	Valeur
      DirectLineExtensionABSEndpoint	Le point de terminaison spécifique au cloud Azure dans lequel votre bot est hébergé. Par exemple, pour le cloud USGov, le point de terminaison est https://directline.botframework.azure.us/v3/extension.

   4. Depuis la section Configuration, sélectionnez la section de paramètres Général et activez les sockets Web.

   5. Sélectionnez Enregistrer pour enregistrer les paramètres. Ceci redémarre Azure App Service.

Vérifiez que l’extension Direct Line et le bot sont configurés

Dans votre navigateur, accédez à https://<your_app_service>.azurewebsites.net/.bot. Si tout est correct, la page renvoie le contenu JSON suivant :

    {"v":"123","k":true,"ib":true,"ob":true,"initialized":true}

• v affiche la version de build de l’extension App Service Direct Line.
• k indique si l’extension a pu lire une clé d’extension à partir de sa configuration.
• initialisé indique si l’extension a pu télécharger les métadonnées du bot à partir d’Azure AI Bot Service.
• ib indique si l’extension a pu établir une connexion entrante au bot.
• ob indique si l’extension a pu établir une connexion sortante à partir du bot.

Dépannage

• Si les valeurs ib et ob affichées par le point de terminaison .bot sont fausses, le bot et l’extension App Service Direct Line ne peuvent pas se connecter les uns aux autres.

  1. Vérifiez que le code d’utilisation de canaux nommés a été ajouté au bot.
  2. Vérifiez que le bot est opérationnel. Les outils utiles sont Tester dans le Chat Web, connexion d’un canal supplémentaire, débogage à distance ou journalisation.
  3. Redémarrez l’intégralité d’Azure App Service dans laquelle le bot est hébergé pour vous assurer le démarrage de tous les processus.

• Si la valeur initialisée du point de terminaison .bot est fausse, l’extension App Service Direct Line ne peut pas valider la clé d’extension App Service ajoutée aux Paramètres d’application du bot ci-dessus.

  1. Vérifiez que la valeur a été correctement saisie.
  2. Basculez vers la clé d’extension alternative affichée dans la page Configurer Direct Line de votre bot.

• Permettez au bot d’utiliser le modèle d’hébergement hors processus ; sinon, vous recevrez une erreur HTTP 500.34 - Erreur d’hébergement mixte ANCM (où ANCM correspond au module ASP.NET Core). Cette erreur se produit car le modèle de bot utilise le modèle d’hébergement InProcess par défaut. Pour configurer l’hébergement hors processus, consultez le modèle d’hébergement hors processus. Pour plus d’informations, consultez Attributs de l’élément aspNetCore et Configuration avec web.config.

• Si vous tentez d’utiliser OAuth avec l’extension App Service Direct Line et que vous rencontrez l’erreur « Impossible d’obtenir l’AppId du bot à partir de la revendication d’audience », définissez ClaimsIdentity sur AudienceClaim sur le BotFrameworkHttpAdapter. Pour ce faire, vous pouvez sous-classer l’adaptateur. Par exemple :

  public class AdapterWithStaticClaimsIdentity : BotFrameworkHttpAdapter
  {
      public AdapterWithStaticClaimsIdentity(IConfiguration configuration, ILogger<BotFrameworkHttpAdapter> logger, ConversationState conversationState = null)
          : base(configuration, logger)
      {
          // Manually create the ClaimsIdentity and create a Claim with a valid AudienceClaim and the AppID for a bot using the Direct Line App Service extension.
          var appId = configuration.GetSection(MicrosoftAppCredentials.MicrosoftAppIdKey)?.Value;
          ClaimsIdentity = new ClaimsIdentity(new List<Claim>{
              new Claim(AuthenticationConstants.AudienceClaim, appId)
          });
      }
  }
  

Étapes suivantes