Créer un package NuGet utilisant MSBuild

  • Article

Lorsque vous créez un package NuGet à partir de votre code, vous compressez cette fonctionnalité dans un composant qui peut être partagé et utilisé avec d’autres développeurs. Cet article décrit comment créer un package à l’aide de MSBuild. MSBuild est préinstallé avec chaque charge de travail Visual Studio qui contient NuGet. Vous pouvez également utiliser MSBuild via l’interface CLI dotnet avec dotnet msbuild.

Pour les projets .NET Core et .NET Standard qui utilisent le format de style SDK, et tout autre projet de style SDK, NuGet utilise les informations dans le fichier projet directement pour créer un package. Pour un projet de style non SDK qui utilise <PackageReference>, NuGet utilise également le fichier projet pour créer un package.

La fonctionnalité de compression est disponible par défaut dans les projets de style SDK. Pour les projets PackageReference de style non SDK, vous devez ajouter le package NuGet.Build.Tasks.Pack aux dépendances du projet. Pour plus d’informations sur les cibles de pack MSBuild, consultez Commandes pack et restore NuGet comme cibles MSBuild.

La commande qui crée un package, msbuild -t:pack, est fonctionnellement équivalente à dotnet pack.

Important

Cette rubrique concerne les projets de style SDK, en général les projets .NET Core et .NET Standard, et aux projets de style non SDK qui utilisent PackageReference.

Définir des propriétés

Les propriétés suivantes sont requises pour créer un package.

  • PackageId, l’identificateur du package, qui doit être unique dans toute la galerie qui héberge le package. Si elle n’est pas spécifiée, la valeur par défaut est AssemblyName.
  • Version, un numéro de version spécifique au format version_principale.version_secondaire.version_corrective [-suffixe] où -suffixe identifie les versions préliminaires. Si elle n’est pas spécifiée, la valeur par défaut est 1.0.0.
  • Titre du package tel qu’il doit apparaître sur l’hôte (par exemple nuget.org)
  • Authors, informations sur l’auteur et le propriétaire. Si elle n’est pas spécifiée, la valeur par défaut est AssemblyName.
  • Company, le nom de votre entreprise. Si elle n’est pas spécifiée, la valeur par défaut est AssemblyName.

En outre, si vous empaqueter des projets de style non SDK qui utilisent PackageReference, les éléments suivants sont requis :

  • PackageOutputPath, le dossier de sortie du package généré lors de l’appel du pack.

Dans Visual Studio, vous pouvez définir ces valeurs dans les propriétés du projet (cliquez avec le bouton droit sur le projet dans Explorateur de solutions, choisissez Propriétés, puis sélectionnez l’onglet Package). Vous pouvez également définir directement ces propriétés dans les fichiers projet (.csproj).

<PropertyGroup>
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>your_name</Authors>
  <Company>your_company</Company>
</PropertyGroup>

Important

Donnez au package un identificateur unique sur nuget.org ou dans la source de package que vous utilisez.

L’exemple suivant montre un fichier projet simple et complet avec ces propriétés incluses.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>ClassLibDotNetStandard</PackageId>
    <Version>1.0.0</Version>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
  </PropertyGroup>
</Project>

Vous pouvez également définir les propriétés optionnelles, telles que Title, PackageDescription et PackageTags, comme cela est décrit dans les cibles de packages MSBuild, Contrôle des ressources de dépendances et Propriétés de métadonnées NuGet.

Remarque

Dans le cas des packages destinés à une utilisation publique, faites particulièrement attention à la propriété PackageTags, car les balises aident les utilisateurs à trouver vos packages et à comprendre leur rôle.

Pour plus d’informations sur la déclaration des dépendances et la spécification des numéros de version, consultez Références de package dans les fichiers projet et Gestion des versions de package. Il est également possible de faire remonter les ressources des dépendances directement dans le package à l’aide des attributs <IncludeAssets> et <ExcludeAssets>. Pour plus d’informations, consultez Contrôle des ressources des dépendances.

Si vous le souhaitez, renseignez le champ description

La description facultative du package s’affiche sous l’onglet LISEZMOI de la page nuget.org du package. La description extrait du <Description> dans le fichier projet ou du $description dans le fichier .nuspec.

L’exemple suivant montre un Description dans le fichier .csproj pour un package .NET :

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Azure.Storage.Blobs</PackageId>
    <Version>12.4.0</Version>
    <PackageTags>Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable</PackageTags>
    <Description>
      This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data.
      For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md
      in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt
      Microsoft Azure Storage quickstarts and tutorials - https://learn.microsoft.com/azure/storage/
      Microsoft Azure Storage REST API Reference - https://learn.microsoft.com/rest/api/storageservices/
      REST API Reference for Blob Service - https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

Choisir un identificateur de package unique et définir le numéro de version

L’identificateur de package et le numéro de version identifient de façon unique le code exact contenu dans le package.

