Een NuGet-pakket maken met MSBuild

Wanneer u een NuGet-pakket maakt op basis van uw code, verpakt u die functionaliteit in een onderdeel dat kan worden gedeeld en gebruikt door een willekeurig aantal andere ontwikkelaars. In dit artikel wordt beschreven hoe u een pakket maakt met behulp van MSBuild. MSBuild wordt vooraf geïnstalleerd bij elke Visual Studio-workload die NuGet bevat. Daarnaast kunt u MSBuild ook gebruiken via de dotnet CLI met dotnet msbuild.

Voor .NET Core- en .NET Standard-projecten die gebruikmaken van de SDK-indeling en andere SDK-projecten, gebruikt NuGet rechtstreeks informatie in het projectbestand om een pakket te maken. Voor een niet-SDK-project dat gebruikmaakt <PackageReference>van, gebruikt NuGet ook het projectbestand om een pakket te maken.

Voor SDK-projecten is standaard de pakketfunctionaliteit beschikbaar. Voor niet-SDK-projecten met PackageReference is het ook standaard beschikbaar vanaf Visual Studio 2026. In eerdere versies van Visual Studio moet u het Pakket NuGet.Build.Tasks.Pack toevoegen aan de projectafhankelijkheden. Het is raadzaam deze pakketreferentie te verwijderen bij het upgraden naar Visual Studio 2026. Zie NuGet-pack en herstel als MSBuild-doelen voor gedetailleerde informatie over MSBuild-packdoelen.

Voor SDK-projecten is msbuild -t:pack functioneel gelijk aan dotnet pack.

Eigenschappen instellen

De volgende eigenschappen zijn vereist om een pakket te maken.

• PackageId, de pakket-id, die uniek moet zijn in de galerie die als host fungeert voor het pakket. Als dit niet is opgegeven, is AssemblyNamede standaardwaarde .
• Version, een specifiek versienummer in de vorm Major.Minor.Patch[-Suffix] waarbij -Suffixpre-release versies identificeert. Als dit niet is opgegeven, is de standaardwaarde 1.0.0.
• De pakkettitel zoals deze moet worden weergegeven op de host (zoals nuget.org)
• Authors, informatie over auteur en eigenaar. Als dit niet is opgegeven, is AssemblyNamede standaardwaarde .
• Company, uw bedrijfsnaam. Als dit niet is opgegeven, is AssemblyNamede standaardwaarde .

Als u niet-SDK-projecten inpakt die gebruikmaken van PackageReference, is het volgende vereist:

• PackageOutputPath, de uitvoermap voor het pakket dat wordt gegenereerd bij het aanroepen van het pakket.

In Visual Studio kunt u deze waarden instellen in de projecteigenschappen (klik met de rechtermuisknop op het project in Solution Explorer, kies Eigenschappen en selecteer het tabblad Pakket ). U kunt deze eigenschappen ook rechtstreeks instellen in de projectbestanden (.csproj).

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

In het volgende voorbeeld ziet u een eenvoudig, volledig projectbestand met deze eigenschappen.

<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>

U kunt ook de optionele eigenschappen, zoals Title, PackageDescriptionen PackageTags, zoals beschreven in MSBuild pack-doelen, het beheren van afhankelijkheidsassets en NuGet-metagegevenseigenschappen instellen.

Zie Pakketverwijzingen in projectbestanden en pakketversiebeheer voor meer informatie over het declareren van afhankelijkheden en het opgeven van versienummers. Het is ook mogelijk om assets uit afhankelijkheden rechtstreeks in het pakket weer te geven met behulp van de <IncludeAssets> en <ExcludeAssets> kenmerken. Zie Afhankelijkheidsassets beheren voor meer informatie.

Een optioneel beschrijvingsveld toevoegen

De optionele beschrijving van het pakket wordt weergegeven op het tabblad README van de nuget.org pagina van het pakket. De beschrijving wordt opgehaald uit het <Description> projectbestand of het $description in het .nuspec-bestand.

In het volgende voorbeeld ziet u een Description in het .csproj-bestand voor een .NET-pakket:

<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://free.blessedness.top/azure/storage/
      Microsoft Azure Storage REST API Reference - https://free.blessedness.top/rest/api/storageservices/
      REST API Reference for Blob Service - https://free.blessedness.top/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

Kies een unieke pakket-id en stel het versienummer in

De pakket-id en het versienummer identificeren de exacte code die in het pakket is opgenomen.

Volg deze aanbevolen procedures om de pakket-id te maken:

• De id moet uniek zijn voor nuget.org en alle andere locaties waarop het pakket wordt gehost. Om conflicten te voorkomen, is het een goed patroon om uw bedrijfsnaam te gebruiken als het eerste deel van de id.

• Volg een .NET-soortgelijke naamconventie met behulp van dot-notatie. Gebruik bijvoorbeeld Contoso.Utility.UsefulStuff in plaats Contoso-Utility-UsefulStuff van of Contoso_Utility_UsefulStuff. Het is ook handig voor consumenten als u de pakket-id koppelt aan de naamruimte die door de code wordt gebruikt.

