Implementatiehandleiding voor NuGet Server

In sommige gevallen wilt u mogelijk uw eigen NuGet-pakketfeed implementeren. Er bestaan veel bestaande implementaties waarmee u uw eigen feed op verschillende manieren kunt hosten, maar het protocol tussen de officiële NuGet-clientsoftware en een pakketfeed wordt gedocumenteerd, zodat u uw eigen feed-implementatie helemaal zelf kunt bouwen.

Het protocol ontwikkelt zich in de loop van de tijd en deze handleiding is gericht op degenen die een NuGet-pakketserver willen of al hebben geïmplementeerd.

Sinds de eerste release van het NuGet V3-protocol in 2015 is NuGet ontwikkeld om ontwikkelaars een rijkere ervaring te bieden. Hiervoor moeten pakketopslagplaatsen extra werk doen om de extra waarde van hun pakketgebruikers te bieden, behalve het exacteren van metagegevens van gehoste pakketten en het retourneren van de metagegevens in verschillende formulieren. De eindpunten voor zoek- en pakketmetagegevens bevatten bijvoorbeeld meer dan alleen metagegevens die in het nuspec bestand van de nupkg zijn gevonden.

Houd er rekening mee dat deze handleiding is gericht op het NuGet V3-protocol omdat het V2-protocol in wezen niet-gedocumenteerd is en sinds 2015 het aanbevolen protocol voor NuGet-client- en servercommunicatie het V3-protocol is. Lees voor meer informatie over protocolversiebeheer.

Chronologie

Om auteurs van bestaande NuGet-opslagplaatsen up-to-date te houden met de nieuwste functies van NuGet, volgt hier de chronologie van de relevante functies die in de rest van het document worden vermeld.

Jaar	Eigenschap
2013	Een blogbericht waarin wordt uitgelegd hoe u pakketeigenaren op nuget.org beheert, verduidelijkte dat de eigenaren die op de website worden weergegeven, de accounts zijn die nieuwe versies mogen uploaden, en daarom worden de owners metagegevens in het pakket genegeerd
2017	Toegevoegd verified aan SearchQueryService antwoorden.
	Ondersteuning voor Semantic Versioning 2.0.0
2018	Ingesloten licenties
2019	Ingesloten pictogrammen
	Veroudering van pakketten in RegistrationBaseUrl (resource voor pakketmetadata)
2020	Pakketkwetsbaarheidsinformatie in RegistrationsBaseUrl (pakketmetagegevensbron)
	Queryparameter packageTypes toegevoegd bij SearchQueryService aanvragen
2021	Ingesloten readme-bestand
2023	Geverifieerde aanvragen vooraf verifiëren VulnerabilityInfo hulpbron
2025	Ingesloten README-downloads inschakelen

Eigenaarsveld

Overweeg twee van de pakketmanifestbestand (.nuspec) -velden <authors> en <owners>. Pakketauteurs die inhoud van derden verpakken, plaatsen vaak de naam van de derde partij in het <authors> veld. Het <owners> veld was bedoeld om aan te geven wie het pakket heeft gepubliceerd in een opslagplaats, en daarom wie contact moet opnemen bij verpakkingsproblemen of vragen.

Dit is uitgelegd in een blogbericht uit 2013, dus het <owners> veld wordt als afgeschaft beschouwd in het .nuspec bestand. Als het manifest van het pakket deze metagegevens bevat, moet dit worden genegeerd. Geef de waarde van het <owners> veld van het .nuspec bestand niet terug in de owners eigenschap in de JSON-reactie van de zoekresource of pakketmetagegevensresource.

Als uw opslagplaats machtigingen per pakket heeft, is het raadzaam om de accounts met machtigingen te rapporteren voor het publiceren van nieuwe versies in de owner metagegevens voor JSON-antwoorden op zoek- en pakketmetagegevensresources.

verified antwoordveld zoeken

De gebruikersinterface van Package Manager van Visual Studio toont een blauw vinkje naast pakketten in zoekresultaten van de zoekservice wanneer een nieuw veld verified is ingesteld op true.

NuGet.org dit gebruikt met pakketvoorvoegselgegevens (gegevens aan de serverzijde, geen deel van de NuGet-API), zodat dit vinkje alleen wordt weergegeven aan klanten wanneer het account dat eigenaar is van het pakket het pakket heeft geüpload. Een pakket met voorvoegsel microsoft.* wordt bijvoorbeeld alleen geverifieerd wanneer het pakket eigendom is van het Microsoft-account op nuget.org. Iedereen die een pakket met pakket-id heeft geüpload vanaf microsoft. voordat gereserveerde voorvoegsels zijn geïmplementeerd, heeft dit geverifieerde vinkje niet. NuGet.org staat ook toe dat voorvoegsels niet exclusief zijn, zodat iedereen een pakket kan uploaden onder Contoso.ToolWithPlugins.Community.*, maar geen geverifieerd vinkje krijgt.

Ondersteuning voor Semantic Versioning 2.0.0

