Complementos dependientes de ensamblaje (versión preliminar)

[Este tema es documentación preliminar y está sujeto a modificaciones.]

Con frecuencia es valioso incluir otro ensamblado o un archivo de recursos dentro de un complemento. Por ejemplo, es posible que desee utilizar Newtonsoft.Json.dll u otro ensamblado. Es posible que desee acceder a una lista de cadenas localizadas.

Sin ensamblajes dependientes, todos los complementos se registran como ensamblajes de .NET Framework individuales. La única forma de incluir otro ensamblaje es combinarlo en uno usando ILMerge. Si bien ILMerge funcionó para muchos, Dataverse nunca lo apoyó, y no siempre funcionó. ILMerge ya no se mantiene.

Con ensamblados dependientes, en lugar de registrar un ensamblado .NET individual, carga un Paquete NuGet que contiene su ensamblaje de complemento Y cualquier ensamblaje dependiente. Este paquete del archivo de NuGet se almacena en una nueva tabla llamada PluginPackage. Los contenidos del paquete NuGet se almacena en el almacenamiento de archivos en lugar de SQL.

Importante

• Esta es una característica en versión preliminar.
• Las vistas previas de características no se han diseñado para un uso de producción y pueden tener una funcionalidad restringida. Estas características están disponibles antes del lanzamiento oficial para que los clientes puedan tener un acceso anticipado y proporcionar comentarios.

Este documento describía anteriormente un proceso para incluir archivos adicionales con el paquete del complemento que estaría disponible en el tiempo de ejecución del ensamblado. No se admitirá esta capacidad. No podemos garantizar que el tiempo de ejecución permita el acceso a estos archivos.

Cuando sube su paquete NuGet, cualquier ensamblado que contenga clases que implementen la interfaz de complemento están registrados en la tabla PluginAssembly y asociados con PluginPackage. A medida que desarrolla y mantiene su proyecto, continúa actualizando 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.

Todavía puede registrar ensamblajes de complementos individualmente, pero usando PluginPackage se convertirá en el enfoque recomendado. Incluso si su proyecto de complemento actual no requiere acceso a un ensamblaje dependiente, si comienza con un proyecto configurado para admitir ensamblajes dependientes, puede agregar un ensamblaje dependiente más adelante si es necesario. No hay trabajo planificado para convertir los proyectos de ensamblaje de complementos existentes para usar PluginPackage.

Enviar comentarios

Si tiene preguntas o problemas con esta función, puede comunicarse con el soporte técnico. Si tiene sugerencias, publíquelas en el sitio del Foro de ideas de Power Apps.

Limitaciones

Las siguientes limitaciones se aplican a los complementos de ensamblaje dependientes.

• Extensiones de flujo de trabajo, también conocidas como ensamblajes de flujo de trabajo, actividades de flujo de trabajo o las actividades de flujo de trabajo personalizadas no son compatibles.
• No se admiten complementos para proveedores de datos de tablas virtuales. La importación de una solución a un entorno fallará si la solución contiene complementos (con ensamblados dependientes) que están registrados en entidades virtuales.
• Los entornos local no son compatibles.
• El código no administrado no es compatible. No puede incluir referencias a recursos no administrados.

Firmas de ensamblados

No es necesario que firme los ensamblajes de complementos utilizados en los paquetes de complementos.

Cuando registra ensamblajes de complementos individuales sin la característica de ensamblajes dependientes, se requiere la firma porque proporciona un nombre único para el ensamblaje. Pero con los ensamblados de complementos dentro del paquete de complementos, los ensamblados se cargan en el servidor de espacio aislado mediante un mecanismo diferente, por lo que no es necesario firmar.

Nota

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 sin firmar, obtendrá un error como el siguiente: Could not load file or assembly '<AssemblyName>, Version=<Version>, Culture=neutral, PublicKeyToken=null' or one of its dependencies. A strongly-named assembly is required.

Cuando usa Microsoft Power Platform CLI (pac cli), la configuración predeterminada firmará el ensamblaje por usted. Utilice parámetro --skip-signing para no configurar la firma. Más información: Crear un proyecto de Visual Studio.

Power Platform Tools no firmará su ensamblaje de complemento por usted.

Opciones de herramientas

Puede utilizar esta función con dos opciones de herramientas:

Herramientas	Introducción
PAC CLI y herramienta de registro de complementos (PRT)	Microsoft Power Platform CLI es una CLI de desarrollador simple y única que permite a los desarrolladores e ISV realizar diversas operaciones en Microsoft Power Platform relacionadas con el ciclo de vida del entorno, la autenticación y el trabajo con entornos, paquetes de soluciones, portales, componentes de código, etc. de Microsoft Dataverse. PRT es una aplicación de Windows que puede usar para administrar el registro de ensamblajes de complementos y registrar registros de pasos de complementos. Consulte las instrucciones en: Usar PAC CLI y PRT
Usar Power Platform Tools para Visual Studio	Power Platform Tools para Visual Studio admite la rápida creación, depuración e implementación de complementos. Otras capacidades incluyen el desarrollo de actividades de flujo de trabajo personalizadas, recursos web, tecnologías de integración como puntos finales y webhooks de Azure Service, y más. Consulte las instrucciones en: Usar Power Platform Tools para Visual Studio

Utilizar PAC CLI y PRT

Utilice PAC CLI para crear un proyecto de Visual Studio y PRT para administrar sus paquetes y registrar los pasos.

Requisitos previos

Para usar esta función con PAC CLI y PRT, debe usar estas herramientas y aplicaciones.

Herramienta/Aplicación	Instrucciones
Microsoft Power Platform CLI	Debe tener la versión 1.17 o superior. El método de instalación preferido es usando Visual Studio Code. Ver Power Platform Tools. También puede descargar e instalar la versión de Windows aquí: https://aka.ms/PowerAppsCLI. Si ya ha instalado la versión de Windows, asegúrese de ejecutar pac install latest para obtener la última versión. Más información: Qué es Microsoft Power Platform CLI
PRT	Debe usar la versión 9.1.0.184 o superior. Utilice estas instrucciones para instalar la versión más reciente: Herramientas de desarrollo de Dataverse.
Visual Studio	Necesitamos Visual Studio 2019 o más reciente.

Crear un proyecto de Visual Studio

Utilice el comando PAC CLI pac plugin init para crear un proyecto de Visual Studio que optimice su proceso de desarrollo con ensamblajes dependientes.

1. Crear una carpeta para su proyecto de complemento. El nombre de esta carpeta determina el nombre del proyecto de biblioteca de Visual Studio .NET Framework Class para su complemento.

2. Abra una ventana de terminal de PowerShell en Visual Studio Code para navegar a la carpeta y ejecutar el comando pac plugin init. Para los paquetes de complementos, le recomendamos que use el parámetro --skip-signing para que sus ensamblajes de complementos no estén firmados.

   Ejemplo:

   PS E:\projects\mypluginproject> pac plugin init --skip-signing
   

Nota

Ya no es necesario firmar los ensamblajes cuando se utilizan ensamblajes dependientes. Si firma su ensamblaje, todos los ensamblajes dependientes también deben estar firmados. Más información: Firma de ensamblados

El comando pac plugin init tiene una serie de parámetros opcionales. Debe usar el parámetro --skip-signing si no desea firmar su ensamblado de complemento.

Estos comandos crean un proyecto de biblioteca de clases de Visual Studio .NET Framework basado en el nombre de la carpeta en la que se creó.

Según la configuración de su solución de Visual Studio, cuando abre el proyecto Visual Studio en Visual Studio y lo compila, se genera un paquete NuGet para el proyecto en la carpeta bin\Debug o bin\Release. Cada vez que crea su proyecto, este paquete NuGet se actualiza. El paquete NuGet es el archivo que carga con la herramienta de registro de complementos.

Agregue un ensamblaje dependiente usando NuGet

Puede agregar un paquete NuGet a su proyecto Visual Studio como lo hace normalmente. Después de compilar el proyecto, debe encontrar el ensamblaje en el paquete NuGet.

Puede usar el Explorador de paquetes NuGet para examinar el paquete NuGet.

Agregar un ensamblado dependiente sin usar NuGet

Si tiene un ensamblaje que no se distribuye como un paquete NuGet, puede agregarlo a su proyecto como lo hace normalmente. En el Explorador de soluciones, haga clic con el botón derecho sobre Dependencias y elija Agregar referencia de ensamblado.... Seleccione el ensamblado que desea agregar.

Uso de la herramienta de registro de complementos

Puede utilizar la herramienta de registro de complementos (PRT) para realizar las siguientes tareas:

1. Ver una lista de paquetes de complementos.
2. Registrar un paquete NuGet como un paquete de complemento.
3. Actualizar un paquete de complemento.
4. Eliminar paquetes de complementos.

Ver una lista de paquetes de complementos

PRT tiene una vista nueva Mostrar por paquete ver para enumerar los paquetes de complementos importados previamente:

Registrar un paquete NuGet como un paquete de complemento

PRT tiene un nuevo comando para seleccionar un paquete NuGet para importar/registrar como un paquete de complemento.

Este comando abre un cuadro de diálogo para seleccionar el paquete del complemento.

Puede seleccionar una solución existente o crear una nueva.

Desde la vista Mostrar por paquete, puede seleccionar los pasos de ensamblado y registro.

El ensamblado también está disponible dentro de la vista Mostrar por ensamblaje.

Actualizar un paquete de complemento

Mientras ve la lista de paquetes de complementos usando la vista Mostrar por paquete, seleccione el paquete de complementos y seleccione el comando Actualizar.

Este comando abre un cuadro de diálogo para que pueda seleccionar el Paquete NuGet con cambios.

Importante

Si su actualización elimina los conjuntos de complementos o los tipos que se utilizan en los registros de pasos de complementos, se rechazará la actualización. Debe eliminar manualmente cualquier registro de paso que use ensamblajes de complementos o tipos de complementos que desee eliminar con su actualización.

La versión del paquete del complemento o del ensamblaje del complemento no es un factor en ningún comportamiento de actualización. Puede actualizar las versiones de estos elementos según lo necesite.

Eliminar paquetes de complementos

Mientras ve la lista de paquetes de complementos usando la vista Mostrar por paquete, seleccione el paquete de complementos y seleccione el comando Cancelar registro.

Importante

No puede anular el registro de un paquete que tenga registros de pasos de complemento para cualquier ensamblado de complementos en el paquete. Antes de poder eliminar el paquete, primero debe anular el registro de todos los registros de pasos para los ensamblados del paquete.

Usar Power Platform Tools para Visual Studio

Utilice Power Platform Tools para Visual Studio para crear un proyecto de Visual Studio, gestionar sus paquetes y pasos de registro.

Requisitos previos

Para usar esta característica con Power Platform Tools para Visual Studio, debe tener Visual Studio 2019 e instalar Power Platform Tools para Visual Studio.

Consulte los siguientes artículos relacionados con la instalación y el uso de Power Platform Tools para Visual Studio para trabajar con complementos.

• Instalación de Power Platform Tools
• Inicio rápido: Crear un proyecto con Power Platform Tools
• Inicio rápido: Crear un complemento con Power Platform Tools

Por lo general, usará el mismo proceso para crear y administrar complementos con Power Platform Tools para Visual Studio; sin embargo, ya no es necesario firmar los ensamblajes. Más información: Firma de ensamblados.

Habilitar paquetes de complementos para Power Platform Tools

Power Platform Tools para Visual Studio proporciona varias opciones de configuración como se describe en Opciones de Power Platform Tools.

1. En Visual Studio, vaya a Herramientas > Opciones y busque Power Platform Tools.

2. Seleccione Use el paquete nuget para implementar complementos en Dataverse.

   

Nota

Cuando se selecciona esta opción, todos sus proyectos de complementos se implementarán con paquetes de complementos.

Agregue un ensamblaje dependiente usando NuGet con Power Platform Tools

Puede agregar un paquete NuGet a su proyecto Visual Studio como lo hace normalmente. Después de compilar el proyecto, debe encontrar el ensamblaje en el paquete NuGet. El paquete NuGet está en la carpeta bin\outputPackages .

Puede usar el Explorador de paquetes NuGet para examinar el paquete NuGet.

Agregar un ensamblado dependiente sin usar NuGet con Power Platform Tools

Si tiene un ensamblaje que no se distribuye como un paquete NuGet, puede agregarlo a su proyecto como lo hace normalmente. En el Explorador de soluciones, haga clic con el botón derecho sobre Dependencias y elija Agregar referencia de ensamblado.... Seleccione el ensamblado que desea agregar.

Implementar paquetes de complementos para Power Platform Tools

Para implementar su paquete de complemento, en el Explorador de solucione haga clic con el botón secundario en el proyecto de complemento y seleccione Implementar en el menú contextual.

