NuGet

NuGet is een pakketbeheerder voor het .NET-ecosysteem en is de primaire manier waarop ontwikkelaars .NET-opensourcebibliotheken ontdekken en verkrijgen. NuGet.org, een gratis service van Microsoft voor het hosten van NuGet-pakketten, is de primaire host voor openbare NuGet-pakketten, maar u kunt publiceren naar aangepaste NuGet-services, zoals MyGet en Azure Artifacts.

Een NuGet-pakket maken

Een NuGet-pakket (*.nupkg) is een ZIP-bestand dat .NET-assembly's en bijbehorende metagegevens bevat.

Er zijn twee manieren om een NuGet-pakket te maken. De nieuwere en aanbevolen manier is om een pakket te maken op basis van een SDK-project (projectbestand waarvan de inhoud begint met <Project Sdk="Microsoft.NET.Sdk">). Assembly's en doelen worden automatisch toegevoegd aan het pakket en de resterende metagegevens worden toegevoegd aan het MSBuild-bestand, zoals pakketnaam en versienummer. Bij het compileren met de dotnet pack opdracht wordt een *.nupkg bestand uitgevoerd in plaats van assembly's.

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

De oudere manier om een NuGet-pakket te maken, is met een *.nuspec bestand en het nuget.exe opdrachtregelprogramma. Een nuspec-bestand biedt u veel controle, maar u moet zorgvuldig opgeven welke assembly's en doelen moeten worden opgenomen in het uiteindelijke NuGet-pakket. Het is eenvoudig om een fout te maken of iemand vergeet de nuspec bij te werken bij het aanbrengen van wijzigingen. Het voordeel van een nuspec is dat u dit kunt gebruiken om NuGet-pakketten te maken voor frameworks die nog geen SDK-projectbestand ondersteunen.

✔️ OVERWEEG om een SDK-projectbestand te gebruiken om het NuGet-pakket te maken.

Pakketafhankelijkheden

NuGet-pakketafhankelijkheden worden uitgebreid beschreven in het artikel Afhankelijkheden .

Belangrijke metagegevens van NuGet-pakketten

Een NuGet-pakket ondersteunt veel metagegevenseigenschappen. De volgende tabel bevat de belangrijkste metagegevens die elk pakket op NuGet.org moet bieden:

NAAM VAN MSBuild-eigenschap	Nuspec-naam	Beschrijving
PackageId	id	De pakket-id. Een voorvoegsel van de id kan worden gereserveerd als het voldoet aan de criteria.
PackageVersion	version	NuGet-pakketversie. Zie NuGet-pakketversie voor meer informatie.
Title	title	Een mensvriendelijke titel van het pakket. Deze wordt standaard ingesteld op de PackageId.
Description	description	Een lange beschrijving van het pakket dat wordt weergegeven in de gebruikersinterface.
Authors	authors	Een door komma's gescheiden lijst met pakketauteurs die overeenkomen met de profielnamen op nuget.org.
PackageTags	tags	Een spatie of door puntkomma's gescheiden lijst met tags en trefwoorden die het pakket beschrijven. Tags worden gebruikt bij het zoeken naar pakketten.
PackageIcon	icon	Een pad naar een afbeelding in het pakket die moet worden gebruikt als pakketpictogram. Meer informatie over icon metagegevens.
PackageProjectUrl	projectUrl	Een URL voor de startpagina van het project of de bronopslagplaats.
PackageLicenseExpression	license	De SPDX-id van de projectlicentie. Alleen OSI- en FSF-goedgekeurde licenties kunnen een id gebruiken. Andere licenties moeten worden gebruikt PackageLicenseFile. Meer informatie over license metagegevens.

Belangrijk

Een project zonder licentie is standaard ingesteld op exclusief auteursrecht, waardoor het wettelijk onmogelijk is voor anderen om het te gebruiken.

✔️ OVERWEEG om een NuGet-pakketnaam te kiezen met een voorvoegsel dat voldoet aan de reserveringscriteria voor nuGet-voorvoegsels.

✔️ GEBRUIK EEN HTTPS-href voor het pakketpictogram.

Sites zoals NuGet.org worden uitgevoerd met HTTPS ingeschakeld en als u een niet-HTTPS-installatiekopieën weergeeft, wordt er een waarschuwing voor gemengde inhoud gemaakt.

✔️ Gebruik wel een afbeelding van een pakketpictogram die 64x64 is en een transparante achtergrond heeft voor de beste weergaveresultaten.

