Sdílet prostřednictvím

Moduly plug-in NuGet pro různé platformy

  • Článek

V nuGetu 4.8+ byla přidána podpora modulů plug-in pro různé platformy. Toho bylo dosaženo vytvořením nového modelu rozšiřitelnosti modulů plug-in, který musí odpovídat striktní sadě pravidel provozu. Moduly plug-in jsou samostatné spustitelné soubory (spustitelné ve světě .NET Core), které klienti NuGet spouští v samostatném procesu. Jedná se o skutečný zápis jednou, spusťte všude plugin. Bude fungovat se všemi klientskými nástroji NuGet. Moduly plug-in můžou být .NET Framework (NuGet.exe, MSBuild.exe a Visual Studio) nebo .NET Core (dotnet.exe). Je definován protokol komunikace se verzí mezi klientem NuGet a modulem plug-in. Během spouštění metody handshake vyjednávají verze protokolu 2.

Aby bylo možné pokrýt všechny scénáře klientských nástrojů NuGet, potřebovali byste rozhraní .NET Framework i modul plug-in .NET Core. Níže jsou popsány kombinace modulů plug-in klienta/architektury.

Klientský nástroj Framework
Visual Studio .NET Framework
dotnet.exe .NET Core
NuGet.exe .NET Framework
MSBuild.exe .NET Framework
NuGet.exe na Mono .NET Framework

Jak to funguje

Pracovní postup vysoké úrovně lze popsat takto:

  1. NuGet zjišťuje dostupné moduly plug-in.
  2. Pokud je to možné, NuGet iteruje moduly plug-in v pořadí priority a spustí je po jednom.
  3. NuGet použije první modul plug-in, který může žádost obsluhovat.
  4. Moduly plug-in budou vypnuté, když už nejsou potřeba.

Obecné požadavky na modul plug-in

Aktuální verze protokolu je 2.0.0. V této verzi jsou požadavky následující:

  • Mají platná důvěryhodná sestavení podpisů Authenticode, která budou spuštěna ve Windows a Mono. Pro sestavení spuštěná v Linuxu a Macu ještě neexistuje žádný zvláštní požadavek na vztah důvěryhodnosti. Relevantní problém
  • Podpora bezstavového spouštění v aktuálním kontextu zabezpečení klientských nástrojů NuGet Například klientské nástroje NuGet nebudou provádět zvýšení oprávnění ani další inicializaci mimo protokol modulu plug-in popsaný později.
  • Buďte neinteraktivní, pokud není explicitně zadáno.
  • Dodržujte verzi protokolu vyjednaných modulů plug-in.
  • Zareagujte na všechny žádosti v přiměřeném časovém období.
  • Respektujte žádosti o zrušení pro všechny probíhající operace.

Technická specifikace je podrobněji popsána v následujících specifikacích:

Klient – Interakce modulu plug-in

Klientské nástroje NuGet a moduly plug-in komunikují s JSON přes standardní streamy (stdin, stdout, stderr). Všechna data musí mít kódování UTF-8. Moduly plug-in se spustí s argumentem -Plugin. V případě, že uživatel přímo spustí spustitelný soubor plug-in bez tohoto argumentu, může modul plug-in poskytnout informativní zprávu místo čekání na handshake protokolu. Časový limit handshake protokolu je 5 sekund. Modul plug-in by měl dokončit nastavení co nejkratším způsobem. Klientské nástroje NuGet se dotazují na podporované operace modulu plug-in předáním indexu služby pro zdroj NuGet. Modul plug-in může použít index služby ke kontrole přítomnosti podporovaných typů služeb.

Komunikace mezi klientskými nástroji NuGet a modulem plug-in je obousměrná. Každý požadavek má časový limit 5 sekund. Pokud by operace měly trvat déle, měl by příslušný proces odeslat zprávu o průběhu, aby se zabránilo časového limitu požadavku. Po 1 minutě nečinnosti se modul plug-in považuje za nečinný a vypne se.

Instalace a zjišťování modulů plug-in

Moduly plug-in budou zjištěny prostřednictvím konvence založené na adresářové struktuře. Scénáře CI/CD a výkonní uživatelé můžou k přepsání chování použít proměnné prostředí. Při použití proměnných prostředí jsou povoleny pouze absolutní cesty. Mějte na paměti, že NUGET_NETFX_PLUGIN_PATHS a NUGET_NETCORE_PLUGIN_PATHS jsou k dispozici pouze s verzí 5.3 nebo novějšími nástroji NuGet.

  • NUGET_NETFX_PLUGIN_PATHS – definuje moduly plug-in, které budou použity nástroji založenými na rozhraní .NET Framework (NuGet.exe/MSBuild.exe/Visual Studio). Má přednost před NUGET_PLUGIN_PATHS. (Pouze NuGet verze 5.3 nebo novější)
  • NUGET_NETCORE_PLUGIN_PATHS – definuje moduly plug-in, které budou použity nástroji založenými na .NET Core (dotnet.exe). Má přednost před NUGET_PLUGIN_PATHS. (Pouze NuGet verze 5.3 nebo novější)
  • NUGET_PLUGIN_PATHS – definuje moduly plug-in, které se použijí pro daný proces NuGet, priorita se zachová. Pokud je tato proměnná prostředí nastavená, přepíše zjišťování na základě konvence. Ignorováno, pokud je zadána kterákoliv z proměnných specifických pro architekturu.
  • User-location, the NuGet Home location in %UserProfile%/.nuget/plugins. Toto umístění nelze přepsat. Pro moduly plug-in .NET Core a .NET Framework se použije jiný kořenový adresář.
