Kurzübersicht zur JavaScript-MigrationJavaScript migration quick reference

gilt für: SDK v4APPLIES TO: SDK v4

Mit Version 4 des BotBuilder JavaScript SDK werden einige grundlegende Änderungen eingeführt, die sich auf die Erstellung von Bots auswirken.The BotBuilder Javascript SDK v4 introduces several fundamental changes that affect how bots are authored. Dieser Leitfaden enthält eine Kurzübersicht über die allgemeinen Unterschiede zwischen der Durchführung einer Aufgabe in v3- und v4-SDKs.The purpose of this guide is to provide a quick reference for common differences between accomplishing a task in the v3 and v4 SDKs.

  • Es wurde geändert, wie Informationen zwischen einem Bot und Kanälen übergeben werden.How information passes between a bot and channels has changed. In v3 haben Sie die Objekte connector und session verwendet.In v3, you used the connector and session objects. In v4 wurden diese Objekte durch adapter und turn context ersetzt.In v4, these are replaced by the adapter and turn context objects.

  • Darüber hinaus wurden Dialoge und Botinstanzen weiter entkoppelt.Also, dialogs and bot instances have been further decoupled. In v3 wurden Dialoge direkt im Konstruktor des Bots registriert.In v3, dialogs were registered directly in the bot's constructor. In v4 übergeben Sie Dialoge jetzt als Argumente in Botinstanzen, um eine höhere Kompositionsflexibilität zu erzielen.In v4, you now pass dialogs into bot instances as arguments, providing greater compositional flexibility.

  • Darüber hinaus wird in v4 eine ActivityHandler-Klasse bereitgestellt, die die Automatisierung der Verarbeitung unterschiedlicher Arten von Aktivitäten ermöglicht, z. B. vom Typ message, conversation update und event.Moreover, v4 provides an ActivityHandler class, which helps automate the handling of different types of activities, such as message, conversation update, and event activities.

Diese Verbesserungen führen zu Änderungen der Syntax zum Entwickeln von Bots in JavaScript, vor allem in Bezug auf das Erstellen von Botobjekten, Definieren von Dialogen und Codieren von Ereignisbehandlungslogik.These improvements result in changes in syntax for developing bots in Javascript, especially around creating bot objects, defining dialogs, and coding event handling logic.

Im restlichen Teil dieses Themas werden die Konstrukte im JavaScript Bot Framework SDK v3 mit den Entsprechungen in v4 verglichen.The rest of this topic compares the constructs in the JavaScript Bot Framework SDK v3 to their equivalent in v4.

Lauschen auf eingehende AnforderungenTo listen for incoming requests

V3v3

var connector = new builder.ChatConnector({
    appId: process.env.MicrosoftAppId,
    appPassword: process.env.MicrosoftAppPassword
});

server.post('/api/messages', connector.listen());

v4v4

const adapter = new BotFrameworkAdapter({
    appId: process.env.MicrosoftAppId,
    appPassword: process.env.MicrosoftAppPassword
});

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

Erstellen einer BotinstanzTo create a bot instance

V3v3

var bot = new builder.UniversalBot(connector, [ ...DIALOG_STEPS ]);

v4v4

// Define the bot class as extending ActivityHandler.
const { ActivityHandler } = require('botbuilder');

class MyBot extends ActivityHandler {
    // ...
}

// Instantiate a new bot instance.
const bot = new MyBot(conversationState, dialog);

Senden einer Nachricht an einen BenutzerTo send a message to a user

V3v3

session.send('Hello and welcome to the help desk bot.');

v4v4

await context.sendActivity('Hello and welcome to the help desk bot.');

Definieren eines StandarddialogsTo define a default dialog

V3v3

var bot = new builder.UniversalBot(connector, [
    // Add default dialog waterfall steps...
]);

v4v4

// In the main dialog class, define a run method.
async run(turnContext, accessor) {
    const dialogSet = new DialogSet(accessor);
    dialogSet.add(this);

    const dialogContext = await dialogSet.createContext(turnContext);
    const results = await dialogContext.continueDialog();
    if (results.status === DialogTurnStatus.empty) {
        await dialogContext.beginDialog(this.id);
    }
}