• Als u een pakket met voorbeeldcode produceert dat laat zien hoe u een ander pakket gebruikt, voegt u .Sample toe aan de identificator, zoals in Contoso.Utility.UsefulStuff.Sample.

  Het voorbeeldpakket heeft een afhankelijkheid van het oorspronkelijke pakket. Wanneer u het voorbeeldpakket maakt, voegt u <IncludeAssets> toe met de contentFiles waarde. Rangschik in de inhoudsmap de voorbeeldcode in een map met de naam \Samples\<identifier>, zoals \Samples\Contoso.Utility.UsefulStuff.Sample.

Volg deze aanbevolen procedures om de pakketversie in te stellen:

• Stel in het algemeen de pakketversie in op overeenstemming met de project- of assemblyversie, hoewel dit niet strikt vereist is. Het aanpassen van de versie is eenvoudig wanneer u een pakket beperkt tot één assembly. NuGet zelf behandelt pakketversies bij het oplossen van afhankelijkheden, niet assemblyversies.

• Als u een niet-standaardversieschema gebruikt, moet u rekening houden met de NuGet-versiebeheerregels , zoals uitgelegd in pakketversiebeheer. NuGet is voornamelijk Semantic Versioning 2.0.0-compliant.

Project configureren voor pakket

Voor SDK-projecten is geen aanvullende configuratie vereist.

Projecten zonder SDK-stijl moeten ten minste één pakket hebben geïnstalleerd (via PackageReference, niet packages.config), of het project moet NuGet expliciet instrueren om het project te behandelen als een PackageReference-project via de RestoreProjectStyle eigenschap.

Visual Studio 2022 en eerder bevat geen ingebouwde pakketten, dus u moet ook het NuGet.Build.Tasks.Pack-pakket installeren. Wanneer u een upgrade uitvoert naar Visual Studio 2026 of hoger, wordt u aangeraden het pakket te verwijderen, zodat u profiteert van nieuwe functies en oplossingen voor fouten.

1. Bewerk het projectbestand.

   Als u NuGet expliciet wilt instrueren om het project te behandelen als PackageReference (het project heeft geen pakketten geïnstalleerd), zoekt of voegt u een <PropertyGroup> pakket toe dat geen instructie Condition heeft en voegt u het volgende toe:

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

   Als u Visual Studio 2022 of eerder gebruikt, voegt u het volgende toe na het <PropertyGroup> element:

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

   Opmerking

   Overweeg om de nieuwste versie van dit pakket te gebruiken.

2. Open een opdrachtprompt voor ontwikkelaars (typ in het zoekvak de opdrachtprompt Developer).

   Doorgaans wilt u de opdrachtprompt voor Ontwikkelaars voor Visual Studio starten vanuit het menu Start , omdat deze wordt geconfigureerd met alle benodigde paden voor MSBuild.

3. Ga naar de map met het projectbestand en typ de volgende opdracht om het Pakket NuGet.Build.Tasks.Pack te herstellen.

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

   Zorg ervoor dat de MSBuild-uitvoer aangeeft dat de build is voltooid.

Voer de opdracht msbuild -t:pack uit

Als u een NuGet-pakket (een .nupkg bestand) wilt bouwen vanuit het project, voert u de msbuild -t:pack opdracht uit, waarmee het project ook automatisch wordt gebouwd:

Typ in de opdrachtprompt Voor Ontwikkelaars voor Visual Studio de volgende opdracht:

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

De uitvoer toont het pad naar het .nupkg bestand.

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

Automatisch pakket genereren tijdens het bouwen

Als u het project automatisch wilt uitvoeren msbuild -t:pack wanneer u het project bouwt of herstelt, voegt u de volgende regel toe aan het projectbestand in <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Wanneer u msbuild -t:pack op een oplossing uitvoert, worden alle projecten in de oplossing gepackaged die gepackaged kunnen worden (de <IsPackable> eigenschap is ingesteld op true).

Installatie van het testpakket

Voordat u een pakket publiceert, wilt u meestal het proces van het installeren van een pakket in een project testen. De tests zorgen ervoor dat de bestanden allemaal op de juiste plaatsen in het project terechtkomen.

U kunt installaties handmatig testen in Visual Studio of op de opdrachtregel met behulp van de normale installatiestappen voor pakketten.

Volgende stappen

Nadat u een pakket hebt gemaakt, dat een .nupkg bestand is, kunt u het publiceren naar de galerie van uw keuze, zoals beschreven in het publiceren van een pakket.

Mogelijk wilt u ook de mogelijkheden van uw pakket uitbreiden of andere scenario's ondersteunen, zoals beschreven in de volgende onderwerpen:

• NuGet-pack en herstel als MSBuild-doelen
• Pakketversiebeheer
• Ondersteuning voor meerdere doelframeworks
• Transformaties van bron- en configuratiebestanden
• Lokalisatie
• Pre-release versies
• Pakkettype instellen
• MSBuild props en doelen
• Pakketten maken met COM-interop-assemblies

Ten slotte zijn er extra pakkettypen om rekening mee te houden:

• Systeemeigen pakketten
• Symbolenpakketten