Marco de trabajo de eventos

La capacidad de ampliar el comportamiento predeterminado de Microsoft Dataverse depende de detectar cuándo se producen eventos en el servidor. El marco de trabajo de eventos proporciona la capacidad de registrar el código personalizado para que se ejecute en respuesta a eventos específicos.

Todas las funcionalidades de ampliar el comportamiento predeterminado de la plataforma dependen del marco de trabajo de eventos. Cuando se configura un flujo de trabajo para responder a un evento usando el diseñador de flujo de trabajo sin necesidad de escribir código, el evento lo proporciona el marco de trabajo de eventos.

Como desarrollador, usará la herramienta de registro de complementos para configurar los complementos, las integraciones con Azure, los proveedores de datos de tabla virtual y los webhooks para responder a los eventos proporcionados por el marco de trabajo de eventos. Cuando se producen eventos y una extensión se registra para dar respuesta a los anteriores, la información contextual sobre los datos que intervengan en la operación se pasa a la extensión. Según como se configure el registro del evento, la extensión puede modificar los datos que se pasan, iniciar algún proceso automatizado que se aplicará inmediatamente o definir que una acción se agrega a una cola que se vaya a desarrollar más adelante.

Para aprovechar el marco de trabajo de eventos para las extensiones personalizadas debe conocer lo siguiente:

• Qué eventos están disponibles
• Cómo se procesa el evento
• Qué tipo de datos está disponible para la extensión personalizada cuando el evento se produce
• Qué limitaciones de tiempo y recursos existen
• Cómo supervisar el rendimiento

Eventos disponibles

Como se describe en Uso de mensajes con SDK para .NET, las operaciones de datos en la plataforma de Dataverse se basan en los mensajes y cada mensaje tiene un nombre. Hay mensajes , Create, Retrieve, RetrieveMultiple, Update, Delete, Associate y Disassociate que satisfacen las operaciones de datos principales que se producen con las tablas. También hay mensajes especializados para operaciones más complejas y las acciones personalizadas agregan nuevos mensajes.

Cuando se usa la herramienta de registro de complementos para asociar una extensión con un mensaje en particular, lo registrará como paso. La captura de pantalla siguiente es el cuadro de diálogo Registrar nuevo paso utilizado al registrar un complemento.

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

Normalmente, se 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, pero también encontrará mensajes para cualquier acción personalizada que se haya creado en la organización. Las operaciones que conlleven definiciones de tabla no están disponibles.

Los datos sobre mensajes se almacenan en las tablas SdkMessage y SdkMessageFilter. La herramienta de registro de complementos filtrará esta información para mostrar solo los mensajes válidos.

Para comprobar si un mensaje y una combinación de tablas admiten la ejecución de complementos utilizando una consulta de base de datos, puede usar la consulta de la API web siguiente:

[Organization URI]/api/data/v9.1/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 usando esta consulta y las instrucciones proporcionadas en esta entrada de blog: Encontrar mensajes y tablas elegibles para complementos mediante Dataverse

También puede utilizar lo siguiente FetchXML para recuperar esta información. El FetchXML Constructor es una herramienta útil para ejecutar este tipo de consultas.

<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 mensaje Execute está disponible, pero no debe registrar las extensiones ya que lo llaman todas las operaciones.

Nota

Existen algunos casos donde los complementos y los flujos de trabajo que se registran para el evento de actualizar se pueden llamar dos veces. Más información: Comportamiento de operaciones de actualización especializadas

Canalización de ejecución del evento

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

Nombre	Descripción
Prevalidación	Para la operación inicial, esta fase se producirá antes de la operación del sistema principal. Esto brinda una oportunidad para 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 pasarán esta fase, pero se incluirán en la transacción de las extensiones de llamada. Esta fase tiene lugar antes de las comprobaciones de seguridad que se realizan para comprobar que el usuario que hace la llamada o que ha iniciado sesión tiene el permiso adecuado para realizar la operación prevista.
PreOperation	Se produce antes de la operación del sistema principal y dentro de la transacción de la base de datos. Si desea cambiar cualquier valor 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á una impacto importante en el rendimiento.
MainOperation	Solo para uso interno, excepto para proveedores de datos de API personalizadas y de tablas virtuales personalizadas. Más información: Crear y usar API personalizadas Proveedores de datos de tablas virtuales personalizadas
PostOperation	Se produce después de la operación del sistema principal y dentro de la transacción de la base de datos. Use esta fase para modificar cualquier propiedad del mensaje antes de que se devuelva al autor de la llamada. Evite aplicar cambios en una entidad incluida en el mensaje, porque esto desencadenará a un nuevo evento Actualizar. Dentro de la fase PostOperation puede registrar pasos que han usar el modo de ejecución asincrónico. Estos pasos se ejecutarán fuera de la transacción de la base de datos mediante el servicio asincrónico. Debe usar el modo asincrónico al registrar su complemento si el complemento está diseñado para realizar una operación de actualización y está registrado en el mensaje Create de la entidad Usuario (SystemUser). Más información: Servicio asincrónico

La fase que debe elegir depende del propósito de la extensión. No es necesario aplicar toda la lógica empresarial en un solo paso. Puede aplicar múltiples pasos para que la lógica sobre si permite que una operación continúe esté en la fase PreValidation y que la lógica para modificar las propiedades del mensaje puede se produzca en la fase PostOperation.

Importante

Una excepción que produzca el código en alguna fase síncrona dentro de la transacción de base de datos hará que la transacción completa que se revierta. Debe asegurarse de que los posibles casos de excepción los gestiona el código. Si desea cancelar la operación, debe detectar esto en la fase PreValidation y solo lanzar una InvalidPluginExecutionException que contenga un mensaje adecuado que explique por qué la operación se ha cancelado.

Se pueden registrarse múltiples extensiones para el mismo mensaje y la fase. En el registro del paso el valor de Orden de ejecución determina el orden en el que las diversas extensiones deben procesarse para una fase determinada.

La información sobre los pasos registrados se almacena en la tabla SdkMessageProcessingStep.

Pasos del complemento asincrónico

Al registrarse para la fase PostOperation, tiene la opción de registrar el paso para ejecutar en Modo de ejecución asincrónico. Estos complementos se ejecutarán después de que se complete la operación de grabación.

Esto suele ser necesario cuando se trabaja con registros asociados con el registro actual pero creados en un proceso diferente. Por ejemplo, UserSettings relacionado con un SystemUser no se creará hasta que se cree la fila SystemUser.

Más información: Servicio asincrónico

Contexto del evento

Si la extensión es un complemento, recibirá un parámetro que implementa la interfaz IPluginExecutionContext. Esta clase proporciona información sobre la Stage para el que está registrado el complemento, así como información sobre el ParentContext que proporciona información sobre cualquier operación en otro complemento que activó la operación actual.

Si la extensión es un extremo de bus de Azure Service, tema de Azure EventHub o un webhook,los datos que se enviarán al extremo registrado estarán en el formulario de un RemoteExecutionContext que implementa ambos IPluginExecutionContext y IExecutionContext

Para obtener más información sobre el contexto de ejecución, lea Conocer el contexto de ejecución.

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).