Suivez ces meilleures pratiques pour créer l’identificateur de package :

  • L’identificateur doit être unique sur nuget.org ainsi que sur tous les autres emplacements qui hébergent le package. Pour éviter les conflits, utilisez le nom de votre société comme première partie de l’identificateur est un bon modèle.

  • Suivez une convention d’affectation de noms similaire à celle de l’espace de noms de .NET, à l’aide de la notation par points. Par exemple, utilisez Contoso.Utility.UsefulStuff plutôt que Contoso-Utility-UsefulStuff ou Contoso_Utility_UsefulStuff. Il est également utile pour les consommateurs si vous faites correspondre à l’identificateur du package à l’espace de noms utilisé par le code.

  • Si vous produisez un package d’exemple de code qui montre comment utiliser un autre package, ajoutez .Sample comme suffixe à l’identificateur, comme dans Contoso.Utility.UsefulStuff.Sample.

    L’exemple de package a une dépendance envers le package d’origine. Lorsque vous créez l’exemple de package, ajoutez <IncludeAssets> avec la valeur contentFiles. Dans le dossier de contenu , disposez l’exemple de code dans un dossier appelé \Samples\<identifier>, tel que \Samples\Contoso.Utility.UsefulStuff.Sample.

Suivez ces meilleures pratiques pour définir la version du package :

  • En général, définissez la version du package pour qu’elle corresponde à la version du projet ou de l’assembly, bien que cela ne soit pas strictement obligatoire. Faire correspondre les version est simple lorsque vous avez des packages à assembly unique. NuGet traire lui-même les versions de package lors de la résolution des dépendances, mais pas les versions d’assembly.

  • Si vous utilisez un schéma de version non standard, veillez à prendre en compte les règles de gestion de versions NuGet, comme expliqué dans Gestion des versions de package. NuGet est la plupart du temps conforme à la Gestion sémantique de version 2.0.0.

Remarque

Pour plus d’informations concernant la résolution des dépendances, consultez Résolution des dépendances avec PackageReference. Pour obtenir des informations qui peuvent vous aider à comprendre la gestions des versions, consultez cette série de billets de blog :

Ajouter le package NuGet.Build.Tasks.Pack

Si vous utilisez MSBuild avec un projet de style non SDK et PackageReference, ajoutez le package NuGet.Build.Tasks.Pack à votre projet.

  1. Ouvrez le fichier projet et ajoutez ce qui suit après l’élément <PropertyGroup> :

    <ItemGroup>
  <!-- ... -->
  <PackageReference Include="NuGet.Build.Tasks.Pack" Version="6.7.0" PrivateAssets="all" />
  <!-- ... -->
</ItemGroup>

    Remarque

    Envisagez d’utiliser la dernière version disponible de ce package.

  2. Ouvrez une invite de commandes développeur (dans la zone Rechercher, saisissez Invite de commandes développeur).

    Il est généralement recommandé de démarrer l’invite de commandes développeur pour Visual Studio à partir du menu Démarrer, car elle est configurée avec tous les chemins nécessaires pour MSBuild.

  3. Basculez vers le dossier contenant le fichier projet et saisissez la commande suivante pour installer le package NuGet.Build.Tasks.Pack.

    # Uses the project file in the current folder by default
msbuild -t:restore

    Assurez-vous que la sortie MSBuild indique que la génération s’est terminée avec succès.

Exécuter la commande msbuild -t:pack

Pour créer un package NuGet (fichier .nupkg) à partir du projet, exécutez la commande msbuild -t:pack, qui génère également le projet automatiquement :

Dans l’invite de commandes Développeur pour Visual Studio, tapez la commande suivante :

# Uses the project file in the current folder by default
msbuild -t:pack

La sortie affiche le chemin d’accès du fichier .nupkg.

Microsoft (R) Build Engine version 16.1.76+g14b0a930a7 for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.

Build started 8/5/2019 3:09:15 PM.
Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" on node 1 (pack target(s)).
GenerateTargetFrameworkMonikerAttribute:
Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output files are up-to-date with respect to the input files.
CoreCompile:
  ...
CopyFilesToOutputDirectory:
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.dll" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll".
  ClassLib_DotNetStandard -> C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb".
GenerateNuspec:
  Successfully created package 'C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\AppLogger.1.0.0.nupkg'.
Done Building Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" (pack target(s)).

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:01.21

Générer automatiquement le package à la création

Pour exécuter automatiquement msbuild -t:pack pendant la création ou la restauration du projet, ajoutez la ligne suivante à votre fichier projet au sein de <PropertyGroup> :

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Lorsque vous exécutez msbuild -t:pack sur une solution, cela compresse tous les projets de la solution qui peuvent être compressés (la propriété <IsPackable> a la valeur true).

Remarque

Lorsque vous créez automatiquement le package, le délai d’attente augmente la durée de création de votre projet.

Tester l’installation de package

Avant de publier un package, il est d’usage de tester son processus d’installation dans un projet de test. Les tests permettent de s’assurer que les fichiers nécessaires se placent tous au bon endroit dans le projet.

Vous pouvez tester des installations manuellement dans Visual Studio ou à partir de la ligne de commande en suivant les étapes d’installation normales du package.

Important

Les packages sont immuables. Si vous remédiez à un problème, modifiez le contenu du package et compressez-le à nouveau. Si vous répétez un test, vous utiliserez l’ancienne version du package tant que vous n’aurez pas effacé votre dossier de packages globaux. C’est particulièrement utile lorsque vous testez des packages qui n’utilisent pas une étiquette de version préliminaire unique sur chaque build.

Étapes suivantes

Une fois que vous avez créé un package, qui est un fichier .nupkg, vous pouvez le publier dans la galerie de votre choix comme décrit dans Publication d’un package.

Vous pouvez également étendre les fonctionnalités de votre package ou prendre en charge d’autres scénarios comme décrit dans les rubriques suivantes :

Enfin, il existe d’autres types de package à connaître :