Créer un package NuGet à l’aide de MSBuild

Lorsque vous créez un package NuGet à partir de votre code, vous empaquetez cette fonctionnalité dans un composant qui peut être partagé avec et utilisé par n’importe quel nombre d’autres développeurs. Cet article explique comment créer un package à l’aide de MSBuild. MSBuild est préinstallé avec chaque charge de travail Visual Studio qui contient NuGet. En outre, 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 tous les autres projets de style SDK, NuGet utilise des 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.

Les projets de style SDK ont la fonctionnalité pack disponible par défaut. Pour les projets PackageReference de style non sdk, il est également disponible par défaut à partir de Visual Studio 2026. Dans les versions antérieures de Visual Studio, vous devez ajouter le package NuGet.Build.Tasks.Pack aux dépendances du projet et nous vous recommandons de supprimer cette référence de package lors de la mise à niveau vers Visual Studio 2026. Pour plus d’informations sur les cibles de pack MSBuild, consultez le pack NuGet et la restauration en tant que cibles MSBuild.

Pour les projets de style SDK, msbuild -t:pack est fonctionnellement équivalent à dotnet pack.

Définir des propriétés

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

• PackageId, l’identificateur de package, qui doit être unique dans la galerie qui héberge le package. Si elle n’est pas spécifiée, la valeur par défaut est AssemblyName.
• Version, numéro de version spécifique sous la forme Major.Minor.Patch[-Suffix] où -Suffix identifie les versions en préversion. 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 (comme nuget.org)
• Authors, les informations sur l’auteur et le propriétaire. Si elle n’est pas spécifiée, la valeur par défaut est AssemblyName.
• Company, nom de votre société. 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 l’Explorateur de solutions, choisissez Propriétés, puis sélectionnez l’onglet Package ). Vous pouvez également définir ces propriétés directement dans les fichiers projet (.csproj).

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

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 facultatives, telles que Title, PackageDescriptionet PackageTags, comme décrit dans les cibles du pack MSBuild, le contrôle des ressources de dépendance et les propriétés de métadonnées NuGet.

Pour plus d’informations sur la déclaration de dépendances et la spécification des numéros de version, consultez références de package dans les fichiers projet et le contrôle de version du package. Il est également possible d’exposer des éléments provenant de dépendances directement dans le package à l’aide des attributs <IncludeAssets> et <ExcludeAssets>. Pour plus d’informations, consultez Contrôle des ressources de dépendance.

Ajouter un champ de description facultatif

La description facultative du package s’affiche sous l’onglet README de la page nuget.org du package. La description provient du <Description> fichier de projet ou du $descriptionfichier .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 du package et le numéro de version identifient de manière unique le code exact contenu dans le package.

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

• L’identificateur doit être unique entre nuget.org et tous les autres emplacements qui hébergent le package. Pour éviter les conflits, un bon modèle consiste à utiliser le nom de votre entreprise comme première partie de l’identificateur.

• Suivez une convention d’affectation de noms de type .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 utilisateurs si vous associez l'identificateur de 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 à l’identificateur, comme dans Contoso.Utility.UsefulStuff.Sample.

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

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

• En règle générale, définissez la version du package pour qu’elle corresponde à la version du projet ou de l’assembly, bien qu’elle ne soit pas strictement requise. La mise en correspondance de la version est simple lorsque vous limitez un package à un seul assembly. NuGet lui-même traite des versions de package lors de la résolution des dépendances, et non des versions d’assembly.

• Si vous utilisez un schéma de version non standard, veillez à prendre en compte les règles de contrôle de version NuGet , comme expliqué dans le contrôle de version du package. NuGet est principalement conforme à la version sémantique 2.0.0.

Configurer le projet pour le package

Les projets de style SDK ne nécessitent aucune configuration supplémentaire.

Les projets de style non SDK ont besoin d’au moins un package installé (via PackageReference, pas packages.config), ou le projet doit explicitement indiquer à NuGet de traiter le projet en tant que projet PackageReference via la RestoreProjectStyle propriété.

Visual Studio 2022 et versions antérieures n’a pas de pack intégré. Vous devez donc également installer le package NuGet.Build.Tasks.Pack. Lors de la mise à niveau vers Visual Studio 2026 ou version ultérieure, nous vous recommandons de désinstaller le package afin que vous bénéficiez de nouvelles fonctionnalités et correctifs de bogues.

1. Modifiez le fichier projet.

   Si vous souhaitez indiquer explicitement à NuGet de traiter le projet comme PackageReference (le projet n’a pas de packages installés), rechercher ou ajouter une instruction <PropertyGroup> qui ne contient aucune instruction Condition, et ajoutez :

   <PropertyGroup>
     <!-- other properties -->
     <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
     <!-- more properties are allowed -->
   </PropertyGroup>
   

   Si vous utilisez Visual Studio 2022 ou version antérieure, ajoutez les éléments suivants après l’élément <PropertyGroup> :

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

   Note

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

2. Ouvrez une invite de commandes Développeur (dans la zone De recherche , tapez invite de commandes Développeur).

   Vous souhaitez généralement démarrer la ligne de commande développeur pour Visual Studio à partir du menu Démarrer, car elle sera configurée avec tous les chemins nécessaires pour MSBuild.

3. Basculez vers le dossier contenant le fichier projet et tapez la commande suivante pour restaurer 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 build s’est terminée correctement.

Exécuter la commande msbuild -t :pack

Pour générer un package NuGet (un .nupkg fichier) à partir du projet, exécutez la msbuild -t:pack commande, 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 au .nupkg fichier.

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 un package sur la build

Pour exécuter msbuild -t:pack automatiquement lors de la compilation ou de la restauration du projet, ajoutez la ligne suivante à votre fichier de projet dans <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Lorsque vous exécutez msbuild -t:pack sur une solution, cela emballe tous les projets de la solution qui sont conditionnables (<IsPackable> la propriété est définie sur true).

Installation du package de test

Avant de publier un package, vous souhaitez généralement tester le processus d’installation d’un package dans un projet. Les tests s’assurent que les fichiers se retrouvent tous dans leurs emplacements corrects dans le projet.

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

Étapes suivantes

Une fois que vous avez créé un package, qui est un .nupkg fichier, vous pouvez le publier dans la galerie de votre choix, comme décrit dans La 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 :

• Pack et restauration NuGet en tant que cibles MSBuild
• Contrôle de version du package
• Prendre en charge plusieurs frameworks cibles
• Transformations des fichiers source et de configuration
• Localisation
• Versions préliminaires
• Définir le type de package
• Propriétés et cibles MSBuild
• Créer des packages avec des assemblys COM Interop

Enfin, il existe des types de package supplémentaires à prendre en compte :

• Packages natifs
• Packages de symboles