Udostępnij za pośrednictwem

Wtyczki międzyplatformowe NuGet

Dodano obsługę wtyczek międzyplatformowych w programie NuGet 4.8 lub nowszym. Zostało to osiągnięte dzięki utworzeniu nowego modelu rozszerzalności wtyczki, który musi być zgodny z rygorystycznym zestawem reguł operacji. Wtyczki są samodzielnymi plikami wykonywalnymi (runnables w świecie platformy .NET Core), które klienci NuGet uruchamiają w osobnym procesie. Jest to prawdziwa wtyczka napisz raz, uruchamiaj wszędzie. Będzie działać z wszystkimi narzędziami klienckimi NuGet. Wtyczki można napisać w dowolnym języku programowania, ale najłatwiejszym środowiskiem programowania i instalacji wtyczki będzie platforma .NET. Zdefiniowano wersjonowany protokół komunikacji między klientem NuGet a wtyczką. Podczas procesu uruchamiania, 2 procesy negocjują wersję protokołu.

Jak to działa?

Ogólny przepływ pracy można opisać w następujący sposób:

  1. Narzędzie NuGet odnajduje dostępne wtyczki.
  2. Jeśli ma to zastosowanie, pakiet NuGet wykonuje iteracje nad wtyczkami w kolejności priorytetu i uruchamia je pojedynczo.
  3. Narzędzie NuGet będzie używać pierwszej wtyczki, która może obsłużyć żądanie.
  4. Wtyczki zostaną zamknięte, gdy nie będą już potrzebne.

Ogólne wymagania dotyczące wtyczki

Bieżąca wersja protokołu to 2.0.0. W tej wersji wymagania są następujące:

  • Umożliwienie bezstanowego uruchamiania w kontekście bieżących zabezpieczeń narzędzi klienckich NuGet. Na przykład narzędzia klienckie NuGet nie będą wykonywać podniesienia uprawnień ani dodatkowej inicjalizacji poza opisanym później protokołem wtyczki.
  • Być nieinterakcyjnym, chyba że określono jawnie.
  • Zastosuj się do wynegocjowanej wersji protokołu wtyczki.
  • Odpowiadanie na wszystkie żądania w rozsądnym czasie.
  • Uwzględniaj żądania anulowania dla każdej operacji będącej w toku.

Wtyczki odkryte z zmiennej środowiskowej PATH (na przykład zainstalowane za pośrednictwem dotnet tool) dodatkowo muszą być zgodne ze schematem nazwy pliku nuget-plugin-*. Część nuget-plugin- musi być napisana w całości małymi literami.

NuGet 6.12 (MSBuild 17.12 oraz .NET SDK 9.0.100) i wcześniejsze wersje również wymagały, aby wtyczki były podpisane za pomocą Authenticode w systemie Windows.

Specyfikacja techniczna została szczegółowo opisana w następujących specyfikacjach:

Klient — interakcja z wtyczką

Narzędzia klienckie NuGet i wtyczki komunikują się z plikiem JSON za pośrednictwem standardowych strumieni (stdin, stdout, stderr). Wszystkie dane muszą być zakodowane w formacie UTF-8. Wtyczki są uruchamiane z argumentem "-Plugin". Jeśli użytkownik bezpośrednio uruchamia plik wykonywalny wtyczki bez tego argumentu, wtyczka może przekazać komunikat informacyjny zamiast czekać na uzgadnianie protokołu. Limit czasu handshake protokołu wynosi 5 sekund. Wtyczka powinna ukończyć instalację w możliwie najkrótszym czasie. Narzędzia klienckie NuGet będą wykonywać zapytania dotyczące obsługiwanych operacji wtyczki, przekazując indeks usługi dla źródła NuGet. Wtyczka może używać indeksu usługi do sprawdzania obecności obsługiwanych typów usług.

Komunikacja między narzędziami klienta NuGet a wtyczką jest dwukierunkowa. Każde żądanie ma limit czasu 5 sekund. Jeśli operacje mają trwać dłużej, odpowiedni proces powinien wysłać komunikat o postępie, aby zapobiec przekroczeniu limitu czasu żądania. Po 1 minucie braku aktywności, plugin jest uznawany za nieaktywny i jest zamykany.

Instalacja i odnajdywanie wtyczki

Narzędzie NuGet wyszukuje wtyczki ze struktury katalogów opartej na konwencji i skanuje zmienną środowiskową PATH.

