Schnellstart: Erstellen und Veröffentlichen eines Pakets mithilfe von Visual Studio (.NET Framework, Windows)

Mit Microsoft Visual Studio können Sie ein NuGet-Paket aus einer .NET Framework-Klassenbibliothek erstellen und dann mit dem NuGet CLI-Tool auf nuget.org veröffentlichen.

Die Schnellstartanleitung ist nur für Windows-Benutzer vorgesehen. Wenn Sie Visual Studio für Mac verwenden, lesen Sie stattdessen die dotnet CLI-Tools.

Voraussetzungen

• Installieren Sie Visual Studio 2022 für Windows mit jeder .NET-bezogenen Workload.

  Sie können die 2022 Community-Edition kostenlos von visualstudio.com installieren oder die Professional oder Enterprise Edition verwenden.

  Visual Studio 2017 oder höher enthält automatisch NuGet-Funktionen, wenn eine .NET-Workload installiert ist.

• Registrieren Sie sich für ein kostenloses Konto auf nuget.org, falls Sie noch kein Konto haben. Sie müssen sich registrieren und das Konto bestätigen, bevor Sie ein Paket hochladen können.

• Installieren Sie die NuGet–CLI, indem Sie sie von nuget.org herunterladen, die Datei nuget.exe in einen geeigneten Ordner speichern und den Ordner der Umgebungsvariable PATH hinzufügen.

Erstellen eines Klassenbibliotheksprojekts

Führen Sie die folgenden Schritte aus, um eine Klassenbibliothek zu erstellen.

1. Klicken Sie in Visual Studio auf Datei>Neu>Projekt.

2. Wählen Sie im Fenster Neues Projekt erstellen in den Dropdownlisten C#, Windows und Bibliothek aus.

3. Wählen Sie in der resultierenden Liste der Projektvorlagen Klassenbibliothek (.NET Framework) und dann Weiter aus.

4. Geben Sie im Fenster Neues Projekt konfigurierenAppLogger als Projektnamen ein, und wählen Sie Erstellen aus.

5. Um sicherzustellen, dass das Projekt ordnungsgemäß erstellt wurde, wählen Sie Build>Build-Lösungaus. Die DLL befindet sich im Ordner „Debuggen“ (oder im Ordner „Release“, wenn Sie stattdessen diese Konfiguration erstellen).

6. (Optional) Für diese Schnellstartanleitung müssen Sie keinen zusätzlichen Code für das NuGet-Paket schreiben, da die Vorlagenklassenbibliothek zum Erstellen eines Pakets ausreicht. Wenn Sie jedoch einen funktionalen Code für dieses Beispielpaket wünschen, schließen Sie den folgenden Code ein:

   namespace AppLogger
   {
       public class Logger
       {
           public void Log(string text)
           {
               Console.WriteLine(text);
           }
       }
   }
   

   In einem echten NuGet-Paket implementieren Sie viele hilfreiche Features, mit denen andere Apps erstellen können. Sie können auch die Zielframeworks beliebig festlegen. Beispiele finden Sie unter UWP und Xamarin.

Konfigurieren der Projekteigenschaften für das Paket

Ein NuGet-Paket umfasst ein Manifest (eine .nuspec-Datei), das relevante Metadaten enthält, z. B. den Paketbezeichner, die Versionsnummer, die Beschreibung, usw. Einige von diesen Metadaten können direkt aus den Projekteigenschaften entnommen werden, wodurch vermieden werden kann, dass diese im Projekt und im Manifest separat aktualisiert werden müssen. In den folgenden Schritten wird beschrieben, wie die entsprechenden Eigenschaften festgelegt werden:

1. Wählen Sie den Menübefehl Projekt > Eigenschaften und dann die Registerkarte Anwendung aus.

2. Legen Sie im Feld Assemblyname einen eindeutigen Bezeichner für Ihr Paket fest. Bei dem Versuch, ein Paket mit einem Namen zu veröffentlichen, der bereits vorhanden ist, wird Ihnen ein Fehler angezeigt.

   Wichtig

   Sie müssen dem Paket einen Bezeichner zuweisen, der auf nuget.org bzw. auf dem Host, den Sie verwenden, einzigartig ist. Andernfalls tritt ein Fehler auf. Für diese Schnellstartanleitung wird empfohlen, Beispiel oder Test in den Namen zu einschließen, da der Veröffentlichungsschritt das Paket öffentlich sichtbar macht.

3. Klicken Sie auf die Schaltfläche Assemblyinformationen, wodurch ein Dialogfeld geöffnet wird, in dem Sie weitere Eigenschaften eingeben können, die dann im Manifest übernommen werden (siehe Ersetzungstoken). Die am häufigsten verwendeten Felder sind Titel, Beschreibung, Unternehmen, Copyright und Assemblyversion. Weil diese Eigenschaften mit Ihrem Paket auf einem Host wie nuget.org angezeigt werden, sollten Sie sich vergewissern, dass diese ausführlich beschrieben sind.

   

4. (Optional) Um die Eigenschaften direkt anzuzeigen und zu bearbeiten, öffnen Sie die Datei Properties/AssemblyInfo.cs im Projekt, indem Sie >Projekt bearbeiten auswählen.

5. Nachdem Sie diese Eigenschaften festgelegt haben, legen Sie die Konfiguration der aktiven Lösung in Build>Configuration Manager auf Freigeben fest, und erstellen Sie das Projekt neu, um die aktualisierte DLL zu generieren.

Erstellen des ersten Manifests

Nachdem Sie die Projekteigenschaften festgelegt und die DLL erstellt haben, können Sie nun eine anfängliche NUSPEC-Datei aus dem Projekt generieren. Dieser Schritt umfasst die relevanten Ersetzungstoken zum Auslesen von Informationen aus der Projektdatei.

