Konfigurieren eines .NET-Bots für die Erweiterung

Artikel
12/29/2023

Ab dem 1. September 2023 wird dringend empfohlen, die Azure Service Tag-Methode für dieNetzwerkisolation zu verwenden. Die Verwendung von DL-ASE sollte auf hochspezifische Szenarien beschränkt sein. Vor der Implementierung dieser Lösung in einer Produktionsumgebung empfehlen wir Ihnen, Ihr Supportteam um Anleitungen zu bitten.

GILT FÜR: SDK v4

In diesem Artikel erfahren Sie, wie Sie einen Bot für die Verwendung von Named Pipes aktualisieren und die App Service-Erweiterung für Direct Line in der Azure App Service-Ressource aktivieren, in der der Bot gehostet wird.

Voraussetzungen

Ein Azure-Konto. Wenn Sie noch nicht über ein Abonnement verfügen, erstellen Sie ein kostenloses Konto, bevor Sie beginnen.
Ein in Azure bereitgestellter .NET-Bot.
Bot Framework SDK für .NET 4.14.1 oder höher.

Aktivieren Sie die App Service-Erweiterung für Direct Line

Dieser Abschnitt beschreibt, wie Sie die App Service-Erweiterung für Direct Line aktivieren, indem Sie den Schlüssel für die App Service-Erweiterung aus der Direct Line-Kanalkonfiguration Ihres Bots verwenden.

Aktualisieren des Bot-Codes

Hinweis

Die NuGet-Vorschaupakete von Microsoft.Bot.Builder.StreamingExtensions sind veraltet. Ab v4.8 enthält das SDK einen Microsoft.Bot.Builder.Streaming Namespace. Wenn ein Bot zuvor die Vorschaupakete verwendet hat, müssen diese entfernt werden, bevor Sie die folgenden Schritte ausführen.

Öffnen Sie Ihr Botprojekt in Visual Studio.

Erlauben Sie Ihrer App, Named Pipies zu verwenden:

Öffnen Sie die Datei Startup.cs.
Fügen Sie einen Verweis auf das Microsoft.Bot.Builder.Integration.AspNet.Core NuGet-Paket hinzu.
```
using Microsoft.Bot.Builder.Integration.AspNet.Core;
```

Fügen Sie derConfigure-Methode einen Aufruf zurUseNamedPipes-Methode hinzu.

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

Speichern Sie die Datei Startup.cs.

Bereitstellen Ihres aktualisierten Bots in Azure

Aktivieren Sie die Bot-App Service-Erweiterung für Direct Line

Wechseln Sie im Azure-Portal zu Ihrer Azure Bot-Ressource.
1. Wählen Sie unter Einstellungen Kanäle, um die Kanäle zu konfigurieren, von denen Ihr Bot Nachrichten akzeptiert.
2. Wenn er noch nicht aktiviert ist, wählen Sie den Direct Line-Kanal aus der Liste der verfügbaren Kanäle aus, um den Kanal zu aktivieren.
3. Nachdem Sie Direct Line aktiviert haben, wählen Sie es erneut unter Kanäle aus.
4. Wählen Sie die Registerkarte App Service-Erweiterung.
5. Wählen Sie unter App Service-Erweiterungsschlüssel das Augensymbol neben dem entsprechenden Schlüssel aus.
Wechseln Sie zur Startseite und wählen Sie oben auf der Seite App Services aus. Alternativ können Sie das Portalmenü aufrufen und dann das Menüelement App Services auswählen. Azure zeigt die Seite App Services an.
Geben Sie im Suchfeld Ihren Azure Bot-Ressourcennamen ein. Ihre Ressource wird aufgelistet.

Beachten Sie, dass eine Liste der zuletzt angezeigten Ressourcen angezeigt wird, wenn Sie den Cursor über dem Symbol oder Menüelement halten. Ihre Azure Bot-Ressource wird wahrscheinlich aufgelistet.

Wählen Sie Ihren Ressourcen-Link.

Wählen Sie im Abschnitt Einstellungen die Option Konfiguration aus.
Geben Sie im rechten Panel die folgenden Einstellungen ein:

Name Wert

DirectLineExtensionKey Der Wert des App Service-Erweiterungsschlüssels, den Sie zuvor kopiert haben.

DIRECTLINE_EXTENSION_VERSION latest