Odnajdywanie zgodne z konwencją

Scenariusze CI/CD i zaawansowani użytkownicy mogą użyć zmiennych środowiskowych, aby zmienić działanie. W przypadku używania zmiennych środowiskowych dozwolone są tylko ścieżki bezwzględne. Należy pamiętać, że NUGET_NETFX_PLUGIN_PATHS i NUGET_NETCORE_PLUGIN_PATHS są dostępne tylko w wersji 5.3 lub nowszej narzędzi NuGet.

  • NUGET_NETFX_PLUGIN_PATHS — definiuje wtyczki, które będą używane przez narzędzia oparte na programie .NET Framework (NuGet.exe/MSBuild.exe/Visual Studio). Ma pierwszeństwo przed NUGET_PLUGIN_PATHS. (Tylko wersja NuGet 5.3 lub nowsza)
  • NUGET_NETCORE_PLUGIN_PATHS — definiuje wtyczki, które będą używane przez narzędzia oparte na platformie .NET Core (dotnet.exe). Ma pierwszeństwo przed NUGET_PLUGIN_PATHS. (Tylko wersja NuGet 5.3 lub nowsza)
  • NUGET_PLUGIN_PATHS - definiuje wtyczki, które będą używane dla tego procesu NuGet, priorytet zachowany. Jeśli ta zmienna środowiskowa jest ustawiona, zastępuje odnajdywanie oparte na konwencji. Ignorowane, jeśli określono jedną ze zmiennych specyficznych dla platformy.
  • Lokalizacja użytkownika, główna lokalizacja NuGet w %UserProfile%/.nuget/plugins. Nie można zastąpić tej lokalizacji. Wtyczki .NET Core i .NET Framework będą używane w innym katalogu głównym.
Struktura Lokalizacja odkrywania korzenia Używane przez
.NET Core %UserProfile%/.nuget/plugins/netcore Interfejs wiersza polecenia dotnet
Środowisko .NET Framework %UserProfile%/.nuget/plugins/netfx MSBuild, NuGet.exe, Visual Studio

Każda wtyczka powinna być zainstalowana we własnym folderze. Punktem wejścia wtyczki będzie nazwa zainstalowanego folderu z rozszerzeniami .dll dla platformy .NET Core i rozszerzeniem .exe dla programu .NET Framework.

.nuget
    plugins
        netfx
            myPlugin
                myPlugin.exe
                nuget.protocol.dll
                ...
        netcore
            myPlugin
                myPlugin.dll
                nuget.protocol.dll
                ...

Odnajdywanie ŚCIEŻKI

Począwszy od nuGet 6.13, NuGet będzie przeszukiwać każdy katalog podany w zmiennej środowiskowej PATH pod kątem plików pasujących do wzorca nuget-plugin-*. Dopasowanie wzorca jest wrażliwe na wielkość liter, a nuget-plugin- musi być napisane całkowicie małymi literami. W systemie Windows plik musi mieć .exe rozszerzenie lub .bat . W systemach Linux i Mac plik musi mieć zestaw bitów wykonywalnych.

Dzięki temu można zainstalować wtyczki NuGet za pomocą dotnet tool poleceń, WinGet, menedżera pakietów dystrybucji systemu Linux lub dowolnej innej metody, która może umieszczać pliki wykonywalne na ścieżce użytkownika. Dzięki temu można również zapisywać wtyczki NuGet w dowolnym języku programowania (wcześniej wtyczki dla systemów Linux i Mac muszą być napisane na platformie .NET).

Zalecamy, aby wtyczki zostały opracowane na platformie .NET, aby można było użyć pakietu NuGet.Protocol , aby uniknąć konieczności pisania kodu RPC w formacie json i umożliwienia klientom odnajdywania wtyczki za pośrednictwem programu dotnet package search nuget-plugin.

Obsługiwane operacje

Dwie operacje są obsługiwane w ramach nowego protokołu wtyczki.

Nazwa operacji Minimalna wersja protokołu Minimalna wersja klienta NuGet
Pobierz pakiet 1.0.0 4.3.0
Uwierzytelnianie 2.0.0 4.8.0

Uruchamianie wtyczek w prawidłowym środowisku uruchomieniowym

W przypadku pakietów NuGet w scenariuszach dotnet.exe wtyczki muszą być wykonywane w ramach tego konkretnego środowiska uruchomieniowego dotnet.exe. To zależy od dostawcy wtyczek i konsumenta, aby upewnić się, że jest używana zgodna kombinacja dotnet.exe/plugin. Potencjalny problem może wystąpić z wtyczkami lokalizacji użytkownika, gdy na przykład dotnet.exe w środowisku uruchomieniowym 2.0 próbuje użyć wtyczki napisanej dla środowiska uruchomieniowego 2.1.

Buforowanie możliwości

Weryfikacja zabezpieczeń i instancjowanie wtyczek jest kosztowne. Operacja pobierania odbywa się częściej niż operacja uwierzytelniania, jednak przeciętny użytkownik NuGet prawdopodobnie będzie miał wtyczkę uwierzytelniania. Aby poprawić doświadczenie, NuGet będzie buforować roszczenia operacyjne dla danego żądania. Ten cache jest dla każdej wtyczki, przy czym kluczem wtyczki jest ścieżka wtyczki, a ten cache funkcji wygasa po 30 dniach.

Pamięć podręczna znajduje się w %LocalAppData%/NuGet/plugins-cache i może być zastąpiona zmienną środowiskową NUGET_PLUGINS_CACHE_PATH. Aby wyczyścić tę pamięć podręczną, można uruchomić polecenie locals z opcją plugins-cache . Opcja all ustawień lokalnych spowoduje teraz również usunięcie pamięci podręcznej wtyczek.

Indeks komunikatów protokołu

Komunikaty protokołu w wersji 1.0.0 :

  1. Zamknij

    • Kierunek żądania: NuGet —> wtyczka
    • Żądanie nie będzie zawierać ładunku
    • Nie oczekuje się odpowiedzi. Prawidłową reakcją jest natychmiastowe zakończenie działania procesu wtyczki.

  2. Kopiowanie plików w pakiecie

    • Kierunek żądania: NuGet - > wtyczka
    • Żądanie będzie zawierać następujące elementy:
      • identyfikator i wersja pakietu
      • lokalizacja repozytorium źródłowego pakietu
      • docelowa ścieżka katalogu
      • lista plików w pakiecie do skopiowania do katalogu docelowego
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji
      • lista pełnych ścieżek dla skopiowanych plików w katalogu docelowym, jeżeli operacja się powiodła

  3. Skopiuj plik pakietu (.nupkg)

    • Kierunek żądania: NuGet —> wtyczka
    • Żądanie będzie zawierać następujące elementy:
      • identyfikator i wersja pakietu
      • lokalizacja repozytorium źródłowego pakietu
      • ścieżka pliku docelowego
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji

  4. Pobieranie poświadczeń

    • Kierunek żądania: wtyczka —> NuGet
    • Żądanie będzie zawierać następujące elementy:
      • lokalizacja repozytorium źródłowego pakietu
      • kod stanu HTTP uzyskany z repozytorium źródłowego pakietu przy użyciu bieżących poświadczeń
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji
      • nazwa użytkownika, jeśli jest dostępna
      • hasło, jeśli jest dostępne

  5. Pobieranie plików w pakiecie

    • Kierunek żądania: wtyczka NuGet ->
    • Żądanie będzie zawierać następujące elementy:
      • identyfikator i wersja pakietu
      • lokalizacja repozytorium źródłowego pakietu
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji
      • kolekcja ścieżek plików w pakiecie, jeśli operacja zakończyła się pomyślnie

  6. Pobieranie roszczeń operacyjnych

    • Kierunek żądania: NuGet —> wtyczka
    • Żądanie będzie zawierać następujące elementy:
      • index.json usługa dla źródła pakietu
      • lokalizacja repozytorium źródłowego pakietu
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji
      • wyliczanie obsługiwanych operacji (np. pobieranie pakietów), jeśli operacja zakończyła się pomyślnie. Jeśli wtyczka nie obsługuje źródła pakietu, wtyczka musi zwrócić pusty zestaw obsługiwanych operacji.

Uwaga / Notatka

Ten komunikat został zaktualizowany w wersji 2.0.0. Do klienta należy zachowanie zgodności z poprzednimi wersjami.

  1. Pobierz skrót pakietu

    • Kierunek żądania: NuGet —> wtyczka
    • Żądanie będzie zawierać następujące elementy:
      • identyfikator i wersja pakietu
      • lokalizacja repozytorium źródłowego pakietu
      • algorytm skrótu
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji
      • skrót pliku pakietu utworzony za pomocą żądanego algorytmu skrótu, jeśli operacja zakończyła się pomyślnie

  2. Pobieranie wersji pakietów

    • Kierunek żądania: NuGet —> wtyczka
    • Żądanie będzie zawierać następujące elementy:
      • identyfikator pakietu
      • lokalizacja repozytorium źródłowego pakietu
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji
      • enumeracja wersji pakietów, jeśli operacja zakończyła się sukcesem

  3. Pobieranie indeksu usługi

    • Kierunek żądania: wtyczka —> NuGet
    • Żądanie będzie zawierać następujące elementy:
      • lokalizacja repozytorium źródłowego pakietu
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji
      • indeks usługi, jeśli operacja zakończyła się pomyślnie

  4. Uścisk dłoni

    • Kierunek żądania: NuGet <—> wtyczka
    • Żądanie będzie zawierać następujące elementy:
      • bieżąca wersja protokołu wtyczki
      • minimalna obsługiwana wersja protokołu wtyczki
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji
      • wynegocjowana wersja protokołu, jeśli operacja zakończyła się pomyślnie. Awaria spowoduje zakończenie wtyczki.

  5. Inicjalizacja

    • Kierunek żądania: NuGet —> wtyczka
    • Żądanie będzie zawierać następujące elementy:
      • wersja narzędzia klienckiego NuGet
      • efektywny język używany przez narzędzie klienta NuGet. Uwzględnia to ustawienie ForceEnglishOutput, jeśli jest używane.
      • domyślny limit czasu żądania, który zastępuje domyślny protokół.
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji. Awaria spowoduje zakończenie wtyczki.

  6. Rejestr

    • Kierunek żądania: wtyczka —> NuGet
    • Żądanie będzie zawierać następujące elementy:
      • Poziom logowania w przypadku żądania
      • komunikat do zalogowania
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji.

  7. Monitorowanie zakończenia procesu NuGet

    • Kierunek żądania: NuGet —> wtyczka
    • Żądanie będzie zawierać następujące elementy:
      • identyfikator procesu NuGet
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji.

  8. Pakiet wstępnego pobierania

    • Kierunek żądania: NuGet —> wtyczka
    • Żądanie będzie zawierać następujące elementy:
      • identyfikator i wersja pakietu
      • lokalizacja repozytorium źródłowego pakietu
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji

  9. Ustaw poświadczenia

    • Kierunek żądania: NuGet —> wtyczka
    • Żądanie będzie zawierać następujące elementy:
      • lokalizacja repozytorium źródłowego pakietu
      • ostatnia znana nazwa użytkownika źródła pakietu, jeśli jest dostępna
      • ostatnie znane hasło źródłowe pakietu, jeśli jest dostępne
      • ostatnia znana nazwa użytkownika serwera proxy, jeśli jest dostępna
      • ostatnie znane hasło serwera proxy, jeśli jest dostępne
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji

  10. Ustaw poziom dziennika

    • Kierunek żądania: wtyczka NuGet>
    • Żądanie będzie zawierać następujące elementy:
      • domyślny poziom dziennika
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji

Komunikaty protokołu w wersji 2.0.0

  1. Uzyskiwanie roszczeń dotyczących operacji

  • Prośba o wskazówki: NuGet -> wtyczka

    • Żądanie będzie zawierać następujące elementy:
      • usługa index.json dla źródła pakietu
      • lokalizacja repozytorium źródłowego pakietu
    • Odpowiedź będzie zawierać:
      • kod odpowiedzi wskazujący wynik operacji
      • wyliczenie obsługiwanych operacji, jeśli operacja zakończyła się pomyślnie. Jeśli wtyczka nie obsługuje źródła pakietu, wtyczka musi zwrócić pusty zestaw obsługiwanych operacji.

    Jeśli indeks usługi i źródło pakietu mają wartość null, wtyczka może odpowiedzieć przy użyciu uwierzytelniania.

  1. Uzyskiwanie poświadczeń uwierzytelniania
  • Kierunek żądania: NuGet —> wtyczka
  • Żądanie będzie zawierać następujące elementy:
    • Uri
    • isRetry
    • Nieinteraktywny
    • CanShowDialog
  • Odpowiedź będzie zawierać
    • Nazwa użytkownika
    • Hasło
    • Komunikat
    • Lista typów uwierzytelniania
    • KodOdpowiedziKomunikatu