Tutorial: Escribir y registrar un complemento

Este tutorial le guiará a través de la escritura de un complemento y su registro en Microsoft Dataverse. Primero debe leer el artículo Escribir un complemento para familiarizarse con la escritura de un complemento.

Puede encontrar los archivos de la solución del complemento para este tutorial aquí: Ejemplo: Crear un complemento básico.

Objetivo

Crear un complemento asincrónico registrado en el mensaje "Crear" de la tabla de cuenta. El complemento crea una actividad de tarea que recuerda al creador de la cuenta que haga un seguimiento una semana después.

Requisitos previos

• Una cuenta de Usuario del sistema con el rol de Administrador o Personalizador del sistema en el entorno de Microsoft Dataverse de destino.
• Una aplicación basada en modelos que incluye las tablas Cuenta y Tarea.
  • Si no dispone de una aplicación basada en modelos que incluya estas tablas, consulte Crear la primera aplicación basada en modelos desde cero para conocer los pasos para crear una en unos minutos.
• Visual Studio 2019 (o posteriores).
• Conocimientos del lenguaje de programación Visual C#.
• Herramienta de registro de complementos instalada en el equipo de desarrollo. Consulte Herramientas de desarrollo de Dataverse.

Crear un proyecto de complemento

Este artículo demuestra el uso de Visual Studio para escribir el complemento y compilar el ensamblado. Sin embargo, puede usar su editor favorito para codificar y usar MSBuild para compilar el ensamblado. En cualquier caso, debe utilizar la herramienta Registro de complementos para registrar el complemento con Dataverse.

Alternativamente, puede usar Power Platform CLI para crear rápidamente un nuevo proyecto con código de complemento repetitivo usando el comando pac plugin init. Seguiría usando la herramienta Registro de complementos para registrar el complemento con Dataverse.

Otra alternativa es usar la extensión de Power Platform Tools como se describe aquí: Crear y registrar un paquete de complemento usando Visual Studio. En este caso, la extensión puede crear y registrar el complemento, por lo que no se necesita la herramienta de registro de complementos.

Crear un proyecto en Visual Studio para el complemento

1. En Visual Studio, abra un nuevo proyecto biblioteca de clases (.NET Framework) destinado a una versión de marco compatible.

   

   El nombre utilizado para el proyecto también es el nombre del ensamblaje. Este tutorial usa el nombre BasicPlugin.

2. En el Explorador de soluciones haga clic con el botón secundario en el proyecto y seleccione Administrar paquetes de NuGet... en el menú contextual.

   

3. Seleccione Buscar y busque Microsoft.CrmSdk.CoreAssemblies e instale la versión más reciente.

   

4. Debe seleccionar Acepto en el diálogo Aceptación de licencia.

   Nota

   Al agregar el paquete NuGet Microsoft.CrmSdk.CoreAssemblies, estos ensamblados se incluirán en la carpeta de compilación de su ensamblado, pero no cargará estos ensamblados junto con el ensamblado que incluye la lógica. Estos ensamblados ya están presentes en el entorno de ejecución aislado.

   Asegúrese de que solo los ensamblados a los que hace referencia directamente el proyecto o a través de cadenas de dependencias de NuGet se encuentran en la carpeta de compilación. No puede incluir otros ensamblados cuando registra el ensamblado en su lógica. No puede suponer que los ensamblajes distintos de los incluidos en el paquete Microsoft.CrmSdk.CoreAssemblies NuGet estarán presentes en el servidor y serán compatibles con su código.

5. En Explorador de soluciones, haga clic con el botón secundario en el archivo Class1.cs y seleccione Cambiar nombre en el menú contextual.

   

6. Cambiar el nombre del archivo Class1.cs a FollowupPlugin.cs.

7. Cuando se solicite, permita que Visual Studio cambie el nombre de la clase para que coincida con el nombre de archivo.

   

Edite el archivo de clase para definir un complemento

1. Agregue las instrucciones using siguientes a la parte superior del archivo FollowupPlugin.cs.

   using System.ServiceModel;  
   using Microsoft.Xrm.Sdk;
   

2. Implementar la interfaz IPlugin editando la clase.

   Nota

   Si sólo escribe : IPlugin después del nombre de clase, Visual Studio sugerirá automáticamente la implementación de un stub para el método Execute.

   public class FollowupPlugin : IPlugin
   {
       public void Execute(IServiceProvider serviceProvider)
       {
           throw new NotImplementedException();
       }
   }
   

3. Reemplace el contenido del método Execute con el siguiente código.

// Obtain the tracing service
ITracingService tracingService =
(ITracingService)serviceProvider.GetService(typeof(ITracingService));

// 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"] is Entity)
{
    // Obtain the target entity from the input parameters.  
    Entity entity = (Entity)context.InputParameters["Target"];

    // Obtain the IOrganizationService instance which you will need for  
    // web service calls.  
    IOrganizationServiceFactory serviceFactory =
        (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
    IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

    try
    {
        // Plug-in business logic goes here.  
    }

    catch (FaultException<OrganizationServiceFault> ex)
    {
        throw new InvalidPluginExecutionException("An error occurred in FollowUpPlugin.", ex);
    }

    catch (Exception ex)
    {
        tracingService.Trace("FollowUpPlugin: {0}", ex.ToString());
        throw;
    }
}

Acerca del código

• El ITracingService permite escribir en el registro de seguimiento. Puede ver un ejemplo en el bloque catch final. Más información: Usar seguimiento
• El IPluginExecutionContext proporciona el acceso al contexto del evento que ejecutó el complemento. Más información: Entender el contexto de ejecución.
• El código comprueba que el contexto InputParameters incluya los parámetros esperados para la CreateRequest para la que se registrará este complemento. Si la propiedad Target está presente, la Entity que se pasó a la solicitud estará disponible.
• La interfaz IOrganizationServiceFactory proporciona acceso a una variable de servicio que implementa la interfaz IOrganizationService que proporciona los métodos que usted usará para interactuar con el servicio para crear la tarea.

Añadir lógica empresarial

El complemento crea una tarea que recuerda al creador de la cuenta que haga un seguimiento una semana después.

Agregue el siguiente código al bloque de prueba. Reemplace el comentario // Plug-in business logic goes here con el siguiente código.

// 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.AddDays(7);
followup["scheduledend"] = DateTime.Now.AddDays(7);
followup["category"] = context.PrimaryEntityName;

// Refer to the account in the task activity.
if (context.OutputParameters.Contains("id"))
{
    Guid regardingobjectid = new Guid(context.OutputParameters["id"].ToString());
    string regardingobjectidType = "account";

    followup["regardingobjectid"] =
    new EntityReference(regardingobjectidType, regardingobjectid);
}

// Create the task in Microsoft Dynamics CRM.
tracingService.Trace("FollowupPlugin: Creating the task activity.");
service.Create(followup);

Acerca del código

• Este código usa el estilo de enlace tardío para crear una tarea y asociarla con la cuenta que se está creando. Más información: Crear tablas usando el SDK para .NET
• Se pueden utilizar clases con enlace temprano, pero su uso requiere generar las clases para las tablas e incluir en el proyecto de ensamblado el archivo que las define. El uso de clases con enlace temprano depende principalmente de las preferencias personales, por lo que se han omitido esos pasos en este tutorial por motivos de brevedad. Más información: Programación con enlace tardío y enlace temprano mediante el SDK para .NET
• La Id de la cuenta que se está creando se encuentra en el contexto OutputParameters y está establecida como columna de búsqueda regardingobjectid para la tarea.

Crear el complemento

En Visual Studio, presione F6 para crear el ensamblado. Compruebe que se compila sin errores.

Firmar el complemento

1. En el Explorador de soluciones, haga clic con el botón secundario en el proyecto BasicPlugin y seleccione Propiedades en el menú contextual.

   

2. En las propiedades del proyecto, seleccione la pestaña Firma y seleccione la casilla Firmar el ensamblado.

   

3. En la lista desplegable Elija un archivo de clave de alta seguridad:, seleccione <Nuevo…>.

4. En el diálogo Crear clave de alta seguridad, introduzca un nombre de archivo de clave y desactive la casilla Proteger mi archivo de clave con contraseña.

5. Seleccione Aceptar para cerrar el cuadro de diálogo Crear una clave de alta seguridad.

6. En la pestaña Generar de las propiedades del proyecto, compruebe que la opción Configuración esté establecida como Depurar.

7. Pulse F6 para crear el complemento de nuevo.

8. Usando el Explorador de Windows, busque el complemento creado en:\bin\Debug\BasicPlugin.dll.

Registrar el complemento

Para registrar un complemento necesitará la herramienta de registro de complementos.

Conéctese usando la herramienta de registro de complementos

1. Abra la herramienta de registro de complementos ejecutando el comando PAC CLI pac tool prt.

2. Seleccione +Crear nueva conexión para conectarse a su entorno de Dataverse.

3. Asegúrese de que Office 365 está seleccionado.

4. Si se está conectando usando una cuenta Microsoft diferente a la que está usando actualmente, haga clic en Mostrar opciones avanzadas e ingrese sus credenciales. De lo contrario, deje Iniciar sesión como usuario actual seleccionado.

   Nota

   Si su cuenta de usuario emplea la autenticación multifactor (MFA), asegúrese de que la casilla Mostrar avanzado no esté marcada.

5. Si su cuenta Microsoft proporciona acceso a varios entornos, seleccione Mostrar la lista de organizaciones disponibles.

   

6. Seleccione Iniciar sesión.

7. Si ha seleccionado Mostrar la lista de organizaciones disponibles, seleccione la organización con la que quiere conectarse y haga clic en Iniciar sesión.

8. Una vez que esté conectado, verá los complementos registrados existentes, las actividades de flujo de trabajo personalizadas y los proveedores de datos.

   

Registrar el ensamblado

1. En el menú desplegable Registro, seleccione Nuevo ensamblaje.

   

2. En el cuadro de diálogo Registrar nuevo ensamblaje, seleccione el botón con puntos suspensivos (…) y vaya hasta el ensamblaje que compiló en el paso anterior.

   

3. Para los usuarios de Microsoft 365, compruebe que el modo aislado sea espacio aislado y la ubicación para almacenar el ensamblado sea Base de datos.

   Nota

   Otras opciones para modo aislado y ubicación se aplican a implementaciones locales de Dynamics 365. En cuanto a la ubicación, puede especificar la base de datos del servidor D365, el almacenamiento local del servidor (disco) o la Global Assembly Cache del servidor. Para obtener más información, consulte Almacenamiento de complementos.

4. Haga clic en Registrar complementos seleccionados.

5. Aparecerá un cuadro de diálogo de confirmación con el título Complementos registrados.

   

6. Seleccione Aceptar para cerrar el cuadro diálogo y cerrar el diálogo Registrar nuevo ensamblado.

7. Ahora aparecerá el ensamblado (Assembly) BasicPlugin que puede expandir para ver el complemento (Plugin) BasicPlugin.FollowUpPlugin.

   

Registrar un nuevo paso

1. Haga clic con el botón secundario en (Plugin) BasicPlugin.FollowUpPlugin y seleccione Registrar nuevo paso.

   

2. En el cuadro de diálogo Registrar nuevo paso, establezca los siguientes campos.

   Ajuste	valor
   Mensaje	Crear
   Entidad principal	cuenta
   Fase de ejecución de la canalización de eventos	Posoperación
   Modo de ejecución	Asincrónico

   

3. Seleccione Registrar nuevo paso para completar el registro y cerrar el diálogo Registrar nuevo paso.

4. Ahora puede ver el paso registrado.

   

Probar complemento

1. Abra una aplicación basada en modelos y cree una tabla de cuentas.

2. En un breve período de tiempo, abra la cuenta y podrá comprobar la creación de la tarea.

   

¿Qué ocurre si la tarea no se creó?

Dado que estamos trabajando con un complemento asincrónico, la operación de crear la tarea se produce una vez creada la cuenta. Normalmente, la creación de la tarea se realiza de inmediato, pero, si no es así, puede que aún pueda ver la tarea del sistema en la cola, pendiente de aplicarse. El registro de este paso utilizó la opción Delete AsyncOperation if StatusCode = Successful, que es una práctica recomendada. Esto quiere decir que, en cuanto el trabajo del sistema finalice correctamente, no podrá ver los datos del trabajo del sistema a menos que vuelva a registrar el complemento con la opción Delete AsyncOperation if StatusCode = Successful desactivada.

Sin embargo, si se produjo un error, puede ver el trabajo del sistema para ver el mensaje de error.

Ver trabajos del sistema

Use la aplicación Dynamics 365 --personalizado para ver trabajos del sistema.

1. En la aplicación basada en modelos, vaya a la aplicación.

   

2. En la aplicación Dynamics 365 --personalizado, vaya a Configuración>Sistema>.Trabajos del sistema.

   

3. Al ver las tareas del sistema, puede filtrar por Tabla (Entidad). Seleccione Cuenta.

   

4. Si el trabajo falló, debería ver un registro con el nombre BasicPlugin.FollowupPlugin: Creación de una cuenta.

   

5. Si abre el trabajo del sistema, puede expandir la sección Detalles para ver la información escrita en la traza y la información sobre el error.

   

Consultar trabajos del sistema

Puede usar la siguiente consulta de la API web para obtener los trabajos del sistema que han fallado para los complementos asíncronos.

GET <your org uri>/api/data/v9.0/asyncoperations?$filter=operationtype eq 1 and statuscode eq 31&$select=name,message

Para obtener más información, consulte Consultar datos mediante la API web

O usar el FetchXml siguiente:

<fetch top='50' >
  <entity name='asyncoperation' >
    <attribute name='message' />
    <attribute name='name' />
    <filter type='and' >
      <condition attribute='operationtype' operator='eq' value='1' />
      <condition attribute='statuscode' operator='eq' value='31' />
    </filter>
  </entity>
</fetch>

Más información: Uso de FetchXML con FetchExpression

Ver registros de seguimiento

El código de ejemplo escribió un mensaje en el registro de seguimiento. Los pasos a continuación describen cómo ver los registros.

De forma predeterminada, los registros de seguimiento de complementos no están habilitados.

Use los siguientes pasos para habilitarlos en una aplicación basada en modelos.

1. Abra la aplicación personalizada de Dynamics 365.

   

2. Vaya a Configuración>Sistema>Administración.

   

3. En Administración, seleccione Configuración del sistema.

4. En el cuadro de diálogo Configuración del sistema, en la pestaña Personalización, establezca Habilitar el registro en el log de seguimiento del complemento en Todo.

   

   Nota

   Debe deshabilitar el registro después de que haya finalizado de probar el complemento, o al menos establecerlo como Excepción en lugar de Todos.

5. Seleccione Aceptar para cerrar el diálogo Configuración del sistema.

6. Repita los pasos para probar el complemento creando una nueva cuenta.

7. En la Aplicación predeterminada de Dynamics 365, vaya a Configuración>Personalización>.Registro de seguimiento del complemento.

8. Deberá ver que se ha creado un nuevo registro de seguimiento de complementos.

   

9. Si abre el registro puede esperar que incluya la información que estableció en su seguimiento, pero no es así. Solo verifica que el rastreo se produjo.

10. Para ver los detalles, es más fácil consultar estos datos mediante API web en el explorador usando la consulta siguiente con el plugintracelog EntityType, usando la propiedad typename para filtrar resultados en la propiedad messageblock basándose en el nombre de la clase de complemento.

    GET <your org uri>/api/data/v9.0/plugintracelogs?$select=messageblock&$filter=typename eq 'BasicPlugin.FollowUpPlugin'

11. Puede esperar ver esta información con formato JSON devuelta con la consulta de la API web.

    {
        "@odata.context": "<your org uri>/api/data/v9.0/$metadata#plugintracelogs(messageblock)",
        "value": [{
            "messageblock": "FollowupPlugin: Creating the task activity.",
            "plugintracelogid": "f0c221d1-7f84-4f89-acdb-bbf8f7ce9f6c"
        }]
    }
    

Pasos siguientes

En este tutorial ha creado un complemento simple y lo ha registrado. Complete Tutorial: Depurar un complemento para aprender a depurar este complemento.

Consulte también

Tutorial: Actualizar un complemento
Escribir un complemento
Registrar un complemento
Depurar complementos.