Création et publication de votre premier package NuGet

Les packages NuGet sont un élément fondamental de .NET et aident à accélérer le développement sans avoir à réinventer la roue. Apprenez dans cet article comment créer votre propre package NuGet, publiez-le et utilisez-le dans vos applications.

Les packages NuGet offrent une large gamme de fonctionnalités pour accélérer le développement Web ASP.NET Core. Avec eux, les développeurs peuvent accéder à tout ce dont ils ont besoin en quelques clics ou commandes.

Dans cet article, nous verrons comment fonctionnent les packages NuGet, puis implémentez notre package, le publierons sur le site officiel de NuGet et l’installer dans une application Web.

📦 Qu’est-ce que Nuget?

Nuget est un mécanisme par lequel les développeurs peuvent créer, partager et consommer des ressources de code utiles à diverses fins.

Ce code est regroupé en «packages» qui contiennent le contenu nécessaire aux projets qui le consomment, tels que les DLL, les algorithmes, les fichiers de configuration, les ressources statiques et les métadonnées.

En termes simples, un package NuGet est un fichier zip avec l’extension .nupkg qui rassemble des DLL (code déjà compilé), des fichiers auxiliaires connexes et un manifeste avec des informations importantes telles que la version du package, ses dépendances et les détails de l’auteur.

🛠️ Comment fonctionne NuGet?

1. Création de packages

Un développeur crée du code dans un projet (généralement une bibliothèque de classe) et regroupe le code compilé (DLL), prenant en charge les fichiers et un manifeste (.nuspec) dans un package, avec une extension .nupkg.

2. Publication

Ce package est publié dans un référentiel NuGet, comme nuget.orgou à un référentiel privé (comme un flux de sociétés interne ou des artefacts Azure).

3. Consommation

Un autre développeur ajoute le package à leur projet via Visual Studio, par CLI (dotnet add package) ou manuellement en modifiant le fichier .csproj. NuGet résout automatiquement les dépendances et télécharge les packages nécessaires.

4. Restauration

Lorsque le projet est construit ou restauré, NuGet télécharge tous les packages et dépendances nécessaires, puis les met en cache localement pour réutiliser.

5. Gestion de la version

Nuget vous permet de spécifier des versions exactes (1.0.0), des gammes (1.0.1) ou d’accepter la dernière version compatible, qui aide à maintenir la stabilité du projet et facilite les mises à niveau contrôlées.

L’image ci-dessous résume ce processus:

⛏️⬆️ Création et publication d’un package Nuget

Maintenant que nous comprenons les bases de ce qu’est un package NuGet et comment cela fonctionne, nous verrons dans la pratique comment implémenter une fonctionnalité qui peut être partagée entre les applications .NET via le gestionnaire de package NuGet.

Imaginez que vous développez le backend d’un blog, mais vous aimeriez que les principales fonctionnalités soient réutilisables. De cette façon, chaque fois que vous devez créer un nouveau blog, vous n’auriez pas besoin de réécrire le même code.

Pour mettre cela en pratique, nous créerons le package NuGet, le publierons puis créerons un projet pour le blog et utiliserons la fonction nouvellement créée.

Vous pouvez consulter le projet complet couvert dans le message, dans ce référentiel GitHub: Création d’un package Nuget.

Ainsi, pour créer l’application de base, vous pouvez utiliser la commande ci-dessous dans le terminal:

dotnet new classlib -n Dango.BlogUtils

Notez que le modèle utilisé est classlibqui est généralement utilisé pour créer des classes avec des fonctionnalités partagées comme les packages NuGet. Aussi, le nom de la bibliothèque Dango.BlogUtilss’inspire du dango sucré japonais, fabriqué à partir de boules de riz collantes et généralement servie sur des brochettes.

Vous pouvez, bien sûr, choisir le nom que vous aimez. Le point principal ici est de souligner l’importance d’utiliser des noms créatifs lors de la création de nouvelles bibliothèques. Un bon nom rend non seulement votre code plus identifiable et organisé, mais il permet également à d’autres développeurs de l’adopter plus facilement, surtout si vous prévoyez de le partager ou de le publier en tant que package.

