Bewährte Methoden für die Paketerstellung

  • Artikel

Diese Anleitung ist eine vereinfachte Referenz zum Erstellen und Veröffentlichen hochwertiger Pakete für NuGet-Paketautoren. Sie konzentriert sich in erster Linie auf paketspezifische bewährte Methoden wie Metadaten und Verpacken. Ausführlichere Empfehlungen zum Entwickeln hochwertiger Bibliotheken finden Sie im Leitfaden für die Open Source-Bibliothek für .NET.

Empfehlungstypen

Jeder Artikel enthält vier Empfehlungstypen: Do, Erwägen, Vermeiden und Do not. Der Empfehlungstyp gibt an, wie strikt die Empfehlung befolgt werden sollte.

Eine Do-Empfehlung sollten Sie fast immer befolgen. Zum Beispiel:

✔️ Beziehen Sie eine kurze Beschreibung des Zwecks Ihres Pakets ein.

Andererseits sollten auf Erwägungen bezogene Empfehlungen im Allgemeinen befolgt werden, berechtigte Ausnahmen bestätigen jedoch die Regel:

✔️ Wählen Sie einen NuGet-Paketnamen mit einem Präfix aus, das den Kriterien der NuGet-Präfixreservierung entspricht.

Empfehlungen hinsichtlich Vermeiden geben Dinge an, die allgemein als keine gute Idee angesehen werden, jedoch kann das Brechen dieser Regel manchmal auch sinnvoll sein:

❌ Vermeiden Sie NuGet-Paketverweise, die eine exakte Version erfordern.

Schließlich kennzeichnen Do not-Empfehlungen Vorgänge, die Sie niemals ausführen sollten:

❌ Verwenden Sie die Metadateneigenschaft LicenseUrl NICHT.

Erstellen eines NuGet-Pakets

Die aktuelle empfohlene Methode ist das Erstellen eines NuGet-Pakets von einem Projekt im SDK-Stil aus. Die Eigenschaften eines Projekts im SDK-Stil einschließlich Zielframework und Paketmetadaten werden in der Projektdatei definiert.

Erstellen Sie ein Paket von Ihrem Projekt im SDK-Stil aus, indem Sie die erforderlichen Eigenschaften definieren und in Visual Studio oder der dotnet CLI verpacken.

✔️ Erstellen Sie ein Projekt im SDK-Stil und erstellen (verpacken) Sie Ihr Paket mithilfe von Visual Studio oder der dotnet CLI.

Ausführlichere Anleitungen zur Paketerstellung einschließlich der erforderlichen Clienttools, des Projektdateibeispiels und der Befehle finden Sie unter Erstellen eines NuGet-Pakets mithilfe der dotnet CLI.

Informationen zur Entscheidung, welche .NET-Frameworks als Ziel festzulegen sind, finden Sie in unserem neuesten Leitfaden für plattformübergreifende Ziele.

Paketmetadaten

Metadaten sind eine grundlegende Komponente jedes NuGet-Pakets. Die Qualität ihrer Metadaten kann die Auffindbarkeit, Nutzbarkeit und Vertrauenswürdigkeit des Pakets erheblich beeinflussen.

In Visual Studio sollten Sie zum Angeben von Paketmetadaten zu „Projekt > Eigenschaften von [Projektname] > Paket“ navigieren.

Elemente von Paketmetadaten können auch direkt in der Projektdatei angegeben werden.

Im Folgenden finden Sie eine Tabellenzuordnung und Beschreibung verfügbarer Paketmetadatenelemente:

Visual Studio-Eigenschaftsname Projektdatei/MSBuild-Eigenschaftsname Nuspec-Eigenschaftsname Beschreibung
Package id PackageId id Der Paketname oder Bezeichner.
Package version PackageVersion version Die NuGet-Paketversion.
Authors Authors authors Eine durch Trennzeichen getrennte Liste von Paketautoren, wo häufig der Anzeigename der Person oder einer Organisation verwendet wird.
Description Description description Eine Beschreibung des Pakets.
Copyright Copyright copyright Copyright-Informationen für das Paket.
Project URL PackageProjectUrl projectUrl Eine App-URL für die Projekthomepage.
Icon File PackageIcon icon Pfad zur Paketsymbol-Bilddatei.
README PackageReadmeFile readme Dies ist der Pfad zur README-Markdowndatei für das Paket.
Repository URL RepositoryUrl repository url Die URL zu dem Repository, von dem aus das Paket erstellt wurde.
Repository type RepositoryType repository type Repositorytyp, auf den die Repository-URL verweist (d. h. „git“).
Tags PackageTags tags Eine durch Leerzeichen getrennte Liste von Tags und Schlüsselwörtern, die das Paket beschreiben. Tags werden bei der Suche nach Paketen verwendet.
Release notes PackageReleaseNotes releaseNotes Eine Beschreibung der Änderungen, die in diesem Release des Pakets vorgenommen wurden.
Licensing - Expression PackageLicenseExpression license type="expression" Ein SPDX-Lizenzausdruck.
Licensing - File PackageLicenseFile license type="file" Pfad zu einer benutzerdefinierten Lizenzdatei.