Framework Umístění kořenového zjišťování
.NET Core %UserProfile%/.nuget/plugins/netcore
.NET Framework %UserProfile%/.nuget/plugins/netfx

Každý modul plug-in by měl být nainstalovaný ve své vlastní složce. Vstupním bodem modulu plug-in bude název nainstalované složky s rozšířeními .dll pro .NET Core a .exe rozšíření pro rozhraní .NET Framework.

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

Poznámka:

V současné době neexistuje žádný uživatelský příběh pro instalaci modulů plug-in. Přesunutí požadovaných souborů do předem určeného umístění je jednoduché.

Podporované operace

V rámci nového protokolu modulu plug-in se podporují dvě operace.

Název operace Minimální verze protokolu Minimální verze klienta NuGet
Stáhnout balíček 1.0.0 4.3.0
Authentication 2.0.0 4.8.0

Spouštění modulů plug-in ve správném modulu runtime

Pro NuGet ve dotnet.exe scénářích musí být moduly plug-in schopné spouštět v rámci tohoto konkrétního modulu runtime dotnet.exe. Je na poskytovateli modulu plug-in a spotřebiteli, aby se zajistilo, že se používá kompatibilní kombinace dotnet.exe/pluginu. Potenciální problém může nastat s moduly plug-in umístění uživatele, když se například dotnet.exe pod modulem runtime 2.0 pokusí použít modul plug-in napsaný pro modul runtime 2.1.

Ukládání funkcí do mezipaměti

Ověření zabezpečení a vytvoření instance modulů plug-in je nákladné. Operace stahování se provádí častěji než ověřovací operace, ale průměrný uživatel NuGet má pravděpodobně pouze ověřovací modul plug-in. Aby se prostředí zlepšilo, NuGet uloží deklarace operací pro danou žádost do mezipaměti. Tato mezipaměť je pro každý modul plug-in s klíčem modulu plug-in cestou a vypršení platnosti této mezipaměti schopností je 30 dnů.

Mezipaměť je umístěna a %LocalAppData%/NuGet/plugins-cache přepsána proměnnou NUGET_PLUGINS_CACHE_PATHprostředí . Pokud chcete tuto mezipaměť vymazat, můžete spustit příkaz locals s plugins-cache možností. Možnost all locals teď také odstraní mezipaměť modulů plug-in.

Index zpráv protokolu

Zprávy protokolu verze 1.0.0 :

  1. Zavřít

    • Směr žádosti: NuGet – modul plug-in>
    • Požadavek nebude obsahovat žádnou datovou část.
    • Neočekává se žádná odpověď. Správná odpověď je, aby se proces plug-inu okamžitě ukončil.

  2. Kopírování souborů v balíčku

    • Směr žádosti: NuGet – modul plug-in>
    • Požadavek bude obsahovat:
      • ID a verze balíčku
      • umístění zdrojového úložiště balíčku
      • cílová cesta k adresáři
      • výčet souborů v balíčku, které se mají zkopírovat do cesty k cílovému adresáři
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace
      • Výčet úplných cest pro zkopírované soubory v cílovém adresáři, pokud byla operace úspěšná

  3. Kopírování souboru balíčku (.nupkg)

    • Směr žádosti: NuGet – modul plug-in>
    • Požadavek bude obsahovat:
      • ID a verze balíčku
      • umístění zdrojového úložiště balíčku
      • cesta k cílovému souboru
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace

  4. Získání přihlašovacích údajů

    • Směr žádosti: modul plug-in –> NuGet
    • Požadavek bude obsahovat:
      • umístění zdrojového úložiště balíčku
      • stavový kód HTTP získaný ze zdrojového úložiště balíčku pomocí aktuálních přihlašovacích údajů
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace
      • uživatelské jméno, pokud je k dispozici
      • heslo, pokud je k dispozici

  5. Získání souborů v balíčku

    • Směr žádosti: NuGet – modul plug-in>
    • Požadavek bude obsahovat:
      • ID a verze balíčku
      • umístění zdrojového úložiště balíčku
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace
      • Výčet cest k souborům v balíčku, pokud byla operace úspěšná

  6. Získání deklarací identity operací

    • Směr žádosti: NuGet – modul plug-in>
    • Požadavek bude obsahovat:
      • index.json služby pro zdroj balíčku
      • umístění zdrojového úložiště balíčku
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace
      • výčet podporovaných operací (např. stažení balíčku), pokud byla operace úspěšná. Pokud modul plug-in nepodporuje zdroj balíčků, modul plug-in musí vrátit prázdnou sadu podporovaných operací.

Poznámka:

Tato zpráva byla aktualizována ve verzi 2.0.0. Je na klientovi, aby se zachovala zpětná kompatibilita.

  1. Získání hodnoty hash balíčku

    • Směr žádosti: NuGet – modul plug-in>
    • Požadavek bude obsahovat:
      • ID a verze balíčku
      • umístění zdrojového úložiště balíčku
      • algoritmus hash
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace
      • hodnota hash souboru balíčku pomocí požadovaného hash algoritmu, pokud operace proběhla úspěšně

  2. Získání verzí balíčků

    • Směr žádosti: NuGet – modul plug-in>
    • Požadavek bude obsahovat:
      • ID balíčku
      • umístění zdrojového úložiště balíčku
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace
      • výčet verzí balíčku, pokud byla operace úspěšná

  3. Získání indexu služby

    • Směr žádosti: modul plug-in –> NuGet
    • Požadavek bude obsahovat:
      • umístění zdrojového úložiště balíčku
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace
      • index služby, pokud operace proběhla úspěšně

  4. Handshake

    • Směr žádosti: NuGet <– modul plug-in>
    • Požadavek bude obsahovat:
      • aktuální verze protokolu modulu plug-in
      • minimální podporovaná verze protokolu plug-in
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace
      • pokud byla operace úspěšná, vyjednaná verze protokolu. Selhání způsobí ukončení modulu plug-in.

  5. Inicializace

    • Směr žádosti: NuGet – modul plug-in>
    • Požadavek bude obsahovat:
      • verze klientského nástroje NuGet
      • efektivní jazyk klientského nástroje NuGet. To bere v úvahu nastavení ForceEnglishOutput, pokud se používá.
      • výchozí časový limit požadavku, který nahrazuje výchozí protokol.
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace. Selhání způsobí ukončení modulu plug-in.

  6. Protokol

    • Směr žádosti: modul plug-in –> NuGet
    • Požadavek bude obsahovat:
      • úroveň protokolu pro požadavek
      • zpráva, která se má protokolovat
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace.

  7. Monitorování ukončení procesu NuGet

    • Směr žádosti: NuGet – modul plug-in>
    • Požadavek bude obsahovat:
      • ID procesu NuGet
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace.

  8. Předběžné načtení balíčku

    • Směr žádosti: NuGet – modul plug-in>
    • Požadavek bude obsahovat:
      • ID a verze balíčku
      • umístění zdrojového úložiště balíčku
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace

  9. Nastavení přihlašovacích údajů

    • Směr žádosti: NuGet – modul plug-in>
    • Požadavek bude obsahovat:
      • umístění zdrojového úložiště balíčku
      • poslední známé zdrojové uživatelské jméno balíčku, pokud je k dispozici
      • poslední známé heslo ke zdroji balíčku, pokud je k dispozici
      • poslední známé uživatelské jméno proxy serveru, pokud je k dispozici
      • poslední známé heslo proxy serveru, pokud je k dispozici
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace

  10. Nastavení úrovně protokolu

    • Směr žádosti: NuGet – modul plug-in>
    • Požadavek bude obsahovat:
      • výchozí úroveň protokolu
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace

Zprávy protokolu verze 2.0.0

  1. Získání deklarací identity operací

  • Směr žádosti: NuGet – modul plug-in>

    • Požadavek bude obsahovat:
      • index.json služby pro zdroj balíčku
      • umístění zdrojového úložiště balíčku
    • Odpověď bude obsahovat:
      • kód odpovědi označující výsledek operace
      • výčet podporovaných operací, pokud byla operace úspěšná. Pokud modul plug-in nepodporuje zdroj balíčků, modul plug-in musí vrátit prázdnou sadu podporovaných operací.

    Pokud má index služby a zdroj balíčku hodnotu null, může modul plug-in odpovědět s ověřováním.

  1. Získání přihlašovacích údajů pro ověřování
  • Směr žádosti: NuGet – modul plug-in>
  • Požadavek bude obsahovat:
    • Identifikátor URI
    • isRetry
    • Neinteraktivní
    • CanShowDialog
  • Odpověď bude obsahovat
    • Username
    • Heslo
    • Zpráva
    • Seznam typů ověřování
    • MessageResponseCode