Referencia rápida de la migración de JavaScriptJavaScript migration quick reference

se aplica a: SDK V4APPLIES TO: SDK v4

El SDK BotBuilder para JavaScript v4 introduce varios cambios fundamentales que afectan a cómo se crean los bots.The BotBuilder Javascript SDK v4 introduces several fundamental changes that affect how bots are authored. El propósito de esta guía es proporcionar una referencia rápida para resaltar las diferencias comunes al realizar una tarea en los SDK de las versiones v3 y v4.The purpose of this guide is to provide a quick reference for common differences between accomplishing a task in the v3 and v4 SDKs.

  • La forma en que la información pasa entre un bot y los canales ha cambiado.How information passes between a bot and channels has changed. En v3, ha utilizado los objetos conector y sesión.In v3, you used the connector and session objects. En v4, se reemplazan por los objetos adaptador y contexto de turno.In v4, these are replaced by the adapter and turn context objects.

  • Además, los diálogos y las instancias de los bot se han desacoplado aún más.Also, dialogs and bot instances have been further decoupled. En v3, se registraron los diálogos directamente en el constructor del bot.In v3, dialogs were registered directly in the bot's constructor. En v4, ahora puede pasar diálogos a instancias de los bot como argumentos, lo que proporciona una mayor flexibilidad de composición.In v4, you now pass dialogs into bot instances as arguments, providing greater compositional flexibility.

  • Además, la versión v4 proporciona una clase ActivityHandler, que ayuda a automatizar el control de diferentes tipos de actividades, tales como mensajes, actualización de conversación y actividades de eventos.Moreover, v4 provides an ActivityHandler class, which helps automate the handling of different types of activities, such as message, conversation update, and event activities.

Estas mejoras dan como resultado cambios en la sintaxis para el desarrollo de bots en JavaScript, especialmente en la creación de objetos de bot, la definición de diálogos y la codificación de la lógica del control de eventos.These improvements result in changes in syntax for developing bots in Javascript, especially around creating bot objects, defining dialogs, and coding event handling logic.

En el resto de este tema se comparan las construcciones de la versión v3 de SDK de Bot Framework para JavaScript con su equivalente de la versión v4.The rest of this topic compares the constructs in the JavaScript Bot Framework SDK v3 to their equivalent in v4.

Para escuchar las solicitudes entrantesTo 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);
    });
});

Para crear una instancia del botTo 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);

Para enviar un mensaje a un usuarioTo 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.');

Para definir un diálogo predeterminadoTo 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();
});

Para iniciar un diálogo secundarioTo start a child dialog

El diálogo principal se reanuda después de que finalice el diálogo secundario.The parent dialog resumes after the child dialog ends.

v3v3

session.beginDialog(DIALOG_ID);

v4v4

await context.beginDialog(DIALOG_ID);

Para reemplazar un diálogoTo replace a dialog

El diálogo actual se reemplaza en la pila por el diálogo nuevo.The current dialog is replaced on the stack by the new dialog.

v3v3

session.replaceDialog(DIALOG_ID);

v4v4

await context.replaceDialog(DIALOG_ID);

Para finalizar un diálogoTo end a dialog

v3v3

session.endDialog();

v4v4

Puede incluir un valor devuelto opcional.You can include an optional return value.

await context.endDialog(returnValue);

Para registrar un diálogo con una instancia de botTo 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);

Para solicitar una entrada del usuarioTo 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'
    }
);

Para recuperar la respuesta del usuario en una petición de consentimientoTo 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;
    // ...
}

Para guardar la información en el estado del diálogoTo 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;

Para escribir los cambios de estado en el nivel de persistenciaTo 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);

Para crear y registrar el almacenamiento de estadoTo 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);

Para detectar un error producido en un diálogoTo 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.');
}

Para registrar los controladores de actividadTo 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) => {
    // ...
}

Para enviar datos adjuntosTo send attachments

v3v3

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

v4v4

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

Para usar el reconocimiento de lenguaje natural (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);

Diálogo de intención de la versión v3 y equivalente de la versión 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();
});