Paket-ID

Wenn Sie ein vollständig neues Paket veröffentlichen:

✔️ Wählen Sie eine eindeutige Paket-ID aus, die sich deutlich von vorhandenen Paketen auf NuGet.org unterscheidet.

Sie können überprüfen, ob eine Paket-ID eindeutig und unterscheidbar ist, indem Sie auf NuGet.org nach der ID suchen oder überprüfen, ob der folgende Link vorhanden ist: https://www.nuget.org/packages/<Paketname>.

✔️ Wählen Sie einen NuGet-Paketnamen mit einem Präfix aus, das den Kriterien der NuGet-Präfixreservierung entspricht.

Wenn Sie die Präfix-ID für Ihr Paket reservieren, wird das „Überprüft“-Häkchen angezeigt: image

Weitere Informationen finden Sie in der Dokumentation zur Reservierung für Paket-ID-Präfixe.

Paketversion

✔️ ERWÄGEN Sie, SemVer für die Versionskontrolle Ihres NuGet-Pakets zu verwenden.

Dies bedeutet im Wesentlichen, dass das Format „Major.Minor.Patch[-prerelease]“ verwendet wird.

✔️ Veröffentlichen Sie ein Paket als Vorabversionspaket, wenn es nicht stabil ist oder als Vorschauversion verfügbar ist.

Eine ausführlichere Anleitung finden Sie im Handbuch zur Versionsverwaltung von .NET-Bibliotheken.

Autoren

✔️ Verwenden Sie das Feld „Autor“ für Ihren Anzeigenamen oder den Ihrer Organisation.

Wenn Ihr NuGet.org-Benutzername beispielsweise „jdoe“ lautet, können Consumer Sie leichter als Autorin erkennen, wenn „Jane Doe“ im Feld „Autor“ steht. Wenn der NuGet.org-Benutzername Ihrer Organisation „ContosoToolkit“ lautet, kann die Verwendung von „Contoso Corporation“ die Erkennbarkeit verbessern und die Vertrauenswürdigkeit bei Consumern steigern.

Beschreibung

✔️ Beziehen Sie eine kurze Beschreibung (bis zu 4.000 Zeichen) ein, um das Paket zu beschreiben.

Die Paketbeschreibung ist eines der wichtigsten Felder, die in der NuGet-Suche angezeigt werden, und wahrscheinlich das erste, was potenzielle Consumer anzeigen, um festzustellen, ob ein Paket für sie geeignet ist.

✔️ Fügen Sie Ihrem Paket mit „Copyright (c) <Name/Unternehmen><Jahr>“ einen Urheberrechtshinweis hinzu.

Ein Copyrighthinweis gibt im Wesentlichen an, dass Ihre Arbeit ohne Ihre Berechtigung nicht kopiert werden kann. Ein Copyrighthinweis lässt sich einfach in Ihr Paket einbeziehen und schadet nicht!

Beispiel: Copyright (c) Contoso 2020

Projekt-URL

✔️ Schließen Sie einen Link zu einem zugeordneten Projekt, Repository oder einer Unternehmenswebsite ein.

Ihre Projektwebsite sollte alles enthalten, was Benutzer über Ihr Paket wissen müssen, und sich dort befinden, wo Benutzer wahrscheinlich nach Dokumentation suchen.

Schaltfläche

✔️ ERWÄGEN Sie, ein Symbol mit Ihrem Paket einzubeziehen, damit es visuell unterschieden werden kann. Es handelt sich um einen relativ kleinen Zusatz, der die Wahrnehmung der Paketqualität verbessern kann.

Es kommen für einzelne Pakete spezifische Symbole oder Markenlogos infrage.

