Meilleures pratiques de création de packages

  • Article

Cette aide est destinée à donner aux auteurs de packages NuGet une référence simplifiée pour créer et publier des packages de haute qualité. Il se concentrera principalement sur les meilleures pratiques spécifiques aux packages, telles que les métadonnées et l’emballage. Pour obtenir des suggestions plus détaillées sur la génération de bibliothèques de haute qualité, consultez l’aide sur les bibliothèques open source .NET.

Types de suggestions

Chaque article présente quatre types de suggestions : À faire, Envisager, Éviter et À ne pas faire. Le type de suggestion indique si celle-ci doit être suivie ou non.

Vous devez presque toujours suivre une suggestion À faire. Par exemple :

✔️ À FAIRE : Incluez une brève description de votre package qui décrit ce qu’il fait.

En revanche, les recommandations Envisager doivent généralement être appliquées, mais il existe des exceptions à la règle qui sont fondées :

✔️ À ENVISAGER : Choisir un nom de package NuGet avec un préfixe qui répond à la réservation du préfixe des critères NuGet.

Les suggestions Éviter indiquent quelque chose qui n’est généralement pas une bonne idée, mais enfreindre les règles peut parfois avoir du sens :

❌ ÉVITEZ les références de package NuGet qui exigent une version précise.

Et enfin, les suggestions À ne pas faire désignent quelque chose que vous ne devez presque jamais faire :

❌ À NE PAS FAIRE : utiliser de la propriété de métadonnées LicenseUrl.

Créer un package NuGet

La dernière méthode recommandée pour créer un package NuGet provient d’un projet de style SDK. Les propriétés des projets de style SDK, y compris la version cible de .Net Framework et les métadonnées de package, sont définies dans le fichier projet.

Créez un package à partir de votre projet de style SDK en définissant les propriétés et l’empaquetage requis dans Visual Studio ou dans l’interface CLI dotnet.

✔️ À faire : créez un projet de style SDK et créez (pack) votre package à l’aide de Visual Studio ou de l’interface CLI dotnet.

Pour obtenir de l’aide plus détaillée sur la création de packages, notamment les outils clients nécessaires, l’exemple de fichier projet et les commandes, consultez Créer un package NuGet à l’aide de l’interface CLI dotnet.

Pour vous aider à déterminer les frameworks .NET à cibler, consultez nos dernières aides à propos du ciblage multiplateforme.

Métadonnées de package

Les métadonnées sont un composant fondamental pour tout package NuGet. La qualité des métadonnées peut influencer considérablement la détectabilité, la facilité d’utilisation et la fiabilité de votre package.

Dans Visual Studio, la méthode recommandée pour spécifier les métadonnées du package consiste à accéder au package de propriétés > Projet > [Nom du projet].

Les éléments de métadonnées de package peuvent également être spécifiés directement dans le fichier projet.

Vous trouverez ci-dessous un tableau qui mappe et décrit les éléments de métadonnées de package disponibles :

Nom de propriété Visual Studio Project file/ MSBuild nom de propriété Nom de propriété nuspec Description
Package id PackageId id Identificateur ou nom de package.
Package version PackageVersion version Version du package NuGet.
Authors Authors authors Liste d’auteurs de packages séparée par des virgules, souvent à l’aide du « nom pretty » de l’individu ou d’une organisation
Description Description description Description du package.
Copyright Copyright copyright Détails de copyright pour le package.
Project URL PackageProjectUrl projectUrl URL de la page d’accueil du projet.
Icon File PackageIcon icon Chemin d'accès du fichier image de l’icône du package.
README PackageReadmeFile readme Chemin d’accès au fichier Markdown LISEZMOI du package.
Repository URL RepositoryUrl repository url URL du référentiel à partir duquel le package a été généré.
Repository type RepositoryType repository type Type de référentiel vers lequel l’URL du dépôt pointe (par exemple, « git »).
Tags PackageTags tags Liste délimitée par des espaces des balises et mots clés qui décrivent le package. Les balises sont utilisées lors de la recherche des packages.
Release notes PackageReleaseNotes releaseNotes Description des modifications apportées dans cette version du package.
Licensing - Expression PackageLicenseExpression license type="expression" Expression de licence SPDX.
Licensing - File PackageLicenseFile license type="file" Chemin d’accès à un fichier de licence personnalisée.

ID du package

Si vous publiez un nouveau package :

✔️ À FAIRE : choisissez un ID de package unique et clairement différencié des packages existants sur NuGet.org.

Vous pouvez vérifier si un ID de package est unique et différent en recherchant l’ID sur NuGet.org ou en vérifiant si le lien suivant existe déjà : https://www.nuget.org/packages/<nom du package>.

✔️ À ENVISAGER : Choisir un nom de package NuGet avec un préfixe qui répond à la réservation du préfixe des critères NuGet.

La réservation de l’ID de préfixe de votre package vous permet d’obtenir la coche de vérification : image

Pour en savoir plus, consultez la documentation concernant la réservation de préfixe d’ID de package.

Version du package

✔️ À ENVISAGER : utiliser SemVer pour gérer les versions du package NuGet.

Essentiellement, cela signifie utiliser le format Major.Minor.Patch[-prerelease].

✔️À FAIRE : publier un package en tant que package version préliminaire s’il s’agit d’un package instable ou un aperçu.

Consultez le guide pour la gestion des versions de la bibliothèque .NET afin d’obtenir une aide plus avancée.

Auteurs

✔️ À FAIRE : Utiliser le champ auteur pour le « nom pretty » de votre organisation ou pour vous-même.