Maintenant, ouvrez le projet et, à l’intérieur, créez une nouvelle classe appelée SlugGen. À l’intérieur, ajoutez le code suivant:

using System.Globalization;
using System.Text;
using System.Text.RegularExpressions;

namespace Dango.BlogUtils;

public static class SlugGen
{
    public static string GenerateSlug(string input)
    {
        if (string.IsNullOrWhiteSpace(input))
            return string.Empty;

        string normalized = input.Normalize(NormalizationForm.FormD);
        var stringBuilder = new StringBuilder();

        foreach (var c in normalized)
        {
            var unicodeCategory = CharUnicodeInfo.GetUnicodeCategory(c);
            if (unicodeCategory != UnicodeCategory.NonSpacingMark)
                stringBuilder.Append(c);
        }

        string result = stringBuilder.ToString().Normalize(NormalizationForm.FormC);
        result = Regex.Replace(result.ToLowerInvariant(), @"[^a-z0-9\s-]", "");
        result = Regex.Replace(result, @"\s+", "-").Trim('-'); 
        result = Regex.Replace(result, @"-+", "-");

        return result;
    }
}

Jetons un coup d’œil à ce code. Tout d’abord, nous définissons une classe statique appelée SlugGenqui est responsable de la génération de limaces à partir d’une chaîne d’entrée. Un limace est une version simplifiée «adaptée à l’URL» du texte, souvent utilisée dans les adresses de page Web pour représenter des titres d’articles ou des noms de ressources. Un exemple courant d’une limace:

• Texte brut: Bonjour, bienvenue sur le blog!
• Slug: bonjour-welcome-t-the-blog

La méthode principale, GenerateSlugprend une chaîne en tant que paramètre et renvoie une autre chaîne, qui est la limace correspondante. Tout d’abord, un chèque est fait pour voir si l’entrée est nul, vide ou composée uniquement d’espace. Si tel est le cas, la méthode renvoie une chaîne vide, en évitant le traitement inutile.

Le texte est ensuite normalisé à l’aide de la forme FormD, qui sépare les caractères accentués de leur forme de base. Cela permet de supprimer les caractères qui appartiennent à la catégorie demarchage de non-espace (tels que les accents) du texte. Cette suppression est effectuée à l’aide de StringBuilder, qui stocke uniquement les caractères considérés comme pertinents.

La chaîne est ensuite à nouveau normalisée, cette fois en utilisant FormC, pour reconstruire les caractères dans leur forme canonique la plus compacte. Avec cette version nettoyée de la chaîne, les caractères sont entièrement convertis en minuscules, en supprimant tous les caractères qui ne sont pas des lettres, des nombres, des espaces ou des traits d’essai, en utilisant une expression régulière.

Ensuite, les espaces blancs sont remplacés par des traits de traits, et tous les traits de traits au début ou à la fin de la chaîne sont supprimés. Enfin, plusieurs tirets consécutifs sont remplacés par un seul trait d’union. Le résultat final est une limace propre et lisible qui convient à une utilisation dans des URL conviviales.

Maintenant, notre package est prêt à être publié.

Publication du package sur Nuget Org

La première étape avant la publication consiste à générer une version, qui contiendra les fichiers binaires emballés. Pour ce faire, ouvrez simplement un terminal dans la racine de l’application et exécutez la commande suivante:

dotnet pack -c Release

Cette commande créera le package et l’enregistrera dans: bin/Release/Dango.BlogUtils.1.0.0.nupkg.

Maintenant, nous devons configurer le site Web de Nuget Org. Ensuite, allez à l’adresse: www.nuget.org. Connectez-vous avec un compte Microsoft, puis cliquez sur votre nom d’utilisateur et cliquez sur l’option «API Keys»:

Ensuite, cliquez sur le menu Créer et remplissez les données:

• Nom de clé: Ce sera le nom de la clé API, alors utilisez un nom descriptif.
• Vérifiez l’option: Poussez les nouveaux packages et versions de package.
• Modèle GLOB: Cette propriété indiquera quels espaces peuvent être publiés, dans cet exemple, en utilisant le nom Dango.* signifie uniquement des packages qui commencent par le nom Dango. peut être publié.

