Microsoft Dynamics CRM: complementos

Un complemento es una lógica empresarial personalizada que se integra con Microsoft Dynamics CRM para modificar o ampliar el comportamiento estándar de la plataforma. Los complementos actúan como controladores de eventos y se registran para ejecutarse en un evento particular en CRM. Los complementos están escritos en C # o VB y pueden ejecutarse en modo síncrono o asíncrono.

Algunos escenarios en los que escribirías un complemento son:

  • Desea ejecutar alguna lógica empresarial, como actualizar ciertos campos de un registro o actualizar registros relacionados, etc. cuando crea o actualiza un registro CRM.

  • Desea llamar a un servicio web externo sobre ciertos eventos, como guardar o actualizar un registro.

  • Desea calcular dinámicamente los valores de campo cuando se abre cualquier registro.

  • Quiere automatizar procesos como el envío de correos electrónicos a sus clientes sobre determinados eventos en CRM.

Marco de eventos

El marco de procesamiento de eventos en CRM procesa las solicitudes de complementos síncronos y asincrónicos pasándolos al canal de ejecución de eventos. Siempre que un evento desencadena una lógica de complemento, se envía un mensaje al Servicio web de la organización de CRM, donde otros complementos o cualquier operación principal de la plataforma pueden leerlo o modificarlo.

Etapas de canalización de complementos

Toda la canalización de complementos se divide en varias etapas en las que puede registrar su lógica empresarial personalizada. La etapa de canalización especificada indica en qué etapa del ciclo de ejecución del complemento se ejecuta el código del complemento. De todas las etapas de canalización especificadas en la siguiente tabla, puede registrar sus complementos personalizados solo en eventos previos y posteriores. No puede registrar complementos en las operaciones principales de Platform Core.

Evento Nombre artístico Descripción
Pre-evento Prevalidación Etapa en la tubería para complementos que se ejecutarán antes de la operación del sistema principal. Los complementos registrados en esta etapa pueden ejecutarse fuera de la transacción de la base de datos.
Pre-evento Preoperación Etapa en la tubería para complementos que se ejecutarán antes de la operación del sistema principal. Los complementos registrados en esta etapa se ejecutan dentro de la transacción de la base de datos.
Operación del núcleo de la plataforma MainOperation Intransacción, la operación principal del sistema, como crear, actualizar, eliminar, etc. No se pueden registrar complementos personalizados en esta etapa. Sólo para uso interno.
Posterior al evento Post operacion Etapa en el pipeline para complementos que se ejecutarán después de la operación principal. Los complementos registrados en esta etapa se ejecutan dentro de la transacción de la base de datos.

Siempre que la aplicación CRM invoca un evento (como guardar o actualizar un registro), se lleva a cabo la siguiente secuencia de acciones:

  • El evento desencadena una llamada de servicio web y la ejecución pasa a través de las etapas de la canalización del evento (pre-evento, operaciones centrales de la plataforma, post-evento).

  • La información se empaqueta internamente como un mensaje de OrganizationRequest y finalmente se envía a los métodos internos del servicio web CRM y las operaciones centrales de la plataforma.

  • El mensaje OrganizationRequest lo reciben primero los complementos previos al evento, que pueden modificar la información antes de pasarla a las operaciones principales de la plataforma. Después de las operaciones centrales de la plataforma, el mensaje se empaqueta como OrganizationResponse y se pasa a los complementos posteriores a la operación. Los complementos de posoperaciones pueden modificar opcionalmente esta información antes de pasarla al complemento asíncrono.

  • Los complementos reciben esta información en forma de objeto de contexto que se pasa al método Execute, después de lo cual ocurre el procesamiento posterior.

  • Una vez que se completa todo el procesamiento del complemento, la ejecución se devuelve a la aplicación que desencadenó el evento.

Mensajes de complementos

Los mensajes son los eventos en los que se registra el complemento (o la lógica empresarial). Por ejemplo, puede registrar un complemento en la entidad Crear mensaje de contacto. Esto activaría la lógica empresarial cada vez que se crea un nuevo registro de contacto.

