Software intermedioMiddleware

se aplica a: SDK V4APPLIES TO: SDK v4

El software intermedio es simplemente una clase que se encuentra entre el adaptador y la lógica del bot, que se agrega a la colección de software intermedio del adaptador durante la inicialización.Middleware is simply a class that sits between the adapter and your bot logic, added to your adapter's middleware collection during initialization. El SDK le permite escribir su propio middleware o agregar middleware creado por terceros.The SDK allows you to write your own middleware or add middleware created by others. Todas las actividades que entran y salen de su bot pasan por el middleware.Every activity coming into or out of your bot flows through your middleware.

El adaptador procesa y dirige las actividades entrantes a través de la canalización de middleware de bot a la lógica de Bot y, después, vuelve a salir.The adapter processes and directs incoming activities in through the bot middleware pipeline to your bot's logic and then back out again. Cuando las actividades entran y salen de los bots, cada fragmento de software intermedio puede inspeccionar o actuar sobre la actividad, tanto antes como después de que se ejecute la lógica del bot.As each activity flows in and out of the bot, each piece of middleware can inspect or act upon the activity, both before and after the bot logic runs.

Antes de centrarse en el software intermedio, es importante entender los bots en general y cómo procesan las actividades.Before jumping into middleware, it is important to understand bots in general and how they process activities.

Usos del software intermedioUses for middleware

A menudo surge la siguiente pregunta: "¿Cuándo debo implementar acciones como middleware, en lugar de usar la lógica normal del bot?"The question often comes up: "When should I implement actions as middleware versus using my normal bot logic?" El middleware le brinda oportunidades adicionales para interactuar con el flujo de conversación de los usuarios tanto antes como después de que se procese cada turno de la conversación.Middleware provides you with additional opportunities to interact with your users' conversation flow both before and after each turn of the conversation is processed. También permite almacenar y recuperar información relativa a la conversación y llamar a una lógica de procesamiento adicional cuando sea necesario.Middleware also allows you to store and retrieve information concerning the conversation and call additional processing logic when required. A continuación encontrará algunos escenarios comunes que muestran situaciones en las que el middleware puede resultar útil.Below are some common scenarios that show where middleware can be useful.

Registrar o actuar sobre todas las actividadesLooking at or acting on every activity

Existen muchas situaciones que requieren que un bot haga algo en todas las actividades, o bien en las actividades de un tipo determinado.There are plenty of situations that require your bot to do something on every activity, or for every activity of a certain type. Por ejemplo, tal vez desee registrar todas las actividades de mensajes que recibe el bot, o proporcionar una respuesta de reserva si el bot no ha generado ninguna respuesta en este turno.For example, you may want to log every message activity your bot receives or provide a fallback response if the bot has not otherwise generated a response this turn. El software intermedio es idóneo para hacerlo, ya que puede actuar tanto antes como después de que se haya ejecutado el resto de la lógica del bot.Middleware is a great place for this, with its ability to act both before and after the rest of the bot logic has executed.

Modificar o mejorar el contexto de turnoModifying or enhancing the turn context

Algunas conversaciones pueden ser mucho más provechosas si el bot tiene más información de la que se proporciona en la actividad.Certain conversations can be much more fruitful if the bot has more information than what is provided in the activity. En este caso, el middleware podría comprobar la información de estado de la conversación que se tiene hasta el momento, consultar un origen de datos externo y anexarlo al objeto del contexto de turno antes de pasar la ejecución a la lógica del bot.Middleware in this case could look at the conversation state information it has so far, query an external data source, and append that to the turn context object before passing execution on to the bot logic.

El SDK define el middleware de registro que puede grabar las actividades de entrada y salida, pero el usuario también puede definir su propio middleware.The SDK defines logging middleware that can record incoming and outgoing activities, but you can also define your own middleware.

La canalización de software intermedio del botThe bot middleware pipeline

Para cada actividad, el adaptador llama al middleware en el orden en que se ha agregado.For each activity, the adapter calls middleware in the order in which you added it. El adaptador pasa el objeto de contexto para el turno y un delegado next, y el software intermedio llama al delegado para pasar el control al siguiente software intermedio de la canalización.The adapter passes in the context object for the turn and a next delegate, and the middleware calls the delegate to pass control to the next middleware in the pipeline. El software intermedio también puede llevar a cabo acciones después de que se devuelva el delegado next antes de completar el método.Middleware also has an opportunity to do things after the next delegate returns before completing the method. Es como si cada objeto de software intermedio tuviese la oportunidad de actuar directamente sobre los objetos de software intermedio que lo siguen en la canalización.You can think of it as each middleware object has the first-and-last chance to act with respect to the middleware objects that follow it in the pipeline.

