Depurar con el emuladorDebug with the Emulator

se aplica a: SDK V4APPLIES TO: SDK v4

El emulador de bot Framework es una aplicación de escritorio que permite a los desarrolladores de bot probar y depurar bots, ya sea de forma local o remota.Bot Framework Emulator is a desktop application that allows bot developers to test and debug bots, either locally or remotely. Con el emulador, puede conversar con el bot e inspeccionar los mensajes que envía y recibe el bot.Using the Emulator, you can chat with your bot and inspect the messages that your bot sends and receives. El emulador muestra los mensajes tal como aparecen en una interfaz de usuario de chat web y registra las solicitudes y respuestas de JSON a medida que intercambia mensajes con el bot.The Emulator displays messages as they would appear in a web chat UI and logs JSON requests and responses as you exchange messages with your bot. Antes de implementar el bot en la nube, ejecútelo localmente y pruébelo mediante el emulador.Before you deploy your bot to the cloud, run it locally and test it using the Emulator. Puede probar el bot mediante el emulador, aunque aún no lo haya creado con Azure bot Service o configurado para ejecutarse en cualquier canal.You can test your bot using the Emulator even if you haven't yet created it with Azure Bot Service or configured it to run on any channels.

PrerrequisitosPrerequisites

Ejecución local de un botRun a bot locally

