Implementeringsguide för NuGet Server

I vissa fall kanske du vill implementera din egen NuGet-paketfeed. Det finns många befintliga implementeringar som gör att du kan vara värd för ditt eget flöde på olika sätt, men protokollet mellan den officiella NuGet-klientprogramvaran och ett paketflöde dokumenteras så att du kan skapa en egen feedimplementering från grunden.

Protokollet utvecklas med tiden och den här guiden riktar sig till dem som vill eller redan har implementerat en NuGet-paketserver.

Sedan den första versionen av NuGet V3-protokollet 2015 har NuGet utvecklats för att ge utvecklare en bättre upplevelse, och detta kräver att paketlagringsplatser utför ytterligare arbete för att ge det extra värdet som paketkonsumenter, utöver att bara kräva metadata från värdbaserade paket och returnera metadata i olika former. Till exempel innehåller slutpunkterna för sök- och paketmetadata mer än bara metadata som finns i nupkg-nuspecfilen.

Observera att den här guiden fokuserar på NuGet V3-protokollet eftersom V2-protokollet i huvudsak är odokumenterat och sedan 2015 är det rekommenderade protokollet för NuGet-klient- och serverkommunikation V3-protokollet. Mer information finns i avsnittet om versionshantering av protokoll.

Kronologi

För att hjälpa författare till befintliga NuGet-lagringsplatser att hålla sig uppdaterade med NuGets senaste funktioner, här är kronologin för relevanta funktioner som nämns i resten av dokumentet.

År	Egenskap
2013	Ett blogginlägg som förklarar hur du hanterar paketägare på nuget.org klargjorde att ägarna som visas på webbplatsen är de konton som har behörighet att ladda upp nya versioner, och därför owners ignoreras metadata i paketet
2017	Har lagts till verified till SearchQueryService-svar.
	Stöd för semantisk versionshantering 2.0.0
2018	Inbäddade licenser
2019	Inbäddade ikoner
	Utfasning av paket i RegistrationBaseUrl (paketmetadataresurs)
2020	Paketera sårbarhetsinformation i RegistrationsBaseUrl (paketmetadataresurs)
	Frågeparametern har lagts packageTypes till i SearchQueryService begäranden
2021	Inbäddad readme
2023	Förautentisera autentiserade begäranden VulnerabilityInfo resurs
2025	Aktivera inbäddade README-nedladdningar

Fältet Ägare

Överväg två av paketmanifestfilens (.nuspec) fält <authors> och <owners>. Paketförfattare som paketerar innehåll från tredje part placerar ofta tredjepartsnamnet i fältet <authors> . Fältet <owners> var avsett att ange vem som publicerade paketet på en lagringsplats och därför vem som skulle kontaktas vid förpackningsproblem eller frågor.

Detta förklarades i ett blogginlägg från 2013, så fältet <owners> anses vara inaktuellt i .nuspec filen. Om paketets manifest innehåller dessa metadata bör det ignoreras. Returnera inte värdet för .nuspec filens <owners> fält i owners egenskapen i JSON-svaret för sökresursen eller paketmetadataresursen .

Om lagringsplatsen har behörighet per paket rekommenderar vi att du rapporterar de konton som har behörighet att publicera nya versioner i owner metadata för JSON-svar för sök- och paketmetadataresurser.

verified söksvarsfält

Visual Studio Package Manager-användargränssnittet visar en blå bockmarkering bredvid paket i sökresultaten när ett nytt fält verified är inställt på true.

NuGet.org använder detta med paketprefixdata (data på serversidan, inte en del av NuGet-API:et), så att den här bockmarkeringen endast visas för kunder när kontot som äger paketet laddade upp paketet. Till exempel verifieras alla paket med prefix microsoft.* endast när paketet ägs av Microsoft-kontot på nuget.org. Alla som laddade upp ett paket med paket-ID som började med microsoft. innan reserverade prefix implementerades kommer inte att ha den här verifierade bockmarkeringen. NuGet.org tillåter också att prefix inte är exklusiva, så att vem som helst kan ladda upp ett paket under Contoso.ToolWithPlugins.Community.*, men inte får en verifierad bockmarkering.

Stöd för semantisk versionshantering 2.0.0

NuGet stöder en hybrid mellan System.Version och semantisk version, men stöd för semantisk version 2.0.0 lades till 2017. NuGet API-resurser som returnerar versioner till klientversioner som är lägre än 3.6.0 får därför inte returnera paket som använder Semantic 2.0.0-funktioner som inte är kompatibla med semantisk version 1.0.0.

De viktigaste skillnaderna mellan de två versionerna är förhandsversionsetiketterna och metadatasträngen. Specifikationen Semantic Versioning 1.0.0 tillhandahåller [0-9A-Za-z-] som ett exempel på strängen Reguljärt uttryck för de enda tecken som tillåts som en del av etiketten före lanseringen och stöder inte metadatasträngar. Med specifikationen Semantic Versioning 2.0.0 kan förversionsidentifierare avgränsas med tecken (och förbjuder en numerisk identifierare från att ha en inledande nolla), och dessutom kan kompileringsmetadata . läggas till efter en +.

I paketmetadataresursen (RegistrationsBaseUrl)får resursversioner under 3.6.0 endast returnera paket som uppfyller . NET:s System.Version eller semantiska versionshantering 1.0.0. Det innebär att paket vars versioner endast är kompatibla med semantisk version 2.0.0 är osynliga för dessa klientversioner.

På samma sätt har sökfrågetjänsten (SearchQueryService) och tjänsten för automatisk komplettering (SearchAutocompleteService) lagt till &semVerLevel={version} frågeparametrar. När semVerLevel saknas antar du värdet 1.0.0. Precis som paketmetadataresursen får paket vars version endast är kompatibel med Semantic Versioning 2.0.0 inte returneras när semVerLevel värdet är under 2.0.0.

Inbäddade filer

Paketikoner, licens- och readme-filer kan bäddas in (och rekommenderas att vara) inbäddade i paketet. Dessa filer behöver en URL-slutpunkt som antingen extraheras och placeras på en statisk filserver eller en URL som dynamiskt extraherar filerna från den .nupkg på begäran, så att de kan visas utan att ladda ned hela nupkg. Om paketlagringsplatsen innehåller paketbläddring och visning av paketinformation kan du använda URL:erna för att visa kunderna det inbäddade innehållet på din webbplats.

Slutligen måste paketmetadataresursen och sökresursen innehålla den värdbaserade URL:en i iconUrlegenskaperna , licenseUrloch/eller readmeUrl för JSON-svaret. Paket (.nupkg filer) får inte ändras eftersom klientfunktioner (låsfiler och signerade paket) identifierar ändringar när paketet har manipulerats.

Observera att licensen kan vara ett SPDX-uttryck eller en inbäddad fil (men inte båda). Paket som använder ett licensuttryck, när de representeras i sökresultat och paketmetadataresultat, kan ha licenseUrl värdet för licensuttrycket, URL:en kodad och bifogad till slutet av https://licenses.nuget.org/. Till exempel https://licenses.nuget.org/Apache-2.0. NuGet.org-serverteamet har ytterligare dokumentation om licenses.nuget.org.

Kända sårbarhets- och utfasningsdata

Paketmetadataresurs (RegistrationsBaseUrl)

Paketmetadataresursen kan innehålla utfasnings- och sårbarhetsinformation. På så sätt kan kunder som bläddrar i paket i Visual Studio Package Manager-användargränssnittet, eller motsvarande i andra IDE:er, meddelas om viktiga säkerhets- eller underhållsproblem.

Om din paketlagringsplats hämtar paket från en annan lagringsplats för att spegla dem i din egen kanal, rekommenderar vi att du regelbundet kontrollerar den ursprungliga källan för eventuella utfasnings- eller sårbarhetsdata och speglar den metadata i din egen lagringsplats. Om din paketlagringsplats hämtar specifikt från nuget.org, genom att behålla tillståndet för den senaste gången du kontrollerade (en "markör"), kan du använda resursen Catalog för att effektivt kontrollera om det finns några paketuppdateringar för paket du speglar, utan att behöva ladda ned ett stort antal paketmetadata-JSON-filer från den ursprungliga feeden. Det finns en guide om hur du använder katalogresursen med exempelkod som kan hjälpa dig att komma igång.

Känd sårbarhetsdatabas (VulnerabilityInfo)

För att tillhandahålla sårbarhetsgenomsökning med höga prestanda under paketåterställningen laddar NuGet ned den fullständiga listan över kända sårbarheter från resursenVulnerabilityInfo. Nuget.org tillhandahåller sårbarhetsdata för alla GitHub-granskade rekommendationer från GitHub Advisories-databasen, som innehåller paket som inte finns på nuget.org.

Om din paketlagringsplats är värd för paket från första part och du vill ge sårbarhetsinformation till kunder som använder ditt eget flöde, men ännu inte har några avslöjade paketsårbarheter, bör du ange ett sårbarhetsindex med en eller flera sårbarhetssidor vars innehåll är en tom JSON-matris ([]).

Om din paketlagringsplats är avsedd att användas av appar som standardlagringsplats (i stället för nuget.org) kan du använda nuget.orgs sårbarhetsdata. Ett alternativ är att använda nuget.orgs url för sårbarhetsindex i tjänstindexet. Ett annat alternativ är att regelbundet kontrollera nuget.orgs VulnerabilityInfo index och ladda ned alla ändrade sidor för att spegla lokalt.

packageTypes sökfråga

Med .NET CLI kan du söka efter .NET-verktygspaket med dotnet tool search kommandot . Detta implementeras genom att lägga till en &packageTypes={value} frågeparameter i sökfrågeresursen som läser värden från paketets .nuspec filfält <packageTypes> .

URL-struktur för autentiserade feeds

Enligt beskrivningen i översikten över NuGet-API:et är start-URL:en för all NuGet-serverkommunikation tjänstindexet. Det här dokumentet innehåller URL:er för alla andra resurser som NuGet-klienter ska fråga efter. Från och med NuGet 6.7 (Visual Studio & MSBuild 17.7 och .NET SDK 7.0.400) använder NuGet . NET: s HttpClientHandler.PreAuthenticate, som endast undviker anonyma HTTP-begäranden när efterföljande URL:er finns i samma virtuella katalog, eller en underkatalog, för en URL som tidigare har autentiserats. Detta minskar dramatiskt antalet oautentiserade HTTP-begäranden som skickas till servern och minskar därför serverarbetsbelastningen.

Här följer några exempel:

Webbadress	Kommer förautentisera?
https://pkgs.contoso.com/nuget/v3/feed/index.json	Det här är tjänstindexet.
https://pkgs.contoso.com/nuget/v3/search	Nej, inte i samma katalog eller i underkatalogen som tjänstindexet.
https://search.pkgs.contoso.com/nuget/v3/feed/	Nej, inte på samma värdnamn som tjänstindexet.
https://pkgs.contoso.com/nuget/v3/feed/search	Ja, i samma katalog som tjänstindexet.
https://pkgs.contoso.com/nuget/v3/registration/	Nej, inte i en underkatalog för tjänstindexet.
https://pkgs.contoso.com/nuget/v3/feed/registration/	Ja, i en underkatalog till tjänstindexet.
https://pkgs.contoso.com/nuget/v3/{guid}/registration/	Se nedan

I det sista exemplet kan servern ha ett kanoniskt (i det här exemplet ett guid)-namn och ha ett eller flera alias. Om begäran om tjänstindex autentiserades på en icke-kanonisk URL (det "egna" namnet i vårt exempel feed), så kommer nej, inga begäranden till resurser under den kanoniska URL:en att matcha HttpClientHandlers regler för PreAuthenticate. Men om den icke-kanoniska URL:en är en HTTP-omdirigering till den kanoniska URL:en https://pkgs.contoso.com/nuget/v3/{guid}/index.jsonanvänds den här URL:en i HttpClientHandlercacheminnet för autentiseringsuppgifter. I det här fallet får varje begäran till tjänstindex ytterligare svarstid på grund av omdirigeringen.

NuGets V3-API har utformats för att fungera på en statisk filserver, men sökresursen är undantaget som alltid kräver en dynamisk webbtjänst för att bearbeta begäranden. Om du vill driva sökning, eller någon annan NuGet API-resurs, på olika servrar för att dra nytta av HttpClientHandlerPreAuthenticate, måste du använda en omvänd proxy för att säkerställa att alla kundriktade URL:er i tjänstindexet följer regeln om "samma eller underkatalog".

Aktivera inbäddade README-nedladdningar

En ny resurs har dokumenterats för att skapa en URL som kan användas för att ladda ned en README för ett visst paket. Detta gör att klienten, till exempel pakethanteringsgränssnittet i VS, kan visa den inbäddade README för paket som inte tidigare har installerats av användaren. Klienten skapar den här URL:en och försöker ladda ned README med hjälp av svaret på begäran för att avgöra om en README är tillgänglig. Det innebär att servrar bör förvänta sig flera begäranden till den konstruerade slutpunkten när användarna navigerar i PM-användargränssnittet.