Por ejemplo:For example:

  • el controlador de activación del primer objeto middleware ejecuta código antes de llamar a Next.1st middleware object's turn handler executes code before calling next.
    • el controlador de activación del segundo objeto middleware ejecuta código antes de llamar a Next.2nd middleware object's turn handler executes code before calling next.
      • El controlador de activación del bot ejecuta y devuelve.The bot's turn handler executes and returns.
    • el controlador de activación del segundo objeto middleware ejecuta cualquier código restante antes de devolver.2nd middleware object's turn handler executes any remaining code before returning.
  • el controlador de activación del primer objeto middleware ejecuta cualquier código restante antes de devolver.1st middleware object's turn handler executes any remaining code before returning.

Si el middleware no llama al siguiente delegado, el adaptador no llama a ninguno de los controladores de activación de middleware o de bot posteriores y a los circuitos cortos de canalización.If middleware doesn't call the next delegate, the adapter does not call any of the subsequent middleware or bot turn handlers, and the pipeline short circuits.

Una vez que se ha completado la canalización de software intermedio del bot, el turno acaba y el contexto de turno sale del ámbito.Once the bot middleware pipeline completes, the turn is over, and the turn context goes out of scope.

El software intermedio o el bot pueden generar respuestas y registrar los controladores de eventos de respuesta, pero debe tener en cuenta que las respuestas se controlan en procesos independientes.Middleware or the bot can generate responses and register response event handlers, but keep in mind that responses are handled in separate processes.

Orden del software intermedioOrder of middleware

Puesto que el orden en el que se agrega el software intermedio determina el orden en el que este procesa una actividad, es importante decidir la secuencia que se seguirá para agregar dicho software intermedio.Since the order in which middleware is added determines the order in which the middleware processes an activity, it's important to decide the sequence that middleware should be added.

Nota

Esto está pensado para proporcionarle un patrón común que funcione para la mayoría de los bots, pero debe tener en cuenta cómo interactuará cada fragmento de software intermedio con los demás según su situación.This is meant to give you a common pattern that works for most bots, but be sure to consider how each piece of middleware will interact with the others for your situation.

Los primeros elementos de la canalización de software intermedio probablemente serán los que se encarguen de las tareas de nivel más bajo que se usan de cada vez,The first things in your middleware pipeline should likely be those that take care of the lowest-level tasks that are used every time. como el registro, el control de excepciones y la traducción.Examples include logging, exception handling, and translation. El orden de estos elementos puede variar en función de sus necesidades, por ejemplo, si quiere que el mensaje entrante se traduzca primero, antes de que se guarden los mensajes, o si primero se deben almacenar, lo que podría significar que los mensajes almacenados no se traducirían.Ordering these can vary depending on your needs, such as whether you want the incoming message to be translated first, before messages are stored, or if message storage should occur first, which could mean stored messages wouldn't be translated.

Los últimos elementos de la canalización de software intermedio deberían ser el software intermedio específico del bot, que es el que se implementa para realizar el procesamiento de cada mensaje que se envía al bot.The last things in your middleware pipeline should be bot-specific middleware, which is middleware you implement to do some processing on every message sent to your bot. Si el software intermedio usa información de estado u otra información definida en el contexto del bot, agréguela a la canalización de software intermedio después del software intermedio que modifica el estado o el contexto.If your middleware uses state information or other information set in the bot context, add it to the middleware pipeline after the middleware that modifies state or context.

CortocircuitosShort circuiting

Una idea importante relacionada con el middleware y los controladores de respuesta es el cortocircuito.An important idea around middleware and response handlers is short circuiting. Si la ejecución va a continuar por las capas siguientes, el middleware (o un controlador de respuestas) debe pasar la ejecución mediante una llamada al delegado next.If execution is to continue through the layers that follow it, middleware (or a response handler) is required to pass execution on by calling its next delegate. Si no se llama al delegado next en dicho middleware (o controlador de respuestas), se producirá un cortocircuito en la canalización asociada y las capas posteriores no se ejecutarán,If the next delegate is not called within that middleware (or response handler), the associated pipeline short circuits and subsequent layers are not executed. lo que significa que se omiten no solo toda la lógica del bot, sino también el middleware posterior de la canalización.This means all bot logic, and any middleware further along the pipeline, is skipped. Hay una sutil diferencia entre que el middleware cortocircuite un turno y que lo haga el controlador de respuestas.There is a subtle difference between your middleware and your response handler short circuiting a turn.

Si el middleware cortocircuita un turno, no se llama al controlador de turnos del bot, pero todo el código del middleware que se haya ejecutado antes de ese momento en la canalización se seguirá ejecutando hasta su finalización.When middleware short circuits a turn, your bot turn handler will not be called, but all middleware code executed prior to this point in the pipeline will still run to completion.