✔️ Verwenden Sie ein Bild, das 128x128 groß ist und einen transparenten Hintergrund (PNG) für die ideale Darstellung hat.

NuGet skaliert Ihr Bild automatisch für den Client, auf dem es angezeigt wird.

❌ Verwenden Sie KEINE veraltete IconUrl-Metadateneigenschaft.

Infodatei

✔️ Fügen Sie eine README-Markdowndatei hinzu, die einen Überblick über die Funktionsweise Ihres Pakets und die ersten Schritte bietet.

Eine README-Datei für das Paket verbessert dessen Qualitätswahrnehmung sowie das Onboarding neuer Benutzer*innen erheblich. Ziehen Sie außerdem eine Vorschau Ihrer README-Datei in Betracht, bevor Sie sie hochladen. Erfahren Sie, wie Sie eine README-Datei in Ihr NuGet-Paket einschließen, um weitere Details zu erhalten.

Repositorytyp und URL

✔️ ERWÄGEN Sie die Einrichtung von SourceLink, um dem NuGet-Paket automatisch Quellcodeverwaltungs-Metadaten hinzuzufügen und das Debuggen der Bibliothek zu vereinfachen.

SourceLink fügt automatisch Repository URL- und Repository Type-Paketmetadaten hinzu. Außerdem wird der spezifische Commit hinzugefügt, der ihrer Paketversion zugeordnet ist.

Tags

✔️ Beziehen Sie mehrere Tags mit wichtigen Begriffen zu Ihrem Paket ein, um die Auffindbarkeit zu verbessern.

Tags werden im Suchalgorithmus von NuGet.org berücksichtigt und sind besonders hilfreich für Begriffe, die nicht in der Paket-ID vorliegen, aber relevant sind.

Wenn Sie z. B. ein Paket zum Protokollieren von Zeichenfolgen in der Konsole veröffentlicht haben, sollten Sie „Protokollierung, Protokoll, Konsole, Zeichenfolge, Ausgabe“ einschließen.

Versionshinweise

✔️ Schließen Sie Versionshinweise in jedes Update ein, die beschreiben, welche Änderungen vorgenommen wurden.

Es ist zwar kein bestimmtes Format für Versionshinweise vorgegeben, aber Sie sollten Folgendes einschließen:

  1. Wichtige Änderungen
  2. Neue Funktionen
  3. Fehlerkorrekturen

Wenn Sie bereits Versionshinweise oder ein Änderungsprotokoll in Ihrem Repository nachverfolgen, können Sie auch einen Link zur entsprechenden Datei einschließen.

Lizenzierung

✔️ Beziehen Sie einen Lizenzausdruck oder eine Lizenzdatei in Ihr Paket ein.

Wichtig

Für ein Projekt ohne Lizenz gilt standardmäßig ein exklusives Copyright, was bedeutet, dass Sie niemandem eine Berechtigung zur Verwendung Ihres Projekts erteilt haben.

❌ Verwenden Sie KEINE veraltete LicenseUrl-Metadateneigenschaft.

Dies führt zu einer rechtlichen Unklarheit, da Lizenzänderungen an der URL die angezeigte Lizenz für vorherige Paketversionen rückwirkend ändern.

Wenn Ihr Paket ein Open-Source-Paket ist

✔️ Wählen Sie eine Open-Source-Lizenz aus, um Ihr Paket zu einem Open-Source-Paket zu machen.

„Open-Source-Lizenzen sind Lizenzen, die der Open-Source-Definition entsprechen – kurz gesagt, sie ermöglichen die freie Nutzung, Änderung und Freigabe von Software.“ – Open Source Initiative. Weitere Informationen zu Open-Source-Software und der Open-Source-Initiative finden Sie unter https://opensource.org/.

✔️ ERWÄGEN Sie, einen Lizenzausdruck in Ihr Paket einzubeziehen.

Lizenzausdrücke werden am deutlichsten angezeigt und zeigen Consumern klarer, ob sie das Paket verwenden können, oder ob sich die Lizenz geändert hat.

Hinweis

NuGet.org akzeptiert nur Lizenzausdrücke für Lizenzen, die von der Open-Source-Initiative oder der Free Software Foundation genehmigt wurden.

Wenn Ihr Paket kein Open-Source-Paket ist

✔️ Beziehen Sie einen Lizenzausdruck in Ihr Paket ein.

Alle Lizenzdateien (TXT oder MD) können dem Paket hinzugefügt werden, einschließlich nicht standardmäßiger Lizenzen.