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.

C#

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 .

JavaScript

JavaScript ActivityHandler använder ett händelseutfärdar- och lyssnarmönster. Använd till exempel onMessage metoden för att registrera en händelselyssnare för meddelandeaktiviteter. Du kan registrera fler än en lyssnare. När roboten tar emot en meddelandeaktivitet skulle aktivitetshanteraren se den inkommande aktiviteten och skicka den var och en av aktivitetslyssnarna onMessage i den ordning de registrerades.

När du skapar din robot hamnar robotlogik för hantering och svar på meddelanden i lyssnarna onMessage . På samma sätt går logiken för hantering av medlemmar som läggs till i konversationen i lyssnarna onMembersAdded , som anropas när en medlem läggs till i konversationen. Om du vill lägga till de här lyssnarna registrerar du dem i roboten enligt avsnittet Robotlogik nedan. Inkludera robotlogik för varje lyssnare och se sedan till att anropa next() i slutet. Genom att anropa next()kontrollerar du att nästa lyssnare körs.

Se till att spara tillstånd innan svängen slutar. Du kan göra det genom att åsidosätta aktivitetshanterarmetoden run och spara tillstånd när den överordnade metoden har slutförts run .

Det finns inga vanliga situationer där du vill åsidosätta bassvänghanteraren, så var försiktig om du försöker göra det. Det finns en särskild hanterare som heter onDialog. onDialog Hanteraren körs i slutet, efter att resten av hanterarna har körts och är inte kopplad till en viss aktivitetstyp. Precis som med alla ovanstående hanterare måste du anropa next() för att se till att resten av processen avslutas.

Java

Om du vill implementera logiken för dessa hanterare åsidosätter du dessa metoder i roboten , till exempel i avsnittet exempelaktivitetshanterare nedan. Det finns ingen basimplementering för var och en av dessa hanterare, så lägg 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 super.onTurn(turnContext); för att se till att basimplementeringen av onTurn körs före din ytterligare kod. Den basimplementeringen ansvarar bland annat för att anropa resten av aktivitetshanterarna, onMessageActivitytill exempel .

Python

När du skapar din robot hamnar robotlogik för hantering och svar på meddelanden i den här on_message_activity hanteraren. På samma sätt går logiken för hantering av medlemmar som läggs till i konversationen i on_members_added hanteraren, som anropas när en medlem läggs till i konversationen.

Om roboten till exempel tar emot en meddelandeaktivitet skulle turhanteraren se den inkommande aktiviteten och skicka den till on_message_activity aktivitetshanteraren.

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 super().on_turn(turnContext); för att se till att basimplementeringen av on_turn körs före din ytterligare kod. Den basimplementeringen ansvarar bland annat för att anropa resten av aktivitetshanterarna, on_message_activitytill exempel .

Aktivitetshantering

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

C#

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.

JavaScript

Huvudrobotlogik definieras i robotkoden. Om du vill implementera en robot som aktivitetshanterare utökar du ActivityHandler. ActivityHandler definierar olika händelser för olika typer av aktiviteter och du kan ändra robotens beteende genom att registrera händelselyssnare, till exempel med onMessage och onConversationUpdate.

Använd dessa metoder för att registrera lyssnare för varje typ av händelse:

Event	Registreringsmetod	beskrivning
Alla aktivitetstyper som tas emot	onTurn	Registrerar en lyssnare för när någon aktivitet tas emot.
Meddelandeaktiviteten har tagits emot	onMessage	Registrerar en lyssnare för när en message aktivitet tas emot.
Konversationsuppdateringsaktiviteten har tagits emot	onConversationUpdate	Registrerar en lyssnare för när någon conversationUpdate aktivitet tas emot.
Medlemmar anslöt sig till konversationen	onMembersAdded	Registrerar en lyssnare för när medlemmar gick med i konversationen, inklusive roboten.
Medlemmar lämnade konversationen	onMembersRemoved	Registrerar en lyssnare för när medlemmar lämnade konversationen, inklusive roboten.
Meddelandereaktionsaktivitet mottagen	onMessageReaction	Registrerar en lyssnare för när någon messageReaction aktivitet tas emot.
Meddelandereaktioner som lagts till i ett meddelande	onReactionsAdded	Registrerar en lyssnare för när reaktioner läggs till i ett meddelande.
Meddelandereaktioner som tagits bort från ett meddelande	onReactionsRemoved	Registrerar en lyssnare för när reaktioner tas bort från ett meddelande.
Händelseaktiviteten har tagits emot	onEvent	Registrerar en lyssnare för när någon event aktivitet tas emot.
Händelseaktivitet för tokensvar mottagen	onTokenResponseEvent	Registrerar en lyssnare för när en tokens/response händelse tas emot.
Installationsuppdateringsaktiviteten har tagits emot	onInstallationUpdate	Registrerar en lyssnare för när någon installationUpdate aktivitet tas emot.
Robot installerad	onInstallationUpdateAdd	Registrerar en lyssnare för när roboten är installerad i en organisationsenhet.
Roboten har avinstallerats	onInstallationUpdateRemove	Registrerar en lyssnare för när roboten avinstalleras i en organisationsenhet.
Annan aktivitetstyp har tagits emot	onUnrecognizedActivityType	Registrerar en lyssnare för när en hanterare för den specifika typen av aktivitet inte har definierats.
Aktivitetshanterare har slutförts	onDialog	Anropas efter att alla tillämpliga hanterare har slutförts.

Anropa fortsättningsfunktionen next från varje hanterare för att tillåta att bearbetningen fortsätter. Om next inte anropas upphör bearbetningen av aktiviteten.

Java

Huvudrobotlogik definieras i robotkoden. Om du vill implementera en robot som aktivitetshanterare härleder du robotklassen Bot från ActivityHandler, som implementerar gränssnittet. ActivityHandler definierar olika hanterare för olika typer av aktiviteter, till exempel onMessageActivity, och onMembersAdded. 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	onTurn	Anropar en av de andra hanterare, baserat på vilken typ av aktivitet som tas emot.
Meddelandeaktiviteten har tagits emot	onMessageActivity	Åsidosätt detta för att hantera en message aktivitet.
Konversationsuppdateringsaktiviteten har tagits emot	onConversationUpdateActivity	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	onMembersAdded	Åsidosätt detta för att hantera medlemmar som ansluter till en konversation.
Medlemmar som inte är robotar lämnade konversationen	onMembersRemoved	Åsidosätt detta för att hantera medlemmar som lämnar en konversation.
Händelseaktiviteten har tagits emot	onEventActivity	I en event aktivitet anropar en hanterare som är specifik för händelsetypen.
Händelseaktivitet för tokensvar mottagen	onTokenResponseEvent	Åsidosätt detta för att hantera tokensvarshändelser.
Händelseaktivitet som inte är token-svar har tagits emot	onEvent	Åsidosätt detta för att hantera andra typer av händelser.
Meddelandereaktionsaktivitet mottagen	onMessageReactionActivity	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	onReactionsAdded	Åsidosätt detta för att hantera reaktioner som lagts till i ett meddelande.
Meddelandereaktioner som tagits bort från ett meddelande	onReactionsRemoved	Åsidosätt detta för att hantera reaktioner som tagits bort från ett meddelande.
Installationsuppdateringsaktiviteten har tagits emot	onInstallationUpdate	I en installationUpdate aktivitet anropar en hanterare baserat på om roboten har installerats eller avinstallerats.
Robot installerad	onInstallationUpdateAdd	Åsidosätt detta om du vill lägga till logik för när roboten installeras i en organisationsenhet.
Roboten har avinstallerats	onInstallationUpdateRemove	Åsidosätt detta om du vill lägga till logik för när roboten avinstalleras i en organisationsenhet.
Annan aktivitetstyp har tagits emot	onUnrecognizedActivityType	Å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 onMessageActivity kommer alltid att hanteras och är vanligtvis den vanligaste.

Det finns också alternativet att implementera den offentliga metoden onTurn. 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 onTurnär det fortfarande ett alternativ.

Viktigt!

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

Python

