2.4 Registro del Plugin con Plugin Registration Tool

Tienes tu DLL compilado y firmado. Ahora necesitas registrarlo en Dataverse para que el sistema sepa cuándo ejecutar tu código. El Plugin Registration Tool es la herramienta oficial de Microsoft para esta tarea, y dominarla es esencial para cualquier desarrollador de plugins.

Objetivos de aprendizaje

• Conectar Plugin Registration Tool a tu entorno de Dataverse
• Registrar assemblies y configurar steps correctamente
• Entender las opciones de aislamiento y ubicación
• Configurar imágenes y filtering attributes

Abriendo el Plugin Registration Tool

Hay varias formas de acceder a la herramienta:

# Forma más simple: via Power Platform CLI
pac tool prt

# Alternativa: ejecutar directamente si lo tienes descargado
PluginRegistration.exe

El comando pac tool prt descarga la herramienta si no la tienes y la abre automáticamente. Es la forma más conveniente porque siempre obtienes la última versión.

Conectando al entorno

La primera vez que abres PRT, necesitas crear una conexión:

1. File → Create New Connection
2. Display Name: ponle un nombre descriptivo como "Desarrollo Contoso"
3. Deployment Type: selecciona "Microsoft 365" para entornos en la nube
4. Region: normalmente "Don't know" funciona bien, el sistema detecta la región
5. User Name: tu email de Microsoft 365 o Azure AD
6. Login: completar la autenticación OAuth

Una vez conectado, verás una lista de entornos a los que tienes acceso. Selecciona el entorno donde quieres registrar plugins y continúa.

Registrando el assembly

Con la conexión establecida, el siguiente paso es registrar tu DLL:

1. En la barra de herramientas, click en "Register" → "Register New Assembly"
2. Click en el botón "..." para buscar tu archivo DLL
3. PRT analiza el DLL y muestra las clases que implementan IPlugin

Opciones de ubicación y aislamiento

Estas opciones determinan dónde y cómo se ejecuta tu código:

Location (ubicación):

• Database: El assembly se almacena en la base de datos de Dataverse. Es la única opción para Dynamics 365 Online.
• Disk: Solo disponible para instalaciones on-premises. El DLL se guarda en el servidor.
• GAC: Global Assembly Cache, también solo para on-premises.

Isolation Mode (aislamiento):

• Sandbox: El plugin se ejecuta en un entorno aislado con restricciones de seguridad. Es obligatorio para Dynamics 365 Online y recomendado para on-premises.
• None: Sin aislamiento, solo para on-premises. Acceso completo al servidor.

Para Dynamics 365 Online, siempre usarás Database + Sandbox. No hay alternativa.

Configurando Steps

El assembly se registró, pero aún no hace nada. Necesitas crear Steps que le digan al sistema cuándo ejecutar cada clase de plugin.

1. Expande tu assembly en el árbol
2. Click derecho en la clase del plugin que quieres configurar
3. Selecciona "Register New Step"

Campos principales del Step

Message: El evento que dispara el plugin. Los más comunes son Create, Update, Delete, Retrieve, RetrieveMultiple.

Primary Entity: La tabla sobre la que aplica. Escribes el nombre lógico, como "account" o "contact". Si lo dejas vacío, el plugin se ejecuta para cualquier entidad que soporte ese mensaje.

Event Pipeline Stage of Execution:

• Pre-validation (10): Antes de validaciones del sistema, fuera de la transacción principal
• Pre-operation (20): Después de validaciones, dentro de la transacción, antes del guardado
• Post-operation (40): Después del guardado, dentro de la transacción

Execution Mode:

• Synchronous: El usuario espera a que termine. Ideal para validaciones y modificaciones de datos.
• Asynchronous: Se ejecuta en segundo plano. Perfecto para operaciones lentas como envío de emails o integraciones.

Execution Order: Si hay múltiples plugins para el mismo mensaje/entidad/stage, este número determina el orden. Los números más bajos se ejecutan primero.

Filtering Attributes

Para Steps en el mensaje Update, los Filtering Attributes son críticos para el rendimiento. Si no los configuras, tu plugin se ejecuta en CUALQUIER actualización de la entidad, aunque los campos que te interesan no hayan cambiado.

Filtering Attributes: creditlimit,customertypecode,primarycontactid

Con esta configuración, el plugin solo se dispara si al menos uno de esos campos cambió. Actualizaciones al teléfono o dirección no ejecutarán tu plugin innecesariamente.

Configurando Entity Images

Las Entity Images capturan el estado del registro en diferentes momentos:

1. Click derecho en un Step existente
2. Selecciona "Register New Image"

Image Type: Pre Image captura el estado antes de la operación, Post Image el estado después.

Name y Entity Alias: Nombres para acceder a la imagen desde el código. Por convención, uso "PreImage" y "PostImage".

Parameters: Los campos específicos que quieres capturar. No captures todo el registro, solo lo que necesitas.

Actualizando el assembly

Has corregido un bug o añadido funcionalidad. Necesitas actualizar el DLL sin perder la configuración de Steps e Images:

1. Click derecho en tu assembly en el árbol
2. Selecciona "Update"
3. Navega al nuevo DLL compilado
4. Click en "Update Selected Plugins"

Este proceso preserva todos los Steps e Images existentes. Solo reemplaza el código del assembly. Es la forma correcta de actualizar un plugin desplegado.

Puntos clave

• Usa pac tool prt para abrir el Plugin Registration Tool
• Para Dynamics 365 Online: siempre Database + Sandbox
• Configura Message, Entity, Stage y Mode en cada Step
• Filtering Attributes son esenciales para plugins de Update
• Actualiza el assembly (no elimines y re-registres) para preservar configuración

Para profundizar

• Registrar plugins - Microsoft Learn