La création et la publication d’un Nuget package sont un processus relativement simple, mais peut constituer un challenge pour la première fois. Cet article explique étape par étape comment s’y prendre.
Création du projet .NET Standard
Idéalement, votre projet doit être une bibliothèque de classes .Net Standard.
Etape 1
[x] Au démarrage de VS, sélectionnez “Créer un nouveau Projet”
[x] Choisir le type de projet Bibliothèque de classes(.NET Standard)
[x] Donner un nom à son projet
Il est toujours préférable de prendre le nom que portera votre librairie comme nom du projet mais cela n’est pas une obligation.
Je souhaite mettre en place une librairie grâce à laquelle je pourrai avoir les données sur l’épidémie de Coronavirus. Mon projet prendra comme nom Covid19Tracker.NET. Il s’agit en réalité d’un projet sur lequel j’ai déjà travaillé et dont le Nuget Package est déjà disponible. Nous verrons donc les étapes de sa mise en œuvre.
Etape 2 - Code
Une fois la première étape terminée, il ne suffit qu’à implémenter la logique derrière la libraire par l’ajout de classes et d’autres librairies.
Dans mon cas, j’ai déjà implémenté les fonctionnalités, le code source est disponible sur Github: https://github.com/egbakou/Covid19Tracker.NET.
Ci-dessous la structure de mon projet:
Vous remarquerez la présence d’un projet “Test unitaire” dans ma solution, nous reviendrons plus tard dans un autre article, sur comment intégrer des tests unitaires.
Il est à remarquer également la présence d’un fichier readme.txt dans mon projet. Il contient la documentation élémentaire de ma libraire. L’objectif en mettant en place ce fichier est de pouvoir l’ouvrir automatiquement à l’utilisateur dès qu’il installera notre Nuget Package à partir de Visual Studio. Plus bas, je reviendrai sur ce volet que beaucoup de développeurs abordent peu.
Etape 3 - Configuration des propriétés de la librairie
La configuration peut se faire de deux manières:
La méthode graphique en faisant un clic droit sur le projet et en allant dans le menu “Propriétés”, ensuite dans la table “Package”.
Par code en éditant le fichier
.csprojdu projet: Faire un double clic sur le projet dans VS pour ouvrir le fichier.
Pour cet article, je me focaliserez sur la seconde méthode.
Ci-dessous le contenu de mon fichier .csproj:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<AssemblyName>Covid19Tracker.NET</AssemblyName>
<RootNamespace>Covid19Tracker.NET</RootNamespace>
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
<Authors>Kodjo Laurent Egbakou</Authors>
<Description>.NET wrapper library around the API provided by @NovelCovid https://github.com/NovelCovid/API for tracking the global coronavirus (COVID-19, SARS-CoV-2) outbreak.</Description>
<PackageProjectUrl>https://github.com/egbakou/Covid19Tracker.NET</PackageProjectUrl>
<RepositoryUrl>https://github.com/egbakou/Covid19Tracker.NET</RepositoryUrl>
<PackageIconUrl>https://raw.githubusercontent.com/egbakou/logos/master/Covid19Tracker.NET/covid-19_4.png?raw=true</PackageIconUrl>
<Version>2.0.2</Version>
<PackageReleaseNotes>See: https://github.com/egbakou/Covid19Tracker.NET </PackageReleaseNotes>
<PackageTags> dotnet-standard, covid19-tracker covid19-data, covid-19,covid-api, nuget-package
</PackageTags>
<Copyright>Copyright 2020</Copyright>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<NeutralLanguage>en</NeutralLanguage>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
<DebugSymbols>true</DebugSymbols>
<OutputPath>bin\Debug</OutputPath>
<DefineConstants>DEBUG</DefineConstants>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
<DebugSymbols>true</DebugSymbols>
<DebugType>portable</DebugType>
<Optimize>true</Optimize>
</PropertyGroup>
<ItemGroup>
<None Include="..\..\nuget\readme.txt" PackagePath="readme.txt" Pack="true" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="Newtonsoft.Json" Version="12.0.3" />
<PackageReference Include="RestSharp" Version="106.11.3" />
</ItemGroup>
</Project>
Les propriétés suivantes sont requises pour créer un package:
PackageId, l’identifiant du package, qui doit être unique sur nuget.org. S’il n’est pas spécifié, sa valeur par défaut est celle de la propriétéAssemblyName.Version, un numéro de version spécifique sous la forme Major.Minor.Patch[-Suffix] où -Suffix identifie pre-release versions. Sa valeur par défaut est 1.0.0.Authors, informations sur l’auteur et le propriétaire. La valeur par défaut est celle deAssemblyName.Company, Le nom de votre société. S’il n’est pas spécifié, la valeur par défaut est également celle deAssemblyName.
Les propriétés facultatives mais très utilées: Quelques unes
Description, elle permet de décrire ce que fait notre projet.GeneratePackageOnBuild, Indique si le Nuget Package de notre projet doit être généré ou pas(true or false) lors d’une opération de Build.RepositoryUrl, le lien du dépôt de votre projet.PackageProjectUrl, l’URL d’accès au projet (Code source ou pas)PackageIconUrl, l’URL du logo de votre librairie.PackageTags, mots-clés séparés par des virgules permettant de décrire le projet(similaire aux hashtag).GenerateDocumentationFile, Indique si la documentation au format xml doit être générée.Copyright
Plus haut, je vous parlais de la présence du fichier readme.txt dans mon projet. Comment l’ouvrir automatiquement à tout utilisateur qui vient d’installer notre librairie dans son projet ?
Il suffit d’inclure le Path du fichier readme.txt dans un ItemGroup comme suit:
<ItemGroup>
<None Include="..\..\nuget\readme.txt" PackagePath="readme.txt" Pack="true" />
</ItemGroup>
Une fois les configurations effectuées, nous allons à présent générer notre Nuget Package.
Génération du package
Etape 4: Exécution de la commandepack
- Assurez-vous que la configuration de votre projet est en mode
Release. - Effectuez un clic droit sur le projet, ensuite sélectionnez la commande
Packdans le menu. - Visual Studio crée pour nous le fichier .nupkg. Examinez la fenêtre sortie pour plus de détails. Elle contient le chemin d’accès au fichier du package.
Ceci peut être fait également en exécutant la commande dotnet pack ou en effectuant un build du projet.
A l’intérieur du dossier netstandard2.0, se trouve la documentation au format xml.
Notre librairie est déjà prête pour utilisation. S’il s’agit d’un usage privé(personnel ou en entreprise), il est conseillé d’intégrer directement le fichier .nupkg aux projets qui en feront référence(utilisation locale). Dans le cas contraire, le mettre en ligne pour permettre au autres développeurs de pouvoir facilement la télécharger. A cet effet, la plateforme https://nuget.org est dédiée à cela.
Publication de la librairie sur nuget.org
Une fois que nous avions le fichier .nupkg, nous essayerons de la mettre sur nuget.org à l’aide de CLI nuget.exe ou dotnet.exe en utilisant la clé API acquise auprès de nuget.org.
NB: Nous pouvons charger directement le fichier .nupkg sur https://nuget.org pour finir le processus de publication et ainsi ignorer les étapes suivantes mais je ne manquerai pas de vous montrer toutes les possibilités.
Etape 5: Obtention de la clé de publication
- Connectez-vous à votre compte nuget.org ou créez en une si vous n’en avez pas.
- Sélectionnez votre nom d’utilisateur (en haut à droite), puis cliquez sur “API Keys”.
- Sélectionnez “Create”, donnez un nom à votre clé, choisir Scopes>Push, entrez “**” pour le Glob Pattern, puis cliquer sur “Create*”.
Enregistrez votre clé à un emplacement sécurisé car vous n’aurez plus la possibilité de la copier ultérieurement. Si vous revenez plus tard sur la page des clés, vous devez générer à nouveau une autre clé. Vous pouvez également supprimer vos clés si vous ne souhaitez plus envoyer de packages via l’outil CLI.
Etape 6: Publication
Pour cette étape , assurez-vous d’avoir installer l’outil nuget cli sur votre machine.
Lien de téléchargement: https://www.nuget.org/downloads
Une fois téléchargé, Il suffira de mettre le fichier nuget.exe à un emplacement tout en pointant la variable d’environnement dessus.
Tapez la commande nuget en ligne de commande pour vérifier si votre variable d’environnement est correctement configurée.
Commande de publication:
dotnet nuget push chemin_vers_le package clé_api –s https://api.nuget.org/v3/index.json
chemin_vers_le package: c’est le chemin vers le fichier
.nupkg;clé_api: est la clé que nous avions récemment générée.
Concrètement dans mon cas la commande devient:
dotnet nuget push Covid19Tracker.2.0.2.nupkg oy2gjga8pl3mvn2alksyq8wcs9yggjg4exypy3bhxy6w6x –s https://api.nuget.org/v3/index.json
Une fois la librairie publiée, allez sur https://www.nuget.org et accédez à votre compte pour voir l’effectivité de la publication.
Lorsque notre librairie est vérifiée et validée par nuget.org, nous pouvons l’installer à présent dans un autre projet via le Package Manager de VS.
Félicitations, votre package a bien été déployé sur NuGet.
Dans un prochain article, je vous montrerai comment automatiser la publication des Nuget Packages grâce à Github Actions pour ainsi gagner en temps.
Quelques précisions
Les termes Nuget Package, librairie et Plugin utilisés dans cet article signifient la même chose.
Ressources
👉 https://github.com/egbakou/Covid19Tracker.NET le lien vers le projet complet sur Github.
N’hésitez pas à me contacter via le formulaire de contact ou par mail.🙏
Commentaires