Marco de eventos en Microsoft Dataverse

El marco de eventos de Microsoft Dataverse permite detectar cuándo se producen eventos en el servidor y ejecutar código personalizado en respuesta. Use el marco de eventos para ampliar el comportamiento predeterminado de la plataforma mediante el registro de complementos, flujos de trabajo, integraciones de Azure y webhooks.

Todas las funcionalidades para ampliar el comportamiento predeterminado de la plataforma dependen del marco de eventos. Al configurar un flujo de trabajo para responder a un evento mediante el diseñador de flujo de trabajo sin escribir código, el marco de eventos proporciona ese evento.

Como desarrollador, use la herramienta Registro de complementos para configurar complementos, integraciones de Azure, proveedores de datos de tabla virtual y webhooks para responder a eventos que proporciona el marco de eventos. Cuando se producen eventos y se registra una extensión para responder a ellos, el marco pasa información contextual sobre los datos implicados en la operación a la extensión. Dependiendo de cómo configure el registro para el evento, la extensión puede modificar los datos pasados, iniciar algún proceso automatizado para aplicarlo inmediatamente o definir que se agrega una acción a una cola para realizar más adelante.

Para aprovechar el marco de eventos de las extensiones personalizadas, debe comprender lo siguiente:

• Qué eventos están disponibles
• Cómo se procesa el evento
• ¿qué tipo de datos están disponibles para la extensión personalizada cuando se produce el evento?
• ¿Qué limitaciones de tiempo y recursos se aplican?
• Supervisión del rendimiento

Eventos disponibles

Como se describe en Uso de mensajes con el SDK para .NET, la plataforma Dataverse basa las operaciones de datos en los mensajes y cada mensaje tiene un nombre. La plataforma incluye Create, Retrieve, RetrieveMultiple, Update, Delete, Associate y Disassociate mensajes que cubren las operaciones de datos básicas que se producen con tablas. La plataforma también incluye mensajes especializados para operaciones más complejas y las acciones personalizadas agregan nuevos mensajes.

Cuando se usa la herramienta Registro de complementos para asociar una extensión a un mensaje determinado, se registra como un paso. La captura de pantalla siguiente es el cuadro de diálogo Registrar nuevo paso que se usa al registrar un complemento.

Un paso proporciona la información sobre el mensaje al que deben responder las extensiones, así como otras opciones de configuración. Use el campo Mensaje para elegir el mensaje al que responde la extensión.

Por lo general, puede esperar encontrar un mensaje para la mayoría de las clases Request en los espacios de nombres Microsoft.Crm.Sdk.Messages o Microsoft.Xrm.Sdk.Messages. También encontrará mensajes para las acciones personalizadas que cree en la organización. La plataforma no ofrece ninguna operación que implique definiciones de tabla.

El sistema almacena datos sobre los mensajes en las tablas SdkMessage y SdkMessageFilter . La herramienta de registro del complemento filtra esta información para mostrar solo mensajes válidos.

Para comprobar si una combinación de mensajes y tablas admite la ejecución de complementos mediante una consulta de base de datos, use la siguiente consulta de API web:

[Organization URI]/api/data/v9.2/sdkmessages?$select=name
&$filter=isprivate eq false 
and (name ne 'SetStateDynamicEntity' 
and name ne 'RemoveRelated' 
and name ne 'SetRelated' and 
name ne 'Execute') 
and sdkmessageid_sdkmessagefilter/any(s:s/iscustomprocessingstepallowed eq true 
and s/isvisible eq true)
&$expand=sdkmessageid_sdkmessagefilter($select=primaryobjecttypecode;
$filter=iscustomprocessingstepallowed eq true and isvisible eq true)
&$orderby=name

Sugerencia

Puede exportar estos datos a una hoja de cálculo de Excel mediante esta consulta y las instrucciones proporcionadas en esta entrada de blog: Buscar mensajes y tablas aptos para complementos mediante Dataverse.

También puede usar el siguiente FetchXML para recuperar esta información. FetchXML Builder es una herramienta útil para ejecutar este tipo de consulta.

<fetch>
  <entity name='sdkmessage'>
    <attribute name='name' />
    <link-entity name='sdkmessagefilter'
      alias='filter'
      to='sdkmessageid'
      from='sdkmessageid'
      link-type='inner'>
      <filter type='and'>
        <condition attribute='iscustomprocessingstepallowed' 
          operator='eq' 
          value='1' />
        <condition attribute='isvisible' 
          operator='eq' 
          value='1' />
      </filter>
      <attribute name='primaryobjecttypecode' />
    </link-entity>
    <filter>
      <condition attribute='isprivate' 
        operator='eq' 
        value='0' />
      <condition attribute='name' 
        operator='not-in'>
        <value>SetStateDynamicEntity</value>
        <value>RemoveRelated</value>
        <value>SetRelated</value>
        <value>Execute</value>
      </condition>
    </filter>
    <order attribute='name' />
  </entity>
