Verwenden von Direct Line Speech in Ihrem BotUse Direct Line Speech in your bot

gilt für: SDK v4APPLIES TO: SDK v4

Für Direct Line Speech wird eine neue WebSocket-basierte Streamingfunktion von Bot Framework genutzt, um Nachrichten zwischen dem Direct Line Speech-Kanal und Ihrem Bot auszutauschen.Direct Line Speech uses a new WebSocket based streaming capability of Bot Framework to exchange messages between the Direct Line Speech channel and your bot. Nachdem der Direct Line Speech-Kanal im Azure-Portal aktiviert wurde, müssen Sie Ihren Bot aktualisieren, um auf diese WebSocket-Verbindungen lauschen und sie akzeptieren zu können.After enabling the Direct Line Speech channel in the Azure Portal, you will need to update your bot to listen for and accept these WebSocket connections. Dies wird in der folgenden Anleitung beschrieben.These instructions explain how to do this.

Schritt 1: Durchführen eines Upgrades auf die neueste Version des SDKStep 1: Upgrade to the latest version of the SDK

Stellen Sie für Direct Line Speech sicher, dass Sie die aktuelle Version des Bot Builder SDK nutzen.For Direct Line Speech ensure you are using the latest version of Bot Builder SDK.

Schritt 2: Aktualisieren Ihres .NET Core-Botcodes, wenn für Ihren Bot kein BotController, sondern AddBot und UseBotFramework verwendet werdenStep 2: Update your .NET Core bot code if your bot uses AddBot and UseBotFramework instead of a BotController

Wenn Sie für die Boterstellung vor Version 4.3.2 zuerst v4 des Bot Builder SDK genutzt haben, enthält Ihr Bot wahrscheinlich keinen BotController. Stattdessen werden die Methoden AddBot() und UseBotFramework() in der Datei „Startup.cs“ verwendet, um den POST-Endpunkt verfügbar zu machen, über den der Bot Nachrichten empfängt.If you have created a bot using v4 of the Bot Builder SDK prior to version 4.3.2, your bot likely does not include a BotController but instead uses the AddBot() and UseBotFramework() methods in the Startup.cs file to expose the POST endpoint where the bot receives messages. Zum Verfügbarmachen des neuen Streamingendpunkts müssen Sie einen BotController hinzufügen und die Methoden AddBot() und UseBotFramework() entfernen.To expose the new streaming endpoint, you will need to add a BotController and remove the AddBot() and UseBotFramework() methods. In dieser Anleitung werden die Änderungen, die Sie vornehmen müssen, einzeln beschrieben.These instructions walk through the changes that need to be made. Fahren Sie mit dem nächsten Schritt fort, falls Sie diese Änderungen bereits vorgenommen haben.If you already have these changes, continue to the next step.

Fügen Sie Ihrem Botprojekt einen neuen MVC-Controller hinzu, indem Sie die Datei „BotController.cs“ hinzufügen.Add a new MVC controller to your bot project by adding a file called BotController.cs. Fügen Sie den Controller dieser Datei hinzu:Add the controller code to this file:


[Route("api/messages")]

[ApiController]

public class BotController : ControllerBase
{
    private readonly IBotFrameworkHttpAdapter _adapter;
    private readonly IBot _bot;
    public BotController(IBotFrameworkHttpAdapter adapter, IBot bot)
    {
        _adapter = adapter;

        _bot = bot;
    }

    [HttpPost, HttpGet]
    public async Task ProcessMessageAsync()
    {
        await _adapter.ProcessAsync(Request, Response, _bot);
    }
}

Suchen Sie in der Datei Startup.cs nach der Configure-Methode.In the Startup.cs file, locate the Configure method. Entfernen Sie die Zeile UseBotFramework(), und stellen Sie sicher, dass die folgenden Zeilen für UseWebSockets vorhanden sind:Remove the UseBotFramework() line and make sure you have these lines to UseWebSockets:


public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    ...
    app.UseDefaultFiles();
    app.UseStaticFiles();
    app.UseWebSockets();
    app.UseMvc();
    ...
}

Suchen Sie in der Datei „Startup.cs“ außerdem nach der ConfigureServices-Methode.Also in the Startup.cs file, locate the ConfigureServices method. Entfernen Sie die Zeile AddBot(), und stellen Sie sicher, dass Sie über die Zeilen für das Hinzufügen von IBot und BotFrameworkHttpAdapter verfügen:Remove the AddBot() line and make sure you have lines for adding your IBot and a BotFrameworkHttpAdapter:


