Przewodnik implementacji serwera NuGet

W niektórych przypadkach możesz zaimplementować własny kanał informacyjny pakietów NuGet. Istnieje wiele gotowych implementacji, które pozwalają na hostowanie własnego kanału pakietów na wiele sposobów, ale protokół między oficjalnym oprogramowaniem klienckim NuGet a kanałem pakietów jest udokumentowany, co pozwala na stworzenie własnej implementacji kanału od podstaw.

Protokół ewoluuje wraz z upływem czasu, a ten przewodnik jest przeznaczony dla tych, którzy chcą lub już zaimplementowali serwer pakietów NuGet.

Od czasu początkowego wydania protokołu NuGet V3 w 2015 roku, NuGet ewoluował, aby zapewnić deweloperom bogatsze doświadczenie, co wymaga od repozytoriów pakietów dodatkowego wysiłku, aby dostarczyć konsumentom pakietów dodatkową wartość, wykraczającą poza zwykłe wydobywanie metadanych z hostowanych pakietów i zwracanie tych metadanych w różnych formach. Na przykład punkty końcowe metadanych wyszukiwania i pakietu zawierają więcej niż tylko metadane znalezione w pliku nuspec nupkg.

Należy pamiętać, że ten przewodnik koncentruje się na protokole NuGet V3, ponieważ protokół V2 jest zasadniczo nieudokumentowany i od 2015 r. zalecanym protokołem komunikacji klienta i serwera NuGet jest protokół V3. Aby uzyskać więcej informacji, przeczytaj o wersjonowaniu protokołu.

Chronology

Aby pomóc autorom istniejących repozytoriów NuGet w nadążaniu za najnowszymi funkcjami NuGet, poniżej przedstawiono chronologiczny przegląd odpowiednich funkcji wymienionych w pozostałej części dokumentu.

Year	Feature
2013	Wpis na blogu wyjaśniający, jak zarządzać właścicielami pakietów w nuget.org wyjaśnia, że właściciele pokazywani na stronie internetowej to konta, które mają uprawnienia do przesyłania nowych wersji, a zatem owners metadane w pakiecie są ignorowane
2017	Dodano verified do SearchQueryService odpowiedzi.
	Obsługa wersji semantycznej 2.0.0
2018	Licencje osadzone
2019	Ikony osadzone
	Wycofanie pakietu w RegistrationBaseUrl (metadanych zasobu pakietu)
2020	Informacje o lukach w zabezpieczeniach pakietu ( RegistrationsBaseUrl zasób metadanych pakietu)
	Dodano packageTypes parametr zapytania do SearchQueryService żądań
2021	Zintegrowany plik readme
2023	Wstępne uwierzytelnianie uwierzytelnionych żądań VulnerabilityInfo zasób
2025	Włącz pobieranie osadzonych plików README

Pole Właściciela

Rozważ dwa pola pliku manifestu pakietu: .nuspec i . Autorzy pakietów, którzy pakują zawartość innej firmy, często umieszczają w polu nazwę <authors> innej firmy. Pole <owners> miało wskazywać, kto opublikował pakiet w repozytorium, a zatem kto powinien się skontaktować w przypadku problemów lub pytań dotyczących pakowania.

Zostało to wyjaśnione we wpisie w blogu z 2013 r., więc <owners> pole jest uznawane za przestarzałe w .nuspec pliku. Jeśli manifest pakietu zawiera te metadane, powinien zostać zignorowany. Nie zwracaj wartości pola .nuspec w pliku <owners> dla właściwości owners w odpowiedzi JSON zasobu wyszukiwania lub zasobu metadanych pakietu.

Jeśli repozytorium ma uprawnienia dla poszczególnych pakietów, zaleca się zgłaszanie kont posiadających uprawnienia do publikowania nowych wersji w metadanych owner, które są częścią odpowiedzi JSON dla zasobów metadanych związanych z wyszukiwaniem i pakietami.

verified pole odpowiedzi wyszukiwania

Interfejs użytkownika menedżera pakietów programu Visual Studio zawiera niebieski znacznik wyboru obok pakietów w wynikach usługi wyszukiwania , gdy nowe pole verified ma wartość true.

