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. Onder de covers roept de turn-handler van de bot de afzonderlijke activiteitshandler aan voor welk type activiteit de bot ook heeft ontvangen.

Als de bot bijvoorbeeld een berichtactiviteit ontvangt, ziet de draaihandler die binnenkomende activiteit en verzendt deze naar de handler voor berichtactiviteit . Bij het bouwen van uw bot gaat uw botlogica voor het verwerken en reageren op berichten hierin op de handler voor berichtactiviteiten . 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 basis-implementatie, dus voeg gewoon de logica toe die u wilt gebruiken in uw onderdrukking.

Er zijn bepaalde situaties waarin u de basisdraaihandler wilt overschrijven, zoals het opslaan van de status aan het einde van een draai. 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 beveiligd, maar kunnen worden overschreven, omdat we hiervan ActivityHandlerafhalen.

De handlers die zijn gedefinieerd in ActivityHandler zijn:

Gebeurtenis Handler Beschrijving
Elk activiteitstype dat is ontvangen 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.
Ontvangen activiteit voor gespreksupdate OnConversationUpdateActivityAsync In een conversationUpdate activiteit roept u een handler aan als andere leden dan de bot deelnemen aan of het gesprek verlaten.
Niet-botleden zijn lid geworden van het gesprek OnMembersAddedAsync Overschrijf dit om leden die deelnemen aan een gesprek af te handelen.
Niet-botleden hebben het gesprek verlaten OnMembersRemovedAsync Overschrijf dit om leden af te handelen 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.
Gebeurtenisactiviteit voor niet-tokenantwoord 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 activiteitstype af te handelen, anders niet verwerkt.

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 een sterk getypte activiteit in de contextparameter van zijn beurt; in de meeste gevallen OnMessageActivityAsync wordt altijd afgehandeld en is 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 afhandelen op leden die zijn toegevoegd om gebruikers te verwelkomen bij een gesprek en om berichten af te handelen om terug te sturen naar de 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);
            }
        }
    }
}

Volgende stappen