✔️ Overweeg het instellen van Source Link om metagegevens van broncodebeheer toe te voegen aan uw assembly's en het NuGet-pakket.

Bronkoppeling voegt automatisch metagegevens toe RepositoryUrl aan RepositoryType het NuGet-pakket. Source Link voegt ook informatie toe over de exacte broncode waaruit het pakket is gebouwd. Voor een pakket dat is gemaakt op basis van een Git-opslagplaats, wordt bijvoorbeeld de doorvoerhash toegevoegd als metagegevens.

Pre-releasepakketten

NuGet-pakketten met een versieachtervoegsel worden beschouwd als voorlopige versie. Standaard worden in de Gebruikersinterface van NuGet Pakketbeheer stabiele releases weergegeven, tenzij een gebruiker zich aanmeldt voor pre-releasepakketten, waardoor pre-releasepakketten ideaal zijn voor beperkte gebruikerstests.

<PackageVersion>1.0.1-beta1</PackageVersion>

Notitie

Een stabiel pakket kan niet afhankelijk zijn van een pre-releasepakket. U moet uw eigen pakket pre-release maken of afhankelijk zijn van een oudere stabiele versie.

✔️ Publiceer een pre-releasepakket bij het testen, bekijken of experimenteren.

✔️ Publiceer een stabiel pakket wanneer het klaar is, zodat andere stabiele pakketten ernaar kunnen verwijzen.

Symbolenpakketten

Symboolbestanden (*.pdb) worden geproduceerd door de .NET-compiler naast assembly's. Symboolbestanden wijzen uitvoeringslocaties toe aan de oorspronkelijke broncode, zodat u de broncode kunt doorlopen terwijl deze wordt uitgevoerd met behulp van een foutopsporingsprogramma. NuGet ondersteunt het genereren van een afzonderlijk symboolpakket (*.snupkg) met symboolbestanden naast het hoofdpakket met .NET-assembly's. Het idee van symbolenpakketten is dat ze worden gehost op een symboolserver en alleen worden gedownload door een hulpprogramma zoals Visual Studio op aanvraag.

NuGet.org een eigen opslagplaats voor symbolenservers host. Ontwikkelaars kunnen de symbolen die zijn gepubliceerd op de NuGet.org symboolserver gebruiken door ze toe te voegen https://symbols.nuget.org/download/symbols aan hun symboolbronnen in Visual Studio.

Belangrijk

De NuGet.org symboolserver ondersteunt alleen de nieuwe draagbare symboolbestanden (*.pdb) die zijn gemaakt door SDK-projecten.

Als u de NuGet.org symboolserver wilt gebruiken bij het opsporen van fouten in een .NET-bibliotheek, moeten ontwikkelaars Beschikken over Visual Studio 2017 versie 15.9 of hoger.

Een alternatief voor het maken van een symboolpakket is het insluiten van symboolbestanden in het belangrijkste NuGet-pakket. Het belangrijkste NuGet-pakket is groter, maar de ingesloten symboolbestanden betekent dat ontwikkelaars de NuGet.org symboolserver niet hoeven te configureren. Als u uw NuGet-pakket bouwt met behulp van een SDK-project, kunt u symboolbestanden insluiten door de eigenschap in te AllowedOutputExtensionsInPackageBuildOutputFolder stellen:

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

Het nadeel van het insluiten van symboolbestanden is dat ze de pakketgrootte met ongeveer 30% verhogen voor .NET-bibliotheken die zijn gecompileerd met behulp van SDK-projecten. Als pakketgrootte een probleem is, moet u in plaats daarvan symbolen publiceren in een symboolpakket.

✔️ OVERWEEG symbolen te publiceren als een symboolpakket (*.snupkg) om te NuGet.org

Symboolpakketten (*.snupkg) bieden ontwikkelaars een goede ervaring voor foutopsporing op aanvraag zonder de grootte van het hoofdpakket op te bloteren en de herstelprestaties te beïnvloeden voor degenen die geen fouten in het NuGet-pakket willen opsporen.

Het nadeel is dat gebruikers mogelijk de NuGet-symboolserver moeten zoeken en configureren in hun IDE (als eenmalige installatie) om symboolbestanden op te halen. Visual Studio 2019 versie 16.1 heeft nuGet.org's symboolserver toegevoegd aan de lijst met standaard symboolservers.

VorigeVolgende