Huvudrobotlogik definieras i robotkoden. Om du vill implementera en robot som aktivitetshanterare härleder du robotklassen från ActivityHandler, som i sin tur härleds från den abstrakta Bot klassen. ActivityHandler definierar olika hanterare för olika typer av aktiviteter, till exempel on_message_activity och on_members_added. 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	on_turn	Anropar en av de andra hanterare, baserat på vilken typ av aktivitet som tas emot.
Meddelandeaktiviteten har tagits emot	on_message_activity	Åsidosätt detta för att hantera en message aktivitet.
Konversationsuppdateringsaktiviteten har tagits emot	on_conversation_update_activity	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	on_members_added_activity	Åsidosätt detta för att hantera medlemmar som ansluter till en konversation.
Medlemmar som inte är robotar lämnade konversationen	on_members_removed_activity	Åsidosätt detta för att hantera medlemmar som lämnar en konversation.
Händelseaktiviteten har tagits emot	on_event_activity	I en event aktivitet anropar en hanterare som är specifik för händelsetypen.
Händelseaktivitet för tokensvar mottagen	on_token_response_event	Åsidosätt detta för att hantera tokensvarshändelser.
Händelseaktivitet som inte är token-svar har tagits emot	on_event_activity	Åsidosätt detta för att hantera andra typer av händelser.
Meddelandereaktionsaktivitet mottagen	on_message_reaction_activity	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	on_reactions_added	Åsidosätt detta för att hantera reaktioner som lagts till i ett meddelande.
Meddelandereaktioner som tagits bort från ett meddelande	on_reactions_removed	Åsidosätt detta för att hantera reaktioner som tagits bort från ett meddelande.
Installationsuppdateringsaktiviteten har tagits emot	on_installation_update	I en installationUpdate aktivitet anropar en hanterare baserat på om roboten har installerats eller avinstallerats.
Robot installerad	on_installation_update_add	Åsidosätt detta om du vill lägga till logik för när roboten installeras i en organisationsenhet.
Roboten har avinstallerats	on_installation_update_remove	Åsidosätt detta om du vill lägga till logik för när roboten avinstalleras i en organisationsenhet.
Annan aktivitetstyp har tagits emot	on_unrecognized_activity_type	Åsidosätt detta för att hantera alla aktivitetstyper som annars inte hanteras.

Dessa olika hanterare har en turn_context 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 on_message_activity 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 on_turn. 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 on_turnär det fortfarande ett alternativ.

Viktigt!

Om du åsidosätter on_turn metoden måste du anropa super().on_turn för att hämta basimplementeringen för att anropa alla andra on_<activity> 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.

C#

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

JavaScript

class EchoBot extends ActivityHandler {
    constructor() {
        super();
        // See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
        this.onMessage(async (context, next) => {
            const replyText = `Echo: ${ context.activity.text }`;
            await context.sendActivity(MessageFactory.text(replyText, replyText));
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });

        this.onMembersAdded(async (context, next) => {
            const membersAdded = context.activity.membersAdded;
            const welcomeText = 'Hello and welcome!';
            for (let cnt = 0; cnt < membersAdded.length; ++cnt) {
                if (membersAdded[cnt].id !== context.activity.recipient.id) {
                    await context.sendActivity(MessageFactory.text(welcomeText, welcomeText));
                }
            }
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });
    }
}

Java

public class EchoBot extends ActivityHandler {

    @Override
    protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
        return turnContext.sendActivity(
            MessageFactory.text("Echo: " + turnContext.getActivity().getText())
        ).thenApply(sendResult -> null);
    }

    @Override
    protected CompletableFuture<Void> onMembersAdded(
        List<ChannelAccount> membersAdded,
        TurnContext turnContext
    ) {
        String welcomeText = "Hello and welcome!";
        return membersAdded.stream()
            .filter(
                member -> !StringUtils
                    .equals(member.getId(), turnContext.getActivity().getRecipient().getId())
            ).map(channel -> turnContext.sendActivity(MessageFactory.text(welcomeText, welcomeText, null)))
            .collect(CompletableFutures.toFutureList()).thenApply(resourceResponses -> null);
    }
}

Python

class EchoBot(ActivityHandler):
    async def on_members_added_activity(
        self, members_added: [ChannelAccount], turn_context: TurnContext
    ):
        for member in members_added:
            if member.id != turn_context.activity.recipient.id:
                await turn_context.send_activity("Hello and welcome!")

    async def on_message_activity(self, turn_context: TurnContext):
        return await turn_context.send_activity(
            MessageFactory.text(f"Echo: {turn_context.activity.text}")
        )

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.