NuGet

NuGet ist ein Paket-Manager für das .NET-Ökosystem und ist die primäre Möglichkeit, wie Entwickler .NET Open-Source-Bibliotheken entdecken und erwerben. NuGet.org, ein kostenloser Dienst, der von Microsoft zum Hosten von NuGet-Paketen bereitgestellt wird, ist der primäre Host für öffentliche NuGet-Pakete, aber Sie können in benutzerdefinierten NuGet-Diensten wie MyGet- und Azure Artifactsveröffentlichen.

Erstellen eines NuGet-Pakets

Ein NuGet-Paket (*.nupkg) ist eine ZIP-Datei, die .NET-Assemblys und zugehörige Metadaten enthält.

Es gibt zwei Hauptmethoden zum Erstellen eines NuGet-Pakets. Die neuere und empfohlene Methode besteht darin, ein Paket aus einem SDK-Formatprojekt zu erstellen (Projektdatei, deren Inhalt mit <Project Sdk="Microsoft.NET.Sdk">beginnt). Assemblys und Ziele werden dem Paket automatisch hinzugefügt und die restlichen Metadaten werden der MSBuild-Datei hinzugefügt, z.B. Paketname und Versionsnummer. Durch kompilieren mit dem dotnet pack Befehl wird eine *.nupkg Datei anstelle von Assemblys ausgegeben.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AssemblyName>Contoso.Api</AssemblyName>
    <PackageVersion>1.1.0</PackageVersion>
    <Authors>John Doe</Authors>
  </PropertyGroup>
</Project>

Die ältere Methode zum Erstellen eines NuGet-Pakets besteht aus einer *.nuspec Datei und dem nuget.exe Befehlszeilentool. Eine Nuspec-Datei bietet Ihnen eine hervorragende Kontrolle, aber Sie müssen sorgfältig angeben, welche Assemblys und Ziele in das endgültige NuGet-Paket eingeschlossen werden sollen. Es ist einfach, einen Fehler zu machen oder dass jemand vergisst, die nuspec zu aktualisieren, wenn Änderungen vorgenommen werden. Der Vorteil einer Nuspec ist, dass Sie es verwenden können, um NuGet-Pakete für Frameworks zu erstellen, die noch keine SDK-Projektdatei unterstützen.

✔️ ERWÄGEN SIE die Verwendung einer SDK-Projektdatei zum Erstellen des NuGet-Pakets.

Paketabhängigkeiten

NuGet-Paketabhängigkeiten werden im Artikel Abhängigkeiten ausführlich behandelt.

Wichtige NuGet-Paketmetadaten

Ein NuGet-Paket unterstützt viele Metadaten-Eigenschaften. Die folgende Tabelle enthält die Kernmetadaten, die jedes Paket auf NuGet.org bereitstellen sollte:

MSBuild-Eigenschaftenname	NUSPEC-Name	Beschreibung
PackageId	id	Der Paketbezeichner. Ein Präfix aus dem Bezeichner kann reserviert werden, wenn es die Kriterien erfüllt.
PackageVersion	version	NuGet-Paketversion. Weitere Informationen finden Sie unter NuGet-Paketversion.
Title	title	Ein menschenfreundlicher Titel des Pakets. Er entspricht standardmäßig PackageId.
Description	description	Eine lange Beschreibung des Pakets, das in der Benutzeroberfläche angezeigt wird.
Authors	authors	Eine durch Trennzeichen getrennte Liste der Paketautoren, die den Profilnamen in nuget.org entsprechen.
PackageTags	tags	Eine durch Leerzeichen oder durch Semikolons getrennte Liste von Tags und Schlüsselwörtern, die das Paket beschreiben. Tags werden beim Suchen nach Paketen verwendet.
PackageIcon	icon	Ein Pfad zu einem Bild im Paket, das als Paketsymbol verwendet werden soll. Weitere Informationen zu icon Metadaten.
PackageProjectUrl	projectUrl	Eine URL für die Projektstartseite oder das Quell-Repository.
PackageLicenseExpression	license	Die SPDX-ID der Projektlizenz. Nur genehmigte OSI- und FSF-Lizenzen können einen Bezeichner verwenden. Andere Lizenzen sollten PackageLicenseFileverwenden. Erfahren Sie mehr über license-Metadaten.

Wichtig

Ein Projekt ohne Lizenz unterliegt standardmäßig exklusivem Copyright, sodass es nicht rechtmäßig von anderen Benutzern verwendet werden kann.

✔️ Erwägen Sie die Auswahl eines NuGet-Paketnamens mit einem Präfix, das die Kriterien der Präfix-Reservierung von NuGet erfüllt.

✔️ Verwenden Sie ein HTTPS-Href zu Ihrem Paketsymbol.

Websites wie NuGet.org laufen mit aktiviertem HTTPS und das Anzeigen eines Bildes ohne HTTPS führt zu einer Warnung wegen gemischter Inhalte.

