Erstellen eines NuGet-Pakets mit der dotnet CLI

  • Artikel

NuGet-Pakete enthalten Code, den Entwickler in ihren Projekten wiederverwenden können. Unabhängig davon, was Ihr Code tut oder enthält, verwenden Sie ein Befehlszeilentool, entweder nuget.exe oder dotnet.exe, um das NuGet-Paket zu erstellen.

In diesem Artikel wird das Erstellen eines Pakets mithilfe der dotnet CLI beschrieben. Ab Visual Studio 2017 ist die dotnet CLI in allen NET- und .NET Core-Workloads enthalten. Wenn Sie die dotnet CLI oder andere NuGet-Clienttools installieren müssen, lesen Sie "nstallieren von NuGet-Client-Tools.

Dieses Thema gilt nur für .NET und andere Projekte, die das SDK-Format verwenden. Für diese Projekte verwendet NuGet Informationen aus der Projektdatei, um ein Paket zu erstellen. Schnellstarter-Tutorials finden Sie unter Erstellen von Paketen mit dotnet CLI oder Erstellen von Paketen mit Visual Studio.

Der MsBuild Befehl msbuild -t:pack entspricht funktionell dem Dotnet-Paket. Weitere Informationen zum Erstellen eines NuGet-Pakets mit MSBuild finden Sie unter Erstellen eines NuGet-Pakets mithilfe von MSBuild.

Hinweis

Eigenschaften festlegen

Sie können ein Beispielprojekt für eine Klassenbibliothek mithilfe des Befehls dotnet new classlib erstellen und das Projekt mithilfe von dotnet pack verpacken. Der Befehl dotnet pack verwendet die folgenden Eigenschaften. Wenn Sie keine Werte in der Projektdatei angeben, verwendet der Befehl Standardwerte.

  • PackageId, der Paketbezeichner muss für nuget.org und alle anderen Ziele eindeutig sein, die das Paket hosten. Wenn Sie keinen Wert angeben, verwendet der Befehl AssemblyName.
  • Version ist eine bestimmte Versionsnummer in der Form Major.Minor.Patch[-Suffix], wobei -Suffix die Vorabversionen identifiziert werden. Wenn Sie hier nichts angeben, lautet der Standardwert 1.0.0.
  • Authors sind die Ersteller des Pakets. Wenn nichts angeben wird, lautet der Standardwert AssemblyName.
  • Company sind Unternehmensdaten Wenn der Wert nicht angegeben ist, lautet der Standardwert Authors.
  • Product sind Produktinformationen Wenn nichts angeben wird, lautet der Standardwert AssemblyName.

In Visual Studio können Sie diese Werte in den Projekteigenschaften festlegen. Klicken Sie im Lösungs-Explorer mit der rechten Maustaste auf das Projekt, wählen Sie Eigenschaften und dann den Abschnitt Paket aus. Sie können die Eigenschaften auch direkt in .csproj oder einer anderen Projektdatei festlegen.

Das folgende Beispiel zeigt eine Projektdatei mit hinzugefügten Paketeigenschaften.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>UniqueID</PackageId>
    <Version>1.0.0</Version>
    <Authors>Author Name</Authors>
    <Company>Company Name</Company>
    <Product>Product Name</Product>
  </PropertyGroup>
</Project>

Sie können weitere optionale Eigenschaften hinzufügen, z. B. Title, PackageDescriptionund PackageTags.

Hinweis

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

Der Befehl dotnet pack konvertiert PackageReferences in Ihren Projektdateien automatisch in Abhängigkeiten im erstellten Paket. Sie können steuern, welche Ressourcen über die Tags IncludeAssets, ExcludeAssets und PrivateAssets eingeschlossen werden sollen. Weitere Informationen finden Sie unter Steuern von Abhängigkeitsobjekten.

Weitere Informationen zu Abhängigkeiten, optionalen Eigenschaften und Versionsverwaltung finden Sie unter:

Auswählen eines eindeutigen Paketbezeichners und Festlegen der Versionsnummer

Der Paketbezeichner und die Versionsnummer bezeichnen eindeutig den exakten 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. Zur Vermeidung von Konflikten empfiehlt es sich, den Namen Ihres Unternehmens im ersten Teil des Bezeichners zu nutzen.

  • Folgen Sie einer .NET-Namespace-ähnlichen Benennungskonvention mit Punktnotation. Schreiben Sie z.B. Contoso.Utility.UsefulStuff statt 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 als Suffix 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:

  • Im Allgemeinen sollten Sie die Paketversion so einstellen, dass sie mit der Projekt- oder Assembly-Version übereinstimmt, obwohl dies nicht zwingend erforderlich ist. Die Anpassung der Version ist einfach, wenn Sie ein Paket auf eine einzige Baugruppe beschränken. NuGet selbst richtet sich beim Auflösen der Abhängigkeiten nach den Paketversionen, nicht nach den Assemblyversionen.

  • Wenn Sie ein nicht standardmäßiges Versionsschema verwenden, müssen Sie die NuGet-Versionsregeln wie unter Paketversionsverwaltung beschrieben anwenden. NuGet ist größtenteils Semantic Versioning 2.0.0-kompatibel.

Hinweis

Weitere Informationen zur Abhängigkeitsauflösung finden Sie unter Abhängigkeitsauflösung mit PackageReference. Informationen, die möglicherweise hilfreich sein können, um die Versionierung besser zu verstehen, finden Sie in dieser Reihe von Blog-Einträgen.

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 <Description> in der Projektdatei oder $description in der .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>

Ausführen des Befehls pack

Um das NuGet-Paket oder die .nupkg-Datei zu erstellen, führen Sie den Befehl dotnet pack aus dem Projektordner aus, wodurch das Projekt ebenfalls automatisch erstellt wird.

dotnet pack

Die Ausgabe zeigt den Pfad zur .nupkg-Datei.

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj (in 97 ms).
  Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'.

Automatisches Generieren des Pakets bei der Erstellung

Um dotnet pack automatisch auszuführen, wenn Sie dotnet build ausführen, fügen Sie folgende Zeile zu Ihrer Projektdatei im Tag <PropertyGroup> hinzu:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Hinweis

Wenn Sie das Paket automatisch generieren, erhöht das Verpacken die Erstellungszeit für Ihr Projekt.

Wenn Sie dotnet pack für eine Löösung ausführen, werden alle Projekte in der Lösung verpackt, die verpackt werden können, das heißt, die Eigenschaft IsPackable wird auf true festgelegt.

Testen der Paketinstallation

Bevor Sie ein Paket veröffentlichen, sollten Sie die Installation des Pakets in einem Projekt testen. Durch das Testen wird sichergestellt, dass die erforderlichen Dateien an den richtigen Stellen im Projekt landen.

Testen Sie die Installation manuell in Visual Studio oder mithilfe der normalen Paketinstallationsschritte über die Befehlszeile.

Wichtig

  • Sie können die Pakete nach der Erstellung nicht mehr ändern. Wenn Sie ein Problem beheben, ändern Sie den Paketinhalt, und packen Sie es erneut.

  • Nachdem Sie das Paket neu erstellt haben, verwendet die erneute Überprüfung weiterhin die alte Version des Pakets, bis Sie den Ordner globale Pakete löschen. Das Löschen des Ordners ist besonders wichtig für Pakete, die für jeden Build keine eindeutige Vorabversionsbezeichnung verwenden.

Nächste Schritte

Nachdem Sie das Paket erstellt haben, können Sie die nupkg-Datei auf dem Host Ihrer Wahl veröffentlichen.

Veröffentlichen eines Pakets

In den folgenden Artikeln finden Sie Möglichkeiten zum Erweitern der Funktionen Ihres Pakets oder zur Unterstützung anderer Szenarien: