Registrar un complemento

Después de escribir y compilar un complemento, debe registrarse en el marco de eventos para ejecutarse cuando se procesa una entidad específica (fila de tabla) y un mensaje (operación) Microsoft Dataverse. Para registrar un complemento con Dataverse se requiere el uso de una herramienta, ya sea la herramienta de registro de complementos (PRT) o la extensión Power Platform Herramientas para Visual Studio.

El PRT crea registros de objetos de Dataverse y admite la edición de esos registros. Este artículo describe cómo registrar un ensamblaje de complemento y el procesamiento de mensajes paso, agregar un ensamblaje a una solución y realizar otras operaciones comunes relacionadas con complementos mediante la herramienta Registro de complementos.

La extensión Visual Studio proporciona un entorno de desarrollo con más funciones y cubre todo el proceso de desarrollo de codificación, implementación y depuración/perfilado. Para obtener información sobre el uso de la extensión Power Platform Tools para Visual Studio, consulte el inicio rápido.

Acerca de la herramienta de registro de complementos

La herramienta de registro de complementos (PRT) admite el registro de ensamblajes de complementos, pasos de procesamiento de mensajes y otros tipos de objetos con Dataverse. PRT es una de varias herramientas de Dataverse disponibles para descargar desde NuGet.org. Siga las instrucciones en Herramientas de desarrollo de Dataverse para descargar PRT y, opcionalmente, otras herramientas de desarrollo.

Después de descargar el PRT, siga las instrucciones de Conéctese usando la herramienta de registro de complementos para conectar la herramienta a su entorno objetivo Dataverse donde su complemento se va a registrar.

Registro de ensamblados

Registrar un ensamblado incluye la carga del ensamblado a la base de datos de Dataverse, que gestiona la herramienta. Consulte las instrucciones que se encuentran en Registrar el ensamblado en el Tutorial: Escribir y registrar un complemento

Nota

Encontrará opciones relacionadas con el modo aislado y ubicación para el ensamblado. Estos hacen referencia a opciones que se aplican a implementaciones locales. Dataverse no está disponible para implementaciones locales, por lo que usted siempre aceptará las opciones predeterminadas de Espacio aislado y Base de datos para estas opciones.

Cuando se carga un ensamblado, se almacena en la tabla PluginAssembly. La mayoría de las propiedades se establecen utilizando la reflexión del ensamblado importado. Los bytes codificados en base64 del conjunto se almacenan en la columna Content. Mientras ve las Propiedades del ensamblado en la PRT, solo puede editar Descripción value. Todas las clases compiladas dentro del ensamblado que implementan la interfaz IPlugin o derivan de CodeActivity se registran automáticamente.

Ver ensamblados registrados

Puede acceder a información sobre los ensambles de complementos registrados y los pasos en Power Apps y en la vista de ensamblaje PRT. Para acceder a la información del complemento en Power Apps, seleccione Soluciones en el panel de navegación izquierdo y luego elija una solución disponible de la lista. A continuación, seleccione Ensamblajes de complementos o Pasos de complementos en el panel Objetos izquierdo.

Nota

Cada ensamblado que registre se agregará a la Solución predeterminada, que no debe confundirse con la Solución predeterminada Common Data Services. Para obtener más información acerca de soluciones, vea Introducción a soluciones

Agregar el ensamblado a una solución

Como se describe en Ver ensamblados registrados, el registro de ensamblados que ha creado se agregó a la Solución predeterminada del sistema. Debe agregar el ensamblado a una solución no administrada para poder distribuirla a otras organizaciones. El PRT no permite especificar una solución al registrar un ensamblado o pasos.

Para obtener más información sobre las soluciones y cómo crear una, consulte Información general de las soluciones y Crear una solución. Una vez que haya creado una solución, puede agregarle el ensamblado del complemento en Power Apps si elige primero la solución en la lista de soluciones y luego elige Agregar existente > Más > Desarrollador > Ensamblado de complemento.

Nota

Los registros de pasos existentes o posteriores (vea la siguiente sección) no se agregan a la solución no administrada que incluye los ensamblados de complementos. Debe agregar cada paso registrado a la solución por separado. Más información: Agrega paso a la solución

Registro de pasos

