Ereignisgesteuerte Konversationen mit einem AktivitätshandlerEvent-driven conversations using an activity handler

gilt für: SDK v4APPLIES TO: SDK v4

Ein Aktivitätshandler ist eine ereignisgesteuerte Möglichkeit, die Konversationslogik für Ihren Bot zu organisieren.An activity handler is an event-driven way to organize the conversational logic for your bot. Jeder unterschiedliche Typ oder Untertyp der Aktivität stellt einen anderen Typ von Konversationsereignis dar.Each different type or sub-type of activity represents a different type of conversational event. Im Allgemeinen ruft der Turn-Handler des Bots den einzelnen Aktivitätshandler für jeden empfangenen Aktivitätstyp auf.Under the covers, the bot's turn handler calls the individual activity handler for whatever type of activity it received.

Wenn der Bot z. B. eine Nachrichtenaktivität empfängt, würde der Turn-Handler diese eingehende Aktivität sehen und an den Aktivitätshandler der On-Nachricht senden.For example, if the bot receives a message activity, the turn handler would see that incoming activity and send it to the on message activity activity handler. Wenn Sie Ihren Bot erstellen, wird Ihre Botlogik für die Verarbeitung und Reaktion auf Nachrichten in diesem Artikel für den Nachrichtenaktivitätshandler verwendet.When building your bot, your bot logic for handling and responding to messages will go in this on message activity handler. Ebenso wird Ihre Logik für die Behandlung von Mitgliedern, die der Konversation hinzugefügt werden, in Ihren Handler für hinzugefügte Mitglieder aufgenommen, der immer dann aufgerufen wird, wenn der Konversation ein Mitglied hinzugefügt wird. Likewise, your logic for handling members being added to the conversation will go in your on members added handler, which is called whenever a member is added to the conversation.

Weitere Möglichkeiten zum Organisieren Ihrer Botlogik finden Sie im Abschnitt bot logic (Botlogik) unter Funktionsweise von Bots.For other ways to organize your bot logic, see the bot logic section in how bots work.

Um Ihre Logik für diese Handler zu implementieren, überschreiben Sie diese Methoden in Ihrem Bot, z. B. im Abschnitt Beispielaktivitätshandler weiter unten.To implement your logic for these handlers, you will override these methods in your bot, such as in the sample activity handler section below. Da für diese Handler keine Basisimplementierung vorhanden ist, können Sie in Ihrer Überschreibung einfach die gewünschte Logik hinzufügen.For each of these handlers, there is no base implementation, so just add the logic that you want in your override.

In bestimmten Situationen empfiehlt es sich, den Turn-Basishandler zu überschreiben (etwa beim Speichern des Zustands am Ende eines Turns).There are certain situations where you will want to override the base turn handler, such as saving state at the end of a turn. Rufen Sie in diesem Fall zunächst await base.OnTurnAsync(turnContext, cancellationToken); auf, um sicherzustellen, dass die Basisimplementierung von OnTurnAsync vor Ihrem zusätzlichen Code ausgeführt wird.When doing so, be sure to first call await base.OnTurnAsync(turnContext, cancellationToken); to make sure the base implementation of OnTurnAsync is run before your additional code. Diese Basisimplementierung ist unter anderem dafür zuständig, die restlichen Aktivitätshandler (etwa OnMessageActivityAsync) aufzurufen.That base implementation is, among other things, responsible for calling the rest of the activity handlers such as OnMessageActivityAsync.

AktivitätsbehandlungActivity handling

Die Botlogik verarbeitet eingehende Aktivitäten aus einem oder mehreren Kanälen und generiert als Reaktion ausgehende Aktivitäten.The bot logic processes incoming activities from one or more channels and generates outgoing activities in response.

Die Hauptlogik des Bots wird im Botcode definiert.The main bot logic is defined in the bot code. Um einen Bot als Aktivitätshandler zu implementieren, leiten Sie Ihre Botklasse von ActivityHandler ab, die die IBot -Schnittstelle implementiert.To implement a bot as an activity handler, derive your bot class from ActivityHandler, which implements the IBot interface. ActivityHandler definiert verschiedene Handler für verschiedene Arten von Aktivitäten, z. OnMessageActivityAsync B. und OnMembersAddedAsync .ActivityHandler defines various handlers for different types of activities, such as OnMessageActivityAsync, and OnMembersAddedAsync. Diese Methoden sind geschützt, können jedoch überschrieben werden, da wir von ActivityHandler ableiten.These methods are protected, but can be overridden, since we're deriving from ActivityHandler.