Führen Sie nuget spec nur einmal aus, um das Startmanifest zu generieren. Beim Aktualisieren des Pakets ändern Sie die Werte in Ihrem Projekt, oder Sie bearbeiten das Manifest direkt.

1. Öffnen Sie bei geöffnetem Projekt in Solution Explorer eine Eingabeaufforderung, indem Sie die Tools>Befehlszeile>Developer-Eingabeaufforderung.

   Die Eingabeaufforderung wird in Ihrem Projektverzeichnis geöffnet, in dem sich die AppLogger.csproj-Datei befindet.

2. Führen Sie den folgenden Befehl aus: nuget spec AppLogger.csproj.

   NuGet erstellt ein Manifest, das dem Namen des Projekts entspricht, in diesem Fall AppLogger.nuspec. Ebenso werden die Ersetzungstoken im Manifest eingeschlossen.

3. Öffnen Sie AppLogger.nuspec in einem Text-Editor, um den Inhalt zu untersuchen, der dem folgenden Code ähnelt:

   <?xml version="1.0"?>
   <package >
     <metadata>
       <id>Package</id>
       <version>1.0.0</version>
       <authors>Your username</authors>
       <owners>Your username</owners>
       <license type="expression">MIT</license>
       <!-- <icon>icon.png</icon> -->
       <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
       <requireLicenseAcceptance>false</requireLicenseAcceptance>
       <description>Package description</description>
       <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
       <copyright>Copyright 2022</copyright>
       <tags>Tag1 Tag2</tags>
     </metadata>
   </package>
   

Das Manifest bearbeiten

1. Bearbeiten Sie die folgenden Eigenschaften, bevor Sie fortfahren. Andernfalls tritt ein Fehler auf, wenn Sie versuchen, ein NuGet-Paket mit den Standardwerten in Ihrer .nuspec-Datei zu erstellen. Informationen zu diesen Eigenschaften finden Sie unter optionalen Metadatenelementen:

   • licenseUrl
   • projectUrl
   • releaseNotes
   • Tags

2. Bei Paketen für die öffentliche Nutzung sollten Sie besonders auf die Tags-Eigenschaft achten, da Tags anderen dabei helfen, Ihr Paket zu finden und dessen Funktion zu verstehen.

3. Zu diesem Zeitpunkt können Sie auch weitere Elemente zu Ihrem Manifest hinzufügen, wie unter .nuspec file reference (NUSPEC-Referenz) beschrieben wird.

4. Speichern Sie die Datei, bevor Sie fortfahren.

Ausführen des Befehls pack

1. Öffnen Sie bei geöffnetem Projekt in Solution Explorer eine Eingabeaufforderung, indem Sie die Tools>Befehlszeile>Developer-Eingabeaufforderung.

   Die Eingabeaufforderung wird in Ihrem Projektverzeichnis geöffnet.

2. Führen Sie den folgenden Befehl aus: nuget pack.

   NuGet generiert im aktuellen Ordner eine .nupkg-Datei in Form von identifier.version.nupkg.

Veröffentlichen des Pakets

Sobald Sie über eine .nupkg-Datei verfügen, können Sie diese über NuGet CLI mit einem von nuget.org bezogenen API-Schlüssel auf nuget.org veröffentlichen. Für nuget.org müssen Sie nuget.exe 4.1.0 oder höher verwenden.

Wenn Sie Ihr Paket testen und überprüfen möchten, bevor Sie es in einem öffentlichen Katalog veröffentlichen, können Sie es in eine Testumgebung wie int.nugettest.org statt in nuget.org hochladen. Beachten Sie, dass Pakete, die in int.nugettest.org hochgeladen wurden, möglicherweise nicht beibehalten werden.

Erwerben des 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.

   

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 der NuGet CLI

Die Verwendung der NuGet CLI (nuget.exe) ist eine Alternative zur Verwendung der .NET CLI:

1. Öffnen Sie eine Befehlszeile, und navigieren Sie zu dem Ordner, der die .nupkg-Datei enthält.

2. Führen Sie den folgenden Befehl aus. Ersetzen Sie den <Paketdateinamen> durch den Dateinamen Ihres Pakets, und ersetzen Sie den <API-Schlüsselwert> durch Ihren API-Schlüssel. Der Paketdateiname ist eine Verkettung Ihrer Paket-ID und Versionsnummer mit der Erweiterung nupkg. Beispiel: AppLogger.1.0.0.nupkg:

   nuget push <package filename> <api key value> -Source https://api.nuget.org/v3/index.json
   

   Das Ergebnis des Veröffentlichungsprozesses wird wie folgt angezeigt:

   Pushing <package filename> to 'https://www.nuget.org/api/v2/package'...
       PUT https://www.nuget.org/api/v2/package/
       Created https://www.nuget.org/api/v2/package/ 6829ms
   Your package was pushed.
   

Weitere Informationen finden Sie unter NuGet-Push.

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.

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.

   

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.

   

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

Nächste Schritte

Herzlichen Glückwunsch zum Erstellen eines NuGet-Pakets mithilfe von Visual Studio .NET Framework. Wechseln Sie zum nächsten Artikel, um zu erfahren, wie Sie ein NuGet-Paket mit der NuGet CLI erstellen.

Um mehr über NuGet zu erfahren, lesen Sie die folgenden Artikel:

• Veröffentlichen eines Pakets
• Erstellen eines Vorabversionspakets
• Unterstützen mehrerer Zielframeworks
• Paketversionsverwaltung
• Erstellen von lokalisierten Paketen