Introduce ActivityHandler class

[benbrown]

Note: Partity with microsoft/botbuilder-dotnet#1358

Description

Introducing ActivityHandler

This introduces a new class called ActivityHandler. ActivityHandlers have a .run() method that accepts the incoming turnContext created by adapter.processActivity. The ActivityHandler then emits events based on the activity type and other characteristics. These events can be handled by developer-defined functions.

The intention is to provide a flexible base class for bots. This should make it easier for developers to handle specific types of activities, and easier to understand the scope of activities a bot might receive. All activity types that might arrive via the Azure Bot Service are exposed as events, along with a few specialized events to - for example - distinguish whether a conversationUpdates represents member added versus members removed.

Here's a simple example, showing an "Echo bot" that replies to any incoming message with an echo.

const bot = new ActivityHandler();

server.post('/api/messages', (req, res) => {
    adapter.processActivity(req, res, async (context) => {
        // Route to main dialog.
        await bot.run(context);
    });
});


bot.onMessage(async (context, next) => { 
// do stuff
await context.sendActivity(`Echo: ${ context.activity.text }`);

// proceed with further processing
await next();
});

bot.onMembersAdded(async(context, next) => {
// send welcome messages to people listed in context.activity.membersAdded
await next();
});

Events

For all incoming activities, a Turn event will fire.

bot.onTurn(async (context, next) => { 
// this method receives every single incoming activity
await next();
});

Then, the type-specific event will fire. For example, ConversationUpdate:

bot.onConversationUpdate(async(context, next) => {
// this is a conversation update of some sort
await next();

Then, any sub-events will fire. For example, MembersAdded, which is a specialized version of ConversationUpdate:

bot.onMembersAdded(async(context, next) => {
// handle context.activity.membersAdded
await next();
});

Finally, a special Dialog event will fire that can be used to process Dialog activities. (see below)

Prevent Propagation of event

At any point in the processing chain, a handler may omit a call to await next() to prevent the event from continuing to be processed by other handlers.

This pattern can be used to capture interruptions or handle special events before they reach other handlers.

Using with Dialogs

In order to use an ActivityHandler along with the Dialogs system, use the onDialog() method, which fires at the very end of the processing chain.

bot.onDialog(async (context, next) => {

    if (context.activity.type === ActivityTypes.Message) {
        const dialogContext = await dialogSet.createContext(context);
        const results = await dialogContext.continueDialog();

        // fallback behavior is to run welcome dialog
        if (results.status === DialogTurnStatus.empty) {
             await dialogContext.beginDialog('hello');
        }

        await conversationState.saveChanges(context);
    }

    await next();

});

Specific Changes

• Add ActivityHandler class
• Add unit tests

Testing

Run unit tests using npm run test

[coveralls]

Pull Request Test Coverage Report for Build #1953

• 84 of 97 (86.6%) changed or added relevant lines in 2 files are covered.
• 2 unchanged lines in 1 file lost coverage.
• Overall coverage decreased (-0.08%) to 84.141%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
libraries/botbuilder-core/src/ActivityHandler.ts	83	96	86.46%

Files with Coverage Reduction	New Missed Lines	%
libraries/botframework-config/src/botConfigurationBase.ts	2	85.59%

Totals
Change from base Build #1952:	-0.08%
Covered Lines:	2915
Relevant Lines:	3338

---

💛 - Coveralls

[johnataylor]

naming: shouldn't this be "MessageReactionsAdded" and "MessageReactionsRemoved"

(for consistency with the property name and the membersAdded etc.)

[johnataylor]

should also handle event name "tokens/response"