In ActivityHandler sind folgende Handler definiert:The handlers defined in ActivityHandler are:

EreignisEvent HandlerHandler BESCHREIBUNGDescription
Beliebigen Aktivitätstyp empfangenAny activity type received OnTurnAsync Ruft einen der anderen Handler auf (abhängig von der Art der empfangenen Aktivität).Calls one of the other handlers, based on the type of activity received.
Nachrichtenaktivität empfangenMessage activity received OnMessageActivityAsync Überschreiben Sie diesen Handler, um eine Aktivität vom Typ message zu behandeln.Override this to handle a message activity.
Konversationsaktualisierungsaktivität empfangenConversation update activity received OnConversationUpdateActivityAsync Ruft bei einer Aktivität vom Typ conversationUpdate einen Handler auf, wenn der Konversation Mitglieder hinzugefügt oder Mitglieder aus der Konversation entfernt werden (abgesehen vom Bot).On a conversationUpdate activity, calls a handler if members other than the bot joined or left the conversation.
Bot-fremde Mitglieder sind der Konversation beigetretenNon-bot members joined the conversation OnMembersAddedAsync Überschreiben Sie diesen Handler, um Mitglieder zu behandeln, die einer Konversation beitreten.Override this to handle members joining a conversation.
Bot-fremde Mitglieder haben die Konversation verlassenNon-bot members left the conversation OnMembersRemovedAsync Überschreiben Sie diesen Handler, um Mitglieder zu behandeln, die eine Konversation verlassen.Override this to handle members leaving a conversation.
Ereignisaktivität empfangenEvent activity received OnEventActivityAsync Ruft bei einer Aktivität vom Typ event einen spezifischen Handler für den Ereignistyp auf.On an event activity, calls a handler specific to the event type.
Tokenantwortereignis-Aktivität empfangenToken-response event activity received OnTokenResponseEventAsync Überschreiben Sie diesen Handler, um Tokenantwortereignisse zu behandeln.Override this to handle token response events.
Tokenantwortereignis-fremde Aktivität empfangenNon-token-response event activity received OnEventAsync Überschreiben Sie diesen Handler, um andere Arten von Ereignissen zu behandeln.Override this to handle other types of events.
messageReaction-Aktivität empfangenMessage reaction activity received OnMessageReactionActivityAsync Ruft bei einer messageReaction-Aktivität einen Handler auf, wenn mindestens eine Antwort zu einer Nachricht hinzugefügt bzw. daraus entfernt wurde.On a messageReaction activity, calls a handler if one or more reactions were added or removed from a message.
Nachrichtenantworten zu einer Nachricht hinzugefügtMessage reactions added to a message OnReactionsAddedAsync Überschreiben Sie dies, um der Nachricht hinzugefügte Antworten zu verarbeiten.Override this to handle reactions added to a message.
Nachrichtenantworten aus einer Nachricht entferntMessage reactions removed from a message OnReactionsRemovedAsync Überschreiben Sie dies, um aus der Nachricht entfernte Antworten zu verarbeiten.Override this to handle reactions removed from a message.
Installationsupdateaktivität empfangenInstallation update activity received OnInstallationUpdateActivityAsync Ruft bei einer installationUpdate Aktivität einen Handler basierend darauf auf, ob der Bot installiert oder deinstalliert wurde.On an installationUpdate activity, calls a handler based on whether the bot was installed or uninstalled.
Bot installiert.Bot installed OnInstallationUpdateAddAsync Überschreiben Sie dies, um Logik für die Installation des Bots in einer Organisationseinheit hinzuzufügen.Override this to add logic for when the bot is installed within an organizational unit.
Bot deinstalliertBot uninstalled OnInstallationUpdateRemoveAsync Überschreiben Sie dies, um Logik hinzuzufügen, wenn der Bot innerhalb einer Organisationseinheit deinstalliert wird.Override this to add logic for when the bot is uninstalled within an organizational unit.
Anderen Aktivitätstyp empfangenOther activity type received OnUnrecognizedActivityTypeAsync Überschreiben Sie diesen Handler, um Aktivitätstypen zu behandeln, die andernfalls nicht behandelt würden.Override this to handle any activity type otherwise unhandled.

