Java-Implementierung vom NuGet-Server

  • Artikel

In einigen Fällen möchten Sie möglicherweise Ihren eigenen NuGet-Paketfeed implementieren. Es gibt viele vorhandene Implementierungen, mit denen Sie Ihren eigenen Feed auf vielfältige Weise hosten können, aber das Protokoll zwischen der offiziellen NuGet-Clientsoftware und einem Paketfeed ist dokumentiert, sodass Sie Ihre eigene Feedimplementierung von Grund auf neu erstellen können.

Das Protokoll entwickelt sich im Laufe der Zeit und dieser Leitfaden richtet sich an diejenigen, die einen NuGet-Paketserver implementiert oder bereits implementiert haben möchten.

Seit der ersten Veröffentlichung des NuGet V3-Protokolls im Jahr 2015 hat sich NuGet entwickelt, um Entwicklern eine umfangreichere Erfahrung zu bieten, und dies erfordert Paketrepositorys zusätzliche Arbeit, um den zusätzlichen Wert für ihre Paketkunden bereitzustellen, und nicht nur die Exaktheit von Metadaten aus gehosteten Paketen und das Zurückgeben der Metadaten in verschiedenen Formularen. Beispielsweise enthalten die Endpunkte für Suche und Paketmetadaten mehr als nur Metadaten, die in der Nuspec-Datei der nupkg gefunden wurden.

Beachten Sie, dass sich dieser Leitfaden auf das NuGet V3-Protokoll konzentriert, da das V2-Protokoll im Wesentlichen nicht dokumentiert ist und seit 2015 das empfohlene Protokoll für die NuGet-Client- und Serverkommunikation das V3-Protokoll ist. Weitere Informationen finden Sie unter Tabellenprotokollversionsverwaltung.

Chronologie

Um Autoren vorhandener NuGet-Repositorys mit den neuesten Features von NuGet auf dem neuesten Stand zu halten, finden Sie hier die Chronologie der relevanten Features Erwähnung im Re Standard der des Dokuments.

Jahr Funktion
2013 Ein Blogbeitrag, in dem erläutert wird, wie Paketbesitzer auf nuget.org klären, welche Besitzer auf der Website angezeigt werden, sind die Konten, die über die Berechtigung zum Hochladen neuer Versionen verfügen, und daher werden die owners Metadaten im Paket ignoriert
2017 verified zu SearchQueryService Antworten hinzugefügt.
Semantische Versionierung 2.0.0
2018 Eingebettete Lizenzen
2019 Eingebettete Symbole
Paketverwerfung in RegistrationBaseUrl (Paketmetadatenressource)
2020 Paketrisikoinformationen in RegistrationsBaseUrl (Paketmetadatenressource)
Abfrageparameter packageTypes zu SearchQueryService Anfragen hinzugefügt
2021 Eingebettete Infodatei
2023 Authentifizierte Anforderungen vorab authentifiziert
VulnerabilityInforesource

Besitzerfeld

Berücksichtigen Sie zwei der Felder der Paketmanifestdatei (.nuspec)<authors> und <owners>. Paketautoren, die Inhalte von Drittanbietern verpacken, setzen häufig den Namen des Drittanbieters in das <authors> Feld. Das <owners> Feld sollte angeben, wer das Paket in einem Repository veröffentlicht hat, und daher, wer bei Verpackungsproblemen oder Fragen kontaktiert werden sollte.

Dies wurde in einem Blogbeitrag aus 2013 erläutert, sodass das <owners> Feld in der .nuspec Datei als veraltet angesehen wird. Wenn das Manifest des Pakets diese Metadaten enthält, sollte es ignoriert werden. Geben Sie nicht den Wert des Felds <owners> der .nuspec Datei in der Eigenschaft in der owners Json-Antwort der Suchressource oder der Paketmetadatenressource zurück.

