Erstellen eines NuGet-Pakets mit MSBuild

Wenn Sie ein NuGet-Paket aus Ihrem Code erstellen, packen Sie diese Funktionalität in eine Komponente, die für eine beliebige Anzahl anderer Entwickler freigegeben und verwendet werden kann. In diesem Artikel wird beschrieben, wie Sie ein Paket mit MSBuild erstellen. MSBuild ist mit jeder Visual Studio-Workload, die NuGet enthält, vorinstalliert. Darüber hinaus können Sie MSBuild auch über die dotnet CLI mit dotnet msbuild verwenden.

Für .NET Core- und .NET Standard-Projekte, die das SDK-Format verwenden, und für alle anderen PROJEKTE im SDK-Stil verwendet NuGet Informationen in der Projektdatei direkt, um ein Paket zu erstellen. Bei einem Projekt im Nicht-SDK-Stil, das <PackageReference>NuGet verwendet, wird auch die Projektdatei zum Erstellen eines Pakets verwendet.

SDK-Stilprojekte verfügen standardmäßig über die Packfunktionalität. Für Nicht-SDK-Stil-PackageReference-Projekte ist es ab Visual Studio 2026 auch standardmäßig verfügbar. In früheren Versionen von Visual Studio müssen Sie das Paket "NuGet.Build.Tasks.Pack" zu den Projektabhängigkeiten hinzufügen, und es wird empfohlen, diesen Paketverweis beim Upgrade auf Visual Studio 2026 zu entfernen. Ausführliche Informationen zu MSBuild-Paketzielen finden Sie unter NuGet Pack und Wiederherstellen als MSBuild-Ziele.

Bei Projekten im SDK-Stil ist msbuild -t:pack funktional äquivalent zu dotnet pack.

Von Bedeutung

Dieses Thema bezieht sich auf PROJEKTE im SDK-Stil , in der Regel .NET Core- und .NET Standard-Projekte und projekte im Nicht-SDK-Stil, die PackageReference verwenden.This topic applies to SDK-style projects, typically .NET Core and .NET Standard projects, and non-SDK-style projects that use PackageReference.

Eigenschaften festlegen

Die folgenden Eigenschaften sind erforderlich, um ein Paket zu erstellen.

• PackageId, der Paketbezeichner, der im Katalog eindeutig sein muss, in dem das Paket gehostet wird. Wenn Sie hier nichts angeben, lautet der Standardwert AssemblyName.
• Version, eine bestimmte Versionsnummer im Format Major.Minor.Patch[-Suffix], wobei -SuffixVorabversionen identifiziert. Wenn nicht angegeben, lautet der Standardwert 1,0,0.0.
• Der Pakettitel, wie er auf dem Host angezeigt werden soll (z. B. nuget.org)
• Authors, Autoren- und Besitzerinformationen. Wenn Sie hier nichts angeben, lautet der Standardwert AssemblyName.
• Company, Ihr Firmenname. Wenn Sie hier nichts angeben, lautet der Standardwert AssemblyName.

Wenn Sie Projekte im Nicht-SDK-Stil packen, die PackageReference verwenden, ist folgendes erforderlich:

• PackageOutputPath, der Ausgabeordner für das Paket, das beim Aufrufen von "pack" generiert wurde.

In Visual Studio können Sie diese Werte in den Projekteigenschaften festlegen (klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, wählen Sie "Eigenschaften" aus, und wählen Sie die Registerkarte " Paket " aus). Sie können diese Eigenschaften auch direkt in den Projektdateien (CSPROJ) festlegen.

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

Von Bedeutung

Weisen Sie dem Paket einen Bezeichner zu, der für nuget.org oder für die verwendete Paketquelle eindeutig ist.

Das folgende Beispiel zeigt eine einfache, vollständige Projektdatei mit diesen Eigenschaften.

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

Sie können auch die optionalen Eigenschaften festlegen, z. B. Title, PackageDescription und PackageTags, wie in MSBuild-Paketzielen, die Steuerung von Abhängigkeitsressourcen und NuGet-Metadaten-Eigenschaften beschrieben.

Hinweis

Bei Paketen, die für den öffentlichen Gebrauch erstellt wurden, achten Sie besonders auf die PackageTags-Eigenschaft , da Tags anderen helfen, Ihr Paket zu finden und zu verstehen, was es tut.

