AcumatiCares
Introducción
Los desarrolladores experimentados probablemente conozcan las ventajas de utilizar un gestor de paquetes para instalar y actualizar archivos de referencia y bibliotecas empaquetadas. Tales paquetes contienen código reutilizable que se publica en un repositorio central para ser consumido por otros programas. La ventaja de utilizar una herramienta de este tipo es que permite mantener cualquier código común en una ubicación común, en lugar de tener que copiar los archivos individuales y mantener sus versiones por separado y manualmente. Hay muchos gestores de paquetes públicos disponibles para diferentes lenguajes, frameworks y plataformas; como los populares NuGet, npm, Bower y yarn. Este artículo se centra en el uso de NuGet porque es el gestor de paquetes estándar para Microsoft.NET, la plataforma utilizada por Acumatica y sus personalizaciones.
Desde que empecé a desarrollar personalizaciones en Acumatica hace cinco años, y viniendo también de una profunda formación en .NET y cliente/servidor full-stack, siempre he querido que las bibliotecas comunes de Acumatica estuvieran disponibles como un paquete y me he preguntado por qué tales paquetes no estaban ya fácilmente disponibles. Durante mucho tiempo he querido llenar este vacío yo mismo para simplificar la referencia a estas bibliotecas para nuestras propias bibliotecas de extensión de código personalizado. Recientemente he podido configurar esto para nuestra empresa, Aktion Associates (un VAR de Acumatica y Gold Certified Partner), y me gustaría compartir con vosotros cómo se puede conseguir.
¿Qué es NuGet?
Retrocediendo un momento, NuGet es un gestor de paquetes .NET integrado con Visual Studio.NET, el entorno de desarrollo de Microsoft integrado y recomendado para su uso como autor de extensiones de código para personalizaciones de Acumatica. NuGet se utiliza para crear y compartir paquetes reutilizables desde un host público o privado designado. https://www.nuget.org/ es el repositorio principal de NuGet Gallery en el que se pueden publicar paquetes públicos y desde el que los proyectos .NET pueden consumirlos. Aquí se pueden encontrar paquetes populares como Json.NET, un analizador y serializador JSON, así como paquetes del marco Microsoft.NET y muchos otros. En lugar de buscar en la web un programa de instalación o el archivo de descarga específico que necesita para una biblioteca de terceros, NuGet se puede utilizar para recuperar e instalar el paquete adecuado de archivos y la versión requerida simplemente seleccionándolo desde su host público. NuGet también se puede utilizar para paquetes alojados de forma privada para uso interno para usted o su empresa. Dado que las bibliotecas de Acumatica no están disponibles públicamente a través de nuget.org, este artículo explica la configuración de estas bibliotecas comunes como paquetes privados para su uso en sus propios proyectos de personalización.
Hay muchas más directrices para el uso y la configuración de NuGet que se pueden encontrar en su documentación en https://docs.microsoft.com/en-us/nuget que lo que se describe aquí.
Uso de NuGet con Acumatica
Para hacer referencia a un paquete NuGet en el proyecto de Visual Studio de su propia biblioteca extendida de personalización, abra el proyecto en Visual Studio, haga clic con el botón derecho en el nodo Referencias del proyecto en el Explorador de soluciones y seleccione la opción de menú contextual Administrar paquetes NuGet. Esto abrirá una ventana como la de la imagen de la Figura 1, que muestra los paquetes NuGet ya instalados y los disponibles para su instalación. Si busca "Newtonsoft.Json", por ejemplo, en nuget.org, debería aparecer ese paquete en los resultados. Al seleccionar un paquete, puede elegir una versión específica disponible en el host de paquetes especificado e instalarla. Ese paquete aparecerá entonces bajo las referencias de su proyecto y sus archivos podrán ser referenciados dentro de su código extendido. Consulte la Figura 2 para ver un ejemplo de referencia a la biblioteca Json.NET en un proyecto de C# Visual Studio después de instalarla a través de NuGet.
Figura 1: Gestor de paquetes NuGet en Visual Studio
Figura 2: Referencia a Json.NET después de instalarlo como referencia
La ventaja de hacer referencia a las bibliotecas a través de NuGet de esta manera es la simplicidad, y lo que le permite gestionar las bibliotecas y sus versiones sin necesidad de hacerlo manualmente. Para instalar después una versión más reciente de la biblioteca, se abre de nuevo el gestor de paquetes NuGet en Visual Studio desde la figura 1, se cambia la versión por otra disponible y se actualiza. Así es como me gustaría que se comportaran las referencias a bibliotecas comunes de Acumatica, y que ahora es posible con la solución que se describe a continuación.
Creación de un paquete NuGet
El primer paso es crear un paquete NuGet que contenga bibliotecas comunes de Acumatica. Estas bibliotecas comunes son las más utilizadas cuando se escribe una extensión de código en una biblioteca externa. Incluyen las siguientes:
- PX.Common.dll
- PX.Common.Std.dll
- PX.CS.Contratos.dll
- PX.Data.dll
- PX.Objetos.dll
También me gusta incluir PX.Data.BQL.Fluent.dll porque prefiero usar la sintaxis Fluent BQL dentro del código.
Manifiesto del paquete
El manifiesto de un paquete NuGet se crea definiendo su contenido en un archivo .nuspec XML. El esquema de un archivo .nuspec se puede encontrar en su documentación en https://docs.microsoft.com/en-us/nuget/reference/nuspec. El siguiente XML muestra un ejemplo del contenido de un archivo .nuspec (por ejemplo, Acumatica.nuspec) para las bibliotecas de Acumatica mencionadas anteriormente.
(Contenido de Acumatica.nuspec)
GIST: https://gist.github.com/tlanzer-aktion/e76f8bc275cc3415344a1183666e59b5
Within this XML, the package is supplied a name (<id>) and a version (<version>), the files to reference in the destination Visual Studio project (<references>), and the source files to include in the package (<files>). Notice in this example that I’m naming the package Acumatica.PX.Main, and I’m including Acumatica build version 22.100.178 of its libraries.
Creación del paquete
El siguiente paso es crear el paquete a partir del manifiesto de paquete .nuspec. Puede descargar nuget.exe de https://www.nuget.org/downloads, que es un programa de línea de comandos utilizado para crear un paquete NuGet a partir de un manifiesto NuGet. En la línea de comandos, la sintaxis para crear el paquete de ejemplo utilizando nuget.exe es:
nuget pack Acumatica.nuspec -NoPackageAnalysis
Esta sintaxis asume que tanto nuget.exe como Acumatica.nuspec son accesibles dentro de la ruta actual, por lo que si no es así, se debe especificar la ruta para uno o ambos. El paquete resultante creado a partir del ejemplo debería ser Acumatica.PX.Main.22.100.178.nupkg.
Versiones adicionales de paquetes
Ahora que tenemos empaquetada una versión de compilación de las bibliotecas comunes de Acumatica, puedes seguir creando versiones adicionales según sea necesario o a medida que Acumatica las publique. Para crear un nuevo paquete para la siguiente versión de compilación (22.101.85), puedes repetir las instrucciones anteriores, pero sustituyendo el número de versión e incluyendo esa versión de las bibliotecas. De este modo, obtendrá un nuevo paquete denominado Acumatica.PX.Main.22.101.85.nupkg, y así sucesivamente.
Configuración de una fuente NuGet
Para que un paquete esté disponible para la referencia del proyecto, es necesario publicarlo en un feed NuGet. Dado que el paquete está destinado a su propio consumo, usted querrá crear un feed privado para usted o su organización. Un feed privado puede ser un archivo compartido o servidor local, o un servicio de alojamiento privado remoto como Azure Artifacts o GitHub Package Registry. En Aktion Associates utilizamos Azure DevOps como nuestro repositorio de control de código fuente, por lo que utilizamos Azure Artifacts como nuestro host de feeds, y esto también se utilizará para los ejemplos en este artículo.
Creación del feed
Para crear un feed NuGet en Azure Artifacts, abre el proyecto Azure DevOps en el que deseas crear un feed y selecciona Create Feed en la página principal de Artifacts. Se abrirá el cuadro de diálogo que se muestra en la Figura 3. Después de nombrar y configurar el feed de acuerdo con la visibilidad y el alcance de sus necesidades, cree el feed.
Figura 3: Cuadro de diálogo Crear nuevo feed
Publicar en el feed
Ahora que tiene un paquete NuGet y una fuente NuGet configurados, puede publicar el paquete en la fuente. En la página principal de Azure Artifacts, elija Connect to Feed, luego seleccione NuGet.exe como tipo de conexión y copie la nueva URL del feed que se muestra. A continuación, en la línea de comandos, la sintaxis para publicar el paquete de ejemplo utilizando nuget.exe es:
nuget push -Source <feed url> -ApiKey <any string> Acumatica.PX.Main.22.100.178.nupkg
Esta sintaxis asume que tanto nuget.exe como Acumatica.PX.Main.22.100.178.nupkg están accesibles dentro de la ruta actual, por lo que si no es así, se debe especificar la ruta para uno o ambos. El paquete especificado debería publicarse ahora en el feed y ser accesible para su consulta de acuerdo con la configuración de su feed. La figura 4 muestra un ejemplo de feed privado y un paquete en Azure Artifacts tras su creación y publicación.
Figura 4: Feed creado en Azure Artifacts
Uso de su fuente NuGet
Después de publicar tus paquetes en tu fuente NuGet, deberías poder hacer referencia al paquete y a la versión de tu fuente dentro de tu proyecto de Visual Studio como se describe en Uso de NuGet con Acumatica. En el Administrador de paquetes de NuGet, agrega tu nueva fuente de paquetes (es decir, la fuente de NuGet que creaste) desde el cuadro de diálogo Opciones que se abre desde el icono de engranaje junto al menú desplegable Fuente de paquetes. Después de agregar la fuente, el paquete publicado debería aparecer en la lista de paquetes disponibles. Seleccione el paquete en la lista y, a continuación, las diferentes versiones publicadas deben estar disponibles en el menú desplegable Versión para elegir la instalación o actualización. Consulte la figura 5 para ver un ejemplo de lo que muestra el gestor de paquetes después de seleccionar el paquete (por ejemplo, Acumatica.PX.Main) en su nueva fuente de NuGet.
Figura 5: Selección de un paquete NuGet y de una versión
Una vez elegido un paquete y la versión adecuada, al instalarlo o actualizarlo se crea una referencia a las versiones de biblioteca de ese paquete en el proyecto de Visual Studio. Consulte la Figura 6 para ver un ejemplo de un proyecto de C# Visual Studio después de instalar el paquete NuGet Acumatica.PX. Main desde una fuente de NuGet.
Figura 6: Proyecto de Visual Studio tras la instalación del paquete
Otras bibliotecas de Acumatica
Puede llevar esta solución más allá y crear paquetes NuGet adicionales para otras bibliotecas de Acumatica de uso común como PX.Api, PX.Caching, PX.Web, etc. y repetir los pasos mencionados anteriormente para estos. Una vez creados y publicados estos paquetes en su feed, también podrá hacer referencia a ellos de la misma manera.
Sus propios paquetes
Si tiene sus propias extensiones de código personalizadas o bibliotecas comunes que sean lo suficientemente genéricas para compartirlas entre módulos de Acumatica, proyectos de personalización o incluso instancias; esta solución también es una gran opción para reutilizar sus propias bibliotecas extendidas personalizadas de Acumatica creando paquetes NuGet para ellas. Por ejemplo, Aktion tiene nuestra propia biblioteca personalizada de API que adapta la API existente de Acumatica a nuestras propias mejores prácticas de integración y comunicación, y la compartimos entre proyectos a través de nuestro propio feed privado.
Resumen
Espero que encuentres útil esta solución para configurar un feed NuGet para paquetes de bibliotecas de Acumatica, y me encantaría saber de ti y de cómo lo has puesto en uso o adaptado a tus propias necesidades. Requiere un poco de mantenimiento para mantener las versiones de los paquetes actualizadas en tu feed, pero la eficiencia obtenida al referenciar y consumir fácilmente una versión de biblioteca adecuada para tus personalizaciones y necesidades de actualización es sustancial y valiosa.
¡Feliz codificación!