Name	Wert
DirectLineExtensionKey	Der Wert des App Service-Erweiterungsschlüssels, den Sie zuvor kopiert haben.
DIRECTLINE_EXTENSION_VERSION	latest

Wenn Ihr Bot in einer souveränen oder anderweitig eingeschränkten Azure-Cloud gehostet wird, bei der Sie nicht über das öffentliche Portal auf Azure zugreifen, müssen Sie auch die folgende Einstellung hinzufügen:

Name	Wert
DirectLineExtensionABSEndpoint	Der Endpunkt, der für die Azure-Cloud spezifisch ist, in der Ihr Bot gehostet wird. Für die USGov-Cloud z. B. lautet der Endpunkt `https://directline.botframework.azure.us/v3/extension`.

Klicken Sie im Abschnitt Konfiguration auf den Einstellungsabschnitt Allgemein, und aktivieren Sie Websockets.
Klicken Sie auf Speichern, um die Einstellungen zu speichern. Daraufhin wird die Azure App Service-Instanz neu gestartet.

Bestätigen Sie, dass die Direct Line-Erweiterung und der Bot konfiguriert sind

Wechseln Sie in Ihrem Browser zu https://<your_app_service>.azurewebsites.net/.bot. Ist alles ordnungsgemäß konfiguriert, gibt die Seite den folgenden JSON-Inhalt zurück:

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

v zeigt die Build-Version der App Service-Erweiterung für Direct Line an.
k gibt an, ob die Erweiterung einen Erweiterungsschlüssel aus seiner Konfiguration lesen konnte.
initialisiert gibt an, ob die Erweiterung Bot-Metadaten aus dem Azure AI Bot-Dienst herunterladen konnte.
ib gibt an, ob die Erweiterung eine eingehende Verbindung mit dem Bot herstellen konnte.
ob angibt, ob die Erweiterung eine ausgehende Verbindung vom Bot herstellen konnte.

Problembehandlung

Wenn die ib- und ob-Werte, die vom BOT-Endpunkt angezeigt werden, falsch sind, können der Bot und die Direct Line App Service-Erweiterung keine Verbindung zueinander herstellen.
1. Überprüfen Sie den Code erneut, ob der Code für die Verwendung von Named Pipes dem Bot hinzugefügt wurde.
2. Vergewissern Sie sich, dass der Bot gestartet und ausgeführt werden kann. Nützliche Tools sind Testen in WebChat, einen zusätzlichen Kanal verbinden, Remote-Debugging oder Protokollierung.
3. Starten Sie den gesamten Azure-App-Service neu, in dem der Bot gehostet wird, um sicherzustellen, dass alle Prozesse sauber gestartet werden.
Wenn der initialisierte Wert des Bot-Endpunkts falsch lautet, kann die Direct Line App Service-Erweiterung den App Service-Erweiterungsschlüssel nicht überprüfen, der den Anwendungseinstellungen des Bots oben hinzugefügt wurde.
1. Bestätigen Sie, dass der Wert richtig eingegeben wurde.
2. Wechseln Sie zu dem alternativen Erweiterungsschlüssel, der auf der Seite Direct Line konfigurieren Ihres Bots angezeigt wird.

Erlauben Sie dem Bot die Verwendung des Out-of-Process-Hosting-Modells; Andernfalls erhalten Sie einen HTTP-Error 500.34 – ANCM Mixed Hosting-Fehler (wobei ANCM für ASP.NET Core Module steht). Dieser Fehler tritt auf, weil die Bot-Vorlage standardmäßig das InProcess Hostingmodell verwendet. Informationen zum Konfigurieren des Out-of-Process-Hosting-Modells finden Sie unter Out-of-Process-Hosting-Modell. Weitere Informationen zum Konfigurieren des Moduls finden Sie unter Attribute des aspNetCore-Elements und mit web.config konfigurieren.

Wenn Sie versuchen, OAuth mit der Direct Line App Service-Erweiterung zu verwenden und auf den Fehler „Die Bot-AppId kann nicht aus dem Zielgruppen-Abruf abgerufen werden" angezeigt werden, legen Sie ClaimsIdentity auf AudienceClaim auf BotFrameworkHttpAdapterfest. Dazu können Sie den Adapter als Unterklasse festlegen. Beispiel:

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

Nächste Schritte

Verwenden von Web Chat mit der App Service-Erweiterung für Direct Line

Freigeben über