NuGet ondersteunt een hybride versie tussen System.Version en Semantische versie, maar ondersteuning voor Semantische versie 2.0.0 is toegevoegd in 2017. Daarom mogen NuGet API-resources die versies retourneren naar clientversies die lager zijn dan 3.6.0, geen pakketten retourneren die gebruikmaken van Semantische 2.0.0-functies die niet compatibel zijn met Semantische versiebeheer 1.0.0.

De belangrijkste verschillen tussen de twee versies zijn de voorgangsversie labels en de metagegevensreeks. De specificatie Semantic Versioning 1.0.0 biedt [0-9A-Za-z-] een voorbeeld van een tekenreeks voor reguliere expressies voor de enige tekens die zijn toegestaan als onderdeel van het pre-releaselabel en biedt geen ondersteuning voor tekenreeksen voor metagegevens. Met de Semantische versiebeheerspecificatie 2.0.0 kunnen pre-release-id's worden gescheiden door . tekens (en wordt een numerieke id verboden om een voorloopnul te hebben) en kunnen bovendien buildmetagegevens worden toegevoegd na een +.

In de pakketmetagegevensresource (RegistrationsBaseUrl)mogen resourceversies onder 3.6.0 alleen pakketten retourneren die voldoen aan . Net's System.Version of Semantische versiebeheer 1.0.0. Dit betekent dat pakketten waarvan de versies alleen compatibel zijn met Semantic Versioning 2.0.0, onzichtbaar zijn voor deze clientversies.

Op dezelfde manier hebben de zoekqueryservice (SearchQueryService) en de service voor automatisch aanvullen (SearchAutocompleteService) queryparameters toegevoegd &semVerLevel={version}. Wanneer semVerLevel ontbreekt, neem aan dat de waarde 1.0.0. Net als bij de resource voor pakketmetagegevens mogen pakketten waarvan de versie alleen compatibel is met Semantic Versioning 2.0.0 niet worden geretourneerd wanneer de semVerLevel waarde lager is dan 2.0.0.

Ingesloten bestanden

Icons, license- en readme-bestanden kunnen in het pakket worden ingesloten en het wordt aanbevolen dit te doen. Deze bestanden hebben een URL-eindpunt nodig, geëxtraheerd en op een statische bestandsserver geplaatst, of een URL waarmee de bestanden dynamisch worden geëxtraheerd uit de .nupkg aanvraag, zodat ze kunnen worden weergegeven zonder het hele nupkgbestand te downloaden. Als uw pakketarchief browsen en gedetailleerde informatie van pakketten biedt, kunt u de URL's gebruiken om klanten de ingesloten inhoud op uw website te tonen.

Ten slotte moeten de resource voor pakketmetagegevens en de zoekresource de gehoste URL in de iconUrl, licenseUrl, en/of readmeUrl eigenschappen van het JSON-antwoord bevatten. Pakketten (.nupkg bestanden) mogen niet worden gewijzigd, omdat clientfuncties (bestanden vergrendelen en ondertekende pakketten) wijzigingen detecteren als het pakket is gemanipuleerd.

Houd er rekening mee dat de licentie een SPDX-expressie of een ingesloten bestand (maar niet beide) kan zijn. Pakketten die gebruikmaken van een licentie-uitdrukking, kunnen, wanneer ze worden weergegeven in zoekresultaten en resultaten van pakketmetagegevens, de licenseUrl ingesteld hebben op de licentie-uitdrukking, URL-gecodeerd en toegevoegd aan het einde van https://licenses.nuget.org/. Bijvoorbeeld: https://licenses.nuget.org/Apache-2.0. Het NuGet.org serverteam bevat aanvullende documentatie over licenses.nuget.org.

Bekende kwetsbaarheids- en deprecatiegegevens

Pakketmetagegevensresource (RegistrationsBaseUrl)

De pakketmetagegevensresource kan verouderingsinformatie en kwetsbaarheidsinformatie bevatten. Hierdoor kunnen klanten door pakketten bladeren in de Package Manager gebruikersinterface van Visual Studio, of het equivalent daarvan in andere IDE's, om op de hoogte te zijn van belangrijke beveiligings- of onderhoudsproblemen.

Als uw pakketrepository pakketten uit een andere repository 'up-sourcet' om ze in uw eigen feed te spiegelen, raden we aan regelmatig de oorspronkelijke bron te controleren op gegevens over saneringen of kwetsbaarheden, en die metadata te spiegelen in uw eigen repository. Als uw pakketopslagplaats gebruik maakt van nuget.org en daarbij specifiek de status van de laatste controle bijhoudt (een 'cursor'), kunt u de Catalog resource gebruiken om efficiënt te controleren of er pakketupdates zijn voor de pakketten die u spiegelt, zonder dat u een groot aantal JSON-bestanden met pakketmetagegevens uit de upstream-feed hoeft te downloaden. Er is een handleiding voor het gebruik van de catalogusresource met voorbeeldcode waarmee u aan de slag kunt gaan.

Bekende beveiligingsproblemendatabase (VulnerabilityInfo)

NuGet downloadt de volledige lijst met bekende beveiligingsproblemen van de VulnerabilityInfo resource om scannen op beveiligingsproblemen met hoge prestaties te bieden tijdens het herstellen van pakketten. Nuget.org biedt gegevens over beveiligingsproblemen voor alle door GitHub gecontroleerde adviezen van de GitHub Advisories-database, waaronder pakketten die niet worden gehost op nuget.org.

Als uw pakketopslagplaats pakketten van derden host en u informatie over beveiligingsproblemen wilt verstrekken aan klanten die uw eigen feed gebruiken, maar nog geen bekende pakketproblemen hebben, moet u een index voor beveiligingsproblemen opgeven met een of meer pagina's met beveiligingsproblemen waarvan de inhoud een lege JSON-matrix ([]) is.

Als uw pakketopslagplaats bedoeld is voor gebruik door apps als de standaardopslagplaats (in plaats van nuget.org), kunt u de beveiligingsgegevens van nuget.org gebruiken. Een optie is het gebruik van de INDEX-URL voor beveiligingsproblemen van nuget.org in uw service-index. Een andere optie is om periodiek de index van VulnerabilityInfo nuget.org te controleren en eventuele gewijzigde pagina's te downloaden om lokaal te spiegelen.

packageTypes zoekquery

Met de .NET CLI kunt u zoeken naar .NET-hulpprogrammapakketten met de dotnet tool search opdracht. Dit wordt geïmplementeerd door een &packageTypes={value} queryparameter toe te voegen aan de zoekqueryresource, waarmee waarden uit het bestandsveld <packageTypes> van .nuspec het pakket worden gelezen.

URL-structuur voor geverifieerde feeds

Zoals beschreven in het overzicht van de NuGet-API, is de begin-URL voor alle NuGet-servercommunicatie de service-index. Dit document bevat de URL's voor alle andere resources waarop NuGet-clients query's uitvoeren. Vanaf NuGet 6.7 (Visual Studio & MSBuild 17.7 en .NET SDK 7.0.400) maakt NuGet gebruik van . NET's HttpClientHandler.PreAuthenticate, die alleen anonieme HTTP-aanvragen voorkomen wanneer volgende URL's zich in dezelfde virtuele map of een submap bevinden, van een URL die eerder is geverifieerd. Dit vermindert het aantal niet-geverifieerde HTTP-aanvragen dat naar de server wordt verzonden aanzienlijk en vermindert daarom uw serverworkload.

Hieronder volgen een aantal voorbeelden:

URL	Zal PreAuthenticate?
https://pkgs.contoso.com/nuget/v3/feed/index.json	N/B, dit is de service index.
https://pkgs.contoso.com/nuget/v3/search	Nee, niet in dezelfde map of submap als de serviceindex.
https://search.pkgs.contoso.com/nuget/v3/feed/	Nee, niet op dezelfde hostnaam als de serviceindex.
https://pkgs.contoso.com/nuget/v3/feed/search	Ja, in dezelfde map als de service-index.
https://pkgs.contoso.com/nuget/v3/registration/	Nee, niet in een submap van de serviceindex.
https://pkgs.contoso.com/nuget/v3/feed/registration/	Ja, in een submap van de service-index.
https://pkgs.contoso.com/nuget/v3/{guid}/registration/	Zie hieronder

In het laatste voorbeeld kan de server een canonieke naam (in dit voorbeeld een GUID) hebben en een of meer aliassen hebben. Als de serviceindexaanvraag is geverifieerd op een niet-canonieke URL (de beschrijvende naam in ons voorbeeld feed), dan zullen nee, alle aanvragen voor resources onder de canonieke URL niet overeenkomen met de regels van HttpClientHandler voor PreAuthenticate. Als de niet-canonieke URL echter een HTTP-omleiding naar de canonieke URL is, https://pkgs.contoso.com/nuget/v3/{guid}/index.jsonwordt deze URL gebruikt in HttpClientHandlerde referentiecache. In dit geval heeft elke aanvraag voor de service-index extra latentie vanwege de omleiding.

Hoewel de V3-API van NuGet is ontworpen om te werken op een statische bestandsserver, is de zoekresource de uitzondering die altijd een dynamische webservice vereist om aanvragen te verwerken. Als u zoekopdrachten wilt hosten of inderdaad een andere NuGet-API-resource op verschillende servers wilt gebruiken om te profiteren van HttpClientHandler's PreAuthenticate, moet u een omgekeerde proxy gebruiken om ervoor te zorgen dat alle klantgerichte URL's in de serviceindex voldoen aan de regel 'dezelfde of submap'.

Ingesloten README-downloads inschakelen

Er is een nieuwe resource gedocumenteerd voor het maken van een URL die kan worden gebruikt om een README voor een bepaald pakket te downloaden. Hierdoor kan de client, zoals de pakketbeheerinterface in VS, het bijgevoegde READMEBESTAND weergeven voor pakketten die de gebruiker nog niet eerder heeft geïnstalleerd. De client maakt deze URL en probeert de LEESMIJ te downloaden met behulp van het antwoord op de aanvraag om te bepalen of er een LEESMIJ beschikbaar is. Dit betekent dat servers meerdere aanvragen naar het samengestelde eindpunt moeten verwachten wanneer gebruikers door de PM-gebruikersinterface navigeren.