// Pass conversation state management and a main dialog objects to the bot (in index.js).
const bot = new MyBot(conversationState, dialog);

// Inside the bot's constructor, add the dialog as a member property and define a DialogState property accessor.
this.dialog = dialog;
this.dialogState = this.conversationState.createProperty('DialogState');

// Inside the bot's message handler, invoke the dialog's run method, passing in the turn context and DialogState accessor.
this.onMessage(async (context, next) => {
    // Run the Dialog with the new message Activity.
    await this.dialog.run(context, this.dialogState);
    await next();
});

Starten eines untergeordneten DialogsTo start a child dialog

Der übergeordnete Dialog wird fortgesetzt, nachdem der untergeordnete Dialog beendet wurde.The parent dialog resumes after the child dialog ends.

V3v3

session.beginDialog(DIALOG_ID);

v4v4

await context.beginDialog(DIALOG_ID);

Ersetzen eines DialogsTo replace a dialog

Der aktuelle Dialog wird im Stapel durch einen neuen Dialog ersetzt.The current dialog is replaced on the stack by the new dialog.

V3v3

session.replaceDialog(DIALOG_ID);

v4v4

await context.replaceDialog(DIALOG_ID);

So beenden Sie einen DialogTo end a dialog

V3v3

session.endDialog();

v4v4

Sie können einen optionalen Rückgabewert einbinden.You can include an optional return value.

await context.endDialog(returnValue);

Registrieren eines Dialogs bei einer BotinstanzTo register a dialog with a bot instance

V3v3

// Create the bot.
var bot = new builder.UniversalBot(connector, [
    // ...
]};

// Add the dialog to the bot.
bot.dialog('myDialog', require('./mydialog'));

v4v4

// In the main dialog class constructor.
this.addDialog(new MyDialog(DIALOG_ID));

// In the app entry point file (index.js)
const { MainDialog } = require('./dialogs/main');

// Create the base dialog and bot, passing the main dialog as an argument.
const dialog = new MainDialog();
const reservationBot = new ReservationBot(conversationState, dialog);

Auffordern eines Benutzers zur EingabeTo prompt a user for input

V3v3

var builder = require('botbuilder');
builder.Prompts.text(session, 'Please enter your destination');

v4v4

const { TextPrompt } = require('botbuilder-dialogs');

// In the dialog's constructor, register the prompt.
this.addDialog(new TextPrompt('initialPrompt'));

// In the dialog step, invoke the prompt.
return await stepContext.prompt(
    'initialPrompt', {
        prompt: 'Please enter your destination'
    }
);

Abrufen der Antwort des Benutzers auf eine AufforderungTo retrieve the user's response to a prompt

V3v3

function (session, result) {
    var destination = result.response;
    // ...
}

v4v4

// In the dialog step after the prompt step, retrieve the result from the waterfall step context.
async nextStep(stepContext) {
    const destination = stepContext.result;
    // ...
}

Speichern von Informationen im DialogzustandTo save information to dialog state

V3v3

session.dialogData.destination = results.response;

v4v4

// In a dialog, set the value in the waterfall step context.
stepContext.values.destination = destination;

So schreiben Sie Statusänderungen in der PersistenzebeneTo write changes in state to the persistence layer

V3v3

// State data is saved by default at the end of the turn.
// Do this to save it manually.
session.save();

v4v4

// State changes are not saved automatically at the end of the turn.
await this.conversationState.saveChanges(context, false);
await this.userState.saveChanges(context, false);

Erstellen und Registrieren des ZustandsspeichersTo create and register state storage

V3v3

var builder = require('botbuilder');

// Create conversation state with in-memory storage provider.
var inMemoryStorage = new builder.MemoryBotStorage();

// Create the base dialog and bot
var bot = new builder.UniversalBot(connector, [ /*...*/ ]).set('storage', inMemoryStorage);

v4v4

const { MemoryStorage } = require('botbuilder');

// Create the memory layer object.
const memoryStorage = new MemoryStorage();

