Comentarios

Escribir un complemento

  • Artículo
  • Tiempo de lectura: 9 minutos

Nota

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

Puede usar las Herramientas de Power Platform para Visual Studio con el fin de crear e implementar (registrar) complementos rápidamente. Está disponible un artículo de inicio rápido que explica cómo se hace.

Un proceso más manual para escribir, registrar y depurar un complemento es:

  1. Crear un proyecto de biblioteca de clases de .NET Framework en Visual Studio
  2. Agregar el paquete Microsoft.CrmSdk.CoreAssemblies NuGet al proyecto
  3. Implementar la interfaz IPlugin en clases que se registrarán como pasos.
  4. Agregar su código al método Execute requerido por la interfaz
    1. Obtener las referencias a los servicios que necesita
    2. Adición de lógica de negocios
  5. Firmar y crear el ensamblado
  6. Probar el ensamblado
    1. Registrar el ensamblado en un entorno de prueba
    2. Agregar el ensamblado registrado y pasos a una solución no administrada
    3. Probar el comportamiento del ensamblado
    4. Comprobar que se escriben los registros de seguimiento esperados
    5. Depure el ensamblado según sea necesario

El contenido de este tema analiza los pasos de 1 a 5 anteriores en negrita y ofrece los tutoriales siguientes:

Restricciones de ensamblado

Tenga en cuenta las siguientes restricciones cuando cree ensamblados.

Usar .NET Framework 4.6.2

Los complementos y ensamblados de flujo de trabajo personalizadas deben usar .NET Framework 4.6.2. Si bien los ensamblados construidos con versiones posteriores deben funcionar normalmente, si usan características introducidas después de 4.6.2 se producirá un error.

Optimizar el desarrollo de ensamblados

El ensamblado debe 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. Más información: 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.

No depender de ningún otro conjunto

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 ensamblados distintos de los incluidos en el paquete Microsoft.CrmSdk.CoreAssemblies NuGet estarán presentes ni que serán compatibles con su código.

Interfaz de IPlugin

Un complemento es un clase dentro de un ensamblado creada mediante un proyecto de biblioteca de clases de .NET Framework usando .NET Framework 4.6.2 en Visual Studio. Cada clase en el proyecto que se registrará como paso debe implementar la interfaz IPlugin que requiere el método Execute.

Importante

Al implementar IPlugin, la clase debe ser 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. Hay algunas excepciones a esto. Por ejemplo puede tener una propiedad que representa una constante y puede tener métodos que representen las funciones 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 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

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

Pasar datos de configuración al complemento

Al registrar un complemento tiene la capacidad de pasarle datos de configuració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: unsecure y secure. Use el primer parámetro unsecure para datos que no le importe que vea la gente. Use el segundo parámetro secure para datos confidenciales.

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

