Escribir un complemento

Artículo
03/14/2023
Tiempo de lectura: 4 minutos

Nota

¿No está seguro de entidad frente a tabla? Vea Desarrolladores: comprender la terminología en Microsoft Dataverse.

Puede crear complementos utilizando uno de los dos siguientes métodos:

Las herramientas de desarrollo de Power Platform proporcionan una forma moderna de crear complementos. Las herramientas a las que se hace referencia aquí son Power Platform Tools para Visual Studio y Power Platform CLI. Ambas Power Platform Tools generan un código de complemento similar, por lo que pasar de un método de herramientas a otro es bastante fácil y comprensible.
- Use las Power Platform Tools para Visual Studio con el fin de crear y registrar (implementar) complementos rápidamente. Está disponible un artículo de inicio rápido que explica cómo se hace. Utilice esta herramienta si le gusta trabajar en Visual Studio.
- Use Power Platform CLI para crear un proyecto de complemento básico (compatible con Visual Studio) con código de complemento de plantilla utilizando un único comando pac plugin. Luego, usando el comando pac tool prt, utiliza de forma interactiva la herramienta de registro de complementos para registrar su creación con Microsoft Dataverse. Utilice este conjunto de herramientas CLI si le gusta trabajar en una ventana de terminal o en Visual Studio Code.
Escriba código manualmente usando su editor favorito o IDE. El resto de la documentación del complemento en este tema y los otros temas relacionados están escritos pensando en el código de escritura del desarrollador, sin embargo, los conceptos presentados se aplican a todos los métodos de desarrollo de complementos.

Interfaz de IPlugin

Un complemento es una clase compilada dentro de un ensamblado creado para apuntar a .NET Framework 4.6.2. Cada clase de un proyecto de complemento que se registrará en un paso de canalización de eventos debe implementar la interfaz IPlugin que define un único método IPlugin.Execute.

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

El método Execute acepta un único parámetro IServiceProvider. El IServiceProvider tiene un solo método: GetService. Usará este método para obtener varios tipos distintos de servicios que puede usar en su código.

Más información: Servicios que puede usar en el código

Importante

Al derivarse de IPlugin, la clase debe escribirse sin estado. Esto se debe a que la plataforma almacena en caché una instancia de clase y la reutiliza por razones de rendimiento. Una forma sencilla de ver esto es que no debe agregar ninguna propiedad ni método a la clase y todo debe estar incluido en el método Execute.

Al usar las Power Platform Tools para la creación de complementos, la clase PluginBase generada se deriva de IPlugin.

Hay algunas excepciones a la declaración sobre agregar propiedades o métodos en la nota anterior. Por ejemplo puede tener una propiedad que representa una constante y puede tener métodos que se llaman desde el método Execute. Lo importante es que nunca almacene ninguna instancia de servicio o datos de contexto como propiedad en la clase. Estos valores cambian con cada invocación y no conviene que los datos se almacenen en caché y se apliquen a invocaciones posteriores.

Más información: Desarrollar implementaciones de IPlugin como sin estado

Pasar datos de configuración al complemento

Cuando registra un complemento, puede especificar opcionalmente los datos de configuración para pasar al complemento en tiempo de ejecución. Los datos de configuración permiten definir cómo una instancia específica de un complemento registrado debe comportarse. Esta información se pasa como datos de cadena a los parámetros en el constructor de la clase. Hay dos parámetros, es decir, unsecure y secure. Use el primer parámetro unsecure para datos que no le importe que vea alguien más. Use el segundo parámetro secure para datos confidenciales.

El código siguiente muestra las tres firmas de constructor posibles para una clase de complemento llamada MyPlugin.

public MyPlugin() {}
public MyPlugin(string unsecure) {}  
public MyPlugin(string unsecure, string secure) {}

Los datos de configuración seguro se almacenan en una tabla aparte que sólo los administradores del sistema tienen privilegios para leer.

Más información: Registrar paso del complemento > Establecer datos de configuración

Servicios que puede usar en el código

Normalmente, en el complemento hará lo siguiente:

Accederá a los datos contextuales pasados a su complemento para determinar la información sobre la entidad y la solicitud de mensaje que provocó el evento e invocó su complemento. Estos datos se llaman contexto de ejecución.
Accederá al servicio web de la organización usando SDK para llamadas .NET para realizar operaciones de solicitud de mensajes como consulta, creación, actualización, eliminación y más.
Escribirá mensajes al servicio de seguimiento para poder evaluar cómo se está ejecutando el código del complemento.

La propiedad IServiceProvider.GetService le proporciona una forma de acceder a las referencias de servicio pasadas en el contexto de ejecución cuando sea necesario. Para obtener una instancia de un servicio invoque el método GetService que pasa el tipo de servicio. Lea más sobre esto en las siguientes secciones.

Contexto de ejecución

El contexto de ejecución contiene una gran cantidad de información que un complemento puede necesitar. El contexto se obtiene usando el siguiente código.

IPluginExecutionContext context = (IPluginExecutionContext)
    serviceProvider.GetService(typeof(IPluginExecutionContext));

Más información: IPluginExecutionContext, Entender el contexto de ejecución

Servicio web de organización

Además de los datos pasados en el contexto de ejecución, los datos de la fila de la tabla de Dataverse se pueden leer o escribir desde el código del complemento mediante llamadas SDK al servicio web de la organización. No intente utilizar la API web, ya que no es compatible con los complementos. Además, no autentique al usuario antes de acceder a los servicios web, ya que el usuario se autentica previamente antes de la ejecución del complemento.

Más información: Operaciones de tabla, Usar mensajes

Para obtener una referencia de objeto al servicio web de la Organización, use el siguiente código:

IOrganizationServiceFactory serviceFactory =
    (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
IOrganizationService orgService = serviceFactory.CreateOrganizationService(context.UserId);

Servicio de seguimiento

Use el servicio de seguimiento para escribir mensajes a la tabla PluginTraceLog para poder revisar los registros y comprender qué sucedió cuando se ejecutó el complemento.

Para escribir el registro de seguimientos, debe obtener una instancia del servicio de seguimiento. El siguiente código muestra cómo obtener una instancia del servicio de seguimiento mediante el método IServiceProvider el.GetService Método.

ITracingService tracingService =
    (ITracingService)serviceProvider.GetService(typeof(ITracingService));

Para escribir el seguimiento, use el método ITracingService.Trace Método.

tracingService.Trace("Write {0} {1}.", "your", "message");

Más información: Usar el seguimiento, Seguimiento y registro.

Otros servicios

Cuando escribe un complemento que usa la integración Azure Service Bus, usará un servicio de notificación que implementa la interfaz IServiceEndpointNotificationService, pero esto no se describirá aquí.

Más información: Integración de Azure

Juntándolo todo

La aplicación de los conceptos de complemento detallados anteriormente da como resultado un código de complemento similar al siguiente.

public class MyPlugin : IPlugin
{
  public MyPlugin() {} // Constructor, does nothing

  public void Execute(IServiceProvider serviceProvider)
  {
    // Obtain the execution context
    IPluginExecutionContext context = (IPluginExecutionContext)
      serviceProvider.GetService(typeof(IPluginExecutionContext));

    // Obtain the Organization service reference 
    IOrganizationServiceFactory serviceFactory =
      (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
    IOrganizationService orgService = serviceFactory.CreateOrganizationService(context.UserId);

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

    try
    {
      // TODO Plug-in business logic goes here. You can access data in the context,
      // and make calls to the Organization web service using the Dataverse SDK.
    }
    catch (FaultException<OrganizationServiceFault> ex)
    {
      throw new InvalidPluginExecutionException("The following error occurred in MyPlugin.", ex);
    }
    catch (Exception ex)
    {
        tracingService.Trace("MyPlugin: error: {0}", ex.ToString());
        throw;
    }
}

Más información sobre cómo controlar las excepciones: Controlar excepciones en los complementos

El diseño del complemento afecta al rendimiento

Al escribir su complemento, es fundamental que se ejecute de manera eficiente y rápida. El tiempo que tarde en ejecutarse el complemento hace que el usuario final que invocó la operación del mensaje (que activó el complemento) tenga que esperar. Además de procesar la operación del mensaje, Dataverse ejecuta todos los complementos sincrónicos registrados en la canalización, incluido su complemento. Cuando los complementos tardan demasiado en ejecutarse, o si se registran demasiados complementos en una canalización, puede provocar que la IU de la aplicación no responda o, en el peor de los casos, un error de tiempo de espera con la reversión de la canalización.

Más información: Analizar el rendimiento del complemento

Uso de tipos enlazados en tiempo de compilación en código de complemento

Puede usar opcionalmente tipos de enlace de tiempo de compilación dentro del código del complemento. Simplemente, incluya el archivo de tipos generado en el proyecto de complemento. Tenga en cuenta que todos los tipos de tabla en la colección de InputParameters del contexto de ejecución son tipos de enlace de tiempo de compilación. Debería convertir esos tipos enlazados en tiempo de ejecución en tipos enlazados en tiempo de compilación.

Por ejemplo puede realizar las siguientes acciones cuando sabe que el parámetro Target representa una tabla de cuenta. En este ejemplo, "Cuenta" es un tipo enlazado en tiempo de compilación.

Account acct = context.InputParameters["Target"].ToEntity<Account>();

Pero nunca debe intentar establecer el valor con un tipo de compilación. Así, se producirá una SerializationException.

context.InputParameters["Target"] = new Account() { Name = "MyAccount" }; // WRONG: Do not do this.

Compiliar el ensamblado de complementos

Al crear un proyecto de complemento, tenga en cuenta las siguientes restricciones de ensamblaje de salida.

Usar .NET Framework 4.6.2

Los proyectos de ensamblaje personalizados y de complemento actividad de flujo de trabajo deben tener como destino .NET Framework 4.6.2. Si bien los ensamblados construidos con versiones posteriores de Framework deben funcionar normalmente, si el código del complemento usa características introducidas después de 4.6.2, se producirá un error.

Optimizar el desarrollo de ensamblados

El ensamblado puede incluir múltiples clases (o tipos) de complementos, pero no pueden ser mayores de 16 MB. Se recomienda consolidar complementos y ensamblados de flujo de trabajo en un único ensamblado siempre que el tamaño se mantenga por debajo de 16 MB.

Procedimiento recomendado: Optimizar desarrollo de ensamblados

Las ensamblados deben estar firmados

Todos los ensamblados deben estar firmados antes de poder registrarlos. Esto se puede hacer mediante la pestaña Firma de Visual Studio en el proyecto o mediante Sn.exe (herramienta Nombre seguro).

No dependen de los ensamblados .NET que interactúan con API de Windows de bajo nivel

Los ensamblados de complementos deben contener toda la lógica necesaria dentro del DLL respectivo. Los complementos pueden hacer referencia a algunos ensamblados .NET principales. Sin embargo, no se admiten las dependencias de ensamblados .NET que interactúen con las APIs de Windows de bajo nivel, como la interfaz de diseño gráfico.

Dependencia de otros ensamblados (no de Dataverse)

Al agregar el paquete NuGet Microsoft.CrmSdk.CoreAssemblies a su proyecto incluirá las referencias de ensamblado de Dataverse necesarias en su proyecto, pero no cargará estos ensamblados junto con su ensamblado de complemento porque estos ensamblados de Dataverse ya existen en el entorno de pruebas del servidor.

La capacidad de ensamblaje dependiente, actualmente en una versión preliminar, se puede usar para incluir otros ensamblajes compilados de .NET con su ensamblaje de complemento en un solo paquete que se puede cargar.

Más información: Complementos dependientes de ensamblaje.

Importante

La capacidad de ensamblado dependiente es tan importante para el desarrollo de complementos que debe considerar su uso desde el principio, incluso si no tiene una necesidad inmediata de hacerlo. Agregar soporte para ensamblajes dependientes a su proyecto de complemento es mucho más difícil más adelante en el ciclo de desarrollo.

Dado que esta característica es una versión preliminar, no la use para el trabajo de producción.

Pasos siguientes

Registrar un complemento
Depuración de complementos

Consulte también

Tutorial: Escribir y registrar un complemento
Administrar excepciones
Prácticas recomendadas e instrucciones sobre la programación de complementos y flujos de trabajo