Para las entidades personalizadas, a continuación se muestran los mensajes admitidos en función de si la entidad es propiedad del usuario o de la organización.

Nombre del mensaje Tipo de Propiedad
Asignar Solo entidades de propiedad del usuario
Crear Entidades propiedad del usuario y propiedad de la organización
Eliminar Entidades propiedad del usuario y propiedad de la organización
Autorizará el acceso Solo entidades de propiedad del usuario
ModifyAccess Solo entidades de propiedad del usuario
Recuperar Entidades propiedad del usuario y propiedad de la organización
Recuperar múltiples Entidades propiedad del usuario y propiedad de la organización
RetrievePrincipalAccess Solo entidades de propiedad del usuario
RetrieveSharedPrincipalsAndAccess Solo entidades de propiedad del usuario
Revocar el acceso Solo entidades de propiedad del usuario
SetState Entidades propiedad del usuario y propiedad de la organización
SetStateDynamicEntity Entidades propiedad del usuario y propiedad de la organización
Actualizar Entidades propiedad del usuario y propiedad de la organización

Para las entidades predeterminadas listas para usar, hay más de 100 mensajes compatibles. Algunos de estos mensajes son aplicables a todas las entidades, mientras que algunos de ellos son específicos de determinadas entidades. Puede encontrar la lista completa de mensajes admitidos en un archivo de Excel dentro del SDK:SDK\Message-entity support for plug-ins.xlsx

Complemento de escritura

En esta sección, aprenderemos los conceptos básicos para escribir un complemento. Crearemos un complemento de muestra que crea una actividad de Tarea para hacer un seguimiento con el cliente cada vez que se agrega un nuevo cliente al sistema, es decir, cada vez que se crea un nuevo registro de contacto en CRM.

En primer lugar, debe incluir las referencias a Microsoft.Xrm.Sdkespacio de nombres. El SDK de CRM contiene todos los ensamblados de SDK necesarios. Suponiendo que ya ha descargado e instalado el SDK en el Capítulo 2, abra Visual Studio. Cree un nuevo proyecto de tipo Biblioteca de clases. Puede nombrar el proyecto como SamplePlugins y hacer clic en Aceptar.

Agregue la referencia de Microsoft.Xrm.Sdkmontaje a su proyecto. La asamblea está presente enSDK/Bin.

Ahora, crea una clase llamada PostCreateContact.cs y extender la clase desde IPlugin. Hasta ahora, su código tendrá un aspecto similar al siguiente.

También deberá agregar una referencia a System.Runtime.Serialization. Una vez que haya agregado las referencias requeridas, copie el siguiente código dentro delPostCreateContact clase.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Microsoft.Xrm.Sdk;

namespace SamplePlugins {
   public class PostCreateContact:IPlugin {
      /// A plug-in that creates a follow-up task activity when a new account is created.
      /// Register this plug-in on the Create message, account entity,
      /// and asynchronous mode.

      public void Execute(IServiceProviderserviceProvider) {
         // Obtain the execution context from the service provider.
         IPluginExecutionContext context =(IPluginExecutionContext)
            serviceProvider.GetService(typeof(IPluginExecutionContext));

         // The InputParameters collection contains all the data
            passed in the message request.

         if(context.InputParameters.Contains("Target")&&
            context.InputParameters["Target"]isEntity) {
            
            // Obtain the target entity from the input parameters.
            Entity entity = (Entity)context.InputParameters["Target"];
            try {
               
               // Create a task activity to follow up with the account customer in 7 days
               Entity followup = new Entity("task");
               followup["subject"] = "Send e-mail to the new customer.";
               followup["description"] =
                  "Follow up with the customer. Check if there are any new issues
                  that need resolution.";
               
               followup["scheduledstart"] = DateTime.Now;
               followup["scheduledend"] = DateTime.Now.AddDays(2);
               followup["category"] = context.PrimaryEntityName;

               // Refer to the contact in the task activity.
               if(context.OutputParameters.Contains("id")) {
                  Guid regardingobjectid = new Guid(context.OutputParameter
                     s["id"].ToString());
                  string regardingobjectidType = "contact";
                  followup["regardingobjectid"] = 
                     new EntityReference(rega rdingobjectidType,regardingobjectid);
               }
               
               // Obtain the organization service reference.
               IOrganizationServiceFactory serviceFactory =
                  (IOrganizationSer viceFactory)serviceProvider.GetService
                  (typeof(IOrganizationServiceFactory));
               IOrganizationService service = 
                  serviceFactory.CreateOrganizationService(context.UserId);

               // Create the followup activity
               service.Create(followup);
            } catch(Exception ex) {
               throw new InvalidPluginExecutionException(ex.Message);
            }
         }
      }
   }
}

A continuación se muestra una explicación paso a paso de lo que hace este código:

Step 1- Implementa el método Execute tomando el objeto IServiceProvider como parámetro. El proveedor de servicios contiene referencias a muchos objetos útiles que utilizará dentro del complemento.

Step 2 - Obtiene el objeto IPluginExecutionContext utilizando el método GetService de IServiceProvider.

Step 3- Obtiene el objeto de la entidad de destino de la colección InputParameters del objeto de contexto. Este objeto de clase de entidad se refiere al registro de la entidad de contacto en el que se registraría nuestro complemento.

Step 4- A continuación, crea un objeto de entidad de Tarea y establece el tema, la descripción, las fechas, la categoría y el objeto correspondiente. El respectingobjectid indica para qué registro de contacto se está creando este registro de actividad. Puede ver que el código obtiene la identificación del registro de contacto principal usando context.OutputParameters y lo asocia con el registro de entidad de tarea que ha creado.

Step 5 - Crea el objeto de IOrganizationServiceFactory usando el objeto IServiceProvider.

Step 6 - Crea un objeto de IOrganizationService utilizando el objeto IOrganizationServiceFactory.

Step 7- Finalmente, usando el método Create de este objeto de servicio. Crea la actividad de seguimiento que se guarda en CRM.

Firma del ensamblado del complemento

Esta sección es aplicable solo si está registrando su ensamblaje de complementos por primera vez. Debe iniciar sesión en el ensamblado con una clave para poder implementar el complemento. Haga clic con el botón derecho en la solución y haga clic en Propiedades.

Seleccione la pestaña Firma de las opciones de la izquierda y marque la opción 'Firmar el ensamblaje'. Luego, seleccione Nuevo en la opción Elija un archivo de clave de nombre seguro.

Introduzca el nombre del archivo de clave como complementos de muestra (puede ser cualquier otro nombre que desee). Desmarque la opción Proteger mi archivo de claves con una contraseña y haga clic en Aceptar. Clic en Guardar.

Finalmente, construya la solución. Haga clic derecho → Construir. La construcción de la solución generará una DLL de ensamblaje, que usaremos en el próximo capítulo para registrar este complemento.

Manejo de excepciones en el complemento

La mayoría de las veces, la lógica de su complemento deberá manejar las excepciones en tiempo de ejecución. Para complementos síncronos, puede devolver unInvalidPluginExecutionExceptionexcepción, que mostrará un cuadro de diálogo de error al usuario. El cuadro de diálogo de error contendrá el mensaje de error personalizado que se pasa al objeto Mensaje del objeto de excepción.

Si observa nuestro código, estamos lanzando la excepción InvalidPluginExecutionException en nuestro bloque de captura.

throw new InvalidPluginExecutionException(ex.Message);

Conclusión

Los complementos son definitivamente cruciales para cualquier implementación CRM personalizada. En este capítulo, nos enfocamos en comprender el modelo de marco de eventos, las etapas de la canalización, los mensajes y escribir un complemento de muestra. En el próximo capítulo, registraremos este complemento en CRM y lo veremos funcionando de un extremo a otro.