NuGet
NuGet är en pakethanterare för .NET-ekosystemet och är det primära sättet för utvecklare att identifiera och hämta .NET-bibliotek med öppen källkod. NuGet.org, en kostnadsfri tjänst som tillhandahålls av Microsoft för att vara värd för NuGet-paket, är den primära värden för offentliga NuGet-paket, men du kan publicera till anpassade NuGet-tjänster som MyGet och Azure Artifacts.
Skapa ett NuGet-paket
Ett NuGet-paket (*.nupkg) är en zip-fil som innehåller .NET-sammansättningar och associerade metadata.
Det finns två huvudsakliga sätt att skapa ett NuGet-paket. Det nyare och rekommenderade sättet är att skapa ett paket från ett SDK-projekt (projektfil vars innehåll börjar med <Project Sdk="Microsoft.NET.Sdk">). Sammansättningar och mål läggs automatiskt till i paketet och återstående metadata läggs till i MSBuild-filen, till exempel paketnamn och versionsnummer. Kompilering med dotnet pack kommandot matar ut en *.nupkg fil i stället för sammansättningar.
<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>
Det äldre sättet att skapa ett NuGet-paket är med en *.nuspec fil och nuget.exe kommandoradsverktyget. En nuspec-fil ger dig bra kontroll, men du måste noggrant ange vilka sammansättningar och mål som ska ingå i det slutliga NuGet-paketet. Det är lätt att göra ett misstag eller att någon glömmer att uppdatera nuspecen när du gör ändringar. Fördelen med en nuspec är att du kan använda den för att skapa NuGet-paket för ramverk som ännu inte stöder en projektfil i SDK-format.
✔️ ÖVERVÄG att använda en SDK-projektfil för att skapa NuGet-paketet.
Paketberoenden
NuGet-paketberoenden beskrivs i detalj i artikeln Beroenden.
Viktiga NuGet-paketmetadata
Ett NuGet-paket stöder många metadataegenskaper. Följande tabell innehåller de grundläggande metadata som varje paket på NuGet.org ska tillhandahålla:
| MSBuild-egenskapsnamn | Nuspec-namn | beskrivning |
|---|---|---|
PackageId |
id |
Paketidentifieraren. Ett prefix från identifieraren kan reserveras om det uppfyller kriterierna. |
PackageVersion |
version |
NuGet-paketversion. Mer information finns i NuGet-paketversion. |
Title |
title |
En människovänlig titel på paketet. Standardvärdet är PackageId. |
Description |
description |
En lång beskrivning av paketet som visas i användargränssnittet. |
Authors |
authors |
En kommaavgränsad lista över paketförfattare som matchar profilnamnen på nuget.org. |
PackageTags |
tags |
En blankstegs- eller semikolonavgränsad lista med taggar och nyckelord som beskriver paketet. Taggar används när du söker efter paket. |
PackageIcon |
icon |
En sökväg till en bild i paketet som ska användas som paketikon. Läs mer om icon metadata. |
PackageProjectUrl |
projectUrl |
En URL för projektets startsida eller källlagringsplats. |
PackageLicenseExpression |
license |
Projektlicensens SPDX-identifierare. Endast OSI- och FSF-godkända licenser kan använda en identifierare. Andra licenser bör använda PackageLicenseFile. Läs mer om license metadata. |
Viktigt!
Ett projekt utan licens försummar exklusiv upphovsrätt, vilket gör det juridiskt omöjligt för andra att använda.
✔️ ÖVERVÄG att välja ett NuGet-paketnamn med ett prefix som uppfyller NuGets villkor för prefixreservation.
✔️ Använd en HTTPS href till paketikonen.
Webbplatser som NuGet.org köras med HTTPS aktiverat och om du visar en icke-HTTPS-avbildning skapas en varning om blandat innehåll.
✔️ Använd en paketikonbild som är 64 x 64 och har en transparent bakgrund för bästa visningsresultat.
✔️ ÖVERVÄG att konfigurera Källlänk för att lägga till källkontrollmetadata i dina sammansättningar och NuGet-paket.
Source Link lägger automatiskt till
RepositoryUrlochRepositoryTypemetadata i NuGet-paketet. Source Link lägger också till information om den exakta källkoden som paketet skapades från. Ett paket som skapats från en Git-lagringsplats får till exempel incheckningshash som metadata.
Förhandsversionspaket
NuGet-paket med ett versionssuffix anses vara förhandsversion. Som standard visar NuGet Package Manager-användargränssnittet stabila versioner såvida inte en användare väljer förhandsversionspaket, vilket gör förhandsversionspaket idealiska för begränsad användartestning.
<PackageVersion>1.0.1-beta1</PackageVersion>
Kommentar
Ett stabilt paket kan inte vara beroende av ett förhandsversionspaket. Du måste antingen göra ett eget paket i förväg eller vara beroende av en äldre stabil version.
✔️ Publicera ett förhandsversionspaket när du testar, förhandsgranskar eller experimenterar.
✔️ Publicera ett stabilt paket när det är klart så att andra stabila paket kan referera till det.
Symbolpaket
Symbolfiler (*.pdb) skapas av .NET-kompilatorn tillsammans med sammansättningar. Symbolfiler mappar körningsplatser till den ursprungliga källkoden så att du kan gå igenom källkoden när den körs med hjälp av ett felsökningsprogram. NuGet stöder generering av ett separat symbolpaket (*.snupkg) som innehåller symbolfiler tillsammans med huvudpaketet som innehåller .NET-sammansättningar. Tanken med symbolpaket är att de finns på en symbolserver och endast laddas ned av ett verktyg som Visual Studio på begäran.
NuGet.org är värd för en egen symbolserverlagringsplats. Utvecklare kan använda de symboler som publiceras på NuGet.org-symbolservern genom att lägga https://symbols.nuget.org/download/symbols till i deras symbolkällor i Visual Studio.
Viktigt!
NuGet.org-symbolservern stöder endast de nya portabla symbolfilerna (*.pdb) som skapats av SDK-liknande projekt.
Om du vill använda NuGet.org symbolservern vid felsökning av ett .NET-bibliotek måste utvecklare ha Visual Studio 2017 version 15.9 eller senare.
Ett alternativ till att skapa ett symbolpaket är att bädda in symbolfiler i huvudpaketet för NuGet. Huvudpaketet för NuGet blir större, men de inbäddade symbolfilerna innebär att utvecklare inte behöver konfigurera NuGet.org symbolservern. Om du skapar ditt NuGet-paket med ett SDK-projekt kan du bädda in symbolfiler genom att ange egenskapen AllowedOutputExtensionsInPackageBuildOutputFolder :
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<!-- Include symbol files (*.pdb) in the built .nupkg -->
<AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
</PropertyGroup>
</Project>
Nackdelen med att bädda in symbolfiler är att de ökar paketstorleken med cirka 30 % för .NET-bibliotek som kompilerats med hjälp av SDK-liknande projekt. Om paketstorleken är ett problem bör du publicera symboler i ett symbolpaket i stället.
✔️ ÖVERVÄG att publicera symboler som ett symbolpaket (*.snupkg) för att NuGet.org
Symbolpaket (
*.snupkg) ger utvecklare en bra felsökningsupplevelse på begäran utan att den huvudsakliga paketstorleken ökar och påverkar återställningsprestanda för dem som inte tänker felsöka NuGet-paketet.Förbehållet är att användarna kan behöva hitta och konfigurera NuGet-symbolservern i sin IDE (som en engångskonfiguration) för att hämta symbolfiler. Visual Studio 2019 version 16.1 lade till NuGet.orgs symbolserver i listan över standardsymbolservrar.