Ausführliche Informationen zum Deklarieren von Abhängigkeiten und angeben von Versionsnummern finden Sie unter Paketverweise in Projektdateien und Paketversionsverwaltung. Es ist auch möglich, Ressourcen aus Abhängigkeiten direkt im Paket mithilfe der <IncludeAssets> Und <ExcludeAssets> Attribute anzuzeigen. Weitere Informationen finden Sie unter Steuern von Abhängigkeitsressourcen.

Hinzufügen eines optionalen Beschreibungsfelds

Die optionale Beschreibung des Pakets wird auf der Registerkarte README der nuget.org Seite des Pakets angezeigt. Die Beschreibung wird aus der <Description> Projektdatei oder der $description im .nuspec-Datei abgerufen.

Das folgende Beispiel zeigt eine Description in der .csproj-Datei für ein .NET-Paket:

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

Wählen Sie einen eindeutigen Paketbezeichner aus, und legen Sie die Versionsnummer fest.

Der Paketbezeichner und die Versionsnummer identifizieren eindeutig den genauen Code, der im Paket enthalten ist.

Befolgen Sie die folgenden bewährten Methoden zum Erstellen des Paketbezeichners:

• Der Bezeichner muss für nuget.org und alle anderen Speicherorte, die das Paket hosten, eindeutig sein. Um Konflikte zu vermeiden, empfiehlt es sich, den Firmennamen als ersten Teil des Bezeichners zu verwenden.

• Folgen Sie einer .NET-Namespace-ähnlichen Benennungskonvention mit Punktnotation. Verwenden Sie Contoso.Utility.UsefulStuff z. B. anstelle von Contoso-Utility-UsefulStuff oder Contoso_Utility_UsefulStuff. Es ist auch für Verbraucher hilfreich, wenn Sie den Paketbezeichner mit dem namespace abgleichen, den der Code verwendet.

• Wenn Sie ein Paket mit Beispielcode erstellen, das veranschaulicht, wie ein anderes Paket verwendet wird, fügen Sie .Sample an den Bezeichner an, wie in .Contoso.Utility.UsefulStuff.Sample

  Das Beispielpaket hat eine Abhängigkeit vom ursprünglichen Paket. Fügen Sie beim Erstellen des Beispielpakets <IncludeAssets> mit dem Wert contentFiles hinzu. Ordnen Sie im Inhaltsordner den Beispielcode in einem Ordner namens \Samples\<identifier> an, z. B. \Samples\Contoso.Utility.UsefulStuff.Sample.

Befolgen Sie die folgenden bewährten Methoden zum Festlegen der Paketversion:

• Legen Sie im Allgemeinen die Paketversion so fest, dass sie mit der Projekt- oder Assemblyversion übereinstimmt, obwohl dies nicht unbedingt erforderlich ist. Das Abgleichen der Version ist einfach, wenn Sie ein Paket auf eine einzelne Assembly beschränken. NuGet selbst befasst sich mit Paketversionen beim Auflösen von Abhängigkeiten, nicht mit Assemblyversionen.

• Wenn Sie ein nicht standardmäßiges Versionsschema verwenden, sollten Sie die NuGet-Versionsverwaltungsregeln berücksichtigen, wie in der Paketversionsverwaltung erläutert. NuGet ist größtenteils mit Semantic Versioning 2.0.0-kompatibel.

Hinweis

Weitere Informationen zur Abhängigkeitsauflösung finden Sie in der Abhängigkeitsauflösung mit PackageReference. Informationen, die Ihnen dabei helfen können, die Versionsverwaltung zu verstehen, finden Sie in dieser Reihe von Blogbeiträgen:

• Teil 1: Übernehmen von DLL Hell
• Teil 2: Der Kernalgorithmus
• Teil 3: Vereinheitlichung über Bindungsumleitungen

Projekt für Pack konfigurieren

FÜR PROJEKTE im SDK-Stil sind keine zusätzliche Konfiguration erforderlich.

Projekte im Nicht-SDK-Stil benötigen entweder mindestens ein paket installiert (über PackageReference, nicht packages.config), oder das Projekt muss NuGet explizit anweisen, das Projekt als PackageReference-Projekt über die RestoreProjectStyle Eigenschaft zu behandeln.