El registro de un procesamiento de mensajes paso informa Dataverse bajo qué condiciones debe ejecutarse su complemento y cómo ejecutarlo. Por condiciones nos referimos a la operación de tabla y mensaje que procesa Dataverse. Se pueden especificar otras opciones de configuración, como ejecución sincrónica o asincrónica, antes o después de la operación principal, y más, durante el registro de paso. Estas opciones de configuración de tiempo de ejecución se detallan en la siguiente sección.

Cuando un ensamblado se carga o actualiza, las clases que implementen IPlugin estarán disponibles en la PRT. Use las instrucciones en Registrar un nuevo paso en el Tutorial: Escribir y registrar un complemento para crear un nuevo registro de paso.

Campos de información de configuración general

Campo	Description
Publicación	El mensaje que al ser procesado por Dataverse da como resultado la ejecución del complemento. Si no se especifica una entidad principal para mensajes principales como Update, Delete, Retrieve y RetrieveMultiple, o cualquier mensaje que se pueda aplicar, el complemento se invocará para todas las entidades que admitan ese mensaje. Más información: Usar mensajes con SDK para .NET
Entidad principal	La entidad (tabla) que, cuando es procesada por Dataverse , da como resultado la ejecución del complemento. Los mensajes tienen un parámetro que acepta un tipo Target o Entity . EntityReference Si se aplican tablas válidas, debe establecer este valor de campo cuando desee limitar la ejecución de su complemento a una entidad específica que se esté procesando.
Entidad secundaria	Este campo se mantiene para la compatibilidad con versiones anteriores para los mensajes obsoletos que aceptaban una matriz de EntityReference como el parámetro Target. Este campo no se suele usar más.
Atributos de filtro	Para el mensaje Update, OnExternalUpdated u otro, cuando se configura la entidad principal, los atributos de filtrado (columnas) limitan la ejecución del complemento a los casos en los que las columnas especificadas se incluyen en la actualización. Establecer este campo esta es una práctica recomendada para rendimiento. No incluya la clave principal de la entidad en los atributos de filtrado. La clave principal siempre se incluye en las operaciones de actualización, por lo que al hacerlo se negarán todos los demás atributos filtrados.
Controlador de eventos	Este valor de campo se completará en el PRT según el nombre del ensamblaje y la clase de complemento.
Nombre del paso	El nombre del procesamiento del mensaje paso. Se indica previamente un valor en función de la configuración del paso, pero este valor puede ser reemplazado.
Ejecutar en contexto de usuario	Proporciona opciones para aplicar suplantación para el paso. El valor predeterminado es Usuario que llama. Si el usuario que llama no tiene privilegios para realizar operaciones en el paso, es posible que necesite configurar este valor de campo como un usuario que tiene estos privilegios. Más información: Establecer la suplantación de identidad del usuario para un paso
Pedido de ejecución	Se pueden registrar varios pasos para la misma etapa y mensaje. El número en este campo determina el orden en que se aplican los pasos dentro de una etapa, del más bajo al más alto. Debe configurar esto para controlar el orden en que se ejecutan los complementos en la misma etapa. No se recomienda para aceptar simplemente el valor predeterminado. El orden de ejecución real de los complementos con el mismo valor de orden de ejecución (para la misma etapa, tabla y mensaje) no está garantizado y puede ser aleatorio.
Description	Una descripción para paso. Este valor se rellena previamente pero puede sobrescribirse.

Fase de canalización de eventos de ejecución

Elija la fase de la canalización de eventos que mejor se adapte al objetivo del complemento. El prefijo "Pre" y "Post" se refiere a antes o después de la operación principal (núcleo). Dataverse La operación principal es la etapa en la que se procesa la combinación de mensaje y entidad.

Opción	Description
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.
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

Más información: Canalización de ejecución de eventos

Modo de ejecución

Hay dos modos de ejecución: asincrónico y sincrónico.

Opción	Description
Asincrónico	El contexto de ejecución y la definición de la lógica empresarial a aplicar se mueven a la cola de trabajos del sistema, que se ejecutará en algún momento después de que se complete la operación principal.
Sincrónico	Los complementos se ejecutan inmediatamente según la fase de ejecución y el orden de ejecución. La operación completa esperará hasta que se complete.

