Guida all'implementazione del server NuGet

In alcuni casi, è possibile implementare il proprio feed di pacchetti NuGet. Esistono molte implementazioni esistenti che consentono di ospitare il proprio feed in diversi modi, ma il protocollo tra il software client NuGet ufficiale e un feed di pacchetti è documentato che consente di creare un'implementazione del feed personalizzata da zero.

Il protocollo si evolve nel tempo e questa guida è destinata a coloro che desiderano o hanno già implementato un server di pacchetti NuGet.

Dal momento che la versione iniziale del protocollo NuGet V3 nel 2015, NuGet si è evoluta per offrire agli sviluppatori un'esperienza più completa e questo richiede che i repository di pacchetti esecupino operazioni aggiuntive per fornire il valore aggiuntivo ai consumer di pacchetti, oltre semplicemente all'esatta esecuzione dei metadati dai pacchetti ospitati e alla restituzione dei metadati in varie forme. Ad esempio, gli endpoint dei metadati di ricerca e pacchetto contengono più dei soli metadati trovati nel file nuspec di nupkg.

Si noti che questa guida è incentrata sul protocollo NuGet V3 poiché il protocollo V2 è essenzialmente non documentato e, dal 2015, il protocollo consigliato per la comunicazione tra client e server NuGet è il protocollo V3. Per altre informazioni, vedere Controllo delle versioni del protocollo.

Cronologia

Per aiutare gli autori di repository NuGet esistenti a rimanere aggiornati con le funzionalità più recenti di NuGet, ecco la cronologia delle funzionalità pertinenti menzionate nel resto del documento.

Anno	Funzionalità
2013	Un post di blog che spiega come gestire i proprietari dei pacchetti in nuget.org chiariti i proprietari visualizzati nel sito Web sono gli account che dispongono dell'autorizzazione per caricare nuove versioni e quindi i owners metadati nel pacchetto vengono ignorati
2017	Aggiunta verified alle SearchQueryService risposte.
	Supporto del controllo delle versioni semantiche 2.0.0
2018	Licenze incorporate
2019	Icone incorporate
	Deprecazione del pacchetto in RegistrationBaseUrl (risorsa metadati del pacchetto)
2020	Informazioni sulla vulnerabilità del pacchetto in RegistrationsBaseUrl (risorsa metadati del pacchetto)
	Aggiunta packageTypes del parametro di query alle SearchQueryService richieste
2021	Readme incorporato
2023	PreAutenticare le richieste autenticate VulnerabilityInfo Risorsa

Campo Proprietario

Si considerino due dei campi del file manifesto del pacchetto (.nuspec) e <owners>. <authors> Gli autori di pacchetti che creano pacchetti di contenuto di terze parti spesso inseriscono il nome di terze parti nel <authors> campo. Il <owners> campo era destinato a indicare chi ha pubblicato il pacchetto in un repository e quindi chi deve essere contattato in caso di problemi o domande di compressione.

Questo è stato spiegato in un post di blog del 2013, quindi il <owners> campo viene considerato deprecato nel .nuspec file. Se il manifesto del pacchetto contiene questi metadati, deve essere ignorato. Non restituire il valore del .nuspec campo del <owners> file nella owners proprietà nella risposta JSON della risorsa di ricerca o della risorsa metadati del pacchetto.

Se il repository dispone di autorizzazioni per pacchetto, è consigliabile segnalare gli account che dispongono delle autorizzazioni per pubblicare nuove versioni nei metadati per le risposte JSON per la ricerca e i metadati del owner pacchetto.

verified campo di risposta di ricerca

L'interfaccia utente Gestione pacchetti di Visual Studio mostra un segno di spunta blu accanto ai pacchetti nei risultati del servizio di ricerca, quando un nuovo campo verified è impostato su true.

NuGet.org usa questa opzione con i dati del prefisso del pacchetto (dati lato server, non parte dell'API NuGet), in modo che questo segno di spunta venga visualizzato solo ai clienti quando l'account proprietario del pacchetto ha caricato il pacchetto. Ad esempio, qualsiasi pacchetto con prefisso microsoft.* viene verificato solo quando il pacchetto è di proprietà dell'account Microsoft in nuget.org. Chiunque abbia caricato un pacchetto con ID pacchetto a partire da microsoft. prima dell'implementazione dei prefissi riservati, non avrà questo segno di spunta verificato. NuGet.org consente inoltre che i prefissi non siano esclusivi, in modo che chiunque possa caricare un pacchetto in Contoso.ToolWithPlugins.Community.*, ma non otterrà un segno di spunta verificato.

Supporto del controllo delle versioni semantiche 2.0.0

NuGet supporta una versione ibrida tra System.Version e versione semantica, ma il supporto per la versione semantica 2.0.0 è stato aggiunto nel 2017. Pertanto, le risorse DELL'API NuGet che restituiscono versioni alle versioni client inferiori alla 3.6.0 non devono restituire pacchetti che usano funzionalità semantiche 2.0.0 incompatibili con il controllo delle versioni semantiche 1.0.0.

Le differenze più importanti tra le due versioni sono le etichette non definitive e la stringa di metadati. La specifica Semantic Versioning 1.0.0 fornisce [0-9A-Za-z-] come stringa di espressione regolare di esempio per gli unici caratteri consentiti come parte dell'etichetta di versione non definitiva e non supporta le stringhe di metadati. La specifica Semantic Versioning 2.0.0 consente di separare gli identificatori di versione non definitiva da . caratteri (e impedisce a un identificatore numerico di avere uno zero iniziale) e di aggiungere i metadati di compilazione dopo un oggetto +.

Nella risorsa metadati del pacchetto (RegistrationsBaseUrl), le versioni delle risorse precedenti alla 3.6.0 devono restituire solo i pacchetti conformi a . Controllo delle versioni semantiche o 1.0.0 di System.Version NET. Ciò significa che i pacchetti le cui versioni sono conformi solo al controllo delle versioni semantiche 2.0.0 sono invisibili a queste versioni client.

Analogamente, il servizio di query di ricerca () e il servizio di completamento automatico (SearchAutocompleteService) hanno aggiunto &semVerLevel={version} parametri di query.SearchQueryService Se semVerLevel manca, si supponga che il valore 1.0.0. Analogamente alla risorsa dei metadati del pacchetto, i pacchetti la cui versione è compatibile solo con il controllo delle versioni semantiche 2.0.0 non devono essere restituiti quando il semVerLevel valore è inferiore a 2.0.0.

File incorporati

Le icone del pacchetto, la licenza e i file leggimi possono essere (e sono consigliati per essere) incorporati nel pacchetto. Questi file richiedono un endpoint URL, estratto e inserito in un file server statico o un URL che estrae dinamicamente i file dalla .nupkg richiesta, in modo che possano essere visualizzati senza scaricare l'intero nupkg. Se il repository di pacchetti fornisce l'esplorazione e la visualizzazione dei dettagli del pacchetto, è possibile usare gli URL per mostrare ai clienti il contenuto incorporato nel sito Web.

Infine, la risorsa di metadati del pacchetto e la risorsa di ricerca devono contenere l'URL ospitato nelle iconUrlproprietà , licenseUrle/o readmeUrl della risposta JSON. I pacchetti (.nupkg file) non devono essere modificati, perché le funzionalità client (file di blocco e pacchetti firmati) rileveranno le modifiche man mano che il pacchetto è stato manomesso.

Si noti che la licenza può essere un'espressione SPDX o un file incorporato (ma non entrambi). I pacchetti che usano un'espressione di licenza, se rappresentati nei risultati dei metadati della ricerca e del pacchetto, possono avere il licenseUrl set sull'espressione di licenza, codificato nell'URL e accodato alla fine di https://licenses.nuget.org/. Ad esempio: https://licenses.nuget.org/Apache-2.0. Il team del server NuGet.org include documentazione aggiuntiva su licenses.nuget.org.

Dati noti relativi a vulnerabilità e deprecazione

Risorsa metadati pacchetto (RegistrationsBaseUrl)

La risorsa metadati del pacchetto può contenere informazioni sulla deprecazione e sulla vulnerabilità . Ciò consente ai clienti di esplorare i pacchetti nell'interfaccia utente di Visual Studio Gestione pacchetti o equivalenti in altri IDE, di ricevere una notifica di importanti problemi di sicurezza o manutenzione.

Se il repository di pacchetti è "up-sourcing" di un altro repository, per eseguire il mirroring dei pacchetti nel proprio feed, è consigliabile controllare periodicamente l'origine originale se sono presenti dati di deprecazione o vulnerabilità e eseguire il mirroring dei metadati nel proprio repository. Se il repository di pacchetti è upsourcing da nuget.org in particolare, mantenendo lo stato dell'ultima volta che è stato selezionato (un "cursore"), è possibile usare la Catalog risorsa per verificare in modo efficiente se sono presenti aggiornamenti del pacchetto per i pacchetti di cui si sta eseguendo il mirroring, senza dover scaricare un numero elevato di file JSON di metadati del pacchetto dal feed upstream. È disponibile una guida sull'uso della risorsa del catalogo con codice di esempio che consente di iniziare.

Database delle vulnerabilità note (VulnerabilityInfo)

Per fornire un'analisi delle vulnerabilità ad alte prestazioni durante il ripristino del pacchetto, NuGet scarica l'elenco completo delle vulnerabilità note dalla VulnerabilityInfo risorsa. Nuget.org fornisce dati sulle vulnerabilità per tutti gli avvisi esaminati da GitHub dal database gitHub Advisories, che include pacchetti non ospitati in nuget.org.

Se il repository di pacchetti ospita pacchetti di prima parte e si vogliono fornire informazioni sulla vulnerabilità ai clienti che usano il proprio feed, ma non hanno ancora vulnerabilità dei pacchetti divulgate, è necessario fornire un indice di vulnerabilità con una o più pagine di vulnerabilità il cui contenuto è una matrice JSON vuota ([]).

Se il repository dei pacchetti deve essere usato dalle app come repository predefinito (anziché nuget.org), è possibile usare i dati sulle vulnerabilità di nuget.org. Un'opzione consiste nell'usare l'URL dell'indice di vulnerabilità di nuget.org nell'indice del servizio. Un'altra opzione consiste nel controllare periodicamente l'indice di VulnerabilityInfo nuget.org e scaricare le pagine modificate in locale.

packageTypes query di ricerca

L'interfaccia della riga di comando di .NET consente di cercare pacchetti di strumenti .NET con il dotnet tool search comando . Questa operazione viene implementata aggiungendo un &packageTypes={value} parametro di query alla risorsa di query di ricerca, che legge i valori dal campo del file <packageTypes> del .nuspec pacchetto.

Struttura dell'URL per i feed autenticati

Come descritto nella panoramica dell'API NuGet, l'URL iniziale per tutte le comunicazioni del server NuGet è l'indice del servizio. Questo documento contiene gli URL per tutte le altre risorse su cui i client NuGet eseguiranno query. A partire da NuGet 6.7 (Visual Studio & MSBuild 17.7 e .NET SDK 7.0.400), NuGet usa . HttpClientHandler.PreAuthenticate, che evita richieste HTTP anonime solo quando gli URL successivi si trovano nella stessa directory virtuale, o in una sottodirectory, di un URL autenticato in precedenza. Ciò ridurrà notevolmente il numero di richieste HTTP non autenticate inviate al server e quindi ridurrà il carico di lavoro del server.

Di seguito sono riportati alcuni esempi.

URL	Will PreAuthenticate?
https://pkgs.contoso.com/nuget/v3/feed/index.json	N/D, si tratta dell'indice del servizio.
https://pkgs.contoso.com/nuget/v3/search	No, non nella stessa directory o nella stessa sottodirectory dell'indice del servizio.
https://search.pkgs.contoso.com/nuget/v3/feed/	No, non nello stesso nome host dell'indice del servizio.
https://pkgs.contoso.com/nuget/v3/feed/search	Sì, nella stessa directory dell'indice del servizio.
https://pkgs.contoso.com/nuget/v3/registration/	No, non in una sottodirectory dell'indice del servizio.
https://pkgs.contoso.com/nuget/v3/feed/registration/	Sì, in una sottodirectory dell'indice del servizio.
https://pkgs.contoso.com/nuget/v3/{guid}/registration/	Vedi di seguito

Nell'ultimo esempio, il server potrebbe avere un nome canonico (in questo esempio un GUID) e avere uno o più alias. Se la richiesta di indice del servizio è stata autenticata in un URL non canonico (il nome "descrittivo", nell'esempio feed), no, le richieste alle risorse nell'URL canonico non corrispondono HttpClientHandleralle regole per PreAuthenticate. Tuttavia, se l'URL non canonico è un reindirizzamento HTTP all'URL canonico, https://pkgs.contoso.com/nuget/v3/{guid}/index.json, questo URL verrà usato nella HttpClientHandlercache delle credenziali di . In questo caso, ogni richiesta all'indice del servizio avrà una latenza aggiuntiva, a causa del reindirizzamento.

Anche se l'API V3 di NuGet è stata progettata per funzionare in un file server statico, la risorsa di ricerca è l'eccezione che richiede sempre un servizio Web dinamico per elaborare le richieste. Se si vuole ospitare la ricerca o qualsiasi altra risorsa API NuGet, in server diversi, per trarre vantaggio da HttpClientHandler, PreAuthenticatesarà necessario usare un proxy inverso per garantire che tutti gli URL per i clienti nell'indice del servizio soddisfino la regola "stessa o sottodirectory".