</fetch>

Precaución

El Execute mensaje está disponible, pero no deberías registrar extensiones, ya que cada operación lo llama.

Nota:

En determinados casos, la plataforma puede llamar dos veces a los complementos y flujos de trabajo que registre para el evento de actualización. Para obtener más información, consulte Comportamiento de las operaciones de actualización especializadas.

Canalización de ejecución de eventos

Al registrar un paso mediante la herramienta de registro de complementos, también debe elegir la etapa de ejecución de la canalización de eventos. Cada mensaje se procesa en una serie de cuatro fases, como se describe en la tabla siguiente:

Nombre	Description
Prevalidación	Para la operación inicial, esta fase se producirá antes de la operación del sistema principal. Esto proporciona la oportunidad de incluir lógica para cancelar la operación antes de la transacción de la base de datos. Las operaciones posteriores desencadenadas por extensiones registradas en otras fases también pasarán a través de esta fase, pero también se incluirán dentro de la transacción de las extensiones de llamada. Esta fase se produce antes de que las comprobaciones de seguridad estén preformadas para comprobar que el usuario que realiza la llamada o que ha iniciado sesión tiene el permiso correcto para realizar la operación prevista.
PreOperation	Se produce antes de la operación principal del sistema y dentro de la transacción de base de datos. Si desea cambiar los valores de una entidad incluida en el mensaje, debe hacerlo aquí. Evite cancelar una operación aquí. La cancelación desencadenará una reversión de la transacción y tendrá un impacto significativo en el rendimiento.
OperaciónPrincipal	Para uso interno únicamente, excepto para los proveedores de datos de tablas virtuales personalizadas y las API personalizadas. Más información: Crear y usar API personalizadas Proveedores de datos de tabla virtual personalizados
PostOperation	Se produce después de la operación principal del sistema y dentro de la transacción de base de datos. Use esta fase para modificar las propiedades del mensaje antes de que se devuelva al autor de la llamada. Evite aplicar cambios a una entidad incluida en el mensaje porque desencadenará un nuevo evento Update. En la fase PostOperation puede registrar los pasos para usar el modo de ejecución asincrónica. Estos pasos se ejecutarán fuera de la transacción de base de datos mediante el servicio asincrónico. Debe usar el modo asincrónico al registrar su complemento si está diseñado para realizar una operación de actualización y se registra en el mensaje de Creación de la entidad User (SystemUser). Más información: Servicio asincrónico.

La fase que elija depende del propósito de la extensión. No es necesario aplicar toda la lógica de negocios en un solo paso. Puede aplicar varios pasos para que la lógica sobre si se permite que una operación continúe puede estar en la fase PreValidation y la lógica para realizar modificaciones en las propiedades del mensaje puede producirse en la fase PostOperation .

Importante

Una excepción lanzada por tu código en cualquier etapa sincrónica dentro de la transacción de base de datos hace que se revierta toda la transacción. Asegúrese de que el código controla los posibles casos de excepción. Si desea cancelar la operación, detecte esta condición en la fase PreValidation y genere un InvalidPluginExecutionException mensaje que contenga un mensaje adecuado que describa por qué se canceló la operación.

Puede registrar varias extensiones para el mismo mensaje y fase. Dentro del registro de pasos, el valor orden de ejecución determina el orden en el que el sistema procesa varias extensiones para una fase determinada.

El sistema almacena información sobre los pasos registrados en la tabla SdkMessageProcessingStep.

Pasos del complemento asincrónico

Al registrarse en la fase PostOperation , puede registrar el paso para ejecutarse en modo de ejecución asincrónica. Estos complementos se ejecutan una vez completada la operación de registro.

Este comportamiento suele ser necesario al trabajar con registros asociados al registro actual, pero creados en un proceso diferente. Por ejemplo, UserSettings relacionado con un registro específico SystemUser no se crea hasta que se crea la fila SystemUser.

Más información: Servicio asincrónico

Contexto de evento

Si la extensión es un complemento, recibe un parámetro que implementa la IPluginExecutionContext interfaz. Esta clase proporciona información sobre el Stage para el cual se registra el complemento. También proporciona información sobre el ParentContext, que proporciona detalles sobre cualquier operación dentro de otro complemento que desencadenó la operación actual.

Si la extensión es un punto de conexión de Azure Service Bus, un tema de Azure Event Hubs o un webhook, los datos se publican en el punto de conexión registrado en forma de RemoteExecutionContext. Esta clase implementa tanto IPluginExecutionContext como IExecutionContext.

Para obtener más información sobre el contexto de ejecución, consulte Descripción del contexto de ejecución.