Diese verschiedenen Handler verfügen über einen Turn-Kontext (turnContext), der Informationen zur eingehenden Aktivität (der eingehenden HTTP-Anforderung) bereitstellt.These different handlers have a turnContext that provides information about the incoming activity, which corresponds to the inbound HTTP request. Aufgrund der verschiedenen möglichen Arten von Aktivitäten gibt jeder Handler in seinem Turn-Kontextparameter eine stark typisierte Aktivität an. OnMessageActivityAsync wird in den meisten Fällen behandelt und ist generell am gängigsten.Activities can be of various types, so each handler provides a strongly-typed activity in its turn context parameter; in most cases, OnMessageActivityAsync will always be handled, and is generally the most common.

Wie in früheren 4.x-Versionen dieses Frameworks besteht auch die Möglichkeit, die öffentliche Methode OnTurnAsync zu implementieren.As in previous 4.x versions of this framework, there is also the option to implement the public method OnTurnAsync. Die Basisimplementierung dieser Methode behandelt aktuell die Fehlerüberprüfung und ruft anschließend abhängig von der Art der eingehenden Aktivität die einzelnen spezifischen Handler auf (beispielsweise die beiden, die in diesem Beispiel definiert wurden).Currently, the base implementation of this method handles error checking and then calls each of the specific handlers (like the two we define in this sample) depending on the type of incoming activity. In den meisten Fällen können Sie diese Methode ignorieren und die einzelnen Handler verwenden. Falls Sie jedoch eine benutzerdefinierte Implementierung von OnTurnAsync benötigen, ist sie weiterhin eine Option.In most cases, you can leave that method alone and use the individual handlers, but if your situation requires a custom implementation of OnTurnAsync, it is still an option.

Wichtig

Wenn Sie die Methode OnTurnAsync überschreiben, müssen Sie base.OnTurnAsync aufrufen, um die Basisimplementierung zum Aufrufen aller anderen Handler vom Typ On<activity>Async zu erhalten, oder diese Handler selbst aufrufen.If you do override the OnTurnAsync method, you'll need to call base.OnTurnAsync to get the base implementation to call all the other On<activity>Async handlers or call those handlers yourself. Andernfalls werden diese Handler nicht aufgerufen, und der Code wird nicht ausgeführt.Otherwise, those handlers won't be called and that code won't be run.

BeispielaktivitätshandlerSample activity handler

Beispielsweise können Sie mit Mitgliedern umgehen, die hinzugefügt wurden, um Benutzer in einer Konversation willkommen zu heißen, und Nachrichten verarbeiten, um Nachrichten zurückzukommen, die sie an den Bot senden. For example, you can handle on members added to welcome users to a conversation, and handle on message to echo back messages they send to the bot.

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

  • Der Microsoft Teams-Kanal führt einige Teams-spezifische Aktivitäten ein, die Ihr Bot unterstützen muss, um ordnungsgemäß mit Teams zu arbeiten.The Microsoft Teams channel introduces some Teams-specific activities that your bot will need to support to work properly with Teams. Informationen zu den wichtigsten Konzepten der Entwicklung von Bots für Microsoft Teams finden Sie unter Funktionsweise von Microsoft Teams-Bots.To understand key concepts of developing bots for Microsoft Teams, see How Microsoft Teams bots work
  • Ein Aktivitätshandler ist eine gute Möglichkeit, einen Bot zu entwerfen, der den Konversationszustand zwischen den Turns nicht nachverfolgen muss.An activity handler is a good way to design a bot that does not need to track conversational state between turns. Die Dialogbibliothek bietet Möglichkeiten zum Verwalten einer Konversation mit dem Benutzer mit langer Laufzeit.The dialogs library provides ways to manage a long-running conversation with the user.