Par exemple, si mon nom d’utilisateur NuGet.org est « jdoe », l’utilisation de « Jane Doe » pour le champ auteur peut aider le consommateur à me reconnaître en tant qu’auteur. Si le nom d’utilisateur NuGet.org de mon organisation est « ContosoToolkit », l’utilisation de « Contoso Corporation » peut être plus reconnaissable et inspirer davantage de confiance chez le consommateurs.

Description

✔️ À FAIRE : Inclure une brève description (jusqu’à 4 000 caractères) pour décrire votre package.

Les descriptions de package sont l’un des champs les plus importants affichés dans la recherche NuGet et sont probablement la première chose que les consommateurs potentiels lisent pour déterminer si un package est approprié pour eux.

✔️À FAIRE : Ajoutez une mention de droits d’auteur à votre package en écrivant ce qui suit « Droit d’auteur (c) <nom/ nom de la société><année>. »

Une mention de droits d’auteur indique que votre travail ne peut pas être copié sans votre autorisation. L’inclusion d’une mention de droits d’auteur dans votre package est facile à réaliser et ne fait pas de mal !

Exemple : Droits d’auteur (c) Contoso 2020

URL du projet

✔️ À FAIRE : Inclure un lien vers un projet, un référentiel ou un site web d’entreprise associé.

Votre site de projet doit avoir tout ce dont les utilisateurs ont besoin savoir à propos de votre package. Ce site sera probablement l’endroit où les utilisateurs chercheront de la documentation.

Icon

✔️ À ENVISAGER : inclure une icône avec votre package pour permettre aux clients de le différencier visuellement. Il s’agit d’un ajout relativement petit qui peut améliorer la perception de la qualité du package.

Les icônes peuvent être spécifiques à des packages en particulier ou être un logo de marque.

✔️ À FAIRE : Utiliser une image au format 128x128 avec un arrière-plan transparent (PNG) pour optimiser l’affichage.

NuGet met automatiquement votre image à l’échelle sur le client sur où elle est affichée.

❌ À NE PAS FAIRE : utiliser de la propriété déconseillée de métadonnées IconUrl.

LISEZ-MOI

✔️ À FAIRE : Ajouter un fichier Markdown LISEZ-MOI qui fournit une vue d’ensemble de ce que fait votre package et comment démarrer avec celui-ci.

Un package README améliore considérablement la perception de la qualité de votre package et vous permet de fidéliser de nouveaux utilisateurs. Envisagez également d’afficher un aperçu de votre fichier LISEZ-MOI avant de le charger ! Pour plus d’informations, découvrez Comment inclure un fichier Lisez-moi dans votre package NuGet.

Type de référentiel et URL

✔️ À ENVISAGER : configurer Source Link pour ajouter automatiquement des métadonnées de contrôle de code source à vos packages NuGet et faire en sorte que votre bibliothèque soit plus simple à déboguer.

Source Link ajoute automatiquement des métadonnées Repository URL et Repository Type au package de métadonnées. Il ajoute également la validation spécifique associée à la version de votre package.

Balises

✔️ À FAIRE : inclure plusieurs balises avec des termes clés liés à votre package pour améliorer la détectabilité.

Les balises sont prises en compte dans l’algorithme de recherche de NuGet.org. Elles sont particulièrement utiles pour les termes qui ne figurent pas dans l’ID de package, mais qui sont tout de même pertinents.

Par exemple, si j’ai publié un package pour journaliser des chaînes dans la console, j’inclurais alors : « journalisation, journal, console, chaîne, sortie »

Notes de publication

✔️ À FAIRE : inclure des notes de publication lors de chaque mise à jour en décrivant les modifications apportées.

Bien qu’il n’existe aucun format spécifique requis pour les notes de publication, nous vous recommandons d’inclure les choses suivantes :

  1. Dernières modifications
  2. Nouvelles fonctionnalités
  3. Résolution des bogues

Si vous effectuez déjà le suivi des notes de publication ou un journal des modifications dans votre référentiel, vous pouvez également inclure un lien vers le fichier approprié.

Gestion des licences

✔️ À FAIRE : inclure une expression de licence ou un fichier de licence dans votre package.

Important

Un projet sans licence est défini par défaut sur droit d’auteur exclusif, ce qui signifie que vous n’avez pas accordé à personne l’autorisation d’utiliser votre projet.

❌ À NE PAS FAIRE : utiliser de la propriété déconseillée de métadonnées LicenseUrl.

Cela présente une ambiguïté juridique, car les modifications de licence à l’URL modifient rétroactivement la licence affichée dans les versions de package précédentes.

Si votre package est open source

✔️ À FAIRE : choisir une licence open source pour rendre votre package open source également.

« Les licences open source sont des licences qui se conforment à la définition Open Source. Autrement dit, elles permettent aux logiciels d’être utilisés, modifiés et partagés librement. » – Open-Source Initiative. Pour en savoir plus sur les logiciels open source et sur l’Open-Source Initiative, consultez https://opensource.org/.

✔️ À ENVISAGER : inclure une expression de licence dans votre package.

Les expressions de licence sont mises en avant et rendent plus évident pour les consommateurs s’ils peuvent utiliser votre package ou si la licence a changé.

Remarque

NuGet.org accepte uniquement les expressions de licence pour les licences approuvées par l’Open-Source Initiative ou la Free Software Foundation.

Si votre package n’est pas open source

✔️ À FAIRE : inclure un fichier de licence dans votre package.

Tout fichier de licence (.txt ou .md) peut être ajouté à votre package, y compris les licences non standard.