Schnellstart: Erstellen und Veröffentlichen eines Pakets mit der dotnet CLI

  • Artikel

In dieser Schnellstartanleitung erfahren Sie, wie Sie schnell ein NuGet-Paket aus einer .NET-Klassenbibliothek erstellen und mithilfe der .NET-Befehlszeilenschnittstelle oder dotnet CLI in nuget.org veröffentlichen.

Voraussetzungen

  • Das .NET SDK, das das dotnet-Befehlszeilentool bietet. Ab Visual Studio 2017 wird die dotnet CLI automatisch mit jeder .NET oder .NET-Core-bezogenen Workload installiert.

  • Ein kostenloses Konto auf nuget.org. Folgen Sie den Anweisungen unter Neues individuelles Konto hinzufügen.

Erstellen eines Klassenbibliotheksprojekts

Sie können ein vorhandenes Projekt in der .NET-Klassenbibliothek für Code verwenden, den Sie packen wollen, oder ein einfaches Projekt wie folgt erstellen:

  1. Erstellen Sie anschließend einen Ordner mit dem Namen AppLogger.
  2. Öffnen Sie eine Eingabeaufforderung, und navigieren Sie zum Ordner AppLogger. Alle dotnet CLI-Befehle in dieser Schnellstartanleitung werden standardmäßig im aktuellen Ordner ausgeführt.
  3. Geben Sie dotnet new classlib ein, das ein Projekt mit dem aktuellen Ordnernamen erstellt.

Weitere Informationen finden Sie unter dotnet new.

Hinzufügen von Paketmetadaten zu einer Projektdatei

Jedes NuGet-Paket benötigt ein Manifest, das die Inhalte und Abhängigkeiten des Pakets beschreibt. In dem letzten Paket ist das Manifest eine .nuspec-Datei, die aus NuGet-Metadateneigenschaften erstellt wird, die Sie in der Projektdatei einbeziehen.

Öffnen Sie die .csproj-, fsproj- oder vbproj-Projektdatei, und fügen Sie die folgenden Eigenschaften innerhalb des vorhandenen <PropertyGroup>-Tags hinzu. Verwenden Sie eigene Werte für Name und Unternehmen, und ersetzen Sie den Paketbezeichner durch einen eindeutigen Wert.

<PackageId>Contoso.08.28.22.001.Test</PackageId>
<Version>1.0.0</Version>
<Authors>your_name</Authors>
<Company>your_company</Company>

Wichtig

Der Paketbezeichner muss für nuget.org und andere Paketquellen eindeutig sein. Die Veröffentlichung macht das Paket öffentlich sichtbar. Wenn Sie also die Beispielbibliothek „AppLogger“ oder eine andere Testbibliothek verwenden, verwenden Sie einen eindeutigen Namen, der Sample oder Test einschließt.

Fügen Sie optionale Eigenschaften wie unter NuGet-Metadateneigenschaften beschrieben hinzu.

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.

Ausführen des Befehls pack

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

dotnet pack

Die Ausgabe zeigt den Pfad zur .nupkg-Datei.

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored C:\Users\myname\source\repos\AppLogger\AppLogger.csproj (in 64 ms).
  AppLogger -> C:\Users\myname\source\repos\AppLogger\bin\Debug\net6.0\AppLogger.dll
  Successfully created package 'C:\Users\myname\source\repos\AppLogger\bin\Debug\Contoso.08.28.22.001.Test.1.0.0.nupkg'.

Automatisches Generieren des Pakets bei der Erstellung

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

    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Veröffentlichen des Pakets

Veröffentlichen Sie Ihre nupkg-Datei in nuget.org mithilfe des Dotnet Nuget-Pushbefehls mit einem API-Schlüssel, den Sie von nuget.org abrufen.

Hinweis

  • Nuget.org überprüft alle hochgeladenen Pakete auf Viren und lehnt die Pakete ab, wenn Viren gefunden werden. Alle auf nuget.org aufgelisteten Pakete werden zudem regelmäßig überprüft.

  • Pakete, die auf nuget.org veröffentlicht werden, sind für andere Entwickler sichtbar, sofern Sie deren Auflistung nicht aufheben. Informationen zum privaten Hosten von Paketen finden Sie unter Hosten eigener NuGet-Feeds.