Antes de conectar el bot a Bot Framework Emulator, debe ejecutar el bot localmente.Before connecting your bot to the Bot Framework Emulator, you need to run your bot locally. Puede usar Visual Studio o Visual Studio Code para ejecutar el bot, o bien usar la línea de comandos.You can use Visual Studio or Visual Studio Code to run your bot, or use command line. Para ejecutar un bot mediante la línea de comandos, haga lo siguiente:To run a bot using command line, do the following:

  • En el símbolo del sistema, cambie el directorio al del proyecto del bot.Go to the command prompt and change directory to your bot project directory.

  • Para iniciar el bot, ejecute el siguiente comando:Start the bot by running the following command:

    dotnet run
    
  • Copie el número de puerto que se indica la línea situada antes de Application started. Press CTRL+C to shut down. (Aplicación iniciada. Presione Ctrl+C para apagar).Copy the port number in the line before Application started. Press CTRL+C to shut down.

    Número de puerto (C#)

En este momento, el bot se ejecuta de forma local.At this point, your bot should be running locally.

Una conexión a un bot que se ejecuta en un host local.Connect to a bot running on localhost

Configuración de los valores de proxyConfigure proxy settings

Cuando se desarrolla detrás de un proxy corporativo, el emulador usará las variables de entorno configuradas HTTP_PROXY y HTTPS_PROXY , que especifican la ruta de la dirección URL del proxy para las solicitudes HTTP y https, respectivamente.When you are developing behind a corporate proxy, the Emulator will use the configured environment variables HTTP_PROXY and HTTPS_PROXY, which specify the proxy URL route for HTTP and HTTPs requests respectively.

Si se está conectando a un bot que se ejecuta en localhost , el emulador intentará primero enrutar a través del proxy antes de conectarse a localhost .If you are connecting to a bot running on localhost, the Emulator will first try to route through the proxy before connecting to localhost. Normalmente, el proxy bloqueará la conexión a menos que especifique que se debe omitir para localhost .Typically, the proxy will block the connection unless you specify that it should be bypassed for localhost.

Para omitir la HTTP_PROXY configuración de y HTTPS_PROXY y permitir que el emulador se conecte a localhost , en el equipo local debe definir la siguiente variable de entorno:In order to bypass the HTTP_PROXY and HTTPS_PROXY settings and allow the Emulator to connect to localhost, on your local machine you must define the following environment variable :

NO_PROXY=localhost

Configurar el emulador para la autenticaciónConfigure the Emulator for authentication

Si un bot requiere autenticación y muestra un cuadro de diálogo de inicio de sesión, debe configurar el emulador tal como se muestra a continuación.If a bot requires authentication, displaying a login dialog, you must configure the Emulator as shown below.

Uso del código de verificación de inicio de sesiónUsing sign-in verification code

  1. Inicie el emulador.Start the Emulator.
  2. En el emulador, haga clic en el icono de engranaje en la parte inferior izquierda o en la pestaña configuración del emulador en la esquina superior derecha.In the Emulator, click the gear icon in the bottom left, or the Emulator Settings tab in the upper right.
  3. Active la casilla Use a sign-in verification code for OAuthCards (Usar un código de verificación de inicio de sesión para OAuthCards).Check the box by Use a sign-in verification code for OAuthCards.
  4. Active la casilla Bypass ngrok for local address (Omitir ngrok para la dirección local).Check the box by Bypass ngrok for local address
  5. Haga clic en el botón Save (Guardar).Click the Save button.

Al hacer clic en el botón de inicio de sesión que muestra el bot, se generará un código de validación.When you click the login button displayed by the bot, a validation code will be generated. Escribirá el código en el cuadro chat de entrada de bot para que tenga lugar la autenticación.You'll enter the code in the bot input chat box for the authentication to take place. Después, puede realizar las operaciones permitidas.After that you can perform the allowed operations.

También tiene la opción de realizar los pasos que se describen a continuación.Alternatively, you can perform the steps described below.

Uso de tokens de autenticaciónUsing authentication tokens

  1. Inicie el emulador.Start the Emulator.
  2. En el emulador, haga clic en el icono de engranaje en la parte inferior izquierda o en la pestaña configuración del emulador en la esquina superior derecha.In the Emulator, click the gear icon in the bottom left, or the Emulator Settings tab in the upper right.
  3. Active la casilla Use version1.0 authentication tokens (Usar los tokens de autenticación de la versión 1.0).Check the box by Use version1.0 authentication tokens.
  4. Escriba la ruta de acceso local a la herramienta ngrok.Enter the local path to the ngrok tool. Para más información sobre la herramienta, consulte ngrok.For more the tool information, see ngrok.
  5. Active la casilla Run ngrok when the Emulator starts up (Ejecutar ngrok cuando se inicie el emulador).Check the box by Run ngrok when the Emulator starts up.
  6. Haga clic en el botón Save (Guardar).Click the Save button.

Al hacer clic en el botón de inicio de sesión que muestra el bot, se le pedirá que escriba sus credenciales.When you click the login button displayed by the bot, you will be asked to enter your credentials. Se genera un token de autenticación.An authentication token is generated. Después, puede realizar las operaciones permitidas.After that you can perform the allowed operations.

Ventana de inicio del emulador

Para conectarse a un bot que se ejecuta localmente, haga clic en Abrir bot.To connect to a bot running locally and click Open bot. Agregue el número de puerto que copió anteriormente en la siguiente dirección URL y pegue la dirección URL actualizada en la barra de direcciones URL del bot:Add the port number your copied earlier into the following URL and paste the updated URL in the Bot URL bar:

http://localhost:número de puerto/api/messageshttp://localhost:port number/api/messages

Cuadro de diálogo Abrir emulador de bot

Si el bot se está ejecutando con credenciales de una cuenta Microsoft (MSA), escriba también estas credenciales.If your bot is running with Microsoft Account (MSA) credentials, enter these credentials too.

Usar credenciales de botUse bot credentials

Cuando abra el bot, establezca el id. de aplicación de Microsoft y la contraseña de aplicación de Microsoft si su bot se ejecuta con credenciales.When you open the bot, set the Microsoft App ID and Microsoft App password if your bot is running with credentials. Si ha creado su bot con Azure Bot Service, las credenciales están disponibles en la instancia de App Service del bot, en la sección Configuración -> Configuración.If you created your bot with the Azure Bot Service, the credentials are available on the bot's App Service, under the Settings -> Configuration section. Si no conoce los valores, puede quitarlos del archivo de configuración del bot que se ejecuta localmente y luego ejecutar el bot en el emulador.If you do not know the values, you can remove those from the locally running bot's configuration file, then run the bot in the Emulator. Si el bot no se ejecuta con esta configuración, no es necesario ejecutar el emulador con la configuración.If the bot isn't running with these settings, you don't need to run the Emulator with the settings either.

Al crear una aplicación de proveedor de identidades de AD, recuerde lo siguiente:When creating an AD identity provider application, remember the following:

  • Cuando los tipos de cuenta admitidos se establecen en un solo inquilino, si usa una suscripción personal en lugar de un cuenta Microsoft, el emulador emitirá el error: el ID. de aplicación de Microsoft de bot o la contraseña de aplicación de Microsoft no son correctos.When the supported account types is set to single tenant, if you use a personal subscription instead of a Microsoft account, the Emulator would issue the error: The bot's Microsoft App ID or Microsoft App Password is incorrect..
  • En este caso, los tipos de cuenta admitidos se deben establecer en Cuentas en cualquier directorio organizativo (cualquier directorio de Azure AD: multiinquilino) y cuentas de Microsoft personales (como Xbox) .In this case, the supported account types must be set to Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Xbox).

Para obtener más información, consulte creación de una aplicación de proveedor de identidad de Azure ad y registro de una nueva aplicación con el Azure portal.For more information, see Create an Azure AD identity provider application and Register a new application using the Azure portal.

Vista detallada de la actividad de mensaje con el inspectorView detailed Message Activity with the Inspector

Envíe un mensaje al bot y este debería responder.Send a message to your bot and the bot should respond back. Puede hacer clic en una burbuja de mensaje dentro de la ventana de la conversación e inspeccionar la actividad JSON sin formato con la característica INSPECTOR que se encuentra a la derecha de la ventana.You can click on the message bubble within the conversation window and inspect the raw JSON activity using the INSPECTOR feature to the right side of the window. Cuando se selecciona, la burbuja de mensaje cambia a color amarillo y el objeto JSON de la actividad se mostrará a la izquierda de la ventana del chat.When selected, the message bubble will turn yellow and the activity JSON object will be displayed to the left of the chat window. Esta información de JSON incluye metadatos de clave que incluyen el identificador de canal, el tipo de actividad, el identificador de la conversación, el mensaje de texto, la dirección URL del punto de conexión, etc.The JSON information includes key metadata, including the channel ID, activity type, conversation ID, the text message, endpoint URL, and so on. Puede inspeccionar las actividades de inspección enviadas desde el usuario, así como también las actividades con las que responde el bot.You can inspect activities sent from the user, as well as activities the bot responds with.

