Przewodnik implementacji serwera NuGet

W niektórych przypadkach możesz zaimplementować własny kanał informacyjny pakietów NuGet. Istnieje wiele istniejących implementacji , które umożliwiają hostowanie własnego kanału informacyjnego w różny sposób, ale protokół między oficjalnym oprogramowaniem klienckim NuGet a kanałem informacyjnym pakietów jest udokumentowany, umożliwiając tworzenie własnej implementacji kanału informacyjnego 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ątkowej wersji protokołu NuGet v3 w 2015 r. nuGet ewoluowało, aby zapewnić deweloperom bogatsze środowisko pracy, a to wymaga, aby repozytoria pakietów działały dodatkową pracę, aby zapewnić dodatkową wartość konsumentom pakietów, poza po prostu wymaganie metadanych z hostowanych pakietów i zwracanie 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 na temat przechowywania wersji protokołu.

Chronologii

Aby pomóc autorom istniejących repozytoriów NuGet na bieżąco z najnowszymi funkcjami NuGet, oto chronologia odpowiednich funkcji wymienionych w pozostałej części dokumentu.

Year (Rok)	Funkcja
2013	Wpis w blogu wyjaśniający, jak zarządzać właścicielami pakietów w nuget.org wyjaśnił właścicieli pokazanych na stronie internetowej są konta, które mają uprawnienia do przekazywania 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 ( RegistrationBaseUrl zasób metadanych pakietu)
2020	Informacje o lukach w zabezpieczeniach pakietu ( RegistrationsBaseUrl zasób metadanych pakietu)
	Dodano packageTypes parametr zapytania do SearchQueryService żądań
2021	Osadzony plik readme
2023	Wstępne uwierzytelnianie żądań VulnerabilityInfo Zasobów

Pole Właściciela

Rozważ dwa pola pliku manifestu pakietu (.nuspec) i <owners>. <authors> 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 .nuspec pola pliku <owners> we właściwości w owners odpowiedzi JSON zasobu wyszukiwania lub zasobu metadanych pakietu.

Jeśli repozytorium ma uprawnienia dla poszczególnych pakietów, zaleca się zgłaszanie kont, które mają uprawnienia do publikowania nowych wersji w owner metadanych na potrzeby odpowiedzi JSON dla zasobów metadanych wyszukiwania i pakietu.

verified pole odpowiedzi wyszukiwania

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

NuGet.org używa tego elementu z danymi prefiksu pakietu (dane po stronie serwera, a nie częścią interfejsu API NuGet), dzięki czemu ta znacznik wyboru jest wyświetlana tylko klientom, gdy konto będące właścicielem pakietu zostało przekazane 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 zezwala również na wykluczanie prefiksów, dzięki czemu każdy może przekazać pakiet w obszarze Contoso.ToolWithPlugins.Community.*, ale nie otrzyma zweryfikowanego znacznika wyboru.

Obsługa wersji semantycznej 2.0.0

Pakiet NuGet obsługuje środowisko hybrydowe między wersją System.Versionsemantyczną i semantyczną, ale w 2017 r. dodano obsługę programu Semantic w wersji 2.0.0. W związku z tym zasoby interfejsu API NuGet, które zwracają wersje do wersji klienckich niższe niż 3.6.0, nie mogą zwracać pakietów korzystających z funkcji Semantic 2.0.0, które są niezgodne z semantyczną wersją 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 stanowi [0-9A-Za-z-] przykładowy ciąg wyrażenia regularnego dla tylko znaków dozwolonych w ramach etykiety wstępnej i nie obsługuje ciągów metadanych. Specyfikacja Semantic Versioning 2.0.0 umożliwia oddzielenie identyfikatorów wersji wstępnej przez . znaki (i zabrania identyfikatora liczbowego od zera wiodącego) 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, wyodrębnionego i umieszczonego na statycznym serwerze plików lub adresu URL, który dynamicznie wyodrębnia pliki z .nupkg żądania, aby można było je wyświetlić bez pobierania całego nupkgpliku . 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 iconUrlodpowiedź w formacie , licenseUrli/lubreadmeUrl. 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 zestaw na wyrażenie licencji, kodowany adres URL i dołączany na końcu elementu 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 przeglądają pakiety w interfejsie użytkownika programu Visual Studio Menedżer pakietów lub równoważnym w innych środowiskach IDE, aby otrzymywać powiadomienia o ważnych problemach z zabezpieczeniami lub konserwacją.

Jeśli repozytorium pakietów to "up-source" pakiety z innego repozytorium, w celu dublowania pakietów we własnym kanale informacyjnym zalecamy okresowe sprawdzanie oryginalnego źródła, jeśli istnieje wycofanie lub dane luk w zabezpieczeniach oraz dublowanie tych metadanych we własnym repozytorium. Jeśli repozytorium pakietów jest źródłem źródła z nuget.org konkretnie, zachowując stan ostatniego sprawdzenia (kursor), możesz użyć Catalog zasobu, aby efektywnie sprawdzić, czy istnieją aktualizacje pakietów dla pakietów, które są dublowane, bez konieczności pobierania dużej liczby plików JSON metadanych pakietu z nadrzędnego źródła danych. Istnieje przewodnik po korzystaniu z zasobu wykazu z przykładowym kodem, który może pomóc w rozpoczęciu pracy.

Znana baza danych luk w zabezpieczeniach (VulnerabilityInfo)

Aby zapewnić skanowanie luk w zabezpieczeniach o wysokiej wydajności podczas przywracania pakietu, NuGet pobiera pełną listę znanych luk w VulnerabilityInfo zabezpieczeniach z zasobu. Nuget.org udostępnia dane luk w zabezpieczeniach dla wszystkich recenzowanych porad usługi GitHub z bazy danych GitHub Advisories, w tym pakietów, które nie są hostowane w 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 ([]).

Jeśli repozytorium pakietów ma być używane przez aplikacje jako domyślne repozytorium (zamiast nuget.org), możesz użyć danych luk w zabezpieczeniach nuget.org. Jedną z opcji jest użycie adresu URL indeksu luk w zabezpieczeniach nuget.org w indeksie usługi. Inną opcją jest okresowe sprawdzanie indeksu VulnerabilityInfo nuget.org i pobieranie wszystkich zmienionych stron w celu zdublowania lokalnego.

packageTypes kwerenda wyszukiwania

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

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, które będą wykonywać zapytania klientów NuGet. Od nuGet 6.7 (Visual Studio i MSBuild 17.7 i .NET SDK 7.0.400) pakiet NuGet używa polecenia . Net' s HttpClientHandler.PreAuthenticate, który unika tylko anonimowych żądań HTTP, 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:

URL	Czy wstępnie uwierzytelnione?
https://pkgs.contoso.com/nuget/v3/feed/index.json	Nie dotyczy to indeksu usługi.
https://pkgs.contoso.com/nuget/v3/search	Nie, nie w tym samym lub 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), nie, żadne żądania do zasobów w adresie URL kanonicznym nie będą zgodne HttpClientHandlerz regułami .PreAuthenticate Jeśli jednak adres URL inny niż kanoniczny jest przekierowaniem HTTP do kanonicznego adresu URL, https://pkgs.contoso.com/nuget/v3/{guid}/index.jsonten adres URL będzie używany w HttpClientHandlerpamięci podręcznej poświadczeń. 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, a nawet jakikolwiek inny zasób interfejsu API NuGet, na różnych serwerach, aby korzystać z HttpClientHandlerparametrów PreAuthenticate, musisz użyć zwrotnego serwera proxy, aby upewnić się, że wszystkie adresy URL klientów w indeksie usługi spełniają regułę "tego samego lub podkatalogu".