Abrufen Ihres API-Schlüssels

  1. Melden Sie sich bei Ihrem nuget.org-Konto an, oder erstellen Sie ein Konto, wenn Sie noch keines besitzen.

  2. Klicken Sie auf Ihren Benutzernamen (oben rechts) und anschließend auf API-Schlüssel.

  3. Wählen Sie Erstellen aus, und geben Sie dann einen Namen für Ihren Schlüssel an.

  4. Wählen Sie unter Bereiche auswählen die Option Push aus.

  5. Geben Sie unter Pakete auswählen>Glob-Muster * ein.

  6. Klicken Sie auf Erstellen.

  7. Wählen Sie Kopieren aus, um den neuen Schlüssel zu kopieren.

    Screenshot, der den neuen API-Schlüssel mit dem Link „Kopieren“ zeigt.

Wichtig

  • Halten Sie Ihren API-Schlüssel grundsätzlich geheim! Der API-Schlüssel ist wie ein Kennwort, mit dem jeder Benutzer Pakete in Ihrem Namen verwalten kann. Löschen Sie Ihren API-Schlüssel oder generieren Sie ihn neu, wenn er versehentlich offengelegt wird.
  • Speichern Sie den Schlüssel an einem sicheren Ort; Sie können den Schlüssel später nicht erneut kopieren. Wenn Sie auf die Seite „API-Schlüssel“ zurückkehren, müssen Sie den Schlüssel erneut generieren, um ihn zu kopieren. Sie können den API-Schlüssel auch entfernen, wenn Sie Pakete nicht mehr mithilfe von Push übertragen möchten.

Mit der Bereichsauswahl können Sie separate API-Schlüssel für verschiedene Zwecke erstellen. Jeder Schlüssel hat seinen Ablaufzeitraum und kann auf bestimmte Pakete (oder Globmuster) festgelegt werden. Sie legen auch jeden Schlüssel auf bestimmte Vorgänge fest: Pushen sie neue Pakete und Paketversionen, pushen Sie nur neue Paketversionen oder heben Sie die Liste auf.

Durch das Festlegen des Gültigkeitsbereichs können Sie API-Schlüssel für verschiedene Personen erstellen, die Pakete für Ihre Organisation so verwalten, dass sie nur über die erforderlichen Berechtigungen verfügen.

Weitere Informationen finden Sie unter bereichsbezogene API-Schlüssel.

Veröffentlichen mit „dotnet nuget push“

Führen Sie im Ordner, der die NUPKG-Datei enthält, den folgenden Befehl aus. Geben Sie ihren nupkg-Dateinamen an, und ersetzen Sie den Schlüsselwert durch Ihren API-Schlüssel.

dotnet nuget push Contoso.08.28.22.001.Test.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json

In der Ausgabe wird das Ergebnis des Veröffentlichungsprozesses angezeigt.

Pushing Contoso.08.28.22.001.Test.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
  PUT https://www.nuget.org/api/v2/package/
warn : All published packages should have license information specified. Learn more: https://aka.ms/nuget/authoring-best-practices#licensing.
  Created https://www.nuget.org/api/v2/package/ 1221ms
Your package was pushed.

Weitere Informationen finden Sie unter dotnet Nuget Push.

Hinweis

Um zu vermeiden, dass Ihr Testpaket auf nuget.org live ist, können Sie an die nuget.org Testwebsite unter https://int.nugettest.org pushen. Beachten Sie, dass Pakete, die in int.nugettest.org hochgeladen wurden, möglicherweise nicht beibehalten werden.

Veröffentlichungsfehler

Fehler des Befehls push geben das Problem in der Regel an. Beispielsweise könnte das Problem darin liegen, dass Sie vergessen haben, die Versionsnummer in ihrem Projekt anzupassen, und Sie versuchen ein Paket zu veröffentlichen, das bereits vorhanden ist.