// Create the conversation state management object, using the storage provider.
const conversationState = new ConversationState(memoryStorage);

// Create the base dialog and bot.
const dialog = new MainDialog();
const reservationBot = new ReservationBot(conversationState, dialog);

Abfangen eines Fehlers, der von einem Dialog ausgelöst wirdTo catch an error thrown from a dialog

V3v3

// Set up the error handler.
session.on('error', function (err) {
    session.send('Failed with message:', err.message);
    session.endDialog();
});

// Throw an error.
session.error('An error has occurred.');

v4v4

// Set up the error handler, using the adapter.
adapter.onTurnError = async (context, error) => {
    const errorMsg = error.message

    // Clear out conversation state to avoid keeping the conversation in a corrupted bot state.
    await conversationState.delete(context);

    // Send a message to the user.
    await context.sendActivity(errorMsg);
};

// Throw an error.
async () => {
    throw new Error('An error has occurred.');
}

Registrieren von AktivitätshandlernTo register activity handlers

V3v3

bot.on('conversationUpdate', function (message) {
    // ...
}

bot.on('contactRelationUpdate', function (message) {
    // ...
}

v4v4

// In the bot's constructor, add the handlers.
this.onMessage(async (context, next) => {
    // ...
}
  
this.onDialog(async (context, next) => {
    // ...
}

this.onMembersAdded(async (context, next) => {
    // ...
}

Senden von AnlagenTo send attachments

V3v3

var message = new builder.Message()
    .attachments(hotelHeroCards
    .attachmentLayout(builder.AttachmentLayout.carousel));

v4v4

await context.sendActivity({
    attachments: hotelHeroCards,
    attachmentLayout: AttachmentLayoutTypes.Carousel
});

Verwenden der Erkennung natürlicher Sprache (LUIS)To use natural language recognition (LUIS)

V3v3

// The LUIS recognizer was part of the 'botbuilder' library
var builder = require('botbuilder');

var recognizer = new builder.LuisRecognizer(LUIS_MODEL_URL);
bot.recognizer(recognizer);

v4v4

// The LUIS recognizer is now part of the 'botbuilder-ai' library
const { LuisRecognizer } = require('botbuilder-ai');

const luisApp = { applicationId: LuisAppId, endpointKey: LuisAPIKey, endpoint: `https://${ LuisAPIHostName }` };
const recognizer = new LuisRecognizer(luisApp);

const recognizerResult = await recognizer.recognize(context);
const intent = LuisRecognizer.topIntent(recognizerResult);

Absichtsdialog in v3 und Entsprechung in v4v3 Intent Dialog and v4 Equivalent

V3v3

// Create a 'greetings' RegExpRecognizer that can be turned off
var greetings = new builder.RegExpRecognizer('Greetings', /hello|hi|hey|greetings/i)
    .onEnabled(function (session, callback) {
        // Check to see if this recognizer should be enabled
        if (session.conversationData.useGreetings) {
            callback(null, true);
        } else {
            callback(null, false);
        }
    });

// Create our IntentDialog and add recognizers
var intents = new builder.IntentDialog({ recognizers: [greetings] });

bot.dialog('/', intents);

// If no intent is recognized, direct user to Recognizer Menu
intents.onDefault('RecognizerMenu');

// Match our "Greetings" and "Farewell" intents with their dialogs
intents.matches('Greetings', 'Greetings');

// Add a greetings dialog
bot.dialog('Greetings', [
    function (session) {
        session.endDialog('Greetings!');
    }
]);

v4v4

this.onMessage(async (context, next) => {

    const recognizerResult = {
        text: context.activity.text,
        intents: []
    };

    const greetingRegex = RegExp(/hello|hi|hey|greetings/i);

    if (greetingRegex.test(context.activity.text)) {
      // greeting intent identified
      recognizerResult.intents.push('Greeting');
    }

    if (recognizerResult.intents.includes('Greeting')) {
        // Run the 'Greeting' dialog
        await context.beginDialog(GREETING_DIALOG_ID);
    }

    await next();
});