Freigeben über

Erstellen eines NuGet-Pakets mit der dotnet CLI

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 beschrieben, wie Sie ein Paket mithilfe der dotnet CLI erstellen. 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 "Installieren von NuGet-Clienttools".

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. Schnellstartlernprogramme finden Sie unter Erstellen von Paketen mit der dotnet CLI oder erstellen von Paketen mit Visual Studio.

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

Hinweis

Eigenschaften festlegen

Sie können ein Beispielklassenbibliotheksprojekt mithilfe des dotnet new classlib Befehls erstellen und das Projekt mithilfe des Befehls dotnet pack verpacken. Der dotnet pack Befehl 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 die AssemblyName.
  • Version ist eine bestimmte Versionsnummer im Formular Major.Minor.Patch[-Suffix], wobei -Suffix die Vorabversionen identifiziert werden. Wenn Sie hier nichts angeben, lautet der Standardwert 1.0.0.
  • Authors sind die Autoren des Pakets. Wenn nicht angegeben, ist der Standardwert die AssemblyName.
  • Company ist Unternehmensinformationen. Wenn nicht angegeben, ist der Standardwert der Authors Wert.
  • Product ist Produktinformationen. Wenn nicht angegeben, ist der Standardwert die AssemblyName.

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 dann den Abschnitt "Paket" aus. Sie können die Eigenschaften auch direkt zur CSPROJ - oder anderen Projektdatei hinzufügen.

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, PackageDescription und PackageTags.

Hinweis

Bei Softwarepaketen, die Sie für die öffentliche Nutzung erstellen, achten Sie besonders auf die PackageTags Eigenschaft. Tags helfen anderen, Ihr Paket zu finden und zu verstehen, was es tut.

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

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

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:

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>

Ausführen des Paketbefehls

Um das NuGet-Paket oder die nupkg-Datei zu erstellen, führen Sie den Dotnet Pack-Befehl aus dem Projektordner aus, der auch das Projekt automatisch erstellt.

dotnet pack

Die Ausgabe zeigt den Pfad zur NUPKG-Datei an:

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

Paket beim Build automatisch generieren

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

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Hinweis

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

Es führt dotnet pack auf einer Lösung aus, wobei alle Projekte, die gepackt werden können, gepackt werden, nämlich solche, die die IsPackable-Eigenschaft auf true gesetzt haben.

Testen der Paketinstallation

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

Testen Sie die Installation manuell in Visual Studio oder in der Befehlszeile, indem Sie den normalen Paketinstallationsprozess verwenden.

Von Bedeutung

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

  • Last updated on