Dela via


Händelsedrivna konversationer med hjälp av en aktivitetshanterare

GÄLLER FÖR: SDK v4

En aktivitetshanterare är ett händelsedrivet sätt att organisera konversationslogik för din robot. Varje aktivitetstyp eller undertyp representerar en annan typ av konversationshändelse. Under täcket anropar robotens turhanterare den enskilda aktivitetshanteraren för vilken typ av aktivitet den tog emot.

Om roboten till exempel tar emot en meddelandeaktivitet skulle turhanteraren se den inkommande aktiviteten och skicka den till aktivitetshanteraren för meddelandeaktivitet. När du skapar din robot hamnar robotlogik för hantering och svar på meddelanden i detta på meddelandeaktivitetshanteraren . På samma sätt går logiken för hantering av medlemmar som läggs till i konversationen i din hanterare för medlemmar som lagts till , som anropas när en medlem läggs till i konversationen.

Andra sätt att organisera robotlogik finns i avsnittet om robotlogik i hur robotar fungerar.

Kommentar

Bot Framework JavaScript-, C#- och Python-SDK:erna fortsätter att stödjas, men Java SDK dras tillbaka med slutligt långsiktigt stöd som slutar i november 2023.

Befintliga robotar som skapats med Java SDK fortsätter att fungera.

Om du vill skapa en ny robot kan du använda Microsoft Copilot Studio och läsa om hur du väljer rätt copilot-lösning.

Mer information finns i Framtiden för robotbygge.

Om du vill implementera logiken för dessa hanterare åsidosätter du dessa metoder i roboten , till exempel i avsnittet exempelaktivitetshanterare nedan. För var och en av dessa hanterare finns det ingen basimplementering, så lägg bara till den logik som du vill använda i åsidosättningen.

Det finns vissa situationer där du vill åsidosätta bassvänghanteraren, till exempel att spara tillstånd i slutet av en sväng. När du gör det måste du först anropa await base.OnTurnAsync(turnContext, cancellationToken); för att se till att basimplementeringen av OnTurnAsync körs före din ytterligare kod. Den basimplementeringen ansvarar bland annat för att anropa resten av aktivitetshanterarna, OnMessageActivityAsynctill exempel .

Aktivitetshantering

Robotlogiken bearbetar inkommande aktiviteter från en eller flera kanaler och genererar utgående aktiviteter som svar.

Huvudrobotlogik definieras i robotkoden. Om du vill implementera en robot som aktivitetshanterare härleder du robotklassen IBot från ActivityHandler, som implementerar gränssnittet. ActivityHandler definierar olika hanterare för olika typer av aktiviteter, till exempel OnMessageActivityAsync, och OnMembersAddedAsync. Dessa metoder är skyddade, men kan åsidosättas, eftersom vi härleds från ActivityHandler.

De hanterare som definieras i ActivityHandler är:

Event Hanterare beskrivning
Alla aktivitetstyper som tas emot OnTurnAsync Anropar en av de andra hanterare, baserat på vilken typ av aktivitet som tas emot.
Meddelandeaktiviteten har tagits emot OnMessageActivityAsync Åsidosätt detta för att hantera en message aktivitet.
Konversationsuppdateringsaktiviteten har tagits emot OnConversationUpdateActivityAsync I en conversationUpdate aktivitet anropar en hanterare om andra medlemmar än roboten anslöt eller lämnade konversationen.
Medlemmar som inte är robotmedlemmar anslöt sig till konversationen OnMembersAddedAsync Åsidosätt detta för att hantera medlemmar som ansluter till en konversation.
Medlemmar som inte är robotar lämnade konversationen OnMembersRemovedAsync Åsidosätt detta för att hantera medlemmar som lämnar en konversation.
Händelseaktiviteten har tagits emot OnEventActivityAsync I en event aktivitet anropar en hanterare som är specifik för händelsetypen.
Händelseaktivitet för tokensvar mottagen OnTokenResponseEventAsync Åsidosätt detta för att hantera tokensvarshändelser.
Händelseaktivitet som inte är token-svar har tagits emot OnEventAsync Åsidosätt detta för att hantera andra typer av händelser.
Meddelandereaktionsaktivitet mottagen OnMessageReactionActivityAsync I en messageReaction aktivitet anropar en hanterare om en eller flera reaktioner har lagts till eller tagits bort från ett meddelande.
Meddelandereaktioner som lagts till i ett meddelande OnReactionsAddedAsync Åsidosätt detta för att hantera reaktioner som lagts till i ett meddelande.
Meddelandereaktioner som tagits bort från ett meddelande OnReactionsRemovedAsync Åsidosätt detta för att hantera reaktioner som tagits bort från ett meddelande.
Installationsuppdateringsaktiviteten har tagits emot OnInstallationUpdateActivityAsync I en installationUpdate aktivitet anropar en hanterare baserat på om roboten har installerats eller avinstallerats.
Robot installerad OnInstallationUpdateAddAsync Åsidosätt detta om du vill lägga till logik för när roboten installeras i en organisationsenhet.
Roboten har avinstallerats OnInstallationUpdateRemoveAsync Åsidosätt detta om du vill lägga till logik för när roboten avinstalleras i en organisationsenhet.
Annan aktivitetstyp har tagits emot OnUnrecognizedActivityTypeAsync Åsidosätt detta för att hantera alla aktivitetstyper som annars inte hanteras.

Dessa olika hanterare har en turnContext som innehåller information om den inkommande aktiviteten, vilket motsvarar den inkommande HTTP-begäran. Aktiviteter kan vara av olika typer, så varje hanterare tillhandahåller en starkt typad aktivitet i sin turkontextparameter. i de flesta fall OnMessageActivityAsync kommer alltid att hanteras och är vanligtvis den vanligaste.

Precis som i tidigare 4.x-versioner av det här ramverket finns det också möjlighet att implementera den offentliga metoden OnTurnAsync. För närvarande hanterar basimplementeringen av den här metoden felkontroll och anropar sedan var och en av de specifika hanterare (som de två vi definierar i det här exemplet) beroende på typen av inkommande aktivitet. I de flesta fall kan du lämna den metoden ensam och använda enskilda hanterare, men om din situation kräver en anpassad implementering av OnTurnAsyncär det fortfarande ett alternativ.

Viktigt!

Om du åsidosätter OnTurnAsync metoden måste du anropa base.OnTurnAsync för att hämta basimplementeringen för att anropa alla andra On<activity>Async hanterare eller anropa dessa hanterare själv. Annars anropas inte dessa hanterare och koden körs inte.

Exempelaktivitetshanterare

Du kan till exempel hantera medlemmar som lagts till för att välkomna användare till en konversation och hantera meddelanden för att upprepa meddelanden som de skickar till roboten.

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ästa steg

  • Microsoft Teams-kanalen introducerar vissa Teams-specifika aktiviteter som din robot behöver stöd för för att fungera korrekt med Teams. Information om viktiga begrepp för att utveckla robotar för Microsoft Teams finns i Så här fungerar Microsoft Teams-robotar
  • En aktivitetshanterare är ett bra sätt att utforma en robot som inte behöver spåra konversationstillstånd mellan svängar. Dialogrutebiblioteket innehåller sätt att hantera en långvarig konversation med användaren.