Los complementos asincrónicos solo pueden registrarse para la fase PostOperation. Para obtener más información sobre el funcionamiento de los trabajos del sistema, consulte Servicio asincrónico

Escenarios especiales de registro de pasos

Hay ciertos escenarios en los que la combinación de un registro de pasos y una tabla no es obvia. Este es el resultado de cómo el sistema está diseñado internamente donde hay una relación especial entre tablas u operaciones. La siguiente información identifica estos casos y proporciona una guía de registro de pasos.

• Hay ciertos casos en los que los complementos registrados para el evento Actualizar pueden llamarse dos veces. Más información: Comportamiento de operaciones de actualización especializadas
• Registre un paso de complemento en cuenta o contacto cuando desee manejar cambios de datos en los registros customeraddress, leadaddress, publisheraddress o competitoraddress.

Implementación

Opción	Description
Servidor	El complemento se ejecutará en el servidor de Dataverse.
Desconectado	El complemento se ejecutará en el cliente de Dynamics 365 for Outlook cuando el usuario esté en modo sin conexión.

Establecer datos de configuración

Los campos Configuración insegura y Configuración segura de la PRT le permiten especificar datos de configuración para pasar al complemento para un paso específico.

Nota

Los datos de configuración segura no se incluyen con el registro de pasos cuando exporta una solución.

Puede escribir el complemento para que acepte valores de cadena en el constructor para utilizar estos datos para controlar cómo el complemento debe funcionar para el paso. Más información: Pasar datos de configuración al complemento

Definir imágenes de entidad

Dentro de su complemento, es posible que desee hacer referencia a los valores de propiedad de la tabla principal que no se incluyeron en una operación. Por ejemplo, en una operación Update es posible que desee conocer cuál era un valor antes de que cambiara, pero el contexto de ejecución no proporciona esta información, solo incluye el valor cambiado.

Si su paso de complemento está registrado en las etapas PreValidation o PreOperation de la canalización de ejecución, podría utilizar el servicio Organización para recuperar el valor actual de la propiedad, pero esto no es una buena práctica para el rendimiento. Un ejercicio mejor es definir una imagen previa de la entidad con el registro del paso del ensamblado. Esto capturará una "instantánea" de la tabla con los campos que le interesan tal y como existían antes de la operación, que podrá utilizar para comparar con los valores modificados.

Importante

El comportamiento predeterminado al crear una imagen de entidad es seleccionar todas las columnas. No use este comportamiento predeterminado. Esto podrá afectar negativamente al rendimiento. Solo incluya aquellas columnas que son requeridas por la lógica de su complemento.

Mensajes que admiten imágenes de la entidad

En Dataverse, solo los mensajes siguientes admiten imágenes de la entidad:

Mensaje	Propiedad de clases de solicitud	Descripción
Assign	Target	La tabla asignada.
Create	Target	La tabla creada.
Delete	Target	La tabla eliminada.
DeliverIncoming	EmailId	Identificador de correo electrónico entregado.
DeliverPromote	EmailId	Identificador de correo electrónico entregado.
Merge	Target o SubordinateId	La tabla principal, en la que se fusionan los datos de la tabla secundaria o de la tabla secundaria que se fusiona con la tabla principal.
Route	Target	El elemento que se enruta.
Send	FaxId, EmailId o TemplateId	El elemento que se envía.
SetState	EntityMoniker	La tabla para la que se establece el estado.
Update	Target	La tabla actualizada.

Tipos de imágenes de la entidad

Existen dos tipos de imágenes de la entidad: Imagen previa y Imagen posterior. Cuando se configuran, estas imágenes estarán disponibles en el contexto de ejecución como propiedades PreEntityImages y PostEntityImages respectivamente. Como sugieren los nombres, estas instantáneas representan cómo se ve la tabla antes de la operación principal y después de la operación principal. Cuando configure una imagen de entidad, definirá un valor de alias* de tabla que será el valor clave que utilizará para acceder a una imagen de entidad específica desde las propiedades PreEntityImages o PostEntityImages.

Disponibilidad de imágenes

Cuando configura una imagen de entidad, es importante que reconozca que el tipo de imágenes de entidad disponibles depende de la etapa del paso registrado y el tipo de operación. Por ejemplo:

• No puede tener una Imagen previa para el mensaje de Create porque la tabla todavía no existe.
• No puede tener una Imagen posterior para el mensaje de Delete porque la tabla ya no existirá.
• Solo puede tener una Imagen posterior para los pasos registrados en PostOperation de la canalización de ejecución porque no hay forma de saber cuáles serán las propiedades de la tabla hasta que se complete la transacción.
• Para una operación Update que se registra en la fase PostOperation puede tener una Imagen previa Y una Imagen posterior.

Agregar imagen de la entidad

Use la extensión Power Platform Tools para Visual Studio para agregar una imagen de entidad a un paso de complemento.

Alternativamente, puede usar la herramienta de registro de complementos para agregar una imagen de entidad a un paso siguiendo las instrucciones en Tutorial: actualizar un complemento en la sección Agregar una imagen.

Agregar un paso a una solución

Como se ha indicado en Agregar el ensamblado a una solución, los Ensamblados de complemento son componentes de la solución que se pueden agregar a una solución no administrada. Los Pasos de procesamiento de mensajes de SDK son también componentes de la solución y también se deben agregar a una solución no administrada para distribuir.

El procedimiento para agregar un paso a una solución es similar a agregar un ensamblado. Utilizará el comando Agregar existente para moverlo a la solución no administrada deseada. La única diferencia es que si intenta agregar un paso pero aún no ha agregado el ensamblado que contiene la clase utilizada en el paso, se le pedirá que agregue los componentes necesarios que faltan.

Si encuentra esto, debe seleccionar Aceptar normalmente para llevar el ensamblado con la solución no administrada. La única vez que no seleccionaría esto es si su solución está diseñada para ser instalada en un entorno en el que ya está instalada otra solución que contiene el conjunto.

Del mismo modo, debe tener en cuenta que eliminar el conjunto de la solución no eliminará ningún paso que dependa de él.

Establecer la suplantación de usuario para un paso

Con la herramienta de registro de complementos ejecutándose e iniciando sesión en el entorno de destino Dataverse, puede proceder a establecer o cambiar el registro de un paso de complemento. En esta sección, discutiremos cómo cambiar el usuario en cuyo nombre el complemento realizará sus operaciones. Es decir, el usuario efectivo que realiza las operaciones de datos iniciadas por el complemento. Por defecto, el usuario que llama (el usuario que invocó una operación en Dataverse) es el propietario de dichas operaciones. Sin embargo, se puede especificar un usuario diferente en el registro del paso. Necesitará tener el rol de seguridad de Administrador del sistema o de Personalizador del sistema para realizar esta operación.

Para configurar el contexto del usuario en un paso de complemento:

1. Expanda el nodo de ensamblaje del complemento de destino en la vista de ensamblaje hasta que vea el nodo de registro (Paso) deseado.
2. Elija el nodo de paso y luego elija Actualizar en el menú contextual o en la barra de herramientas.
3. Elija un usuario de la lista desplegable de usuarios disponibles junto a la etiqueta Ejecutar en el contexto del usuario.
4. Elija Paso de actualización.

Más información: Suplantar a un usuario

Actualizar un ensamblado

Cuando cambie y reconstruya un ensamblado que haya registrado previamente, tendrá que actualizarlo. Consulte el paso Actualizar el registro de ensamblado del complementos en el Tutorial: Actualizar un complemento para conocer los pasos.

Versiones de ensamblado

Si va a realizar cambios en un ensamblado de complemento que forma parte de una solución administrada que se ha implementado, debe tener en cuenta el impacto que pueden tener sus cambios cuando actualice esa solución administrada. La versión del ensamblado controlará el comportamiento.

Pueden crearse versiones de los ensamblados del complemento con un formato semántico de control de versiones de major.minor.build.revision definido en el archivo Assembly.info del proyecto de Microsoft Visual Studio. Según la parte del número de versión de ensamblado que se cambie en una solución más reciente, se aplica el siguiente comportamiento cuando se actualiza una solución existente a través de la importación.