Visual Studio 2022 und früher verfügen nicht über integrierte Pakete, daher müssen Sie auch das Paket NuGet.Build.Tasks.Pack installieren. Beim Upgrade auf Visual Studio 2026 oder höher empfehlen wir die Deinstallation des Pakets, sodass Sie von neuen Features und Fehlerbehebungen profitieren.

1. Bearbeiten Sie die Projektdatei.

   Wenn Sie NuGet ausdrücklich anweisen möchten, das Projekt als PackageReference zu behandeln (das Projekt hat keine installierten Pakete), suchen Sie ein <PropertyGroup>, das keine Condition-Anweisung enthält, oder fügen Sie es hinzu, und fügen Sie Folgendes hinzu:

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

   Wenn Sie Visual Studio 2022 oder früher verwenden, fügen Sie Folgendes nach dem <PropertyGroup> Element hinzu:

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

   Hinweis

   Erwägen Sie die Verwendung der neuesten Version dieses Pakets.

2. Öffnen Sie eine Eingabeaufforderung für Entwickler (geben Sie in das Suchfeld die Eingabeaufforderung für Entwickler ein).

   Normalerweise möchten Sie die Entwickler-Eingabeaufforderung für Visual Studio über das Startmenü starten, da sie mit allen erforderlichen Pfaden für MSBuild konfiguriert wird.

3. Wechseln Sie zu dem Ordner, der die Projektdatei enthält, und geben Sie den folgenden Befehl ein, um das NuGet.Build.Tasks.Pack-Paket wiederherzustellen.

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

   Stellen Sie sicher, dass die MSBuild-Ausgabe angibt, dass der Build erfolgreich abgeschlossen wurde.

Ausführen des Befehls "msbuild -t:pack"

Um ein NuGet-Paket (eine .nupkg Datei) aus dem Projekt zu erstellen, führen Sie den msbuild -t:pack Befehl aus, der auch das Projekt automatisch erstellt:

Geben Sie in der Eingabeaufforderung für Entwickler für Visual Studio den folgenden Befehl ein:

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

Die Ausgabe zeigt den Pfad der Datei .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

Paket beim Build automatisch generieren

Um msbuild -t:pack beim Erstellen oder Wiederherstellen des Projekts automatisch auszuführen, fügen Sie folgende Zeile innerhalb von <PropertyGroup> in Ihre Projektdatei hinzu.

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Wenn Sie eine Lösung ausführen msbuild -t:pack , packt dies alle Projekte in der Projektmappe, die packbar sind (<IsPackable> Eigenschaft ist auf true).

Hinweis

Wenn Sie das Paket automatisch erstellen lassen, verlängert die Zeit zum Verpacken die Buildzeit für Ihr Projekt.

Testen der Paketinstallation

Vor dem Veröffentlichen eines Pakets möchten Sie in der Regel den Prozess der Installation eines Pakets in einem Projekt testen. Die Tests stellen sicher, dass alle Dateien an ihren richtigen Stellen im Projekt enden.

Sie können Installationen manuell in Visual Studio oder über die Befehlszeile testen, indem Sie die normalen Installationsschritte des Pakets ausführen.

Von Bedeutung

Pakete sind unveränderlich. Wenn Sie ein Problem beheben, ändern Sie den Inhalt des Pakets und packen Sie es erneut, wenn Sie erneut testen, verwenden Sie weiterhin die alte Version des Pakets, bis Sie den Ordner „Globale Pakete“ löschen. Dies ist insbesondere beim Testen von Paketen relevant, die für jeden Build keine eindeutige Vorabversionsbezeichnung verwenden.

Nächste Schritte

Nachdem Sie ein Paket erstellt haben, bei dem es sich um eine .nupkg Datei handelt, können Sie es im Katalog Ihrer Wahl veröffentlichen, wie im Veröffentlichen eines Pakets beschrieben.

Möglicherweise möchten Sie auch die Funktionen Ihres Pakets erweitern oder andere Szenarien unterstützen, wie in den folgenden Themen beschrieben:

• NuGet Pack und Wiederherstellung als MSBuild-Ziele
• Paketversionsverwaltung
• Unterstützen mehrerer Zielframeworks
• Transformationen von Quell- und Konfigurationsdateien
• Lokalisierung
• Vorabversionen
• Pakettyp festlegen
• MSBuild-Props und Ziele
• Pakete mit COM-Interop-Assemblies erstellen

Schließlich sind zusätzliche Pakettypen zu beachten:

• Native Pakete
• Symbolpakete