Wtyczki międzyplatformowe NuGet

Artykuł
10/18/2023

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 prawdziwy zapis raz, uruchamiany wszędzie wtyczka. Będzie działać z wszystkimi narzędziami klienckimi NuGet. Wtyczki mogą być wtyczki .NET Framework (NuGet.exe, MSBuild.exe i Visual Studio) lub .NET Core (dotnet.exe). Zdefiniowany jest protokół komunikacji w wersji między klientem NuGet a wtyczką. Podczas uzgadniania uruchamiania 2 procesy negocjują wersję protokołu.

Aby uwzględnić wszystkie scenariusze narzędzi klienckich NuGet, potrzebne będą zarówno programy .NET Framework, jak i wtyczka platformy .NET Core. Poniżej opisano kombinacje wtyczki klienta/struktury.

Narzędzie klienckie	Framework
Visual Studio	.NET Framework
dotnet.exe	.NET Core
NuGet.exe	.NET Framework
Msbuild.exe	.NET Framework
NuGet.exe na platformie Mono	.NET Framework

Jak to działa?

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

Narzędzie NuGet odnajduje dostępne wtyczki.
Jeśli ma to zastosowanie, pakiet NuGet wykonuje iteracje nad wtyczkami w kolejności priorytetu i uruchamia je pojedynczo.
Narzędzie NuGet będzie używać pierwszej wtyczki, która może obsłużyć żądanie.
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:

Mieć prawidłowe, zaufane zestawy podpisów Authenticode, które będą uruchamiane w systemach Windows i Mono. Nie ma jeszcze specjalnego wymogu zaufania dla zestawów uruchamianych w systemach Linux i Mac. Odpowiedni problem
Obsługa bezstanowego uruchamiania w bieżącym kontekście 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.
Honoruj żądania anulowania dla każdej operacji w toku.

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 uzgadniania 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 powinny trwać dłużej, odpowiedni proces powinien wysłać komunikat o postępie, aby zapobiec upłynął limit czasu żądania. Po upływie 1 minuty braku aktywności wtyczka jest uważana za bezczynną i jest zamykana.

Instalacja i odnajdywanie wtyczki

Wtyczki zostaną odnalezione za pośrednictwem struktury katalogów opartej na konwencji. Scenariusze ciągłej integracji/ciągłego wdrażania i użytkownicy zasilania mogą użyć zmiennych środowiskowych, aby zastąpić zachowanie. W przypadku używania zmiennych środowiskowych dozwolone są tylko ścieżki bezwzględne. Należy pamiętać, że NUGET_NETFX_PLUGIN_PATHS narzędzia NuGet i NUGET_NETCORE_PLUGIN_PATHS są dostępne tylko w wersji 5.3 lub nowszej.

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 pakiet NuGet w wersji 5.3 lub nowszej)
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 pakiet NuGet w wersji 5.3 lub nowszej)
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 , lokalizacja główna Narzędzia NuGet w lokalizacji %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.

Framework	Lokalizacja odnajdywania głównego
.NET Core	`%UserProfile%/.nuget/plugins/netcore`
.NET Framework	`%UserProfile%/.nuget/plugins/netfx`

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

Uwaga

Obecnie nie ma scenariusza użytkownika dla instalacji wtyczek. Jest to tak proste, jak przeniesienie wymaganych plików do wstępnie określonej lokalizacji.

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
Authentication	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. Znajduje się on u dostawcy wtyczek i odbiorcy, aby upewnić się, że jest używana zgodna kombinacja dotnet.exe/wtyczki. Może wystąpić potencjalny problem 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 tworzenie wystąpień 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 ulepszyć środowisko pracy, narzędzie NuGet będzie buforować oświadczenia operacji dla danego żądania. Ta pamięć podręczna jest na wtyczkę z kluczem wtyczki jest ścieżką wtyczki, a wygaśnięcie tej pamięci podręcznej funkcji wynosi 30 dni.

Pamięć podręczna znajduje się w %LocalAppData%/NuGet/plugins-cache lokalizacji i jest zastępowana 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 :

Zamknij
- Kierunek żądania: NuGet —> wtyczka
- Żądanie nie będzie zawierać ładunku
- Nie oczekuje się odpowiedzi. Odpowiednia odpowiedź dotyczy procesu wtyczki, aby szybko zakończyć działanie.
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
  - wyliczanie plików w pakiecie do skopiowania do docelowej ścieżki katalogu
- Odpowiedź będzie zawierać:
  - kod odpowiedzi wskazujący wynik operacji
  - wyliczanie pełnych ścieżek dla skopiowanych plików w katalogu docelowym, jeśli operacja zakończyła się pomyślnie
Kopiowanie pliku 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
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
Pobieranie 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
- Odpowiedź będzie zawierać:
  - kod odpowiedzi wskazujący wynik operacji
  - wyliczanie ścieżek plików w pakiecie, jeśli operacja zakończyła się pomyślnie
Pobieranie oświadczeń operacji
- Kierunek żądania: NuGet —> wtyczka
- Żądanie będzie zawierać następujące elementy:
  - index.json usługi 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

Ten komunikat został zaktualizowany w wersji 2.0.0. Jest on na kliencie, aby zachować zgodność z poprzednimi wersjami.

Pobieranie skrótu 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 przy użyciu żądanego algorytmu skrótu, jeśli operacja zakończyła się pomyślnie
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
  - wyliczanie wersji pakietów, jeśli operacja zakończyła się pomyślnie
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
Uzgadniania
- 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.
Inicjowanie
- Kierunek żądania: NuGet —> wtyczka
- Żądanie będzie zawierać następujące elementy:
  - wersja narzędzia klienckiego NuGet
  - efektywny język narzędzia 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.
Dziennik
- Kierunek żądania: wtyczka —> NuGet
- Żądanie będzie zawierać następujące elementy:
  - poziom dziennika dla żądania
  - komunikat do zalogowania
- Odpowiedź będzie zawierać:
  - kod odpowiedzi wskazujący wynik operacji.
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.
Pakiet przed pobraniem
- 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
Ustawianie poświadczeń
- 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
Ustawianie poziomu dziennika
- Kierunek żądania: NuGet —> wtyczka
- Żą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

Uzyskiwanie oświadczeń operacji

Kierunek żądania: NuGet —> wtyczka
- Żądanie będzie zawierać następujące elementy:
  - index.json usługi 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, 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.

Uzyskiwanie poświadczeń uwierzytelniania

Kierunek żądania: NuGet —> wtyczka
Żądanie będzie zawierać następujące elementy:
- Identyfikator URI
- isRetry
- Nieinteraktywnych
- CanShowDialog
Odpowiedź będzie zawierać
- Username
- Hasło
- Komunikat
- Lista typów uwierzytelniania
- MessageResponseCode

Udostępnij za pośrednictwem