AcumatiCares
Introduction
Les développeurs chevronnés sont probablement conscients des avantages de l’utilisation d’un outil de gestion de paquets pour l’installation et la mise à jour de fichiers de référence et de bibliothèques empaquetés. Ces packages contiennent du code réutilisable qui est publié dans un référentiel central pour être consommé par d’autres programmes. Les avantages de l’utilisation d’un tel outil sont de maintenir tout code commun dans un emplacement commun, plutôt que d’avoir à copier les fichiers individuels et à maintenir leurs versions séparément et manuellement. Il existe de nombreux gestionnaires de paquets publics disponibles pour différentes langues, frameworks et plates-formes; tels que le populaire NuGet, npm, Bower, et le fil. Cet article se concentre sur l’utilisation de NuGet car il s’agit du gestionnaire de paquets standard pour Microsoft.NET - la plate-forme utilisée pour Acumatica et ses personnalisations.
Depuis que j’ai commencé à développer des personnalisations dans Acumatica il y a cinq ans, et que je viens également d’un arrière-plan .NET profond et client / serveur full-stack, j’ai toujours voulu que les bibliothèques communes Acumatica soient disponibles en tant que package et je me suis demandé pourquoi de tels paquets n’étaient pas déjà facilement 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 partenaire certifié Acumatica VAR et Gold), et j’aimerais partager avec vous comment cela peut être accompli.
Qu’est-ce que NuGet?
Revenez un instant en arrière, NuGet est un gestionnaire de paquets .NET intégré à Visual Studio.NET - l’environnement de développement Microsoft intégré et recommandé pour une utilisation pour créer des 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 principal référentiel NuGet Gallery sur lequel les paquets publics peuvent être publiés et à partir duquel les projets .NET peuvent consommer. Des packages populaires tels que Json.NET - un analyseur et un sérialiseur JSON - peuvent être trouvés ici, ainsi que des paquets de framework Microsoft.NET, et bien d’autres. Au lieu de rechercher 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 package de fichiers approprié et la version requise simplement en le sélectionnant dans son hôte public. NuGet peut également être utilisé pour les packages hébergés en privé pour une utilisation en interne pour vous-même ou votre entreprise. Étant donné que les bibliothèques Acumatica ne sont pas disponibles publiquement via nuget.org, cet article explique la configuration de ces bibliothèques communes en tant que packages privés à utiliser dans vos propres projets de personnalisation.
Il existe beaucoup plus de directives pour l’utilisation et la configuration de NuGet qui peuvent être trouvées dans sa documentation trouvée dans https://docs.microsoft.com/en-us/nuget que ce qui est décrit ici.
Utilisation de NuGet avec Acumatica
Pour référencer un package 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 sur le nœud Références du projet dans l’Explorateur de solutions et sélectionnez l’option de menu contextuel Gérer les packages NuGet. Cela ouvrira une fenêtre comme l’image de la figure 1, qui affiche les paquets NuGet déjà installés, et ceux disponibles pour l’installation. Si vous recherchez « Newtonsoft.Json », par exemple, à partir de nuget.org, il devrait afficher ce package dans les résultats. Lorsque vous sélectionnez un package, vous pouvez ensuite choisir une version spécifique disponible auprès de l’hôte de package spécifié et l’installer. Ce package s’affichera ensuite sous vos références de projet et ses fichiers pourront être référencés dans votre code étendu. Voir figure 2 pour un exemple de référencement de la bibliothèque Json.NET dans un projet C # Visual Studio après l’avoir installé via NuGet.
Figure 1 : Gestionnaire de paquets NuGet dans Visual Studio
Figure 2 : référencement des Json.NET après l’installation en tant que référence
L’avantage de référencer des bibliothèques via NuGet comme ceci est la simplicité et de lui permettre de gérer les bibliothèques et leurs versions sans avoir à le faire manuellement. Pour ensuite installer une version plus récente de la bibliothèque, vous ouvrez à nouveau le Gestionnaire de paquets NuGet dans Visual Studio à partir de la figure 1, modifiez la version en une autre version disponible et Mettez à jour. C’est ainsi que j’aimerais que les références de bibliothèque communes acumatica se comportent, et ce qui est maintenant possible avec la solution décrite ci-dessous.
Création d’un package NuGet
La première étape consiste à créer un package NuGet contenant des bibliothèques Acumatica communes. Ces bibliothèques courantes sont les plus souvent utilisées lors de l’écriture d’une extension de code dans une bibliothèque externe. Il s’agit notamment des éléments suivants :
- PX. Commun.dll
- PX. Common.Std.dll
- PX.CS. Contrats.dll
- PX. Données.dll
- PX. Objets.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 de package
Un manifeste de package NuGet est créé en définissant le contenu dans 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 code 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 package
L’étape suivante consiste à créer le package à partir du manifeste de package .nuspec. Vous pouvez télécharger nuget.exe à partir de https://www.nuget.org/downloads, qui est un programme de 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 package à 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, donc sinon, le chemin d’accès pour l’un ou les deux doit être spécifié. Le package résultant créé à partir de l’exemple doit être Acumatica.PX.Main.22.100.178.nupkg.
Versions de package supplémentaires
Maintenant que nous avons une version de construction des bibliothèques communes d’Acumatica empaquetées, vous pouvez continuer à créer des versions supplémentaires selon les besoins ou au fur et à mesure qu’elles sont libéré par Acumatica. Pour créer un package pour la version de build suivante ( 22.101.85 ), vous pouvez répéter les instructions ci-dessus, mais remplacer le numéro de version et inclure cette version des bibliothèques. Vous devriez alors vous retrouver avec un nouveau paquet nommé Acumatica.PX.Main.22.101.85.nupkg, et ainsi de suite.
Configuration d’un flux NuGet
Pour rendre un package disponible pour référence de projet, il doit être publié dans un flux NuGet. Étant donné que le package est destiné à votre propre consommation, vous voudrez créer un flux privé pour vous-même ou votre organisation. Un flux privé peut être un partage de fichiers ou un serveur local, ou un service d’hébergement privé distant tel que Azure Artifacts ou GitHub Package Registry. Chez Aktion Associates, nous utilisons Azure DevOps comme référentiel de contrôle de code source, nous utilisons donc Azure Artifacts comme hôte de flux, et cela sera également utilisé à titre d’exemples dans 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 Créer un flux sur la page principale Artefacts. 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 l’étendue de vos besoins, créez le flux.
Figure 3 : boîte de dialogue Créer un flux
Publication dans le flux
Maintenant que vous avez configuré à la fois un package NuGet et un flux NuGet, vous pouvez publier le package dans le flux. Sur la page principale artefacts Azure, choisissez Se connecter au flux, 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 l’exemple de package à l’aide de 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 sinon, le chemin d’accès pour l’un ou les deux doit être spécifié. Le paquet spécifié doit maintenant être publié dans le flux et être accessible pour référencement en fonction de la configuration de votre flux. La figure 4 montre un exemple de flux et de package privés dans 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 package et la version de votre flux dans votre projet Visual Studio comme décrit dans Utilisation de NuGet avec Acumatica. Dans le Gestionnaire de paquets NuGet, ajoutez votre nouvelle source de package (c’est-à-dire le flux NuGet que vous avez créé) à partir de la boîte de dialogue Options ouverte à partir de l’icône d’engrenage à côté de la liste déroulante Source du package. Après avoir ajouté le flux, le paquet publié doit s’afficher dans la liste des paquets disponibles. Sélectionnez le package dans la liste, puis les différentes versions publiées doivent être disponibles dans le menu déroulant Version pour choisir l’installation ou la mise à jour. Voir la figure 5 pour un exemple de ce que le Gestionnaire de paquets montre après avoir sélectionné le package (par exemple Acumatica.PX.Main) dans votre nouveau flux NuGet.
Figure 5 : sélection d’un package et d’une version NuGet
Une fois que vous avez choisi un package et une version appropriée, son installation ou sa mise à jour crée une référence aux versions de bibliothèque de ce package dans votre projet Visual Studio. Voir figure 6 pour un exemple d’un projet C # Visual Studio après l’installation du paquet Acumatica.PX.Main NuGet à partir d’un flux NuGet.
Figure 6 : projet Visual Studio après l’installation du package
Autres bibliothèques Acumatica
Vous pouvez aller plus loin dans cette solution et créer des packages NuGet supplémentaires pour d’autres bibliothèques Acumatica couramment utilisées comme PX. Api, PX. Mise en cache, PX. Web, etc. et répétez les étapes mentionnées ci-dessus pour ceux-ci. Une fois que ces paquets sont 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 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éutilisant vos propres bibliothèques étendues personnalisées Acumatica en créant des packages NuGet pour eux. Par exemple, Aktion dispose de notre propre bibliothèque personnalisée API 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 vous trouverez cette solution pour la mise en place d’un flux NuGet pour les paquets de bibliothèque Acumatica utile, et j’aimerais avoir de vos nouvelles et comment vous l’avez utilisé ou adapté à vos propres besoins. Il nécessite un peu de maintenance pour garder les versions de paquets mises à jour dans votre flux, mais l’efficacité acquise en référençant et en consommant facilement une version de bibliothèque appropriée pour vos personnalisations et vos besoins de mise à niveau est substantielle et précieuse.
Bon codage!