Cuando implemente por primera vez, debería ver un mensaje en la ventana de salida que le informa que se creó el paquete del complemento:

6/22/2022 3:03:17 PM : registration of Plugin Package sample_PowerPlatformVSSolution.ExamplePlugins, 
at E:\projects\PowerPlatformVSSolution\ExamplePlugins\bin\outputPackages\PowerPlatformVSSolution.ExamplePlugins.1.0.0.nupkg was successful. 
ID allotted was 06a20e15-77f2-ec11-bb3c-000d3a892245.

Cada vez que implemente después de eso, verá un mensaje en la ventana de salida que le informa que el paquete del complemento se actualizó.

6/22/2022 3:20:14 PM : update of Plugin Package sample_PowerPlatformVSSolution.ExamplePlugins, at
E:\projects\PowerPlatformVSSolution\ExamplePlugins\bin\outputPackages\PowerPlatformVSSolution.ExamplePlugins.1.0.0.nupkg was successful.

Importante

Si su actualización elimina los conjuntos de complementos o los tipos que se utilizan en los registros de pasos de complementos, se rechazará la actualización. Debe eliminar manualmente cualquier registro de paso que use ensamblajes de complementos o tipos de complementos que desee eliminar con su actualización.

La versión del paquete del complemento o del ensamblaje del complemento no es un factor en ningún comportamiento de actualización. Puede actualizar las versiones de estos elementos según lo necesite.

Ver paquetes de complementos con Power Platform Tools

Dentro de Power Platform Explorer, puede ver los paquetes de complementos disponibles.

Eliminar un paquete de complementos con Power Platform Tools

Dentro del Power Platform Explorer, seleccione un paquete de complementos y seleccione Eliminar del menú contextual.

Importante

Eliminar un paquete, se eliminará el paquete, todos los ensamblajes dentro de él, todos los complementos dentro del ensamblaje y cualquier registro de paso de complemento para los complementos.

Crear un paquete de complementos con Power Platform Tools

Nota

Como se menciona en Implementar paquetes de complementos para Power Platform Tools, normalmente no tendrá que crear un paquete de complemento en el flujo habitual de creación de un complemento. Se creará automáticamente la primera vez que implemente el complemento si la opción Use el paquete nuget para implementar complementos en Dataverse está configurada en Visual Studio. Sin embargo, puede crear un nuevo paquete de complementos a partir de un paquete Nuget mediante los siguientes pasos.

1. Dentro del Power Platform Explorer, seleccione un Paquetes de complementos y seleccione Crear del menú contextual.

   

2. Este comando abre el cuadro de diálogo Importar nuevo paquete de complementos.

   

   Seleccione el paquete NuGet y elija a qué solución se debe agregar, o cree una nueva solución.

Actualizar un paquete de complementos con Power Platform Tools

Nota

Como se menciona en Implementar paquetes de complementos para Power Platform Tools, normalmente no tendrá que actualizar un paquete de complemento en el flujo habitual de creación de un complemento. Se actualizará automáticamente cada vez que implemente el complemento si la opción Use el paquete nuget para implementar complementos en Dataverse está configurada en Visual Studio. Sin embargo, puede actualizar un nuevo paquete de complementos a partir de un paquete Nuget siguiendo los pasos a continuación.

Dentro del Power Platform Explorer, seleccione un paquete de complementos y seleccione Actualizar del menú contextual.

Este comando abre un cuadro de diálogo para que pueda seleccionar un paquete NuGet para actualizar el paquete del complemento.

Notas de Diseño

A continuación se detallan algunas cosas a considerar al crear paquetes de complementos.

Generación del paquete NuGet

El proyecto de Visual Studio creado con pac plugin init usa las capacidades de Visual Studio que permiten generar paquetes NuGet. Este método utiliza el formato de proyecto estilo SDK. Power Platform Tools para Visual Studio usa el formato de proyecto con Estilo sin SDK.

No es necesario que utilice estas herramientas para generar un paquete NuGet con sus complementos. Puede usar cualquier capacidad que elija para generar un paquete NuGet, pero debe usar las herramientas disponibles para cargar el paquete en Dataverse.

Más información:

• Crear un paquete NuGet usando MSBuild
• Empaquetar y restaurar NuGet como objetivos de MSBuild

Qué no incluir en su paquete

