Delen via


Gebeurtenisgestuurde gesprekken met behulp van een activiteitshandler

VAN TOEPASSING OP: SDK v4

Een activiteitshandler is een gebeurtenisgestuurde manier om de gesprekslogica voor uw bot te organiseren. Elk ander type of subtype van activiteit vertegenwoordigt een ander type gespreksevenement. In de achtergrond roept de turn handler van de bot de afzonderlijke activiteitshandler aan voor het type activiteit dat het heeft ontvangen.

Als de bot bijvoorbeeld een berichtactiviteit ontvangt, zal de draaiafhandelaar die binnenkomende activiteit opmerken en naar de handler voor berichtactiviteit verzenden. Bij het bouwen van uw bot gaat de logica van uw bot voor het verwerken en reageren op berichten in de berichtactiviteitenhandler. Op dezelfde manier gaat uw logica voor het verwerken van leden die aan het gesprek worden toegevoegd, in uw aan leden toegevoegde handler, die wordt aangeroepen wanneer een lid wordt toegevoegd aan het gesprek.

Zie de sectie botlogica in de werking van bots voor andere manieren om uw botlogica te organiseren.

Notitie

De Sdk's voor Bot Framework JavaScript, C# en Python blijven ondersteund, maar de Java SDK wordt buiten gebruik gesteld met definitieve langetermijnondersteuning die eindigt op november 2023.

Bestaande bots die zijn gebouwd met de Java SDK blijven functioneren.

Voor het bouwen van nieuwe bots kunt u Microsoft Copilot Studio gebruiken en lezen over het kiezen van de juiste copilot-oplossing.

Zie De toekomst van botbouw voor meer informatie.

Als u uw logica voor deze handlers wilt implementeren, overschrijft u deze methoden in uw bot, zoals in de onderstaande sectie voor de handler voor voorbeeldactiviteiten. Voor elk van deze handlers is er geen basisimplementatie, dus voeg gewoon de logica toe die u wilt in uw overschrijving.

Er zijn bepaalde situaties waarin u de standaard beurthandler wilt overschrijven, zoals het opslaan van de status aan het einde van een beurt. Als u dit doet, moet u eerst aanroepen await base.OnTurnAsync(turnContext, cancellationToken); om ervoor te zorgen dat de basis-implementatie van OnTurnAsync wordt uitgevoerd voordat uw aanvullende code wordt uitgevoerd. Deze basis-implementatie is onder andere verantwoordelijk voor het aanroepen van de rest van de activiteitshandlers zoals OnMessageActivityAsync.

Activiteitsafhandeling

De botlogica verwerkt binnenkomende activiteiten van een of meer kanalen en genereert uitgaande activiteiten als reactie.

De belangrijkste botlogica wordt gedefinieerd in de botcode. Als u een bot wilt implementeren als een activiteitshandler, moet u uw botklasse afleiden van ActivityHandler, waarmee de IBot interface wordt geïmplementeerd. ActivityHandler definieert verschillende handlers voor verschillende soorten activiteiten, zoals OnMessageActivityAsync, en OnMembersAddedAsync. Deze methoden zijn beschermd, maar kunnen worden overschreven, omdat we afleiden van ActivityHandler.

De handlers die zijn gedefinieerd in ActivityHandler zijn:

Gebeurtenis Behandelaar Beschrijving
Elk ontvangen activiteitstype OnTurnAsync Roept een van de andere handlers aan op basis van het type activiteit dat is ontvangen.
Berichtactiviteit ontvangen OnMessageActivityAsync Overschrijf dit om een message activiteit af te handelen.
Activiteit voor gespreksupdate ontvangen OnConversationUpdateActivityAsync In een conversationUpdate activiteit roept u een handler aan als andere leden dan de bot deelnemen aan of het gesprek verlaten.
Andere leden dan bots hebben aan het gesprek deelgenomen. OnMembersAddedAsync Overschrijf dit om leden die deelnemen aan een gesprek af te handelen.
Niet-botleden hebben het gesprek verlaten OnMembersRemovedAsync Overschrijf dit om om te gaan met leden die een gesprek verlaten.
Gebeurtenisactiviteit ontvangen OnEventActivityAsync Bij een event activiteit roept u een handler aan die specifiek is voor het gebeurtenistype.
Activiteit van tokenresponsgebeurtenis ontvangen OnTokenResponseEventAsync Overschrijf dit om reactiegebeurtenissen van tokens af te handelen.
Niet-tokengebaseerd antwoord voor gebeurtenis ontvangen OnEventAsync Overschrijf dit om andere typen gebeurtenissen te verwerken.
Berichtreactieactiviteit ontvangen OnMessageReactionActivityAsync Bij een messageReaction activiteit roept u een handler aan als een of meer reacties zijn toegevoegd aan of verwijderd uit een bericht.
Berichtreacties toegevoegd aan een bericht OnReactionsAddedAsync Overschrijf dit om reacties af te handelen die zijn toegevoegd aan een bericht.
Berichtreacties verwijderd uit een bericht OnReactionsRemovedAsync Overschrijf dit om reacties af te handelen die zijn verwijderd uit een bericht.
Ontvangen installatie-updateactiviteit OnInstallationUpdateActivityAsync Bij een installationUpdate activiteit roept u een handler aan op basis van of de bot is geïnstalleerd of verwijderd.
Bot geïnstalleerd OnInstallationUpdateAddAsync Overschrijf dit om logica toe te voegen voor wanneer de bot in een organisatie-eenheid is geïnstalleerd.
Bot verwijderd OnInstallationUpdateRemoveAsync Overschrijf dit om logica toe te voegen voor wanneer de bot wordt verwijderd in een organisatie-eenheid.
Ander activiteitstype ontvangen OnUnrecognizedActivityTypeAsync Overschrijf dit om elk type activiteit af te handelen die anders niet wordt afgehandeld.

Deze verschillende handlers bevatten informatie turnContext over de binnenkomende activiteit, die overeenkomt met de inkomende HTTP-aanvraag. Activiteiten kunnen van verschillende typen zijn, dus elke handler biedt in zijn beurtcontextparameter een sterk getypeerde activiteit aan; in de meeste gevallen zal OnMessageActivityAsync altijd worden afgehandeld en is het over het algemeen de meest voorkomende.

Net als in vorige 4.x-versies van dit framework, is er ook de optie om de openbare methode OnTurnAsyncte implementeren. Momenteel verwerkt de basis-implementatie van deze methode foutcontrole en roept vervolgens elk van de specifieke handlers aan (zoals de twee die we in dit voorbeeld definiëren) afhankelijk van het type binnenkomende activiteit. In de meeste gevallen kunt u die methode alleen laten en de afzonderlijke handlers gebruiken, maar als voor uw situatie een aangepaste implementatie OnTurnAsyncis vereist, is dit nog steeds een optie.

Belangrijk

Als u de OnTurnAsync methode overschrijft, moet u de basis-implementatie aanroepen base.OnTurnAsync om alle andere On<activity>Async handlers aan te roepen of deze handlers zelf aan te roepen. Anders worden deze handlers niet aangeroepen en wordt die code niet uitgevoerd.

Voorbeeldactiviteitshandler

U kunt bijvoorbeeld leden toevoegen om gebruikers te verwelkomen bij een gesprek en op bericht om berichten die ze naar de bot sturen, te beantwoorden.

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

Volgende stappen