NuGet

NuGet ist ein Paket-Manager für das .NET-Ökosystem und das primäre System, mit dem Entwickler Open Source-Bibliotheken von .NET untersuchen und abrufen. NuGet.org ist ein kostenloser Dienst von Microsoft zum Hosten von NuGet-Paketen und der primäre Host für öffentliche NuGet-Pakete. Sie können damit auch Veröffentlichungen in benutzerdefinierten NuGet-Diensten wie MyGet und Azure Artifacts ausführen.

Erstellen eines NuGet-Pakets

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

Sie haben im Wesentlichen zwei Optionen, ein NuGet-Paket zu erstellen. Der neuere und empfohlene Ansatz ist das Erstellen eines Pakets aus einem Projekt im SDK-Stil, d. h. aus einer 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. Die Kompilierung mit dem Befehl dotnet pack gibt anstelle von Assemblys eine *.nupkg-Datei aus.

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

Der ältere Ansatz zum Erstellen eines NuGet-Pakets erfordert eine *.nuspec-Datei und das Befehlszeilentool nuget.exe. Mit einer NUSPEC-Datei haben Sie umfangreiche Kontrolle, doch Sie müssen sorgfältig angeben, welche Assemblys und Ziele in das endgültige NuGet-Paket aufgenommen werden. Achten Sie darauf, dass Ihnen keine Fehler unterlaufen, und dass Sie nicht vergessen, die NUSPEC-Datei zu aktualisieren, nachdem Sie Änderungen vorgenommen haben. Der Vorteil einer NUSPEC-Datei ist, dass Sie mit ihr NuGet-Pakete für Frameworks erstellen können, die noch keine im Projektdatei im SDK-Stil unterstützen.

✔️ Verwenden Sie eine SDK-Projektdatei zum Erstellen des NuGet-Pakets.

Paketabhängigkeiten

Abhängigkeiten von NuGet-Paketen werden im Artikel Abhängigkeiten ausführlich erläutert.

Wichtige Metadaten von NuGet-Paketen

Ein NuGet-Paket unterstützt viele Metadateneigenschaften. Die folgende Tabelle enthält die wichtigsten Metadaten, 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	Die NuGet-Paketversion. Weitere Informationen finden Sie unter NuGet-Paketversion.
Title	title	Ein benutzerfreundlicher Pakettitel. Er entspricht standardmäßig PackageId.
Description	description	Eine ausführliche Beschreibung des Pakets, die in der Benutzeroberfläche angezeigt wird.
Authors	authors	Eine durch Trennzeichen getrennte Liste von Paketerstellern, die den Profilnamen auf nuget.org entspricht.
PackageTags	tags	Eine durch Leerzeichen getrennte Liste von Tags und Keywords, die das Paket beschreiben Tags werden bei der Suche nach Paketen verwendet.
PackageIcon	icon	Ein Pfad zu einem Bild im Paket, das als Paketsymbol verwendet werden soll. Erfahren Sie mehr über icon-Metadaten.
PackageProjectUrl	projectUrl	Eine URL für die Projekthomepage oder das Quellrepository.
PackageLicenseExpression	license	Die SPDX-ID der Projektlizenz. Nur OSI- und FSF-genehmigte Lizenzen können eine ID verwenden. Andere Lizenzen sollten PackageLicenseFile verwenden. 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.

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

✔️ Verwenden Sie einen HTTPS-Hypertextverweis für Ihr Paketsymbol.

Websites wie NuGet.org werden mit aktiviertem HTTPS ausgeführt, und die Anzeige eines Nicht-HTTPS-Bildes generiert eine Warnung vor gemischten Inhalten.

✔️ Verwenden Sie ein Paketsymbolbild, das 64x64 groß ist und einen transparenten Hintergrund für die ideale Darstellung hat.

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

SourceLink fügt dem NuGet-Paket automatisch RepositoryUrl- und RepositoryType-Metadaten hinzu. SourceLink fügt auch Informationen zum genauen Quellcode hinzu, mit dem das Paket erstellt wurde. Beispielsweise wird einem Paket, das aus einem Git-Repository erstellt wurde, der Commithash als Metadaten hinzugefügt.

Vorabversionen von Paketen

NuGet-Pakete mit einem Versionssuffix gelten als Vorabversion. Standardmäßig zeigt die Benutzeroberfläche des NuGet-Paket-Managers stabile Versionen an, es sei denn, ein Benutzer veröffentlicht Pakete vorab – Vorabversionspakete eignen sich ideal für eingeschränkte Benutzertests.

<PackageVersion>1.0.1-beta1</PackageVersion>

Hinweis

Ein stabiles Paket kann nicht von einem Vorabversionspaket abhängen. Sie müssen entweder Ihr eigenes Paket vorab veröffentlichen oder eine ältere stabile Version verwenden.

✔️ Veröffentlichen Sie ein Vorabversionspaket für Tests und Vorschauen.

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

Symbolpakete

Symboldateien (*.pdb) werden vom .NET-Compiler neben Assemblys erstellt. Symboldateien ordnen Ausführungsstandorte dem ursprünglichen Quellcode zu, sodass Sie den Quellcode bei der Ausführung mit einem Debugger durchgehen können. 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 und nur bei Bedarf von einem Tool wie Visual Studio heruntergeladen werden.

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

Wichtig

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

Entwickler benötigen Visual Studio 2017 Version 15.9 oder höher, um beim Debuggen einer .NET-Bibliothek den NuGet.org-Symbolserver zu verwenden.

Eine Alternative zum Erstellen eines Symbolpakets ist das Einbetten von Symboldateien in das NuGet-Hauptpaket. Das NuGet-Hauptpaket ist zwar größer, doch da die Symboldateien eingebettet sind, müssen Entwickler den NuGet.org-Symbolserver nicht konfigurieren. Wenn Sie Ihr NuGet-Paket mit einem SDK-Projekt 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 von eingebetteten Symboldateien ist, dass sie die Paketgröße für .NET-Bibliotheken, die mit SDK-Projekten kompiliert wurden, um etwa 30 % erhöhen. Wenn die Paketgröße ein Problem darstellt, sollten Sie Symbole stattdessen in einem Symbolpaket veröffentlichen.

✔️ Überlegen Sie sich, ob Sie Symbole als Symbolpaket (*.snupkg) auf NuGet.org veröffentlichen möchten

Mit Symbolpaketen (*.snupkg) erhalten Entwickler eine gute abrufbare Debugfunktion, ohne dass die Größe des Hauptpakets und die Wiederherstellungsleistung für diejenigen, die das NuGet-Paket nicht debuggen möchten, beeinträchtigt wird.

Der Nachteil ist, dass Benutzer möglicherweise den NuGet-Symbolserver in ihrer IDE finden und konfigurieren müssen (einmalige Konfiguration), um Symboldateien abzurufen. In Version 16.1 von Visual Studio 2019 wurde der Symbolserver von nuget.org der Liste der Standardsymbolserver hinzugefügt.

ZurückWeiter