Crear y empaquetar código de complementos

Este artículo describe las restricciones y limitaciones que necesita conocer al configurar y crear un ensamblado para su complemento Microsoft Dataverse.

Restricciones de ensamblado de complemento

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 personalizados y de complemento actividad de flujo de trabajo deben tener como destino .NET Framework 4.6.2. Los ensamblados creados con versiones posteriores de .NET Framework generalmente deberían funcionar. Sin embargo, si el código del complemento utiliza alguna característica introducida después de 4.6.2, se produce un error de tiempo de ejecución.

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, le sugerimos consolidar complementos y ensamblados de flujo de trabajo en un único ensamblado siempre que el tamaño se mantenga por debajo de 16 MB.

Firmar ensamblajes antes de registrarlos

Si no está utilizando la capacidad de ensamblados dependientes, los ensamblados deben estar firmados antes de poder registrarlos en Dataverse. Para firmar el ensamblaje, use la pestaña Visual Studio Firma en las propiedades de su proyecto o el comando Sn.exe (herramienta de nombre seguro)

NuGet CoreAssemblies están en el espacio aislado

Si agrega el paquete Microsoft.CrmSdk.CoreAssemblies NuGet a su proyecto, también se agregan las referencias de ensamblaje Dataverse necesarias, pero los ensamblajes en sí no se cargan con su ensamblaje de complemento. Ya existen en el tiempo de ejecución de la zona de pruebas del servidor donde se ejecuta su código

Asambleas dependientes

Importante

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

No damos soporte a ILMerge. La capacidad de ensamblajes dependientes ofrece la misma funcionalidad que ILMerge y más.

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 tiempo de ejecución de la zona de pruebas. De esta forma, todos los ensamblajes dependientes necesarios para el complemento están disponibles.

Importante

El nombre y la versión del paquete de complemento no se pueden cambiar una vez creado. Intentar hacerlo mediante una llamada API genera un error.

No se requieren asambleas firmadas

No es necesario que firme los ensamblajes de complementos utilizados 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 los ensamblados de complementos en un paquete de complementos, los ensamblados se cargan en el servidor de espacio aislado mediante un mecanismo diferente, por lo que no es necesario firmar.

Importante

Si firma sus ensamblados, tenga en cuenta que los ensamblados firmados no pueden usar recursos contenidos en ensamblados sin firmar. Si firma sus ensamblados de complementos o cualquier ensamblado dependiente, todos los ensamblados de los que dependan esos ensamblados deben estar firmados.

Si algún ensamblado firmado depende de ensamblados no firmados, recibirá un error como este: "No se pudo cargar el archivo o el ensamblado AssemblyName, Version=Version, Culture=neutral, PublicKeyToken=null o una de sus dependencias. Se requiere un ensamblado con nombre seguro."

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.

Consideración del rendimiento al importar o registrar un paquete de complemento

Los paquetes de complementos que contienen ensamblados con una gran cantidad (de cientos a miles) de clases que implementan IPlugin tardarán relativamente mucho en importarse a Dataverse.

Hemos visto tiempos de importación de quince (15) minutos para mil tipos de complementos. Esta duración se aplica independientemente de si está importando una solución mediante una llamada API o a través de la interfaz de usuario web, o si está registrando el paquete con la herramienta de 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 cómo crear y registrar un paquete de complemento usando PAC CLI y cómo crear y registrar un paquete de complemento usando Visual Studio.

Todos los proyectos deben tener el estilo SDK.

Un paquete de complemento solo debe contener ensamblados personalizados creados a partir de un archivo de proyecto en un formato específico conocido como estilo SDK. Si no se sigue esta regla, se producirá un error ("no se puede encontrar el archivo") al intentar registrar el paquete utilizando la herramienta de registro de complementos.

Importante

Todos los proyectos de MSBuild, donde el ensamblado compilado resultante se agregará a un paquete de complemento, deben estar en el formato "estilo SDK".

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

Cuando crea un proyecto de complemento utilizando una de nuestras herramientas, por ejemplo el comando Power Platform CLI pac plugin init, el archivo del proyecto de 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 está agregando otro proyecto a la solución Visual Studio, digamos un proyecto de biblioteca de clases, puede crear 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 secundario en el nombre del proyecto en el Explorador de soluciones y seleccione Editar archivo de proyecto, o simplemente 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.

Más información: SDK del proyecto .NET

No dependa de System.Text.Json

Debido a que el paquete Microsoft.CrmSdk.CoreAssemblies NuGet tiene una dependencia de System.Text.Json, puede consultar los tipos System.Text.Json en 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 la misma versión a la que hace referencia en su proyecto. Si necesita usar System.Text.Json, debe usar la capacidad de ensamblaje dependiente e incluirla explícitamente en su paquete NuGet.

Siguiente paso

• Registrar un complemento

Consulte también

• Use complementos para ampliar los procesos de negocio

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