Enfin, cliquez sur Créer.

N’oubliez pas de copier la clé API nouvellement créée et de le laisser dans un endroit accessible. Nous en aurons besoin plus tard.

Nous pouvons maintenant pousser le package vers l’hôte NuGet. Pour ce faire, exécutez simplement la commande suivante dans un terminal à la racine de l’application.

dotnet nuget push bin/Release/Dango.BlogUtils.1.0.0.nupkg \
--api-key YOUR_API_KEY\
--source https://api.nuget.org/v3/index.json

Remplacer YOUR_API_KEY Avec la clé API que vous venez de créer.

Si tout se passe bien, vous devriez voir quelque chose comme ça dans le terminal:

Pushing Dango.BlogUtils.1.0.0.nupkg to 'https://api.nuget.org/v3/index.json'... 
PUT https://www.nuget.org/api/v2/package/ 
Created https://www.nuget.org/api/v2/package/ 5716ms
Your package was pushed.

Utilisation du package NuGet dans une application Web

À ce stade, le package est prêt à être téléchargé et installé. Donc, pour tester cela, nous créerons une API simple qui recevra n’importe quel texte et renverra la limace correspondante.

Ainsi, vous pouvez utiliser la commande suivante pour créer le projet API:

dotnet new web -o SweetNewsBlog

Ensuite, ouvrez l’application et dans la racine du projet, exécutez la commande ci-dessous dans un terminal pour télécharger le package.

dotnet add package Dango.BlogUtils

Après avoir exécuté la commande, vous pouvez vérifier si elle a été téléchargée avec succès en accédant au code du fichier .csproj, qui aura le contenu suivant:

Ensuite, ouvrez la classe de programme et remplacez le code existant par ce qui suit:

using Dango.BlogUtils;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapPost("/slug", (SlugRequest request) =>
{
    var slug = SlugGen.GenerateSlug(request.Text);
    return Results.Ok(new { slug });
});

app.Run();

public record SlugRequest(string Text);

Notez que, ici, nous avons créé un point de terminaison qui reçoit tout texte et utilise le GenerateSlug() Méthode du package NuGet et renvoie la limace générée.

🧪 Tester l’application

Testons maintenant si la mise en œuvre du package et son utilisation fonctionnent. Pour ce faire, exécutez l’application (dotnet run), puis faire une demande au point final localhost:PORT/slugpassant n’importe quel texte dans le corps de la demande comme dans l’exemple ci-dessous:

{
   "text": "Writing Clean Code in ASP.NET Core"
}

Ensuite, vous obtiendrez le texte transformé en limace en tant que retour:

{
    "slug": "writing-clean-code-in-aspnet-core"
}

De cette façon, nous avons une application fonctionnelle consommant le package NuGet créé et publié sur nuget.org.

💡 Conclusion et pensées finales

Les forfaits NuGet permettent aux entreprises et aux développeurs individuels de partager leurs idées via des composants réutilisables, accélérant le développement d’applications Web.

Considérez une tâche commune comme désérialiser les données JSON, ce qui est courant dans les systèmes backend modernes. Sans Nuget, vous devrez implémenter manuellement cette fonctionnalité chaque fois que vous en avez besoin.

Bien qu’il existe des alternatives, telles que l’utilisation de fichiers .dll, aucune n’offre le même niveau d’efficacité, de commodité et d’intégration que NuGet. Avec des milliers de packages facilement disponibles et un soutien continu dans les environnements de développement comme Visual Studio, NuGet simplifie considérablement la gestion des dépendances et favorise les meilleures pratiques dans le développement de logiciels.

Dans cet article, nous avons créé un package NuGet à partir de zéro et vu comment le publier nuget.org. Ensuite, nous avons créé une API Web, ajouté le package et testé la fonctionnalité de génération de limaces.

J’espère que ce post vous a aidé à comprendre comment fonctionnent les packages NuGet et comment tirer parti de ces fonctionnalités pour créer et publier votre propre package.