public SamplePlugin()  
public SamplePlugin(string unsecure)  
public SamplePlugin(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

En el complemento deberá:

  • Obtener acceso a la información contextual sobre lo que ocurre en el evento que el complemento se registró para administrar. Esto se llama contexto de ejecución.
  • Obtener acceso al servicio web de la organización para poder escribir código para consultar datos, trabajar con registros de tabla, usar mensajes para realizar operaciones.
  • Escribir mensajes al servicio de seguimiento para poder evaluar cómo se está ejecutando el código.

La propiedad IServiceProvider.GetService el método proporciona una forma de tener acceso a estos servicios según sea necesario. Para obtener una instancia del servicio invoque el método GetService que pasa el tipo de servicio.

Nota

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

Servicio de organización

Para trabajar con datos en un complemento, use el servicio de la organización. No intente usar la API web. Los complementos solo se pueden escribir con la API del SDK y se pueden compilar como ensamblados .NET.

Para obtener acceso a una variable svc que implemente la interfaz IOrganizationService, use el siguiente código:

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

La variable context.UserId usada con IOrganizationServiceFactory.CreateOrganizationService(Nullable<Guid>) procede del contexto de ejecución de la propiedad UserId, por lo que se llama después de haber accedido al contexto de ejecución.

Más información:

Puede usar tipos de compilación en un complemento. Basta incluir el archivo de tipos generado en el proyecto. Pero debería tener en cuenta que todos los tipos de tabla proporcionados por los parámetros de entrada del contexto de ejecución serán tipos de ejecución. Deberá convertirlos a tipos de compilación. Por ejemplo puede realizar las siguientes acciones cuando sabe que el parámetro Target representa una tabla de cuenta.

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

Pero nunca debe intentar establecer el valor con un tipo de compilación. No intente hacer esto:

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

Esto hará que se produzca una SerializationException.

Utilizar el 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.

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

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

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

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

Consideraciones sobre el rendimiento

Al agregar lógica de negocios para el complemento necesita tener muy en cuenta el impacto que tendrán en el rendimiento general.

Importante

La lógica de negocios en complementos registrados para pasos sincrónicos no debe tardar más de 2 segundos en completarse.

Restricciones de tiempo y de recursos

Hay un límite de tiempo de 2 minutos para que las operaciones de mensaje se completen. También existen limitaciones de la cantidad de CPU y recursos de memoria que pueden usar las extensiones. Si se superan los límites se lanza una excepción y la operación se cancelará.

Si se supera el límite de tiempo, se producirá una TimeoutException. Si alguna extensión personalizada supera el umbral de la CPU, la memoria o el control de límites, o si de otra manera no responde, la plataforma eliminará ese proceso. En ese momento cualquier extensión actual de dicho proceso producirá un error con excepciones. Sin embargo, la próxima vez que se ejecute la extensión se ejecutará normalmente.

Supervisar el rendimiento

La información en tiempo de ejecución sobre complementos y extensiones de flujo de trabajo personalizadas se capturan y almacenan en Tabla PluginTypeStatistic. Estos registros se rellenan entre 30 minutos y una hora después de que el código personalizado se ejecute. Esta tabla proporciona los puntos de datos siguientes:

Column Descripción
AverageExecuteTimeInMilliseconds Tiempo de ejecución promedio (en milisegundos) para el tipo de complemento.
CrashContributionPercent Porcentaje de contribución del tipo de complemento con respecto a los bloqueos.
CrashCount Número de veces que el tipo de complemento se bloqueó.
CrashPercent Porcentaje de bloqueos para el tipo de complemento.
ExecuteCount Número de veces que se ejecutó el tipo de complemento.
FailureCount Número de veces que se produjo un error en el tipo de complemento.
FailurePercent Porcentaje de errores para el tipo de complemento.
PluginTypeIdName Identificador único del usuario que modificó las estadísticas del tipo de complemento por última vez.
TerminateCpuContributionPercent Finalización del porcentaje de contribución del tipo de complemento al proceso de trabajo debido al uso excesivo de la CPU.
TerminateHandlesContributionPercent Finalización del porcentaje de contribución del tipo de complemento al proceso de trabajo debido al uso excesivo del identificador.
TerminateMemoryContributionPercent Finalización del porcentaje de contribución del tipo de complemento al proceso de trabajo debido al uso excesivo de la memoria.
TerminateOtherContributionPercent Finalización del porcentaje de contribución del tipo de complemento al proceso de trabajo por razones desconocidas.

Estos datos también están disponibles para que los examine mediante el Centro de administración de Power Platform. Seleccione Análisis > Dataverse > Complementos.

Pasos siguientes

Registro de un complemento
Depuración de complementos

Vea también

Escriba complementos para ampliar los procesos de negocio
Prácticas recomendadas e instrucciones sobre la programación de complementos y flujos de trabajo
Administrar excepciones
Suplantar a un usuario
Tutorial: Escribir y registrar un complemento
Tutorial: Depurar un complemento
Tutorial: Actualizar un 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).