NuGet.org używa tego elementu wraz z danymi prefiksu pakietu (danymi po stronie serwera, które nie są częścią interfejsu API NuGet), dzięki czemu ten znacznik wyboru jest wyświetlany tylko klientom, gdy konto będące właścicielem pakietu przekazano pakiet. Na przykład każdy pakiet z prefiksem microsoft.* jest weryfikowany tylko wtedy, gdy pakiet jest własnością konta Microsoft na nuget.org. Każda osoba, która przekaże pakiet o identyfikatorze pakietu rozpoczynającym się od microsoft. przed zaimplementowaniu prefiksów zarezerwowanych, nie będzie miała tego zweryfikowanego znacznika wyboru. NuGet.org również pozwala na to, aby prefiksy nie były wyłączne, dzięki czemu każdy może przesłać pakiet w obszarze Contoso.ToolWithPlugins.Community.*, ale nie otrzyma zweryfikowanego znacznika.

Obsługa wersji semantycznej 2.0.0

Pakiet NuGet obsługuje hybrydę między System.Version a wersją semantyczną, ale obsługa wersji semantycznej 2.0.0 została dodana w 2017 r. W związku z tym zasoby interfejsu API NuGet, które zwracają wersje do klientów korzystających z wersji niższych niż 3.6.0, nie mogą zwracać pakietów wykorzystujących funkcje Semantic 2.0.0, które są niezgodne z Semantic Versioning 1.0.0.

Najważniejsze różnice między dwiema wersjami to etykiety wersji wstępnej i ciąg metadanych. Specyfikacja Semantic Versioning 1.0.0 dostarcza [0-9A-Za-z-] przykładowy ciąg znaków wyrażenia regularnego dla jedynych dozwolonych znaków, które mogą być częścią etykiety wersji wstępnej, i nie obsługuje ciągów metadanych. Specyfikacja Semantic Versioning 2.0.0 umożliwia oddzielenie identyfikatorów wersji wstępnej za pomocą znaków . (i zabrania, aby identyfikator liczbowy rozpoczynał się zerem wiodącym) i dodatkowo umożliwia dodawanie metadanych kompilacji po znaku +.

W zasobie metadanych pakietu (RegistrationsBaseUrl)wersje zasobów poniżej wersji 3.6.0 muszą zwracać tylko pakiety zgodne z . Net lub System.Version Semantic Versioning 1.0.0. Oznacza to, że pakiety, których wersje są zgodne tylko z semantyczną wersją 2.0.0, są niewidoczne dla tych wersji klienta.

Podobnie usługa zapytań wyszukiwania (SearchQueryService) i usługa autouzupełniania (SearchAutocompleteService) dodała &semVerLevel={version} parametry zapytania. Jeśli semVerLevel brakuje wartości , przyjmij wartość 1.0.0. Podobnie jak zasób metadanych pakietu, pakiety, których wersja jest zgodna tylko z semantyczną wersją 2.0.0, nie mogą być zwracane, gdy semVerLevel wartość jest niższa niż 2.0.0.

Pliki osadzone

Ikony pakietów, licencja i pliki readme mogą być (i są zalecane) osadzone w pakiecie. Te pliki wymagają punktu końcowego adresu URL, który jest albo wyodrębniony i umieszczony na statycznym serwerze plików, albo adresu URL, który dynamicznie wyodrębnia pliki z .nupkg na żądanie, aby można było je wyświetlić bez pobierania całego nupkg. Jeśli repozytorium pakietów udostępnia przeglądanie pakietów i wyświetlanie szczegółów pakietu, możesz użyć adresów URL, aby pokazać klientom zawartość osadzoną w witrynie internetowej.

Na koniec zasób metadanych pakietu i zasób wyszukiwania muszą zawierać hostowany adres URL w właściwościach iconUrl, licenseUrl i/lub readmeUrl odpowiedzi JSON. Pakiety (.nupkg pliki) nie mogą być modyfikowane, ponieważ funkcje klienta (blokowanie plików i podpisanych pakietów) wykryje modyfikacje, gdy pakiet został naruszony.

