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 met .NET-assembly's en bijbehorende metagegevens.

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">). Assemblies en doelen worden automatisch toegevoegd aan het pakket en de resterende metadata wordt toegevoegd aan het MSBuild-bestand, zoals de pakketnaam en het versienummer. Bij het compileren met de opdracht dotnet pack 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 besproken in het artikel Afhankelijkheden.

Belangrijke metagegevens van NuGet-pakketten

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

Eigenschapsnaam MSBuild	Nuspec-naam	Beschrijving
PackageId	id	De pakket-id. Een voorvoegsel van de identificatiecode kan worden gereserveerd als het voldoet aan het criterium.
PackageVersion	version	NuGet-pakketversie. Zie NuGet-pakketversievoor 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. Lees meer over icon metagegevens.
PackageProjectUrl	projectUrl	Een URL voor de startpagina van het project of de bronopslagplaats.
PackageLicenseExpression	license	De SPDX-identificator van de projectlicentie. Alleen OSI- en FSF-goedgekeurde licenties kunnen een id gebruiken. Andere licenties moeten PackageLicenseFilegebruiken. Lees meer over license metagegevens.

Belangrijk

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

✔️ OVERWEEG een NuGet-pakketnaam te kiezen met een voorvoegsel dat voldoet aan de reservatiecriteria van NuGet voorvoegsels .

✔️ GEBRUIK EEN HTTPS-href voor het pakketpictogram.

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

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

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

Bronkoppeling voegt automatisch RepositoryUrl en RepositoryType metagegevens toe aan 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.

Prereleasepakketten

NuGet-pakketten met een versieachtervoegsel worden beschouwd als prerelease-. De Gebruikersinterface van NuGet Package Manager toont standaard stabiele releases, tenzij een gebruiker zich aanmeldt voor prereleasepakketten, waardoor prereleasepakketten ideaal zijn voor beperkte gebruikerstests.

<PackageVersion>1.0.1-beta1</PackageVersion>

Notitie

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

✔️ Publiceer een prereleasepakket 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 host een eigen serveropslagplaats voor symbolen. Ontwikkelaars kunnen de symbolen die zijn gepubliceerd op de NuGet.org symboolserver gebruiken door https://symbols.nuget.org/download/symbols toe te voegen 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 AllowedOutputExtensionsInPackageBuildOutputFolder in te 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 sdk-stijlprojecten. Als pakketgrootte een probleem is, moet u in plaats daarvan symbolen publiceren in een symboolpakket.

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

Symboolpakketten (*.snupkg) bieden ontwikkelaars een goede ervaring voor foutopsporing op aanvraag zonder de grootte van het hoofdpakket op te bloppen 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