Wenn Ihr Repository über Paketberechtigungen verfügt, empfiehlt es sich, die Konten zu melden, die über Berechtigungen zum Veröffentlichen neuer Versionen in den owner Metadaten für JSON-Antworten für Such- und Paketmetadatenressourcen verfügen.

verified Suchantwortfeld

Visual Studio's Package Manager UI zeigt ein blaues Häkchen neben den Paketen in den Suchergebnissen, wenn ein neues Feld verified auf true gesetzt wird.

NuGet.org verwendet dies mit Paketpräfixdaten (serverseitige Daten, nicht Teil der NuGet-API), sodass dieses Häkchen nur Kunden angezeigt wird, wenn das Konto, das das Paket besitzt, das Paket hochgeladen hat. Beispielsweise wird jedes Paket mit Präfix microsoft.* nur überprüft, wenn das Paket im Besitz des Microsoft-Kontos auf nuget.org ist. Jeder, der ein Paket mit paket-ID hochgeladen hat, beginnend mit microsoft. vor der Implementierung reservierter Präfixe, hat dieses überprüfte Häkchen nicht. NuGet.org ermöglicht außerdem, dass Präfixe nicht exklusiv sind, sodass jeder ein Paket unter Contoso.ToolWithPlugins.Community.*hochladen kann, aber kein überprüftes Häkchen erhält.

Semantische Versionierung 2.0.0

NuGet unterstützt eine Hybrid-Zwischen System.Version - und Semantikversion, aber Die Unterstützung für die semantische Version 2.0.0 wurde 2017 hinzugefügt. Daher dürfen NuGet-API-Ressourcen, die Versionen an Clientversionen unter 3.6.0 zurückgeben, keine Pakete zurückgeben, die semantische 2.0.0-Features verwenden, die mit der semantischen Versionsverwaltung 1.0.0 nicht kompatibel sind.

Die wichtigsten Unterschiede zwischen den beiden Versionen sind die Vorabversionsbezeichnungen und die Metadatenzeichenfolge. Die Spezifikation für die semantische Versionsverwaltung 1.0.0 stellt [0-9A-Za-z-] als Beispielzeichenfolge für reguläre Ausdrücke für die einzigen Zeichen bereit, die als Teil der Vorabversionsbezeichnung zulässig sind, und unterstützt keine Metadatenzeichenfolgen. Die Spezifikation für die semantische Versionierung 2.0.0 ermöglicht das Trennen von Vorversionsbezeichnern durch . Zeichen (und verbietet, dass ein numerischer Bezeichner eine führende Null hat), und zusätzlich können Buildmetadaten nach einem Wert +hinzugefügt werden.

In der Paketmetadatenressource (RegistrationsBaseUrl)müssen Ressourcenversionen unter 3.6.0 nur Pakete zurückgeben, die den Anforderungen entsprechen. Nets System.Version oder semantischer Versionierung 1.0.0. Dies bedeutet, dass Pakete, deren Versionen nur mit der semantischen Versionierung 2.0.0 kompatibel sind, für diese Clientversionen unsichtbar sind.

Ebenso haben der Suchabfragedienst (SearchQueryService) und der AutoVervollständigen-Dienst (SearchAutocompleteService) Abfrageparameter hinzugefügt&semVerLevel={version}. Wenn semVerLevel dieser Wert 1.0.0fehlt, gehen Sie davon aus. Wie die Paketmetadatenressource dürfen Pakete, deren Version nur mit der semantischen Versionsverwaltung 2.0.0 kompatibel ist, nicht zurückgegeben werden, wenn der semVerLevel Wert unter 2.0.0 liegt.

Eingebettete Dateien

Paketsymbole, Lizenz- und Readme-Dateien können in das Paket eingebettet werden (und empfohlen werden). Diese Dateien benötigen einen URL-Endpunkt, der entweder extrahiert und auf einem statischen Dateiserver abgelegt wird, oder eine URL, die die Dateien dynamisch aus der .nupkg Anforderung extrahiert, sodass sie angezeigt werden können, ohne das gesamte nupkgHerunterzuladen. Wenn Ihr Paket-Repository Paketbrowsen und Anzeigen von Paketdetails bereitstellt, können Sie die URLs verwenden, um Kunden die eingebetteten Inhalte auf Ihrer Website anzuzeigen.

Schließlich muss die Paketmetadatenressource und die Suchressource die gehostete URL in den iconUrl, licenseUrlund/oder readmeUrl Eigenschaften der JSON-Antwort enthalten. Pakete (.nupkg Dateien) dürfen nicht geändert werden, da Clientfeatures (Sperrdateien und signierte Pakete) Änderungen erkennen, wenn das Paket manipuliert wurde.

Beachten Sie, dass die Lizenz ein SPDX-Ausdruck oder eine eingebettete Datei (aber nicht beide) sein kann. Pakete, die einen Lizenzausdruck verwenden, wenn sie in suchergebnissen und Paketmetadatenergebnissen dargestellt werden, können den licenseUrl Lizenzausdruck, die URL codiert und am Ende angefügt https://licenses.nuget.org/werden. Beispielsweise, https://licenses.nuget.org/Apache-2.0. Das NuGet.org Serverteam verfügt über zusätzliche Dokumentation zu licenses.nuget.org.

Bekannte Sicherheitsrisiken und Veraltete Daten

Paketmetadatenressource (RegistrationsBaseUrl)

Die Paket-Metadaten-Ressource kann veraltete und gefährdete Informationen enthalten. Auf diese Weise können Kunden Pakete in der Paket-Manager Benutzeroberfläche von Visual Studio oder gleichwertig in anderen IDEs über wichtige Sicherheits- oder Standard Zusicherungsprobleme benachrichtigt werden.

Wenn Ihr Paket-Repository "Up-Sourcing"-Pakete aus einem anderen Repository ist, um Pakete in Ihrem eigenen Feed zu Spiegel, empfehlen wir, die ursprüngliche Quelle regelmäßig zu überprüfen, wenn veraltete oder Sicherheitsrisikodaten vorhanden sind, und Spiegel diese Metadaten in Ihrem eigenen Repository. Wenn Ihr Paket-Repository von nuget.org speziell neu erstellt wird, indem Sie den Status der letzten Überprüfung beibehalten (ein "Cursor"), können Sie mithilfe der Catalog Ressource effizient überprüfen, ob Paketupdates für Pakete vorhanden sind, die Sie Spiegel, ohne eine große Anzahl von JSON-Paketdateien aus dem Upstreamfeed herunterladen zu müssen. Es gibt einen Leitfaden zur Verwendung der Katalogressource mit Beispielcode, der Ihnen bei den ersten Schritten helfen kann.

Datenbank für bekannte Sicherheitsanfälligkeiten (VulnerabilityInfo)

Um während der Paketwiederherstellung eine leistungsstarke Sicherheitsrisikoüberprüfung bereitzustellen, lädt NuGet die vollständige Liste der bekannten Sicherheitsrisiken aus der VulnerabilityInfo Ressource herunter. Nuget.org stellt Sicherheitsrisikodaten für alle von GitHub überprüften Empfehlungen aus der GitHub Advisories-Datenbank bereit, die Pakete enthält, die nicht auf nuget.org gehostet werden.

Wenn Ihr Paketrepository Pakete von Erstanbietern hosten und Sie Kunden sicherheitsrelevante Informationen bereitstellen möchten, die Ihren eigenen Feed verwenden, aber noch keine offengelegten Paketrisiken haben, sollten Sie einen Sicherheitsrisikoindex mit einer oder mehreren Sicherheitsrisikenseiten bereitstellen, deren Inhalt ein leeres JSON-Array ([]) ist.

