Freigeben über


Ereignisgesteuerte Unterhaltungen mit einem Aktivitätshandler

GILT FÜR: SDK v4

Ein Aktivitätshandler ist eine ereignisgesteuerte Methode zum Organisieren der Unterhaltungslogik für Ihren Bot. Jeder andere Typ oder Untertyp von Aktivität stellt einen anderen Typ von Unterhaltungsereignis dar. Im Verborgenen ruft der Turn-Handler des Bots die einzelnen Aktivitätshandler für die jeweilige Art von empfangener Aktivität auf.

Wenn der Bot beispielsweise eine Nachrichtenaktivität empfängt, erkennt der Turn-Handler diese eingehende Aktivität und sendet sie an den Aktivitätshandler für die Nachrichtenaktivität. Bei der Boterstellung muss Ihre Botlogik für die Behandlung von bzw. die Reaktion auf Nachrichten in diesem Handler für die Nachrichtenaktivität platziert werden. Analog dazu muss Ihre Logik für die Behandlung von Mitgliedern, die der Konversation hinzugefügt werden, im Handler auf Mitglieder hinzugefügt platziert werden, der aufgerufen wird, wenn der Konversation ein Mitglied hinzugefügt wird.

Weitere Möglichkeiten zum Organisieren Ihrer Bot-Logik finden Sie im Abschnitt Bot-Logik in der Funktionsweise von Bots.

Hinweis

Die JavaScript-, C#- und Python-SDKs für Bot Framework werden weiterhin unterstützt, das Java-SDK wird jedoch eingestellt und der langfristige Support endet im November 2023.

Bestehende Bots, die mit dem Java SDK erstellt wurden, werden weiterhin funktionieren.

Für das erstellen eines neuen Bots sollten Sie Microsoft Copilot Studio verwenden und lesen, wie Sie die richtige Copilot-Lösung auswählen.

Weitere Informationen finden Sie unter Die Zukunft des Bot-Buildings.

Um Ihre Logik für diese Handler zu implementieren, überschreiben Sie diese Methoden in Ihrem Bot, wie z. B. im folgenden Beispiel für einen Aktivitätshandler. Da für diese Handler keine Basisimplementierung vorhanden ist, können Sie in Ihrer Überschreibung einfach die gewünschte Logik hinzufügen.

In bestimmten Situationen empfiehlt es sich, den Turn-Basishandler zu überschreiben (etwa beim Speichern des Zustands am Ende eines Turns). 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. Diese Basisimplementierung ist unter anderem dafür zuständig, die restlichen Aktivitätshandler (etwa OnMessageActivityAsync) aufzurufen.

Umgang mit Aktivitäten

Die Botlogik verarbeitet eingehende Aktivitäten aus einem oder mehreren Kanälen und generiert als Reaktion ausgehende Aktivitäten.

Die Hauptlogik des Bots wird im Botcode definiert. Um einen Bot als Aktivitätshandler zu implementieren, leiten Sie die Bot-Klasse von ActivityHandler ab, der die IBot-Schnittstelle implementiert. ActivityHandler definiert verschiedene Handler für verschiedene Arten von Aktivitäten, beispielsweise OnMessageActivityAsync und OnMembersAddedAsync. Diese Methoden sind zwar geschützt, können aber dank der Ableitung von ActivityHandler überschrieben werden.

In ActivityHandler sind folgende Handler definiert:

Ereignis Handler Beschreibung
Beliebigen Aktivitätstyp empfangen OnTurnAsync Ruft einen der anderen Handler auf (abhängig von der Art der empfangenen Aktivität).
Nachrichtenaktivität empfangen OnMessageActivityAsync Überschreiben Sie diesen Handler, um eine Aktivität vom Typ message zu behandeln.
Konversationsaktualisierungsaktivität empfangen 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).
Bot-fremde Mitglieder sind der Konversation beigetreten OnMembersAddedAsync Überschreiben Sie diesen Handler, um Mitglieder zu behandeln, die einer Konversation beitreten.
Bot-fremde Mitglieder haben die Konversation verlassen OnMembersRemovedAsync Überschreiben Sie diesen Handler, um Mitglieder zu behandeln, die eine Konversation verlassen.
Ereignisaktivität empfangen OnEventActivityAsync Ruft bei einer Aktivität vom Typ event einen spezifischen Handler für den Ereignistyp auf.
Tokenantwortereignis-Aktivität empfangen OnTokenResponseEventAsync Überschreiben Sie diesen Handler, um Tokenantwortereignisse zu behandeln.
Tokenantwortereignis-fremde Aktivität empfangen OnEventAsync Überschreiben Sie diesen Handler, um andere Arten von Ereignissen zu behandeln.
messageReaction-Aktivität empfangen OnMessageReactionActivityAsync Ruft bei einer messageReaction-Aktivität einen Handler auf, wenn mindestens eine Antwort zu einer Nachricht hinzugefügt bzw. daraus entfernt wurde.
Nachrichtenantworten zu einer Nachricht hinzugefügt OnReactionsAddedAsync Überschreiben Sie dies, um der Nachricht hinzugefügte Antworten zu verarbeiten.
Nachrichtenantworten aus einer Nachricht entfernt OnReactionsRemovedAsync Überschreiben Sie dies, um aus der Nachricht entfernte Antworten zu verarbeiten.
Aktualisierungsaktivität der Installation erhalten OnInstallationUpdateActivityAsync Ruft in einer installationUpdate-Aktivität einen Handler auf, der darauf basiert, ob der Bot installiert oder deinstalliert wurde.
Bot installiert. OnInstallationUpdateAddAsync Überschreiben Sie dies, um Logik hinzuzufügen, wenn der Bot in einer Organisationseinheit installiert wird.
Bot deinstalliert OnInstallationUpdateRemoveAsync Überschreiben Sie dies, um Logik hinzuzufügen, wenn der Bot in einer Organisationseinheit deinstalliert wird.
Anderen Aktivitätstyp empfangen OnUnrecognizedActivityTypeAsync Überschreiben Sie diesen Handler, um Aktivitätstypen zu behandeln, die andernfalls nicht behandelt würden.

Diese verschiedenen Handler verfügen über einen Turn-Kontext (turnContext), der Informationen zur eingehenden Aktivität (der eingehenden HTTP-Anforderung) bereitstellt. 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.

Wie in früheren 4.x-Versionen dieses Frameworks besteht auch die Möglichkeit, die öffentliche Methode OnTurnAsync zu implementieren. 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). 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.

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. Andernfalls werden diese Handler nicht aufgerufen, und der Code wird nicht ausgeführt.

Beispielaktivitätshandler

So können Sie z. B. auf hinzugefügte Mitglieder einwirken, um Benutzer in einer Unterhaltung willkommen zu heißen und auf Nachrichten einwirken, um die von ihnen an den Bot gesendeten Nachrichten zurückzusenden.

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 Schritte

  • Der Microsoft-Teams-Kanal führt einige Teams-spezifische Aktivitäten ein, die Ihr Bot unterstützen muss, um ordnungsgemäß mit Teams zu arbeiten. Informationen zu den wichtigsten Konzepten der Entwicklung von Bots für Microsoft Teams finden Sie unter Funktionsweise von Microsoft Teams-Bots.
  • Ein Aktivitätshandler ist eine gute Möglichkeit, einen Bot zu entwerfen, der nicht den Unterhaltungszustand zwischen Turns nachverfolgen muss. Die Dialogbibliothek bietet Möglichkeiten zur Verwaltung einer zeitintensiven Unterhaltung mit dem Benutzer.