Grundlegendes zur Struktur eines EchobotsUnderstand the structure of an echo bot

gilt für: SDK v4APPLIES TO: SDK v4

Die Bot Framework Vorlagen und Beispiele sind für ASP.NET (C#), restify (JavaScript) und aiohttp (Python) geschrieben.The Bot Framework templates and samples are written for ASP.NET (C#), restify (JavaScript), and aiohttp (Python). Die Webdienstfeatures sind jedoch nicht Teil des Bot Framework SDK, sondern Teil des Webframeworks, das Sie verwenden möchten.However, the web service features are not part of the Bot Framework SDK, but part of the web framework you choose to use.

Alle Botanwendungen nutzen einige gemeinsame Features.All bot applications share some common features.

FunktionFeature BESCHREIBUNGDescription
RessourcenbereitstellungResource provisioning Der Bot als Web-App muss einen Webdienst, einen Botadapter und ein Botobjekt erstellen.The bot as a web app needs to create a web service, bot adapter, and bot object.
Messaging-EndpunktMessaging endpoint Die Web-App muss einen Messagingendpunkt implementieren, auf dem Aktivitäten empfangen und Aktivitäten an den Botadapter weitergeleitet werden können.The web app needs to implement a messaging endpoint on which to receive activities and forward activities to the bot adapter.
BotadapterBot adapter Der Adapter empfängt Aktivitäten vom Messagingendpunkt, gibt sie an den Turn-Handler des Bots weiter und fängt alle Fehler oder Ausnahmen ab, die die Logik des Bots nicht abfängt.The adapter receives activities from the messaging endpoint, forwards them to the bot's turn handler, and catches any errors or exceptions the bot's logic doesn't catch.
Bot-ObjektBot object Das Botobjekt verarbeitet die Logik des Bots für den Turn.The bot object handles the bot's reasoning or logic for the turn.

Sie können einen Echobot aus den Vorlagen erstellen, wie in den Schnellstartanleitungen beschrieben (für C#, JavaScript, Javaoder Python),oder Sie können ein Echobotprojekt aus dem Repository Microsoft/BotBuilder-Samples kopieren.You can create an echo bot from the templates, as described in the quickstarts (for C#, JavaScript, Java, or Python), or you can copy an echo bot project from the Microsoft/BotBuilder-Samples repository.

Die C#- und JavaScript-Vorlagen verfügen über integrierte Unterstützung für Streamingverbindungen.The C# and JavaScript templates have built-in support for streaming connections. In diesem Artikel werden Streamingfeatures behandelt.This article does cover streaming features. Informationen zu Streamingverbindungen finden Sie unter Herstellen einer Verbindung zwischen einem Bot und Direct Line Speech.For information about streaming connections, see how to connect a bot to Direct Line Speech.

VoraussetzungenPrerequisites

BotvorlagenBot templates

Ein Bot ist eine Webanwendung. Vorlagen werden für jede Sprache bereitgestellt.A bot is a web application, and templates are provided for each language.

Die Bot Framework enthält sowohl VSIX- als auch dotnet-Vorlagen.The Bot Framework includes both VSIX and dotnet templates.

Die Vorlagen generieren eine ASP.NET MVC Core-Web-App.The templates generate an ASP.NET MVC Core web app. Wenn Sie sich die ASP.NET-Grundlagen ansehen, werden Sie ähnlichen Code in Dateien wie Program.cs und Startup.cs sehen.If you look at the ASP.NET fundamentals, you'll see similar code in files such as Program.cs and Startup.cs. Diese Dateien sind für alle Web-Apps erforderlich und nicht botspezifisch.These files are required for all web apps and are not bot specific.

Hinweis

Das VSIX -Paket umfasst sowohl .net Core 2,1-als auch .net Core 3,1-Versionen der c#-Vorlagen.The VSIX package includes both .NET Core 2.1 and .NET Core 3.1 versions of the C# templates. Sie sollten beim Erstellen neuer Bots in Visual Studio 2019 die .NET Core 3.1-Vorlagen verwenden.When creating new bots in Visual Studio 2019, you should use the .NET Core 3.1 templates. Für die aktuellen Botbeispiele werden .NET Core 3.1-Vorlagen verwendet.The current bot samples use .NET Core 3.1 templates. Beispiele mit .NET Core 2.1-Vorlagen finden Sie im Branch 4.7-archive des Repositorys BotBuilder-Samples.You can find the samples that use .NET Core 2.1 templates in the 4.7-archive branch of the BotBuilder-Samples repository. Informationen zum Bereitstellen von .net Core 3,1-Bots in Azure finden Sie unter Bereitstellen Ihres bot in Azure.For information about deploying .NET Core 3.1 bots to Azure, see how to deploy your bot to Azure.

Der appsettings.jsdatei gibt die Konfigurationsinformationen für Ihren Bot an, z. B. die App-ID und das Kennwort.The appsettings.json file specifies the configuration information for your bot, such as its app ID, and password among other things. Wenn Sie bestimmte Technologien verwenden oder diesen Bot in einer Produktionsumgebung einsetzen, müssen Sie der Konfiguration Ihre spezifischen Schlüssel oder Ihre URL hinzufügen.If using certain technologies or using this bot in production, you will need to add your specific keys or URL to this configuration. Für diesen Echobot müssen Sie hier jedoch derzeit nichts tun. Die App-ID und das Kennwort sind derzeit möglicherweise nicht definiert.For this echo bot, however, you don't need to do anything here right now; the app ID and password may be left undefined at this time.

Die Datei EchoBot.csproj gibt Abhängigkeiten und die zugehörigen Versionen für Ihren Bot an.The EchoBot.csproj file specifies dependencies and their associated versions for your bot. All dies wird durch die Vorlage und Ihr System eingerichtet.This is all set up by the template and your system. Zusätzliche Abhängigkeiten können mit dem NuGet-Paket-Manager oder dem Befehl installiert dotnet add package werden.Additional dependencies can be installed using NuGet package manager or the dotnet add package command.

RessourcenbereitstellungResource provisioning

Der Bot als Web-App muss einen Webdienst, einen Botadapter und ein Botobjekt erstellen.The bot as a web app needs to create a web service, bot adapter, and bot object.

Viele Bots würden auch die Speicherebene und Speicherverwaltungsobjekte für den Bot erstellen, aber der Echobot erfordert keinen Zustand.Many bots would also create the storage layer and memory management objects for the bot, but the echo bot does not require state. Andere Bots würden auch alle Objekte außerhalb des Botobjekts oder Adapters erstellen, die entweder verwendet werden müssen.Other bots would also create any objects external to the bot object or adapter that either need to consume.

In ASP.NET registrieren Sie Objekte und Objekterstellungsmethoden in der Datei Startup.cs.In ASP.NET, you register objects and object creation methods in the Startup.cs file. Die ConfigureServices -Methode lädt die verbundenen Dienste sowie deren Schlüssel aus appsettings.jsauf oder Azure Key Vault (sofern vorhanden), verbindet den Zustand usw.The ConfigureServices method loads the connected services, as well as their keys from appsettings.json or Azure Key Vault (if there are any), connects state, and so on. Hier werden adapter und bot so definiert, dass sie durch Abhängigkeitsinjektion verfügbar sind.Here, the adapter and bot are defined to be available through dependency injection. Anschließend beendet die Configure -Methode die Konfiguration Ihrer App.Then, the Configure method finishes the configuration of your app.

ConfigureServices und Configure werden von der Runtime aufgerufen, wenn die App gestartet wird.ConfigureServices and Configure are called by the runtime when the app starts.

Messaging-EndpunktMessaging endpoint

Die Vorlage implementiert einen Webdienst mit einem Messagingendpunkt.The template implements a web service with a messaging endpoint. Der Dienst extrahiert den Authentifizierungsheader und die Anforderungsnutzlast und gibt sie an den Adapter weiter.The service extracts the authentication header and request payload and forwards them to the adapter.

Die C#- und JavaScript-SDKs unterstützen Streamingverbindungen.The C# and JavaScript SDKs support streaming connections. Obwohl der Echobot keine der Streamingfeatures verwendet, ist der Adapter in der Vorlage darauf ausgelegt, sie zu unterstützen.While the echo bot does not use any of the streaming features, the adapter in the template is designed to support them.

Jede eingehende Anforderung stellt den Anfang eines neuen Durchtritts dar.Each incoming request represents the start of a new turn.

Controller \ BotController.csControllers\BotController.cs

// This ASP Controller is created to handle a request. Dependency Injection will provide the Adapter and IBot
// implementation at runtime. Multiple different IBot implementations running at different endpoints can be
// achieved by specifying a more specific type for the bot constructor argument.
[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 PostAsync()
    {
        // Delegate the processing of the HTTP POST to the adapter.
        // The adapter will invoke the bot.
        await Adapter.ProcessAsync(Request, Response, Bot);
    }
}

Der BotadapterThe bot adapter

Der Adapter empfängt Aktivitäten vom Messagingendpunkt, gibt sie an den Turn-Handler des Bots weiter und fängt alle Fehler oder Ausnahmen ab, die die Logik des Bots nicht abfängt.The adapter receives activities from the messaging endpoint, forwards them to the bot's turn handler, and catches any errors or exceptions the bot's logic doesn't catch.

Mit dem Adapter können Sie einen eigenen On-Turn-Fehlerhandler hinzufügen.The adapter allows you to add your own on turn error handler.

Startup.csStartup.cs

Der zu verwendende Adapter wird in der -Methode ConfigureServices definiert.The adapter to use is defined in the ConfigureServices method.

// Create the Bot Framework Adapter with error handling enabled.
services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();

AdapterWithErrorHandler.csAdapterWithErrorHandler.cs

public class AdapterWithErrorHandler : CloudAdapter
{
    public AdapterWithErrorHandler(IConfiguration configuration, IHttpClientFactory httpClientFactory, ILogger<IBotFrameworkHttpAdapter> logger)
        : base(configuration, httpClientFactory, logger)
    {
        OnTurnError = async (turnContext, exception) =>
        {
            // Log any leaked exception from the application.
            // NOTE: In production environment, you should consider logging this to
            // Azure Application Insights. Visit https://aka.ms/bottelemetry to see how
            // to add telemetry capture to your bot.
            logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

            // Send a message to the user
            await turnContext.SendActivityAsync("The bot encountered an error or bug.");
            await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

            // Send a trace activity, which will be displayed in the Bot Framework Emulator
            await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
        };
    }
}

Die BotlogikThe bot logic

Der Echobot verwendet einen Aktivitätshandler und implementiert Handler für die Aktivitätstypen, die er erkennt und darauf reagiert, in diesem Fall die Konversationsaktualisierungs- und Nachrichtenaktivitäten.The echo bot uses an activity handler and implements handlers for the activity types it will recognize and react to, in this case, the conversation update and message activities.

  • Eine Konversationsaktualisierungsaktivität enthält Informationen darüber, wer der Konversation beigetreten ist oder diese verlassen hat.A conversation update activity includes information on who has joined or left the conversation. Bei Nicht-Gruppenkonversationen treten sowohl der Bot als auch der Benutzer der Konversation bei, wenn sie beginnt.For non-group conversations, both the bot and the user join the conversation when it starts. Bei Gruppenkonversationen wird immer dann ein Konversationsupdate generiert, wenn eine Person der Konversation beitritt oder diese verlässt, unabhängig davon, ob es sich um den Bot oder einen Benutzer handelt.For group conversations, a conversation update is generated whenever someone joins or leaves the conversation, whether that's the bot or a user.
  • Eine Nachrichtenaktivität stellt eine Nachricht dar, die der Benutzer an den Bot sendet.A message activity represents a message the user sends to the bot.

Der Echobot empfängt einen Benutzer, wenn er an der Konversation teilnimmt, und gibt alle Nachrichten zurück, die er an den Bot sendet.The echo bot welcomes a user when they join the conversation and echoes back any messages they send to the bot.

Startup.csStartup.cs

Der zu verwendende Bot ist in der ConfigureServices -Methode definiert.The bot to use is defined in the ConfigureServices method.

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

Bots\EchoBot.csBots\EchoBot.cs

public class EchoBot : ActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var replyText = $"Echo: {turnContext.Activity.Text}";
        await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
    }

    protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
    {
        var welcomeText = "Hello and welcome!";
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text(welcomeText, welcomeText), cancellationToken);
            }
        }
    }
}

Nächste SchritteNext steps