Tutorial: Escribir y registrar un complemento

Este tutorial es el primero de una serie que le muestra cómo trabajar con los complementos. Este tutorial es un requisito previo para los tutoriales siguientes:

Para una explicación detallada de los conceptos relacionados y la información técnica, consulte:

Objetivo

Crear un complemento asincrónico registrado en el mensaje Crear de la tabla de cuenta. El complemento creará una actividad de tarea que recordará 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

  • Acceso de nivel de administrador a un entorno Microsoft Dataverse
  • Una aplicación basada en modelos que incluye las tablas de cuenta y tarea.
  • Visual Studio 2017 (o posteriores)
  • Conocimientos del lenguaje de programación Visual C#
  • Descargue la herramienta de registro de complementos siguiendo las instrucciones que se muestran aquí: Herramientas de desarrollo de Dataverse.

Crear un proyecto de complemento

Debe usar Visual Studio para escribir un complemento. Use estos pasos para escribir un complemento básico. Como alternativa, puede usar Power Platform CLI para crear un proyecto nuevo usando el comando pac plugin init.

También puede encontrar los archivos de la solución del complemento aquí: Ejemplo: Crear un complemento básico.

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

    Abra un nuevo proyecto de biblioteca de clases (.NET Framework) mediante .NET Framework 4.6.2.

    El nombre usado para el proyecto será el nombre del complemento. 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.

    Administrar paquetes NuGet.

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

    Instalar el paquete Microsoft.CrmSdk.CoreAssemblies NuGet.

  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.

    Cambiar nombre de la clase.

  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.

    Diálogo Confirmar cambio de nombre.

Edite el archivo de clase para habilitar 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

Adición de lógica de negocios

El complemento creará una actividad de tarea que recordará 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 lo siguiente:

// 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. Se trata sobre todo de una preferencia personal, por lo que estos pasos se ha dejado fuera de 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 Explorador de soluciones, haga clic con el botón secundario en el proyecto BasicPlugin y seleccione Propiedades en el menú contextual.

    Abrir propiedades del proyecto.

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

    Firme 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. Haga clic en 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.

    Inicio de sesión con la herramienta de registro de complementos.

  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.

    Ver complementos existentes y activades personalizadas del flujo de trabajo.

Registrar el ensamblado

  1. En el desplegable Registrar, seleccione Nueva ensamblado.

    registrar nuevo 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.

    Cuadro de diálogo de registro de nuevo ensamblado.

  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, vea Almacenamiento de complementos.

  4. Haga clic en Registrar complementos seleccionados.

  5. Verá un diálogo de confirmación Complementos registrados.

    Diálogo de confirmación de complementos registrados.

  6. Haga clic en 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.

    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.

    Registrar un nuevo paso.

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

    Ajuste Value
    Mensaje Crear
    Entidad principal account
    Fase de canalización de eventos de ejecución PostOperation
    Modo de ejecución Asincrónico

    Introducción de datos de pasos relevantes.

  3. Haga clic en Registrar nuevo paso para completar el registro y cerrar el diálogo Registrar nuevo paso.

  4. Ahora puede ver el paso registrado.

    Vea 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. Consulte Agregar el ensamblado a una solución y Agregar paso a la solución para obtener más informació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.

    Registro de tabla Cuenta con actividad de tarea relacionada creada por complemento.

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

Dado que se trata de un complemento asincrónico, la operación de crear la tarea se produce una vez creada la cuenta. Normalmente, esto 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

    ver la aplicación personalizada de Dynamics 365.

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

    navegar a trabajos del sistema.

  3. Cuando ve trabajos del sistema, puede filtrar por Tabla (Entidad). Seleccione Cuenta.

    Filtrar por cuentas.

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

    Error de trabajo del sistema.

  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.

    detalles del trabajo del sistema.

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

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.

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.

    Abra la aplicación personalizada de Dynamics 365.

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

    vaya a 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.

    Pestaña Personalización de Configuración del sistema.

    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. Haga clic en 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.

    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 lo siguiente devuelto 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.

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