Wenn Ihr Paket-Repository von Apps als Standard-Repository (anstelle von nuget.org) verwendet werden soll, können Sie die Sicherheitsrisikodaten von nuget.org verwenden. Eine Option besteht darin, die Sicherheitsrisikoindex-URL von nuget.org in Ihrem Dienstindex zu verwenden. Eine weitere Option besteht darin, den Index von nuget.org VulnerabilityInfo regelmäßig zu überprüfen und alle geänderten Seiten lokal auf Spiegel herunterzuladen.

packageTypes Suchabfrage

Die .NET CLI ermöglicht die Suche nach .NET-Toolpaketen mit dem dotnet tool search Befehl. Dies wird implementiert, indem der Suchabfrageressource ein &packageTypes={value} Abfrageparameter hinzugefügt wird, der Werte aus dem .nuspec-Dateifeld <packageTypes> des Pakets liest.

URL-Struktur für authentifizierte Feeds

Wie in der Übersicht über die NuGet-API beschrieben, ist die Start-URL für alle NuGet-Serverkommunikation der Dienstindex. Dieses Dokument enthält die URLs für alle anderen Ressourcen, die NuGet-Clients abfragen. Ab NuGet 6.7 (Visual Studio & MSBuild 17.7 und .NET SDK 7.0.400) verwendet NuGet .NET's HttpClientHandler.PreAuthenticate, die anonyme HTTP-Anforderungen nur vermeiden, wenn nachfolgende URLs sich im selben virtuellen Verzeichnis oder einem Unterverzeichnis einer URL befinden, die zuvor authentifiziert wurde. Dadurch wird die Anzahl der nicht authentifizierten HTTP-Anforderungen, die an den Server gesendet werden, erheblich reduziert und dadurch die Serverauslastung reduziert.

Im Folgenden finden Sie einige Beispiele:

URL Wird PreAuthenticate?
https://pkgs.contoso.com/nuget/v3/feed/index.json N/A, dies ist der Dienstindex.
https://pkgs.contoso.com/nuget/v3/search Nein, nicht im selben oder Unterverzeichnis wie der Dienstindex.
https://search.pkgs.contoso.com/nuget/v3/feed/ Nein, nicht auf demselben Hostnamen wie der Dienstindex.
https://pkgs.contoso.com/nuget/v3/feed/search Ja, im selben Verzeichnis wie der Dienstindex.
https://pkgs.contoso.com/nuget/v3/registration/ Nein, nicht in einem Unterverzeichnis des Dienstindexes.
https://pkgs.contoso.com/nuget/v3/feed/registration/ Ja, in einem Unterverzeichnis des Dienstindexes.
https://pkgs.contoso.com/nuget/v3/{guid}/registration/ Siehe unten

Im letzten Beispiel verfügt der Server möglicherweise über einen kanonischen (in diesem Beispiel einen GUID-Namen) und einen oder mehrere Aliase. Wenn die Dienstindexanforderung auf einer nicht kanonischen URL authentifiziert wurde (der "Anzeigename", in unserem Beispiel feed), stimmen keine Anforderungen an Ressourcen unter der kanonischen URL mit HttpClientHandlerden Regeln überein PreAuthenticate. Wenn die nicht kanonische URL jedoch eine HTTP-Umleitung zur kanonischen URL ist, https://pkgs.contoso.com/nuget/v3/{guid}/index.jsonwird diese URL im HttpClientHandlerAnmeldeinformationscache verwendet. In diesem Fall hat jede Anforderung an den Dienstindex aufgrund der Umleitung zusätzliche Latenz.

Während die V3-API von NuGet für die Arbeit an einem statischen Dateiserver entwickelt wurde, ist die Suchressource die Ausnahme, die immer einen dynamischen Webdienst zum Verarbeiten von Anforderungen erfordert. Wenn Sie die Suche oder tatsächlich eine andere NuGet-API-Ressource auf verschiedenen Servern hosten möchten, müssen HttpClientHandlerPreAuthenticateSie einen Reverseproxy verwenden, um sicherzustellen, dass alle kundenorientierten URLs im Dienstindex die Regel "identisch" oder "Unterverzeichnis" erfüllen.