Configurare un bot .NET per l'estensione

A partire dal 1° settembre 2023, è consigliabile usare il metodo tag del servizio di Azure per l'isolamento della rete. L'utilizzo di DL-A edizione Standard deve essere limitato a scenari altamente specifici. Prima di implementare questa soluzione in un ambiente di produzione, è consigliabile consultare il team di supporto per indicazioni.

SI APPLICA A: SDK v4

Questo articolo descrive come aggiornare un bot .NET per lavorare con named pipe e come abilitare l'estensione servizio app Direct Line nella risorsa del servizio app Azure in cui è stato distribuito il bot.

Prerequisiti

• Un account di Azure. Se non se ne ha già uno, creare un account gratuito prima di iniziare.
• Un bot .NET distribuito in Azure.
• Bot Framework SDK per .NET, 4.14.1 o versione successiva.

Abilitare l'estensione servizio app Direct Line

Questa sezione descrive come abilitare l'estensione servizio app Direct Line usando la chiave di estensione servizio app dalla configurazione del canale Direct Line del bot.

Aggiornare il codice del bot

1. Aprire il progetto del bot in Visual Studio.
2. Consenti all'app di usare named pipe:

   1. Aprire il file Startup.cs.

   2. Aggiungere un riferimento al pacchetto NuGet Microsoft.Bot.Builder.Integration.AspNet.Core .

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

   3. Configure Nel metodo aggiungere una chiamata al UseNamedPipes metodo .

      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. Salvare il file Startup.cs.

3. Distribuire il bot aggiornato in Azure.

Abilitare l'estensione servizio app direct line per bot

1. Nella portale di Azure passare alla risorsa di Azure Bot.

   1. In Impostazioni selezionare Canali per configurare i canali da cui il bot accetta i messaggi.
   2. Se non è già abilitata, selezionare il canale Direct Line dall'elenco Canali disponibili per abilitare il canale.
   3. Dopo aver abilitato Direct Line, selezionarlo di nuovo nella pagina Canali .
   4. Selezionare la scheda estensione servizio app.
   5. In servizio app Chiavi di estensione selezionare l'icona a forma di occhio accanto alla chiave corrispondente.

2. Passare alla home page e selezionare servizio app nella parte superiore della pagina. In alternativa, visualizzare il menu del portale e quindi selezionare la voce di menu servizio app s. Azure visualizzerà la pagina servizio app s.

3. Nella casella di ricerca immettere il nome della risorsa azure Bot . La risorsa verrà elencata.

   Si noti che se si passa il puntatore del mouse sull'icona o sulla voce di menu, si ottiene un elenco delle ultime risorse visualizzate. È probabile che la risorsa di Azure Bot sia elencata.

4. Selezionare il collegamento alla risorsa.

   1. Nella sezione Impostazioni selezionare la voce di menu Configurazione.

   2. Nel pannello destro aggiungere le impostazioni seguenti:

      Nome	valore
      DirectLineExtensionKey	Valore della chiave di estensione servizio app copiata in precedenza.
      DIRECTLINE_EXTENSION_VERSION	più recente

   3. Se il bot è ospitato in un cloud di Azure sovrano o con restrizioni diverse, in cui non si accede ad Azure tramite il portale pubblico, è necessario aggiungere anche l'impostazione seguente:

      Nome	valore
      DirectLineExtensionABSEndpoint	L'endpoint specifico del cloud di Azure in cui è ospitato il bot. Per il cloud USGov, ad esempio, l'endpoint è https://directline.botframework.azure.us/v3/extension.

   4. Nella sezione Configurazione selezionare la sezione Impostazioni generali e attivare Web Socket.

   5. Selezionare Salva per salvare le impostazioni. Il servizio app di Azure verrà riavviato.

Verificare che l'estensione Direct Line e il bot siano configurati

Nel browser, accedere a https://<your_app_service>.azurewebsites.net/.bot. Se tutto è corretto, la pagina restituirà il contenuto JSON seguente:

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

• v mostra la versione build dell'estensione servizio app Direct Line.
• k indica se l'estensione è stata in grado di leggere una chiave di estensione dalla configurazione.
• inizializzato indica se l'estensione è stata in grado di scaricare i metadati del bot dal servizio Bot di Intelligenza artificiale di Azure.
• ib indica se l'estensione è stata in grado di stabilire una connessione in ingresso al bot.
• ob indica se l'estensione è stata in grado di stabilire una connessione in uscita dal bot.

Risoluzione dei problemi

• Se i valori ib e ob visualizzati dall'endpoint .bot sono false, il bot e l'estensione servizio app Direct Line non sono in grado di connettersi tra loro.

  1. Verificare che il codice per l'uso di named pipe sia stato aggiunto al bot.
  2. Verificare che il bot sia in grado di avviare ed eseguire. Gli strumenti utili sono Test in WebChat, connessione di un canale aggiuntivo, debug remoto o registrazione.
  3. Riavviare l'intero servizio app Azure in cui è ospitato il bot per garantire un avvio pulito di tutti i processi.

• Se il valore inizializzato dell'endpoint con estensione bot è false, l'estensione servizio app Direct Line non è in grado di convalidare la chiave di estensione servizio app aggiunta all'applicazione del bot Impostazioni precedente.

  1. Verificare che il valore sia stato immesso correttamente.
  2. Passare alla chiave di estensione alternativa visualizzata nella pagina Configura Direct Line del bot.

• Abilitare il bot per l'uso del modello di hosting out-of-process; in caso contrario, verrà visualizzato un errore HTTP 500.34 - ANCM Mixed Hosting (dove ANCM è l'acronimo di ASP.NET Core Module). Questo errore si verifica perché il modello di bot usa il InProcess modello di hosting per impostazione predefinita. Per configurare l'hosting out-of-process, vedere Modello di hosting out-of-process. Per altre informazioni, vedere Attributi dell'elemento aspNetCore e Configuration con web.config.

• Se si prova a usare OAuth con l'estensione servizio app Direct Line e viene visualizzato l'errore "Impossibile ottenere il bot AppId dall'attestazione del gruppo di destinatari", impostare su ClaimsIdentity AudienceClaim su BotFrameworkHttpAdapter. A tale scopo, è possibile sottoclassare l'adapter. Ad esempio:

  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)
          });
      }
  }
  

Passaggi successivi