Należy pamiętać, że licencja może być wyrażeniem SPDX lub plikiem osadzonym (ale nie obie). Pakiety korzystające z wyrażenia licencji, reprezentowane w wynikach metadanych wyszukiwania i pakietu, mogą mieć licenseUrl ustawiony na wyrażenie licencji, zakodowane w formacie URL, dołączone do końca https://licenses.nuget.org/. Na przykład https://licenses.nuget.org/Apache-2.0. Zespół serwera NuGet.org ma dodatkową dokumentację dotyczącą licenses.nuget.org.

Znane luki w zabezpieczeniach i wycofywanie danych

Zasób metadanych pakietu (RegistrationsBaseUrl)

Zasób metadanych pakietu może zawierać informacje o wycofaniu i lukach w zabezpieczeniach. Dzięki temu klienci mogą przeglądać pakiety w interfejsie użytkownika Menedżera pakietów programu Visual Studio lub równoważnej w innych środowiskach IDE, aby otrzymywać powiadomienia o ważnych problemach z zabezpieczeniami lub konserwacją.

Jeśli twoje repozytorium pakietów pozyskuje pakiety z innego repozytorium, aby zreplikować je we własnym repozytorium, zalecamy okresowe sprawdzanie oryginalnego źródła pod kątem informacji o wycofaniach lub lukach w zabezpieczeniach oraz odzwierciedlenie tych metadanych we własnym repozytorium. Jeśli twoje repozytorium pakietów pobiera dane bezpośrednio z nuget.org, zachowując stan ostatniego sprawdzenia (kursor), możesz użyć Catalog zasobu, aby efektywnie sprawdzić, czy są dostępne aktualizacje dla pakietów, które są kopiowane, bez konieczności pobierania dużej ilości plików JSON z metadanymi pakietów z nadrzędnego źródła. Istnieje przewodnik po korzystaniu z zasobu wykazu z przykładowym kodem, który może pomóc w rozpoczęciu pracy.

Baza wiedzy o znanych lukach w zabezpieczeniach (VulnerabilityInfo)

Aby zapewnić skanowanie luk w zabezpieczeniach o wysokiej wydajności podczas przywracania pakietu, NuGet pobiera pełną listę znanych luk w zabezpieczeniach z zasobu VulnerabilityInfo. Nuget.org udostępnia dane o lukach w zabezpieczeniach dla wszystkich porad dotyczących bezpieczeństwa przeglądanych przez GitHub, z bazy danych GitHub Advisories, w tym również pakietów, które nie są hostowane na nuget.org.

Jeśli repozytorium pakietów hostuje pakiety pierwszej firmy i chcesz udostępnić klientom informacje o lukach w zabezpieczeniach przy użyciu własnego kanału informacyjnego, ale nie ma jeszcze żadnych ujawnionych luk w zabezpieczeniach pakietów, należy podać indeks luk w zabezpieczeniach z co najmniej jedną stroną luk w zabezpieczeniach , których zawartość jest pustą tablicą JSON ([]).

Ponowne wykorzystanie danych luk w zabezpieczeniach nuget.org

Pakiet NuGet nie wymaga, aby zasoby w indeksie usługi lub indeks luk w zabezpieczeniach znajdować się na tym samym serwerze co sam indeks usługi. Istnieje jednak kilka powodów, dla których niektóre firmy zdecydują się zablokować nuget.org w zaporze lub mieć lokalne źródła danych w rozłączonej sieci. Aby uniknąć problemów z łącznością, zalecamy obsługę danych luk w zabezpieczeniach za pomocą własnej aplikacji internetowej, tak aby klienci NuGet nawiązywali połączenia HTTP tylko z hostem, na którym zainstalowany jest kanał informacyjny.

✔️ Buforuj lub używaj serwera proxy dla stron podatności we własnej aplikacji internetowej

❌ Nie anonsuj api.nuget.org w indeksie usługi lub indeksie luk w zabezpieczeniach bez konfiguracji, aby wyłączyć tę funkcję.

packageTypes kwerenda wyszukiwania

Interfejs wiersza poleceń .NET umożliwia wyszukiwanie pakietów narzędzi .NET za pomocą polecenia dotnet tool search. Jest to implementowane przez dodanie parametru &packageTypes={value} zapytania do zasobu zapytania wyszukiwania, który odczytuje wartości z pola pliku .nuspec pakietu<packageTypes>.