✔️ Verwenden Sie ein Paketsymbolbild mit einer Größe von 64 x 64 und verfügt über einen transparenten Hintergrund, um optimale Anzeigeergebnisse zu erzielen.

✔️ Erwägen Sie die Einrichtung von Source Link, um Ihren Assemblys und dem NuGet-Paket Metadaten der Quellcodeverwaltung hinzuzufügen.

Der Quelllink fügt dem NuGet-Paket automatisch RepositoryUrl und RepositoryType Metadaten hinzu. Der Quelllink fügt außerdem Informationen zum genauen Quellcode hinzu, aus dem das Paket erstellt wurde. Ein aus einem Git-Repository erstelltes Paket hat z. B. den Commit-Hash als Metadaten hinzugefügt.

Vorabpakete

NuGet-Pakete mit einem Versionssuffix werden als Vorabversionbetrachtet. Standardmäßig zeigt die Benutzeroberfläche des NuGet-Paket-Managers stabile Versionen an, es sei denn, ein Benutzer entscheidet sich für Vorabversionen von Paketen, sodass Vorabversionspakete ideal für eingeschränkte Benutzertests geeignet sind.

<PackageVersion>1.0.1-beta1</PackageVersion>

Anmerkung

Ein stabiles Paket kann nicht von einem Vorabpaket abhängen. Sie müssen entweder ihr eigenes Paket vorab erstellen oder von einer älteren stabilen Version abhängen.

✔️ Veröffentlichen Sie ein Vorabversionspaket zum Testen und Experimentieren und zur Vorschau.

✔️ Veröffentlichen Sie ein stabiles Paket, wenn es bereit ist, damit andere stabile Pakete darauf verweisen können.

Symbolpakete

Symboldateien (*.pdb) werden vom .NET-Compiler zusammen mit Assemblys erstellt. Symboldateien ordnen Ausführungsspeicherorte dem ursprünglichen Quellcode zu, sodass Sie den Quellcode schrittweise durchlaufen können, während er mit einem Debugger ausgeführt wird. NuGet unterstützt das Generieren eines separaten Symbolpakets (*.snupkg) mit Symboldateien neben dem Hauptpaket mit .NET-Assemblys. Die Idee von Symbolpaketen ist, dass sie auf einem Symbolserver gehostet werden und nur von einem Tool wie Visual Studio bei Bedarf heruntergeladen werden.

NuGet.org hostet sein eigenes Symbolserverrepository. Entwickler können die auf dem NuGet.org-Symbolserver veröffentlichten Symbole verwenden, indem sie https://symbols.nuget.org/download/symbols zu ihren -Symbolquellen in Visual Studiohinzufügen.

Wichtig

Der NuGet.org-Symbolserver unterstützt nur die neuen portablen Symboldateien (*.pdb), die von SDK-Formatprojekten erstellt wurden.

Um den NuGet.org-Symbolserver beim Debuggen einer .NET-Bibliothek zu verwenden, müssen Entwickler über Visual Studio 2017, Version 15.9 oder höher, verfügen.

Eine Alternative zum Erstellen eines Symbolpakets ist das Einbetten von Symboldateien im NuGet-Hauptpaket. Das NuGet-Hauptpaket ist größer, aber die eingebetteten Symboldateien bedeuten, dass Entwickler den NuGet.org Symbolserver nicht konfigurieren müssen. Wenn Sie Ihr NuGet-Paket mit einem SDK-Formatprojekt erstellen, können Sie Symboldateien einbetten, indem Sie die eigenschaft AllowedOutputExtensionsInPackageBuildOutputFolder festlegen:

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
    <!-- Include symbol files (*.pdb) in the built .nupkg -->
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
</Project>

Der Nachteil der Einbettungssymboldateien besteht darin, dass sie die Paketgröße für .NET-Bibliotheken, die mit SDK-Formatprojekten kompiliert wurden, um etwa 30% erhöhen. Wenn die Paketgröße ein Problem darstellt, sollten Sie stattdessen Symbole in einem Symbolpaket veröffentlichen.

✔️ Erwägen Sie, Symbole als Symbolpaket (*.snupkg) auf NuGet.org hochzuladen.

Symbolpakete (*.snupkg) bieten Entwicklern eine gute On-Demand-Debugging-Erfahrung, ohne die Hauptpaketgröße aufzublähen und die Wiederherstellungsleistung für diejenigen zu beeinträchtigen, die das NuGet-Paket nicht debuggen möchten.

Der Vorbehalt besteht darin, dass Benutzer möglicherweise den NuGet-Symbolserver in ihrer IDE (als einmaliges Setup) suchen und konfigurieren müssen, um Symboldateien abzurufen. Visual Studio 2019, Version 16.1, hat den Symbolserver von NuGet.org der Liste der Standardsymbolserver hinzugefügt.

VorherigeNächste