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 la cuenta que realice seguimiento una semana más tarde.

Nota

Este objetivo se puede conseguir fácilmente utilizando un flujo de trabajo sin escribir código. Estamos usando este ejemplo simple para poder centrarnos en el proceso de creación y de implementar un complemento.

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 de 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. Abra Visual Studio y abra un nuevo proyecto Biblioteca de clase (.NET Framework) mediante .NET Framework 4.6.2

   

   El nombre usado para el proyecto también es el nombre del ensamblado. Este tutorial usa el nombre BasicPlugin.

2. En 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

   La adición del paquete Microsoft.CrmSdk.CoreAssemblies NuGet incluirá estos ensamblados en la carpeta de compilación de su ensamblado, pero no cargará estos ensamblados con el ensamblado que incluye su lógica. Estos ensamblados ya están presentes en el runtime de espacio aislado.

   No incluya ningún otro paquete o ensamblaje NuGet en la carpeta de compilación de su proyecto. No puede incluir estos ensamblados cuando registra el ensamblado con 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 la bloque de captura 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.

Adición de lógica de negocios

El complemento crea una actividad de tarea que recuerda al creador la cuenta que realice seguimiento una semana más tarde.

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 en tiempo de ejecución para crear una tarea y para asociarla a la cuenta que se está creando. Más información: Crear tablas usando el SDK para .NET
• Pueden utilizarse clases de enlaces en tiempo de compilación, pero esto requiere generar las clases para las tablas e incluir el archivo que define esas clases con el proyecto de ensamblados. El uso de clases de unión temprana es sobre todo una preferencia personal, por lo que esos pasos se omiten en este tutorial por brevedad. Más información: Programación en tiempo de ejecución y en tiempo de compilación con 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.

Nota

Cree el ensamblado usando la configuración de Depuración porque usará el generador de perfiles de complementos para depurarlo en un tutorial posterior. Antes de incluir un complemento con la solución, debe generarlo mediante la configuración de versión.

Registrar complemento

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

Conéctese usando la herramienta de registro de complementos

1. Una vez que haya descargado la herramienta de registro de complementos, haga clic en el PluginRegistration.exe para abrirla.

2. Haga clic en Crear nueva conexión para conectarse a su instancia.

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 el usuario actual seleccionado.

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

   

6. Haga clic en 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 desplegable Registrar, seleccione Nueva ensamblado.

   

2. En el diálogo Registrar nuevo ensamblado, seleccione el botón de puntos suspensivos (…) y busque el ensamblado que generó 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. Para la ubicación, puede especificar la base de datos del servidor de D365, el almacenamiento local del servidor (disco) o los ensamblados de la caché de ensamblados global. Para obtener más información, consulte Almacenamiento de complementos.

4. Haga clic en Registrar complementos seleccionados.

5. Verá un diálogo de confirmación 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
   Publicación	Crear
   Entidad principal	cuenta
   Fase de canalización de eventos de ejecución	PostOperation
   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.

   

Nota

En este punto el ensamblado y los pasos son parte de la solución predeterminada del sistema. Al crear un complemento de producción, los agregaría a la solución no administrada que distribuirá. Estos pasos no se incluyen en este tutorial. Para obtener más información, consulte Agregar su ensamblaje a una solución y Agregar paso a la solución .

Probar complemento

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

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 ocurrirá inmediatamente, pero si no es así, puede seguir viendo el trabajo del sistema en la cola en espera de aplicarse. Este registro del pasos usó la opción Delete AsyncOperation if StatusCode = Successful que es una práctica recomendada. Esto quiere decir que tan pronto como el trabajo del sistema finaliza 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.

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. Cuando ve trabajos del sistema, puede filtrar por Tabla (Entidad). Seleccione Cuenta.

   

4. Si el trabajo tiene error, debe ver un registro con el nombre BasicPlugin.FollowupPlugin: Creación de cuenta.

   

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

   

Consultar trabajos del sistema

Puede usar la consulta API web siguiente para devolver trabajos del sistema con error para complementos asincrónicos.

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

Más información: Consulta de 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 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.

Sugerencia

Si prefiere cambiar este valor en código: Este valor está en el Columna PluginTraceLogSetting de la tabla de la organización.

Los valores válidos son:

valor	Etiqueta
0	Desactivado
1	Excepción
2	Toda

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 diálogo Configuración del sistema, en la pestaña de personalización, establezca Habilitar registro para registro de seguimientos de complemento como Todos.

   

   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 comprueba que el seguimiento se ha producido.

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
Depuración de complementos.

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