Implementierungshandbuch für NuGet-Server

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 Protokollversionsverwaltung.

Chronology

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, die im restlichen Dokument erwähnt werden.

Eigentümerfeld

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 .nuspec der <owners> 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

Die Benutzeroberfläche des Paket-Managers von Visual Studio zeigt ein blaues Häkchen neben Paketen in Suchergebnissen an, wenn ein neues Feld verified auf true festgelegt ist.

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.

Unterstützung für semantische Versionsverwaltung 2.0.0

NuGet unterstützt einen Hybrid aus System.Version und Semantische Version, 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 von .NET oder der semantischen Versionierung 1.0.0 entsprechen. 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 fehlt, nehmen Sie den Wert 1.0.0 an. 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. Beispiel: 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. Damit können Kunden, die in der Benutzeroberfläche des Visual Studio-Paketmanagers oder in gleichwertigen Funktionen anderer IDEs Pakete durchsuchen, über wichtige Sicherheits- oder Wartungsprobleme benachrichtigt werden.

Wenn Ihr Paket-Repository Pakete aus einem anderen Repository übernimmt, um diese in Ihrem eigenen Feed zu spiegeln, empfehlen wir, regelmäßig die ursprüngliche Quelle zu überprüfen, um festzustellen, ob es veraltete oder Sicherheitsrisikodaten gibt, und diese Metadaten in Ihrem eigenen Repository zu spiegeln. 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.

Erneute Verwendung der Sicherheitsrisikodaten von nuget.org

NuGet erfordert nicht, dass sich Ressourcen im Dienstindex oder der Sicherheitsrisikoindex auf demselben Server wie der Dienstindex selbst befinden müssen. Es gibt jedoch mehrere Gründe, warum einige Unternehmen nuget.org an der Firewall blockieren oder lokale Feeds in einem getrennten Netzwerk haben. Um Verbindungsprobleme zu vermeiden, empfehlen wir die Bereitstellung von Sicherheitsrisikodaten aus Ihrer eigenen Web-App, sodass NuGet-Clients nur HTTP-Verbindungen mit dem Host herstellen, auf dem der Feed installiert ist.

✔️ Cachen oder proxyen Sie die Schwachstellenseiten in Ihrer eigenen Webanwendung

❌ Werben Sie nicht api.nuget.org in Ihrem Dienstindex oder Sicherheitsrisikoindex ohne Konfiguration, um dies zu deaktivieren.

packageTypes Suchabfrage

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

Hier sind einige Beispiele:

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.

Aktivieren von eingebetteten README-Downloads

Eine neue Ressource wurde zum Erstellen einer URL dokumentiert, die zum Herunterladen einer README für ein bestimmtes Paket verwendet werden kann. Dadurch kann der Client wie die Paketverwaltungs-UI in VS die eingebettete README-Datei für Pakete anzeigen, die noch nicht vom Benutzer installiert wurden. Der Client erstellt diese URL und versucht, die README-Datei mithilfe der Antwort auf die Anforderung herunterzuladen, um festzustellen, ob eine README verfügbar ist. Dies bedeutet, dass Server mehrere Anforderungen an den erstellten Endpunkt erwarten sollten, während Benutzer in der PM-Benutzeroberfläche navigieren.