Sdílet prostřednictvím

Moduly plug-in NuGet pro různé platformy

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ý plugin ve stylu "napsat jednou, spustit všude." Bude fungovat se všemi klientskými nástroji NuGet. Moduly plug-in lze psát v libovolném programovacím jazyce, ale nejjednodušší vývoj a instalační prostředí modulů plug-in bude s .NET. Je definován protokol komunikace se verzí mezi klientem NuGet a modulem plug-in. Během úvodního handshake vyjednávají dva procesy verzi protokolu.

Jak to funguje

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

  1. NuGet zjišťuje dostupné pluginy.
  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í:

  • 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 vyjednanou verzi protokolu zásuvného modulu.
  • 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.

Plug-iny zjištěné z proměnné prostředí PATH (například nainstalované prostřednictvím dotnet tool) navíc musí odpovídat názvu souboru vzoru nuget-plugin-*. Část nuget-plugin- musí být napsaná zcela malými písmeny.

NuGet 6.12 (MSBuild 17.12 a .NET SDK 9.0.100) a starší také vyžadovaly moduly plug-in, které mají být v systému Windows podepsané technologií Authenticode.

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 pluginu bez tohoto argumentu, může plugin poskytnout informační 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 mají operace trvat déle, měl by příslušný proces odeslat zprávu o průběhu, aby se zabránilo vypršení časového limitu požadavku. Po minutě nečinnosti je plugin považován za neaktivní a vypnutý.

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

NuGet vyhledává plug-iny podle adresářové struktury založené na konvencích a prohledává proměnnou prostředí PATH.

Zjišťování založené na konvencích

Scénáře CI/CD a pokročilí 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žívány 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žívány 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í nastavena, překonává objevování na základě konvence. Ignorováno, pokud je zadána kterákoliv z proměnných specifických pro architekturu.
  • Umístění uživatele, umístění NuGet Home v %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ář.
.NET Framework Umístění detekce rootu Používáno kým
.NET Core %UserProfile%/.nuget/plugins/netcore Rozhraní příkazového řádku dotnet
.NET Framework %UserProfile%/.nuget/plugins/netfx MSBuild, NuGet.exe, Visual Studio

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

Zjišťování PATH

Od NuGetu 6.13 Bude NuGet prohledávat každý adresář zadaný v proměnné prostředí PATH pro soubory odpovídající vzoru nuget-plugin-*. Porovnávání vzorů rozlišuje malá a velká písmena a nuget-plugin- musí být napsáno malými písmeny. Ve Windows musí mít soubor příponu .exe nebo .bat. V Linuxu a Macu musí mít soubor nastavenou bitovou sadu spustitelného souboru.

To umožňuje instalaci modulů plug-in NuGet prostřednictvím dotnet tool příkazů, WinGetu, správce balíčků distribuce Linuxu nebo jakékoli jiné metody, které můžou umístit spustitelné soubory do cesty uživatele. To také umožňuje psát moduly plug-in NuGet v libovolném programovacím jazyce (dříve moduly plug-in pro Linux a Mac musí být napsané v .NET).

Doporučujeme vyvíjet moduly plug-in v .NET, takže můžete použít balíček NuGet.Protocol , abyste se vyhnuli nutnosti psát kód JSON RPC a umožnit zákazníkům zjistit váš modul plug-in prostřednictvím dotnet package search nuget-plugin.

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
Autentizace 2.0.0 4.8.0

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

Pro NuGet ve dotnet.exe scénářích musí pluginy být schopné běžet pod specifickým runtime dotnet.exe. Je na poskytovateli pluginu a uživateli, aby bylo zajištěno, že se používá kompatibilní kombinace dotnet.exe/pluginu. Potenciální problém může nastat s pluginy pro umístění uživatelů, když se například dotnet.exe v prostředí runtime 2.0 pokusí použít plugin napsaný pro runtime 2.1.

Ukládání schopností 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ý plugin, přičemž klíč pluginu je jeho cesta, a vypršení platnosti této mezipaměti schopností je 30 dnů.

Mezipaměť je umístěna v %LocalAppData%/NuGet/plugins-cache a lze ji přepsat proměnnou prostředí NUGET_PLUGINS_CACHE_PATH. 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 dotazu: NuGet – plugin>
    • 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 dotazu: NuGet – plugin>
    • 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 dotazu: NuGet – plugin>
    • 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: plugin –> 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 dotazu: NuGet – plugin>
    • 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í nároků na operace

    • Směr dotazu: NuGet – plugin>
    • Požadavek bude obsahovat:
      • index.json služby pro zdroj zásilky
      • 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 dotazu: NuGet – plugin>
    • Požadavek bude obsahovat:
      • ID a verze balíčku
      • umístění zdrojového úložiště balíčku
      • hashovací algoritmus
    • 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 dotazu: NuGet – plugin>
    • 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: plugin –> 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. Podání ruky

    • 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
      • vyjednaná verze protokolu, pokud byla operace úspěšná. Selhání způsobí ukončení modulu plug-in.

  5. Inicializovat

    • Směr dotazu: NuGet – plugin>
    • 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. Záznam

    • Směr žádosti: plugin –> 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 dotazu: NuGet – plugin>
    • 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 dotazu: NuGet – plugin>
    • 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 dotazu: NuGet – plugin>
    • 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 dotazu: NuGet – plugin>
    • 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í nároků operací

  • Směr dotazu: NuGet – plugin>

    • Požadavek bude obsahovat:
      • index.json služby pro zdroj zásilky
      • 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 plugin odpovědět formou ověření.

  1. Získání přihlašovacích údajů pro ověřování
  • Směr dotazu: NuGet – plugin>
  • Požadavek bude obsahovat:
    • URI
    • isRetry
    • Neinteraktivní
    • CanShowDialog
  • Odpověď bude obsahovat
    • Uživatelské jméno
    • Heslo
    • Zpráva
    • Seznam typů autentizace
    • MessageResponseCode
  • Last updated on