Außerdem werden Fehler angezeigt, wenn Ihr API-Schlüssel ungültig oder abgelaufen ist, oder wenn Sie versuchen, ein Paket mit einem Bezeichner zu veröffentlichen, der bereits auf dem Host vorhanden ist. Angenommen, der Bezeichner AppLogger-test ist bereits auf nuget.org vorhanden. Wenn Sie versuchen, ein Paket mit diesem Bezeichner zu veröffentlichen, gibt der push-Befehl den folgenden Fehler:

Response status code does not indicate success: 403 (The specified API key is invalid,
has expired, or does not have permission to access the specified package.).

Wenn dieser Fehler angezeigt wird, überprüfen Sie, ob Sie einen gültigen API-Schlüssel verwenden, der noch nicht abgelaufen ist. Ist dies der Fall, gibt der Fehler an, dass der Paketbezeichner bereits auf dem Host vorhanden ist. Ändern Sie den Paketbezeichner, erstellen Sie das Projekt neu, erstellen Sie die .nupkg-Datei neu, und versuchen Sie den push-Befehl erneut.

Verwalten des veröffentlichten Pakets

Wenn Ihr Paket erfolgreich veröffentlicht wird, erhalten Sie eine Bestätigungs-E-Mail. Um das gerade veröffentlichte Paket anzuzeigen, wählen Sie nuget.org ihren Benutzernamen oben rechts aus, und wählen Sie dann Pakete verwalten aus.

Hinweis

Möglicherweise dauert es etwas, bis Ihr Paket indiziert wurde und anderen Benutzern in den Suchergebnissen angezeigt wird. Während dieser Zeit wird Ihr Paket unter Nicht aufgelistete Pakete angezeigt, und auf der Paketseite wird die folgende Meldung angezeigt:

Screenshot der Veröffentlichungsbenachrichtigung, die angezeigt wird, wenn Sie ein Paket in nuget.org hochladen.

Sie haben jetzt Ihr erstes NuGet-Paket auf nuget.org veröffentlicht, das andere Entwickler nun in ihren Projekten verwenden können.

Wenn Sie ein Paket erstellt haben, das nicht hilfreich ist (z. B. dieses Beispielpaket, das mit einer leeren Klassenbibliothek erstellt wurde), oder Sie entscheiden, dass das Paket nicht sichtbar sein soll, können Sie die Auflistung des Pakets aufheben, um es aus den Suchergebnissen auszublenden:

  1. Nachdem das Paket auf der Seite Pakete verwalten unter Veröffentlichte Pakete angezeigt wird, wählen Sie das Stiftsymbol neben dem Paketeintrag aus.

    Screenshot, der das Symbol „Bearbeiten“ für eine Paketliste auf nuget.org zeigt.

  2. Wählen Sie auf der nächsten Seite Listing55222 aus, deaktivieren Sie das Kontrollkästchen In Suchergebnissen auflisten, und wählen Sie dann Speichern aus.

    Screenshot, der zeigt, wie das Kontrollkästchen „Liste“ für ein Paket auf nuget.org deaktiviert wird.

Das Paket wird jetzt unter Nicht aufgelistete Pakete in Pakete verwalten aufgeführt und in den Suchergebnissen nicht mehr angezeigt.

Hinweis

Um zu vermeiden, dass Ihr Testpaket auf nuget.org live ist, können Sie an die nuget.org Testwebsite unter https://int.nugettest.org pushen. Beachten Sie, dass Pakete, die in int.nugettest.org hochgeladen wurden, möglicherweise nicht beibehalten werden.

Herzlichen Glückwunsch zur Erstellung Ihres ersten NuGet-Pakets!

Auf Channel 9 und auf YouTube finden Sie weitere Videos zu NuGet.

Nächste Schritte

Weitere Informationen zum Erstellen von Paketen mit dotnet CLI finden Sie unter:

Erstellen eines NuGet-Pakets mit der dotnet CLI

Weitere Informationen zum Erstellen und Veröffentlichen von NuGet-Paketen: