Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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.
Fin dal rilascio iniziale del protocollo NuGet V3 nel 2015, NuGet si è evoluto per offrire agli sviluppatori un'esperienza più completa, richiedendo ai repository di pacchetti di eseguire operazioni aggiuntive per fornire un valore aggiuntivo ai consumatori di pacchetti, oltre alla semplice estrazione 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.
Chronology
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.
| Year | Feature |
|---|---|
| 2013 |
Un post di blog che spiega come gestire i proprietari di pacchetti su nuget.org ha chiarito che i proprietari visualizzati sul 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 per il versionamento semantico 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) |
Aggiunto il parametro di query packageTypes alle richieste SearchQueryService |
|
| 2021 | Readme incorporato |
| 2023 |
PreAutenticare le richieste autenticate VulnerabilityInfo risorsa |
| 2025 | Abilitare i download README incorporati |
Campo Proprietario
Si considerino due dei campi .nuspec del e <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 hanno il permesso di pubblicare nuove versioni nei metadati delle risorse di ricerca e nei metadati del pacchetto nelle risposte JSON.
verified campo di risposta di ricerca
L'interfaccia utente di 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 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 delle versioni preliminari 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 attraverso i caratteri . (e impedisce a un identificatore numerico di avere uno zero iniziale) e consente di aggiungere metadati di compilazione seguendo un simbolo +.
Nella risorsa metadati del pacchetto (RegistrationsBaseUrl), le versioni delle risorse precedenti alla 3.6.0 devono restituire solo pacchetti conformi alla Semantic Versioning 1.0.0 di .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 ricerca (SearchQueryService) e il servizio di completamento automatico (SearchAutocompleteService) sono stati aggiunti &semVerLevel={version} parametri alla query.
Quando semVerLevel manca, si suppone 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 della ricerca e nei metadati del pacchetto, possono avere il licenseUrl impostato sull'espressione di licenza, codificato come URL e aggiunto alla fine di https://licenses.nuget.org/.
Ad esempio: https://licenses.nuget.org/Apache-2.0.
Il team del server di NuGet.org ha documentazione aggiuntiva disponibile su licenses.nuget.org.
Dati noti relativi a vulnerabilità e deprecazione
Risorsa dei metadati del 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 Gestione pacchetti di Visual Studio o equivalenti in altri IDE, di ricevere una notifica di importanti problemi di sicurezza o manutenzione.
Se il tuo repository di pacchetti importa pacchetti da un altro repository per duplicarli nel tuo feed, ti consigliamo di controllare periodicamente la fonte originale per verificare la presenza di dati di deprecazione o vulnerabilità, e riflettere tali metadati nel tuo repository.
Se il repository di pacchetti è in sourcing da nuget.org in particolare, mantenendo lo stato dell'ultima verifica (un "cursore"), è possibile utilizzare la Catalog risorsa per verificare in modo efficiente la presenza di aggiornamenti dei pacchetti per i pacchetti di cui si sta eseguendo il mirroring, senza dover scaricare numerosi file JSON di metadati 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 ([]).
Riutilizzo dei dati di vulnerabilità di nuget.org
NuGet non richiede che le risorse nell'indice del servizio o l'indice di vulnerabilità siano nello stesso server dell'indice del servizio stesso. Esistono tuttavia diversi motivi per cui alcune aziende scelgono di bloccare nuget.org al firewall o di avere feed locali in una rete disconnessa. Per evitare problemi di connettività, è consigliabile gestire i dati delle vulnerabilità dalla propria app Web, in modo che i client NuGet esecupino solo connessioni HTTP all'host in cui è installato il feed.
✔️ Memorizzare nella cache o proxy le pagine di vulnerabilità nell'app Web
❌ NON annunciare api.nuget.org nell'indice del servizio o nell'indice di vulnerabilità senza una configurazione per disattivarla.
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 .nuspec del <packageTypes> 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 utilizza
Ecco alcuni esempi:
| URL | "Preautenticherà?" |
|---|---|
| https://pkgs.contoso.com/nuget/v3/feed/index.json | N/A, si tratta dell'indice del servizio. |
| https://pkgs.contoso.com/nuget/v3/search | No, non nella stessa directory o nella stessa sottodirectory dell'indice dei servizi. |
| 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 di servizio. |
| https://pkgs.contoso.com/nuget/v3/feed/registration/ | Sì, in una sottocartella dell'indice del servizio. |
| https://pkgs.contoso.com/nuget/v3/{guid}/registration/ | Vedere 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), allora no, qualsiasi richiesta alle risorse nell'URL canonico non rispetterà le regole di HttpClientHandler 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 desideri ospitare la ricerca, o qualsiasi altra risorsa API NuGet, su server diversi per trarre vantaggio da HttpClientHandlerPreAuthenticate, sarà necessario utilizzare un proxy inverso per garantire che tutti gli URL rivolti ai clienti nell'indice del servizio rispettino la regola "stessa o sottodirectory".
Abilitare i download README incorporati
È stata documentata una nuova risorsa per la creazione di un URL che può essere usato per scaricare un file README per un determinato pacchetto. In questo modo il client, ad esempio l'interfaccia utente di Gestione pacchetti in Visual Studio, visualizzerà il file README incorporato per i pacchetti che non sono stati installati in precedenza dall'utente. Il client creerà questo URL e tenterà di scaricare il file README, usando la risposta alla richiesta per determinare se è disponibile un file README. Ciò significa che i server devono aspettarsi più richieste all'endpoint costruito mentre gli utenti esplorano l'interfaccia utente pm.