Crear y empaquetar código de complementos

En este artículo se describen las restricciones y limitaciones que debe saber al compilar y empaquetar código de complemento para Microsoft Dataverse, incluidas las restricciones de ensamblado, los requisitos de ensamblado dependientes y las opciones de empaquetado de NuGet.

Restricciones de ensamblaje de plugins

Cuando cree un proyecto de complemento, tenga en cuenta las siguientes restricciones del ensamblaje de salida.

Usar .NET Framework 4.6.2

Los proyectos de ensamblaje de complementos y de actividades de flujo de trabajo personalizadas deben apuntar a .NET Framework 4.6.2.

Limite los ensamblajes a 16 MB

Su ensamblaje puede incluir múltiples clases o tipos de complementos e incluso actividades de flujo de trabajo personalizadas, pero no puede tener más de 16 MB. Como procedimiento recomendado, consolide complementos y ensamblados de flujo de trabajo en un único ensamblado, siempre y cuando el tamaño permanezca por debajo de 16 MB.

Firmar ensamblados antes de registrarlos

Si no usa la funcionalidad de ensamblados dependientes , debe firmar los ensamblados antes de registrarlos con Dataverse. Para firmar el ensamblado, use la pestaña Firma de Visual Studio en las propiedades del proyecto o el comando Sn.exe (Herramienta de nombre seguro).

NuGet CoreAssemblies están en el espacio aislado

Si agrega el paquete Microsoft.CrmSdk.CoreAssembliesNuGet a tu proyecto, se le agregan las referencias de ensamblado de Dataverse necesarias. Sin embargo, los ensamblados en sí mismo no se suben con el ensamblado del complemento. Ya existen en el entorno de ejecución del espacio aislado del servidor donde se ejecuta el código.

Asambleas dependientes

Utilice la capacidad de ensamblado dependiente para incluir otros recursos o ensamblados .NET necesarios, como cadenas localizadas, con su ensamblado de complemento en un único paquete NuGet que se carga en el servidor Dataverse durante el registro.

El archivo del paquete NuGet se almacena en la tabla PluginPackage. El contenido del paquete se almacena en un almacenamiento de archivos en lugar de en la base de datos SQL.

Cuando carga su paquete NuGet, cualquier ensamblado que contenga clases que implementen la interfaz IPlugin se registra en la tabla PluginAssembly y se asocia con el paquete del complemento. A medida que desarrolla y mantiene su proyecto, continúa actualizando la fila de la tabla PluginPackage y los cambios en los conjuntos de complementos relacionados se administran en el servidor.

En tiempo de ejecución, Dataverse copia el contenido del paquete NuGet de la fila PluginPackage y lo extrae al entorno de ejecución de la zona de pruebas. De esta forma, todos los ensamblajes dependientes necesarios para el complemento están disponibles.

Los ensamblados firmados no son necesarios

No es necesario iniciar sesión en los ensamblados de complemento usados en los paquetes de complementos.

Cuando registra ensamblajes de complementos individuales sin la capacidad de ensamblajes dependientes, se requiere la firma porque proporciona un nombre único para el ensamblaje. Pero con ensamblados de complemento en un paquete de complementos, los ensamblados se cargan en el servidor de espacio aislado mediante un mecanismo diferente, de modo que no es necesario realizar la firma.

Limitaciones de los ensamblajes dependientes

Se aplican las siguientes limitaciones cuando utiliza ensamblados dependientes de complementos:

• Las extensiones de flujo de trabajo, también conocidas como actividades de flujo de trabajo personalizadas, no son compatibles.
• Los entornos local no son compatibles.
• El código no administrado no es compatible. No puede incluir referencias a recursos no administrados.

Consideraciones de rendimiento al importar o registrar un paquete de complemento

Los paquetes de complemento que contienen ensamblados con un gran número (cientos a miles) de clases que implementan IPlugin tardan un tiempo relativamente largo en importarse en Dataverse.

Se han observado tiempos de importación de 15 minutos para mil tipos de complementos. Esta duración se aplica independientemente de si va a importar una solución mediante una llamada API o a través de la interfaz de usuario web, o bien al registrar el paquete mediante la herramienta Registro de complementos.

Crear un paquete de complemento

Puede colocar su ensamblaje de complemento y cualquier ensamblaje dependiente juntos en un paquete NuGet y luego registrar y cargar el paquete en el servidor Dataverse. Si su proyecto de complemento no requiere ningún ensamblado dependiente en tiempo de ejecución que no sea el que se incluye en el paquete Microsoft.CrmSdk.CoreAssemblies NuGet, no necesita crear un paquete.

Aprenda a crear y registrar un paquete de complemento mediante la CLI de PAC y a crear y registrar un paquete de complemento mediante Visual Studio.

Todos los proyectos deben usar el estilo del SDK

Un paquete de complemento solo puede contener ensamblados personalizados que se compilan a partir de un archivo de proyecto en un formato específico conocido como estilo del SDK. Si no sigue esta regla, recibirá un error ("no se encuentra el archivo") al intentar registrar el paquete mediante la herramienta Registro de complementos.

Un proyecto de estilo SDK es aquel en el que el contenido del archivo .csproj del proyecto contiene la siguiente línea de código: <Project Sdk="Microsoft.NET.Sdk">.

Al crear un proyecto de complemento mediante una de las herramientas, como el comando de la CLI pac plugin init de Power Platform, el archivo del proyecto del complemento tiene el formato correcto. He aquí un ejemplo de un archivo de proyecto de este tipo.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net462</TargetFramework>
    <PowerAppsTargetsPath>$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\PowerApps</PowerAppsTargetsPath>
    <AssemblyVersion>1.0.0.0</AssemblyVersion>
    <FileVersion>1.0.0.0</FileVersion>
    <ProjectTypeGuids>{4C25E9B5-9FA6-436c-8E19-B395D2A65FAF};{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</ProjectTypeGuids>
  </PropertyGroup>
  ...
</Project>

Si va a agregar otro proyecto a la solución de Visual Studio, como un proyecto de biblioteca de clases, cree un proyecto de estilo sdk siguiendo estos pasos:

1. En Visual Studio, agregue el nuevo proyecto a su solución usando una plantilla .NET o .NET Standard. No tenga como objetivo .NET Framework.
2. Edite el archivo del proyecto haciendo clic con el botón derecho en el nombre del proyecto en el Explorador de soluciones y seleccionando Editar archivo de proyecto o abra el archivo .csproj del proyecto en un editor independiente.
3. Debería ver la línea <Project Sdk="Microsoft.NET.Sdk"> en el archivo del proyecto. Cambie la propiedad TargetFramework a <TargetFramework>net462</TargetFramework> y guarde el archivo.
4. Verifique las compilaciones de su solución y listo.

Para obtener más información, consulte SDK de proyectos de .NET.

No dependa de System.Text.Json

Dado que el Microsoft.CrmSdk.CoreAssemblies paquete NuGet tiene una dependencia de System.Text.Json, puede hacer referencia a tipos System.Text.Json en el tiempo de diseño. Sin embargo, es posible que el archivo System.Text.Json.dll en el tiempo de ejecución de la zona de pruebas no sea el mismo archivo al que haces referencia en tu proyecto. Si necesita usar System.Text.Json, use la funcionalidad de ensamblado dependiente e incluyalo explícitamente en el paquete NuGet.

Siguiente paso

• Registrar un complemento

Consulte también

• Use complementos para ampliar los procesos de negocio