AcumatiCares
Introduction
Les développeurs chevronnés connaissent probablement les avantages de l'utilisation d'un gestionnaire de paquets pour l'installation et la mise à jour de fichiers de référence et de bibliothèques. Ces paquets contiennent du code réutilisable qui est publié dans un référentiel central pour être consommé par d'autres programmes. L'avantage d'utiliser un tel outil est de maintenir tout code commun dans un emplacement commun, plutôt que de devoir copier les fichiers individuels et de maintenir leurs versions séparément et manuellement. Il existe de nombreux gestionnaires de paquets publics disponibles pour différents langages, frameworks et plateformes, tels que les populaires NuGet, npm, Bower et yarn. Cet article se concentre sur l'utilisation de NuGet car c'est le gestionnaire de paquets standard pour Microsoft.NET - la plateforme utilisée par Acumatica et ses personnalisations.
Depuis que j'ai commencé à développer des personnalisations dans Acumatica il y a cinq ans, et venant également d'une profonde expérience .NET et client/serveur full-stack, j'ai toujours voulu que les bibliothèques communes d'Acumatica soient disponibles sous forme de package et je me suis demandé pourquoi de tels packages n'étaient pas déjà disponibles. J'ai longtemps voulu combler ce vide moi-même afin de simplifier le référencement de ces bibliothèques pour nos propres bibliothèques d'extension de code personnalisé. J'ai récemment pu mettre cela en place pour notre société, Aktion Associates (un VAR Acumatica et Gold Certified Partner), et j'aimerais partager avec vous comment cela peut être réalisé.
Qu'est-ce que NuGet ?
NuGet est un gestionnaire de paquets .NET intégré à Visual Studio.NET - l'environnement de développement Microsoft intégré et recommandé pour la création d'extensions de code pour les personnalisations Acumatica. NuGet est utilisé pour créer et partager des packages réutilisables à partir d'un hôte public ou privé désigné. https://www.nuget.org/ est le dépôt principal de NuGet Gallery vers lequel les packages publics peuvent être publiés, et à partir duquel les projets .NET peuvent consommer. Des packages populaires tels que Json.NET - un analyseur syntaxique et un sérialiseur JSON - peuvent être trouvés ici, ainsi que des packages Microsoft.NET Framework, et bien d'autres. Au lieu de chercher sur le Web un programme d'installation ou le fichier de téléchargement spécifique dont vous avez besoin pour une bibliothèque tierce, NuGet peut être utilisé pour récupérer et installer le paquet de fichiers approprié et la version requise, simplement en le sélectionnant à partir de son hôte public. NuGet peut également être utilisé pour les paquets hébergés en privé pour une utilisation interne pour vous-même ou votre entreprise. Comme les bibliothèques Acumatica ne sont pas disponibles publiquement via nuget.org, cet article explique comment configurer ces bibliothèques communes en tant que paquets privés pour les utiliser dans vos propres projets de personnalisation.
Il existe de nombreuses autres recommandations pour l'utilisation et la configuration de NuGet, que l'on peut trouver dans sa documentation à l'adresse suivante https://docs.microsoft.com/en-us/nuget que ce qui est décrit ici.
Utiliser NuGet avec Acumatica
Pour référencer un paquetage NuGet dans le projet Visual Studio de votre propre bibliothèque étendue de personnalisation, ouvrez votre projet dans Visual Studio, cliquez avec le bouton droit de la souris sur le nœud References du projet dans l'explorateur de solutions et sélectionnez l'option de menu contextuel Manage NuGet Packages (Gérer les paquetages NuGet). Une fenêtre semblable à celle de la figure 1 s'ouvre alors, affichant les paquets NuGet déjà installés et ceux qui sont disponibles pour l'installation. Si vous recherchez "Newtonsoft.Json", par exemple, sur nuget.org, ce paquet devrait apparaître dans les résultats. Lorsque vous sélectionnez un paquet, vous pouvez alors choisir une version spécifique disponible auprès de l'hôte du paquet spécifié et l'installer. Ce paquetage apparaîtra alors sous les références de votre projet et ses fichiers pourront être référencés dans votre code étendu. La figure 2 présente un exemple de référencement de la bibliothèque Json.NET dans un projet C# Visual Studio après son installation via NuGet.
Figure 1: Le gestionnaire de paquets NuGet dans Visual Studio
Figure 2: Référencement de Json.NET après l'installation en tant que référence
L'avantage de référencer les bibliothèques via NuGet est la simplicité et la possibilité de gérer les bibliothèques et leurs versions sans avoir à le faire manuellement. Pour installer une version plus récente de la bibliothèque, il suffit d'ouvrir à nouveau le NuGet Package Manager dans Visual Studio à partir de la Figure 1, de changer la version pour une autre version disponible, et de mettre à jour. C'est ainsi que j'aimerais que les références aux bibliothèques communes d'Acumatica se comportent, et c'est désormais possible avec la solution décrite ci-dessous.
Création d'un paquetage NuGet
La première étape consiste à créer un paquet NuGet contenant les bibliothèques communes d'Acumatica. Ces bibliothèques communes sont les plus souvent utilisées lors de l'écriture d'une extension de code dans une bibliothèque externe. Elles comprennent les éléments suivants :
- PX.Common.dll
- PX.Common.Std.dll
- PX.CS.Contracts.dll
- PX.Data.dll
- PX.Objects.dll
J'aime aussi inclure PX.Data.BQL.Fluent.dll parce que je préfère utiliser la syntaxe Fluent BQL dans le code.
Le manifeste du paquet
Le manifeste d'un paquet NuGet est créé en définissant le contenu d'un fichier XML .nuspec. Le schéma d'un fichier .nuspec se trouve dans sa documentation à l'adresse https://docs.microsoft.com/en-us/nuget/reference/nuspec. Le XML suivant montre un exemple du contenu d'un fichier .nuspec (par exemple Acumatica.nuspec) pour les bibliothèques Acumatica mentionnées ci-dessus.
(contenu 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.
Création du paquet
L'étape suivante consiste à créer le paquetage à partir du manifeste .nuspec. Vous pouvez télécharger nuget.exe à partir de https://www.nuget.org/downloads. Il s'agit d'un programme en ligne de commande utilisé pour créer un package NuGet à partir d'un manifeste NuGet. Sur la ligne de commande, la syntaxe pour créer l'exemple de paquetage à l'aide de nuget.exe est la suivante :
nuget pack Acumatica.nuspec -NoPackageAnalysis
Cette syntaxe suppose que nuget.exe et Acumatica.nuspec sont accessibles dans le chemin d'accès actuel, si ce n'est pas le cas, le chemin d'accès de l'un ou des deux doit être spécifié. Le paquetage résultant de l'exemple devrait être Acumatica.PX.Main.22.100.178.nupkg.
Versions supplémentaires du paquet
Maintenant que nous disposons d'une version des bibliothèques communes d'Acumatica, vous pouvez continuer à créer des versions supplémentaires si nécessaire ou au fur et à mesure qu'elles sont publiées par Acumatica. Pour créer un nouveau paquetage pour la version suivante - 22.101.85 - vous pouvez répéter les instructions ci-dessus mais en remplaçant le numéro de version et en incluant cette version des bibliothèques. Vous devriez alors obtenir un nouveau paquetage nommé Acumatica.PX.Main.22.101.85.nupkg, et ainsi de suite.
Mise en place d'un flux NuGet
Pour qu'un paquetage soit disponible pour la référence d'un projet, il doit être publié dans un flux NuGet. Comme le paquet est destiné à votre propre consommation, vous devez créer un flux privé pour vous ou votre organisation. Un flux privé peut être un partage de fichiers ou un serveur local, ou un service d'hébergement privé distant comme Azure Artifacts ou GitHub Package Registry. Chez Aktion Associates, nous utilisons Azure DevOps comme référentiel de contrôle de source, nous utilisons donc Azure Artifacts comme hôte de flux, et c'est également ce que nous utiliserons pour les exemples de cet article.
Création du flux
Pour créer un flux NuGet dans Azure Artifacts, ouvrez le projet Azure DevOps dans lequel vous souhaitez créer un flux et choisissez Create Feed (Créer un flux) sur la page principale d'Artifacts. La boîte de dialogue illustrée à la figure 3 devrait s'ouvrir. Après avoir nommé et configuré le flux en fonction de la visibilité et de la portée de vos besoins, créez le flux.
Figure 3: Boîte de dialogue Créer un nouveau flux
Publier dans le flux
Maintenant que vous avez configuré un paquet NuGet et un flux NuGet, vous pouvez publier le paquet dans le flux. Sur la page principale d'Azure Artifacts, choisissez Connect to Feed, puis sélectionnez NuGet.exe comme type de connexion et copiez la nouvelle URL de flux affichée. Ensuite, sur la ligne de commande, la syntaxe pour publier le paquet d'exemple en utilisant nuget.exe est la suivante :
nuget push -Source <feed url> -ApiKey <any string> Acumatica.PX.Main.22.100.178.nupkg
Cette syntaxe suppose que nuget.exe et Acumatica.PX.Main.22.100.178.nupkg sont accessibles dans le chemin actuel, donc si ce n'est pas le cas, le chemin de l'un ou des deux doit être spécifié. Le paquet spécifié devrait maintenant être publié dans le flux et être accessible pour le référencement selon la configuration de votre flux. La figure 4 montre un exemple de flux privé et de paquet à l'intérieur d'Azure Artifacts après la création et la publication.
Figure 4: Flux créé dans Azure Artifacts
Utilisation de votre flux NuGet
Après avoir publié vos paquets dans votre flux NuGet, vous devriez être en mesure de référencer le paquet et la version de votre flux à l'intérieur de votre projet Visual Studio comme décrit dans Utiliser NuGet avec Acumatica. Dans le gestionnaire de paquets NuGet, ajoutez votre nouvelle source de paquets (c'est-à-dire le flux NuGet que vous avez créé) dans la boîte de dialogue Options qui s'ouvre à partir de l'icône d'engrenage située à côté de la liste déroulante Source de paquets. Après avoir ajouté le flux, le paquet publié devrait s'afficher dans la liste des paquets disponibles. Sélectionnez le paquet dans la liste, puis les différentes versions publiées devraient être disponibles dans le menu déroulant Version à choisir pour l'installation ou la mise à jour. Voir la Figure 5 pour un exemple de ce que le Package Manager affiche après avoir sélectionné le package (par exemple Acumatica.PX.Main) dans votre nouveau flux NuGet.
Figure 5: Sélection d'un paquetage et d'une version NuGet
Une fois que vous avez choisi un package et la version appropriée, l'installation ou la mise à jour crée une référence aux versions de la bibliothèque de ce package dans votre projet Visual Studio. Voir la figure 6 pour un exemple de projet C# Visual Studio après l'installation du package NuGet Acumatica.PX.Main à partir d'un flux NuGet.
Figure 6: Projet Visual Studio après l'installation du paquet
Autres bibliothèques Acumatica
Vous pouvez pousser cette solution plus loin et créer des packages NuGet supplémentaires pour d'autres bibliothèques Acumatica couramment utilisées comme PX.Api, PX.Caching, PX.Web, etc. et répéter les étapes mentionnées ci-dessus pour celles-ci. Une fois ces paquets créés et publiés dans votre flux, vous pourrez également les référencer de la même manière.
Vos propres forfaits
Si vous avez vos propres extensions de code personnalisées ou des bibliothèques communes qui sont suffisamment génériques pour être partagées entre les modules Acumatica, les projets de personnalisation, ou même les instances, cette solution est également une excellente option pour réutiliser vos propres bibliothèques étendues personnalisées Acumatica en créant des packages NuGet pour eux. Par exemple, Aktion a sa propre bibliothèque API personnalisée qui adapte l'API Acumatica existante à nos propres meilleures pratiques d'intégration et de communication, et nous la partageons entre les projets via notre propre flux privé.
Résumé
J'espère que cette solution de mise en place d'un flux NuGet pour les packages de la bibliothèque Acumatica vous sera utile, et j'aimerais que vous me disiez comment vous l'avez mise en œuvre ou adaptée à vos propres besoins. Cela demande un peu de maintenance pour maintenir les versions des paquets à jour dans votre flux, mais l'efficacité gagnée en référençant et en consommant facilement une version de bibliothèque appropriée pour vos personnalisations et vos besoins de mise à jour est substantielle et précieuse.
Bon codage !