Actividad de mensaje del emulador

Sugerencia

Para depurar los cambios de estado en un bot conectado a un canal, puede agregar middleware de inspección al bot.You can debug state changes in a bot connected to a channel by adding Inspection Middleware to the bot.

Inspección de serviciosInspect services

Con el emulador V4 también puede inspeccionar las respuestas JSON de LUIS y QnA.With the v4 Emulator you can also inspect the JSON responses from LUIS and QnA. Mediante un bot con un servicio de lenguaje conectado, puede seleccionar trace en la ventana LOG (Registro) en la esquina inferior derecha.Using a bot with a connected language service, you can select trace in the LOG window to the bottom right. Esta nueva herramienta también proporciona características para actualizar los servicios de lenguaje directamente desde el emulador.This new tool also provides features to update your language services directly from the Emulator.

Inspector de LUIS

Con un servicio de LUIS conectado, verá que el vínculo de seguimiento especifica el seguimiento de LUIS.With a connected LUIS service, you'll notice that the trace link specifies Luis Trace. Cuando se seleccione, verá la respuesta sin formato proveniente del servicio de LUIS, que incluye intenciones y entidades junto con sus puntuaciones especificadas.When selected, you'll see the raw response from your LUIS service, which includes intents, entities along with their specified scores. También tiene la opción de volver a asignar intenciones a las expresiones del usuario.You also have the option to re-assign intents for your user utterances.

Inspector de QnA

Con un servicio de QnA conectado, el registro mostrará el seguimiento de QnA y cuando esté seleccionado, podrá obtener una vista previa del par de pregunta y respuesta asociado con esa actividad, junto con una puntuación de confianza.With a connected QnA service, the log will display QnA Trace, and when selected you can preview the question and answer pair associated with that activity, along with a confidence score. Desde aquí, puede agregar frases de preguntas alternativas para una respuesta.From here, you can add alternative question phrasing for an answer.

Inicio de sesión en AzureLogin to Azure

Puede usar Emulator para iniciar sesión en la cuenta de Azure.You can use Emulator to login in to your Azure account. Esto es especialmente útil para agregar y administrar los servicios de los que depende el bot.This is particularly helpful for you to add and manage services your bot depends on. Siga estos pasos para iniciar sesión en Azure:Log into Azure by following these steps:

  1. Haga clic en archivo-> iniciar sesión con AzureClick on File -> Sign in with Azure

    Iniciar sesión en el emulador con Azure

  2. En la pantalla de bienvenida, haga clic en iniciar sesión con su cuenta de Azure.On the welcome screen click on Sign in with your Azure account. Opcionalmente, puede hacer que el emulador mantenga la sesión iniciada en los reinicios de la aplicación del emulador.You can optionally have Emulator keep you signed in across Emulator application restarts.

    Emulador de inicio de sesión correcto de Azure

Deshabilitación de la recopilación de datosDisabling data collection

Si decide que ya no desea permitir que Emulator recopile datos de uso, puede deshabilitar fácilmente la recopilación de datos siguiendo estos pasos:If you decide that you no longer want to allow the Emulator to collect usage data, you can easily disable data collection by following these steps:

  1. Vaya a la página de configuración de Emulator. Para ello, haga clic en el botón de configuración (icono de engranaje) en la barra de navegación del lado izquierdo.Navigate to the Emulator's settings page by clicking on the Settings button (gear icon) in the nav bar on the left side.

    Botón Configuración del emulador

  2. Desactive la casilla denominada Help improve the Emulator by allowing us to collect usage data (Ayúdenos a mejorar Emulator permitiéndonos recopilar datos de uso) en la sección Recopilación de datos.Uncheck the checkbox labeled Help improve the Emulator by allowing us to collect usage data under the Data Collection section.

    Configuración del emulador, recopilación de datos

  3. Haga clic en el botón “Save” (Guardar).Click the "Save" button.

    Configuración del emulador, botón Guardar

Si cambia de opinión, puede habilitar esta opción siempre que quiera volviendo a activar la casilla.If you change your mind, you can always enable it by re-checking the checkbox.

Recursos adicionalesAdditional resources

Bot Framework Emulator es de código abierto.The Bot Framework Emulator is open source. También puede colaborar en el desarrollo y enviar errores y sugerencias.You can contribute to the development and submit bugs and suggestions.

Para solucionar el problema, consulte cómo solucionar problemas generales y otros artículos de solución de problemas en esa sección.For troubleshooting, see troubleshoot general problems and the other troubleshooting articles in that section.

Pasos siguientesNext steps

Use el middleware de inspección para depurar un bot conectado a un canal.Use inspection middleware to debug a bot connected to a channel.