public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
    services.AddSingleton<ICredentialProvider, ConfigurationCredentialProvider>();
    services.AddSingleton<IChannelProvider, ConfigurationChannelProvider>();

    // Create the Bot Framework Adapter.
    services.AddSingleton<IBotFrameworkHttpAdapter, BotFrameworkHttpAdapter>();

    // Create the bot as a transient. In this case the ASP Controller is expecting an IBot.
    services.AddTransient<IBot, EchoBot>();
}

Der Rest des Botcodes bleibt unverändert!The remainder of your bot code stays the same!

Schritt 3: Sicherstellen der Aktivierung von WebSocketsStep3: Ensure WebSockets are enabled

Wenn Sie über das Azure-Portal mit einer der Vorlagen einen neuen Bot erstellen, z. B. EchoBot, erhalten Sie einen Bot mit einem ASP.NET MVC-Controller, der einen GET- und einen POST-Endpunkt verfügbar macht und zusätzlich WebSockets nutzt.When you create a new bot from the Azure Portal using one of the templates such as EchoBot, you will get a bot that includes an ASP.NET MVC controller that exposes a GET and POST endpoint and will also use WebSockets. In dieser Anleitung wird beschrieben, wie Sie diese Elemente Ihrem Bot hinzufügen, wenn Sie ein Upgrade durchführen oder Ihren Bot nicht über eine Vorlage erstellt haben.These instructions explain how to add these elements to your bot if you are upgrading or did not make your bot from a template.

Öffnen Sie die Datei BotController.cs im Ordner „Controllers“ Ihrer Lösung.Open BotController.cs under the Controllers folder in your solution

Suchen Sie in der Klasse nach der PostAsync-Methode, und aktualisieren Sie die Dekoration von „[HttpPost]“ auf „[HttpPost, HttpGet]“:Find the PostAsync method in the class and update its decoration from [HttpPost] to [HttpPost, HttpGet]:


[HttpPost, HttpGet]
public async Task PostAsync()
{
    await _adapter.ProcessAsync(Request, Response, _bot);
}

Speichern und schließen Sie „BotController.cs“.Save and close BotController.cs

Öffnen Sie die Datei Startup.cs im Stammverzeichnis Ihrer Lösung.Open Startup.cs in the root of your solution.

Navigieren Sie in „Startup.cs“ an das Ende der „Configure“-Methode.In Startup.cs, navigate to the bottom of the Configure method. Fügen Sie vor dem Aufruf von  app.UseMvc() einen Aufruf von  app.UseWebSockets() hinzu.Before the call to app.UseMvc(), add a call to app.UseWebSockets(). Dies ist wichtig, weil die Reihenfolge dieser Use-Aufrufe eine Rolle spielt.This is important as the order of these use calls matters. Das Ende der Methode sollte in etwa wie folgt aussehen:The end of the method should look something like this:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    ...
    app.UseDefaultFiles();
    app.UseStaticFiles();
    app.UseWebSockets();
    app.UseMvc();
    ...
}

Der Rest des Botcodes bleibt unverändert!The remainder of your bot code stays the same!

Schritt 4: Festlegen des Felds „Speak“ in den Aktivitäten zum Anpassen des gesprochenen Texts für den Benutzer (optional)Step 4: Optionally set the Speak field on Activities to customize what is spoken to the user

Standardmäßig werden alle Nachrichten gesprochen, die per Direct Line Speech an den Benutzer gesendet werden.By default, all messages sent through Direct Line Speech to the user will be spoken.

Sie können optional anpassen, wie die Nachricht gesprochen wird, indem Sie das Feld „Speak“ für eine vom Bot gesendete Aktivität festlegen:You can optionally customize how the message is spoken by setting the Speak field of any Activity sent from the bot:


public IActivity Speak(string message)
{
    var activity = MessageFactory.Text(message);
    string body = @"<speak version='1.0' xmlns='https://www.w3.org/2001/10/synthesis' xml:lang='en-US'>

        <voice name='Microsoft Server Speech Text to Speech Voice (en-US, JessaRUS)'>" +
        $"{message}" + "</voice></speak>";

    activity.Speak = body;
    return activity;
}

Der folgende Codeausschnitt veranschaulicht, wie die obige Speak-Funktion verwendet wird:The following snippet shows how to use the previous Speak function:


protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    await turnContext.SendActivityAsync(Speak($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}

Zusätzliche InformationenAdditional information