Es posible que experimente un problema al crear y registrar paquetes de complementos donde el estándar de ensamblaje de Dataverse se incluye en su paquete, lo que genera un error en el momento del registro del paquete.

Importante

No incluya los siguientes ensamblajes de Dataverse en su paquete. Hacerlo resultará en un error al registrar el paquete.

Microsoft.Crm.Sdk.Proxy.dll
Microsoft.Xrm.Sdk.dll
Microsoft.Xrm.Sdk.Workflow.dll
Microsoft.Xrm.Sdk.Data.dll
Microsoft.Crm.Sdk.dll

La inclusión de cualquiera de estos ensamblados en el paquete de complemento genera el siguiente mensaje de error al registrar el paquete de complemento con Dataverse:

"PluginPackage no puede contener ensamblados incluidos en los paquetes nuget Microsoft.CrmSdk.CoreAssemblies o Microsoft.CrmSdk.Workflow".

Puede corregir esta situación siguiendo la información de este artículo, Controlar los activos de dependencia, para que estos activos de dependencia no estén incluidos en su paquete. Deberá marcar la referencia del ensamblaje usando la etiqueta <PrivateAssets> en el archivo de configuración del proyecto (.csprog).

Usando System.Text.Json

Si usa System.Text.Json, preste especial atención para agregar explícitamente una referencia al paquete NuGet System.Text.Json.

Con los ensamblados dependientes, debe incluir dependencias de paquetes NuGet para cualquier biblioteca externa que use. Es necesario incluir estas dependencias para poder hacer referencia a esos tipos en el momento del diseño. Su proyecto de biblioteca de clases también debe incluir una referencia al paquete NuGet Microsoft.CrmSdk.CoreAssemblies para que pueda consultar las interfaces esenciales para escribir su complemento.

Debido a que el paquete NuGet Microsoft.CrmSdk.CoreAssemblies depende de System.Text.Json, puede consultar tipos System.Text.Json en tiempo de diseño sin agregar explícitamente el paquete System.Text.Json NuGet. Sin embargo, el paquete System.Text.Json NuGet no está incluido en su paquete de complemento debido a esta dependencia indirecta. Debe agregarlo explícitamente como una dependencia de primer nivel para su paquete de complemento.

Actualmente, System.Text.Json es la única dependencia en el paquete NuGet Microsoft.CrmSdk.CoreAssemblies. Esta guía será válida si se agregan otras dependencias nuevas en el futuro.

Preguntas frecuentes

P: ¿Puedo seguir usando ILMerge?

R : Nunca hemos admitido ILMerge. Esta característica de ensamblajes dependientes proporciona una solución que podemos admitir con la misma funcionalidad y más. Pero nada más ha cambiado. Si ILMerge funciona para usted, puede continuar usándolo. Recomendamos usar ensamblajes dependientes porque podemos admitir esta solución.

Problemas conocidos

Los siguientes son problemas conocidos que deben resolverse antes de que los ensamblados dependientes para complementos estén disponibles de forma general.

Cambios en la clave de exportación de la API personalizada

Al importar una solución que contiene una API personalizada que usa un paquete de complemento, es posible que encuentre el siguiente error:

Lookup value <plugintypeexportkey>{guid value}</plugintypeexportkey> is not resolvable.

Este error ocurre solo para soluciones que se exportaron/generaron antes de mayo de 2023. La fecha exacta varía según la región. La solución a este problema se implementó en la región de América del Norte el 26 de mayo de 2023.

Para resolver este problema, debe actualizar el paquete del complemento, exportar/generar la solución y volver a instalarlo.

Más información: Establecer una relación con un tipo de complemento (opcional)

Generador de perfiles de complementos

Para depurar complementos que forman parte de un paquete de complementos, debe:

1. Usar la última versión de la herramienta de registro de complementos (PRT). Versión 9.1.0.184 o posterior.

   Use el comando pac CLI pac tool prt con el interruptor --update para actualizar.

2. En la carpeta que contiene el PRT, edite el archivo appsettings.json. Establezca LegacyPluginProfiler en false.

   Si ha instalado usando pac CLI, la carpeta debe ser:

   C:\Users\<you>\AppData\Local\Microsoft\PowerPlatform\PRT\9.1.0.184\tools

Más información:

• pac tool prt
• Usar el generador de perfiles de complementos

Consulte también

Use complementos para ampliar los procesos de negocio
Inicio del complemento pac CLI de PAC

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