En el caso de los controladores de eventos, si no se llama a next el evento se cancela, lo que supone un resultado muy diferente del que se obtiene cuando el software intermedio omite la lógica.For event handlers, not calling next means that the event is cancelled, which is a significantly different result than middleware skipping logic. Al no procesar el resto del evento, el adaptador no lo envía nunca.By not processing the rest of the event, the adapter never sends it.

Sugerencia

Si provoca un cortocircuito en un evento de respuestas, como SendActivities, asegúrese de que es el comportamiento que tenía previsto.If you do short-circuit a response event, such as SendActivities, be sure it's the behavior you intend. De lo contrario, puede resultar muy difícil solucionar los errores.Otherwise, it can result in difficult to fix bugs.

Controladores de eventos de respuestaResponse event handlers

Además de la lógica de la aplicación y del middleware, se pueden agregar controladores de respuesta (a veces llamados controladores de eventos o controladores de eventos de actividad) al objeto de contexto.In addition to the application and middleware logic, response handlers (also sometimes referred to as event handlers, or activity event handlers) can be added to the context object. Se llama a estos controladores cuando la respuesta asociada se produce en el objeto de contexto actual, antes de ejecutar la respuesta real.These handlers are called when the associated response happens on the current context object, before executing the actual response. Estos controladores son útiles si sabe que querrá hacer algo, ya sea antes o después del evento real, para todas las actividades de ese tipo durante el resto de la respuesta actual.These handlers are useful when you know you'll want to do something, either before or after the actual event, for every activity of that type for the rest of the current response.

Advertencia

Tenga cuidado de no llamar a un método de respuesta de actividad desde su controlador de eventos de respuesta correspondiente, por ejemplo, mediante una llamada al método de actividad de envío desde un controlador de actividad de envío.Be careful to not call an activity response method from within its respective response event handler, for example, calling the send activity method from within an on send activity handler. Si lo hace, puede generar un bucle infinito.Doing so can generate an infinite loop.

Recuerde que cada actividad nueva obtiene un nuevo subproceso en el que se ejecuta.Remember, each new activity gets a new thread to execute on. Cuando se crea el subproceso para procesar la actividad, la lista de controladores de esa actividad se copia en ese subproceso nuevo.When the thread to process the activity is created, the list of handlers for that activity is copied to that new thread. No se ejecutará para ese evento de actividad específico ningún controlador agregado después de ese punto.No handlers added after that point will be executed for that specific activity event. El adaptador administra los controladores registrados en un objeto de contexto de forma muy similar al modo en que administra la canalización de middleware.The handlers registered on a context object are handled very similarly to how the adapter manages the middleware pipeline. Es decir, se llama a los controladores en el orden en que se agregan y al llamar al delegado next se pasa el control al siguiente controlador de eventos registrado.Namely, handlers get called in the order they're added, and calling the next delegate passes control to the next registered event handler. Si un controlador no llama al delegado siguiente, no se llama a ninguno de los controladores de eventos subsiguientes, los circuitos cortos del evento y el adaptador no envía la respuesta al canal.If a handler doesn't call the next delegate, none of the subsequent event handlers are called, the event short circuits, and the adapter does not send the response to the channel.

Control del estado en el middlewareHandling state in middleware

Un método común para guardar el estado es llamar al método para guardar cambios al final del controlador de turnos.A common method to save state is to call the save changes method at the end of the turn handler. Aquí hay un diagrama con una especial atención a la llamada.Here is a diagram with a focus on the call.

problemas de estado de middleware

El problema de este enfoque es que las actualizaciones de estado realizadas desde algún middleware personalizado que se produzca después de que se haya devuelto el controlador de activación del bot no se guardarán en el almacenamiento duradero.The problem with this approach is that any state updates made from some custom middleware that happens after the bot's turn handler has returned will not be saved to durable storage. La solución es mover la llamada al método para guardar cambios a después de que el middleware personalizado se haya completado mediante la adición de una instancia del middleware para guardar cambios automáticamente al principio de la pila de middleware, o al menos antes de que cualquiera del estado del middleware se actualice.The solution is to move the call to the save changes method to after the custom middleware has completed by adding an instance of the auto-save changes middleware to the beginning of the middleware stack, or at least before any of the middleware that might update state. A continuación se muestra la ejecución.The execution is shown below.

solución de estados de middleware

Agregue los objetos de administración de estado que será necesario actualizar a un objeto conjunto de estados del bot y, después, úselos al crear el middleware para guardar cambios automáticamente.Add the state management objects that will need updating to a bot state set object, and then use that when you create your auto-save changes middleware.

Recursos adicionalesAdditional resources

Puede echar un vistazo al middleware del registrador de transcripciones, tal como está implementado en Bot Framework SDK [C# | JS].You can take a look at the transcript logger middleware, as implemented in the Bot Framework SDK [C# | JS].