• Se modifica el número de versión de compilación o de ensamblado de revisión

  Esto se considera una actualización en contexto. La versión anterior del ensamblado desaparece cuando se importa la solución que contiene el ensamblado actualizado. Los pasos preexistentes de la solución anterior cambian automáticamente para hacer referencia a la versión más reciente del ensamblado.

• Se modifica el número de versión principal o secundaria del ensamblado

  Cuando se importa una solución actualizada que contiene el ensamblado revisado, el ensamblado se considera un conjunto diferente a la versión anterior de ese conjunto en la solución existente. Los pasos de registro de complementos de la solución existente continuarán haciendo referencia a la versión anterior del ensamblado. Si desea que los pasos de registro de complementos existentes para el montaje anterior apunten al ensamblado revisado, tendrá que utilizar la herramienta de registro de complementos para cambiar manualmente la configuración de los pasos para que hagan referencia al tipo de ensamblado revisado. Esto debe hacerse antes de exportar el ensamblado actualizado a una solución para importación posterior.

Anule el registre o deshabilite componentes de complementos

Puede anular el registro o deshabilitar los complementos y sus componentes mediante la herramienta de registro de complementos (PRT).

Importante

Ya no es posible anular el registro o deshabilitar Microsoft o los complementos y pasos del sistema listos para usar. Anteriormente, podía anular el registro o deshabilitar algunos de Microsoft.* y otros complementos del sistema listos para usar. Hemos cambiado este comportamiento para que ya no lo permita. El cambio en la funcionalidad se realizó porque anular el registro o deshabilitar estos complementos o pasos puede hacer que las características del producto no funcionen como se esperaba. Si necesita anular el registro o deshabilitar dicho complemento o paso, presente una solicitud de soporte técnico de Microsoft.

Deshabilitar o habilitar un paso de complemento

Con la herramienta de registro de complementos ejecutándose e iniciando sesión en el entorno de destino Dataverse, puede proceder a deshabilitar o habilitar paso de complemento. Al deshabilitar un paso, se evita que el complemento se ejecute cuando Dataverse procesa la combinación de entidad y mensaje especificada en el registro del paso.

Importante

Deshabilitar un complemento puede afectar negativamente la funcionalidad de su aplicación, una solución o el sistema Dataverse. Asegúrese de comprender las implicaciones antes de continuar.

Para deshabilitar o habilitar un paso de complemento registrado:

1. Expanda el nodo de ensamblaje del complemento de destino en la vista de ensamblaje hasta que vea el nodo de registro de paso deseado.
2. Elija el nodo de paso y luego elija Habilitar o Deshabilitar en el menú contextual o en la barra de herramientas.

También puede deshabilitar o habilitar pasos en la interfaz de usuario del explorador de soluciones de Dataverse heredada mediante las opciones de comandos Activar y Desactivar.

En Power Apps, deshabilite o habilite los pasos del complemento usando las opciones "Desactivar" y "Activar" del paso elegido. Puede acceder a las opciones de paso navegando primero a Soluciones, eligiendo una solución y luego, en el panel izquierdo Objetos, elija Pasos del complemento.

Anular el registro de componentes

PRT proporciona comandos para anular el registro de ensamblados, tipos, pasos e imágenes. Consulte las instrucciones de Anular registro de ensamblado, complemento y paso en el Tutorial: Actualizar un complemento para conocer el procedimiento.

Estas son operaciones de borrado en las tablas PluginAssembly, PluginType, SdkMessageProcessingStep y SdkMessageProcessingStepImage.

También puede eliminar Ensamblados de complementos y Pasos de procesamiento de mensajes de SDK en el explorador de soluciones para lograr los mismos resultados. En la figura siguiente se muestra una solución personalizada llamada Solución predeterminada de Common Data Service.

Nota

No puede eliminar (desregistrar) cualquier Ensamblados de complementos mientras haya Pasos de procesamiento de mensajes de SDK existentes que dependen de ellos. Las imágenes de la entidad no están disponibles para eliminar por separado, pero se eliminarán cuando se eliminen los pasos que los usan.

Pasos siguientes

Depuración de complementos

Consulte también

Escriba complementos para ampliar los procesos de negocio
Escribir un complemento
Tutorial: Escribir y registrar un complemento
Tutorial: Depurar un complemento
Tutorial: Actualizar un complemento

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).