Struktura adresów URL dla uwierzytelnionych źródeł danych

Zgodnie z opisem w omówieniu interfejsu API NuGet początkowy adres URL dla całej komunikacji serwera NuGet to indeks usługi. Ten dokument zawiera adresy URL dla wszystkich innych zasobów, o które zapytają klienci NuGet. Od NuGet 6.7 (Visual Studio, MSBuild 17.7 oraz .NET SDK 7.0.400) NuGet wykorzystuje .NET HttpClientHandler.PreAuthenticate, który unika anonimowych żądań HTTP tylko wtedy, gdy kolejne adresy URL znajdują się w tym samym katalogu wirtualnym lub podkatalogu adresu URL, który został wcześniej uwierzytelniony. Spowoduje to znaczne zmniejszenie liczby nieuwierzytelnionych żądań HTTP wysyłanych do serwera i w związku z tym zmniejszy obciążenie serwera.

Oto kilka przykładów:

adres URL	Czy zostanie wstępnie uwierzytelnione?
https://pkgs.contoso.com/nuget/v3/feed/index.json	Brak danych, jest to indeks usługi.
https://pkgs.contoso.com/nuget/v3/search	Nie, nie w tym samym katalogu ani podkatalogu co indeks usługi.
https://search.pkgs.contoso.com/nuget/v3/feed/	Nie, nie na tej samej nazwie hosta co indeks usługi.
https://pkgs.contoso.com/nuget/v3/feed/search	Tak, w tym samym katalogu co indeks usługi.
https://pkgs.contoso.com/nuget/v3/registration/	Nie, nie w podkatalogu indeksu usługi.
https://pkgs.contoso.com/nuget/v3/feed/registration/	Tak, w podkatalogu indeksu usługi.
https://pkgs.contoso.com/nuget/v3/{guid}/registration/	Zobacz poniżej

W ostatnim przykładzie serwer może mieć nazwę kanoniczną (w tym przykładzie identyfikator GUID) i mieć co najmniej jeden alias. Jeśli żądanie indeksu usługi zostało uwierzytelnione pod adresem URL innym niż kanoniczny (przyjazna nazwa, w naszym przykładzie feed), wtedy nie, żadne żądania kierowane do zasobów pod adresem kanonicznym URL nie będą zgodne z regułami HttpClientHandler dla PreAuthenticate. Jednakże, jeśli adres URL inny niż kanoniczny jest przekierowywany przez HTTP do kanonicznego adresu URL, wówczas ten adres URL będzie używany w pamięci podręcznej poświadczeń https://pkgs.contoso.com/nuget/v3/{guid}/index.json. W takim przypadku każde żądanie do indeksu usługi będzie miało dodatkowe opóźnienie ze względu na przekierowanie.

Chociaż interfejs API programu NuGet w wersji 3 został zaprojektowany do pracy na statycznym serwerze plików, zasób wyszukiwania jest wyjątkiem, który zawsze wymaga dynamicznej usługi internetowej do przetwarzania żądań. Jeśli chcesz hostować wyszukiwanie lub dowolny inny zasób interfejsu API NuGet na różnych serwerach, aby skorzystać z HttpClientHandler'a PreAuthenticate, musisz użyć zwrotnego proxy, aby upewnić się, że wszystkie adresy URL skierowane do klientów w indeksie usług spełniają zasadę "tego samego katalogu lub podkatalogu".

Włącz osadzone pliki README

Nowy zasób został udokumentowany pod kątem konstruowania adresu URL, który może służyć do pobierania pliku README dla danego pakietu. Umożliwi to klientowi, takim jak interfejs użytkownika zarządzania pakietami w programie VS, wyświetlanie osadzonego pliku README dla pakietów, które nie zostały wcześniej zainstalowane przez użytkownika. Klient skonstruuje ten adres URL i spróbuje pobrać plik README przy użyciu odpowiedzi na żądanie w celu ustalenia, czy plik README jest dostępny. Oznacza to, że serwery powinny oczekiwać wielu żądań do skonstruowanego endpointu, gdy użytkownicy nawigują po interfejsie użytkownika PM.