NuGet keresztplatform beépülő modulok

A NuGet 4.8+-ban a platformfüggetlen beépülő modulok támogatása meg lett adva. Ez egy új beépülő modul bővíthetőségi modell létrehozásával érhető el, amelynek meg kell felelnie a szigorú működési szabályoknak. A beépülő modulok önálló végrehajthatók (futtathatók a .NET Core-világban), amelyeket a NuGet-ügyfelek külön folyamatban indítanak el. Ez egy valódi "egyszer megírni, mindenhol futtatni" típusú beépülő modul. Az összes NuGet-ügyféleszközzel működni fog. A beépülő modulok bármilyen programozási nyelven írhatók, de a legegyszerűbb beépülő modul fejlesztési és telepítési élménye a .NET lesz. A NuGet-ügyfél és a beépülő modul között egy verziószámozott kommunikációs protokoll van meghatározva. Az indítási kézfogás során a 2 folyamat egyezteti a protokoll verzióját.

Hogyan működik?

A magas szintű munkafolyamat a következőképpen írható le:

1. A NuGet felderíti az elérhető beépülő modulokat.
2. Ha alkalmazható, a NuGet prioritási sorrendben űzi át a beépülő modulokat, és egyenként indítja el őket.
3. A NuGet az első beépülő modult fogja használni, amely képes kiszolgálni a kérést.
4. A beépülő modulok leállnak, ha már nincs rájuk szükség.

Általános beépülő modulkövetelmények

Az aktuális protokollverzió a 2.0.0. Ebben a verzióban a követelmények a következők:

• Az állapot nélküli indítás támogatása a NuGet-ügyféleszközök jelenlegi biztonsági környezetében. A NuGet-ügyféleszközök például nem hajtanak végre emelési vagy további inicializálást a később ismertetett beépülő modulprotokollon kívül.
• Ne legyen interaktív, kivéve, ha kifejezetten meg van adva.
• Tartsa be a egyeztetett beépülő modulprotokoll-verziót.
• Válaszoljon minden kérésre ésszerű időn belül.
• A folyamatban lévő műveletekre vonatkozó lemondási kérelmek tiszteletbentartása.

A PATH környezeti változóból felderített beépülő moduloknak (például a dotnet tool-on keresztül telepítetteknek) további feltételként meg kell egyezniük a fájlnévmintával nuget-plugin-*. A nuget-plugin- részt teljes egészében kisbetűkbe kell írni.

A Windows rendszeren a NuGet 6.12 (MSBuild 17.12, és .NET SDK 9.0.100) és a korábbi verziókhoz Authenticode-aláírással rendelkező beépülő modulokra is szükség volt.

A műszaki specifikációt részletesebben a következő specifikációk ismertetik:

• NuGet-csomag letöltő beépülő modul
• NuGet többplatformos hitelesítési beépülő modul
• Dotnet Tools modulok

Ügyfél – Beépülő modul interakciója

A NuGet ügyféleszközök és a beépülő modulok szabványos streameken keresztül kommunikálnak a JSON-jal (stdin, stdout, stderr). Minden adatnak UTF-8 kódolásúnak kell lennie. A beépülő modulok a "-Plugin" argumentummal indulnak el. Abban az esetben, ha a felhasználó közvetlenül elindít egy végrehajtható beépülő modult ezen argumentum nélkül, a beépülő modul informatív üzenetet adhat ahelyett, hogy protokollos kézfogásra várna. A protokoll kézfogási időkorlátja 5 másodperc. A beépülő modulnak a lehető legrövidebb idő alatt végre kell hajtania a telepítést. A NuGet-ügyféleszközök lekérdezik egy beépülő modul támogatott műveleteit, a NuGet-forrás szolgáltatásindexének beadásával. A beépülő modul a szolgáltatásindex használatával ellenőrizheti a támogatott szolgáltatástípusok meglétét.

A NuGet-ügyféleszközök és a beépülő modul közötti kommunikáció kétirányú. Minden kérelem 5 másodperces időtúllépéssel rendelkezik. Ha a műveletek hosszabb időt vesznek igénybe, a megfelelő folyamatnak egy állapotüzenetet kell küldenie, amely megakadályozza, hogy a kérés túllépje az időkorlátot. 1 perc inaktivitás után a beépülő modul tétlennek minősül, és le van állítva.

Beépülő modul telepítése és felderítése

A NuGet konvencióalapú címtárstruktúrából keres beépülő modulokat, és vizsgálja meg a PATH környezeti változót.

Konvencióalapú felderítés

A CI-/CD-forgatókönyvek és az energiafelhasználók környezeti változókkal felülbírálhatják a viselkedést. Környezeti változók használatakor csak abszolút elérési utak engedélyezettek. Vegye figyelembe, hogy NUGET_NETFX_PLUGIN_PATHSNUGET_NETCORE_PLUGIN_PATHS csak a NuGet eszközkészlet 5.3+-os és újabb verziójával érhetők el.

• NUGET_NETFX_PLUGIN_PATHS - meghatározza azokat a beépülő modulokat, amelyeket a .NET-keretrendszer-alapú eszközök fognak használni (NuGet.exe/MSBuild.exe/Visual Studio). Elsőbbséget élvez a NUGET_PLUGIN_PATHS. (Csak a NuGet 5.3+-os verziója)
• NUGET_NETCORE_PLUGIN_PATHS - meghatározza azokat a beépülő modulokat, amelyeket a .NET Core-alapú eszközkészlet (dotnet.exe) fog használni. Elsőbbséget élvez a NUGET_PLUGIN_PATHS. (Csak a NuGet 5.3+-os verziója)
• NUGET_PLUGIN_PATHS - meghatározza azokat a beépülő modulokat, amelyek az adott NuGet-folyamathoz lesznek használva, prioritás megőrzve. Ha ez a környezeti változó be van állítva, az felülírja a konvencióalapú felderítést. Figyelmen kívül hagyja, ha valamelyik keretrendszer-specifikus változó meg van adva.
• Felhasználó helye, a NuGet kezdőlapja a következő helyen %UserProfile%/.nuget/plugins: . Ez a hely nem bírálható felül. A rendszer egy másik gyökérkönyvtárat használ a .NET Core és a .NET-keretrendszer beépülő moduljaihoz.

Keretrendszer	Gyökérfelderítés helye	Használta:
.NET Core	%UserProfile%/.nuget/plugins/netcore	dotnet parancssori felület
.NET-keretrendszer	%UserProfile%/.nuget/plugins/netfx	MSBuild, NuGet.exe, Visual Studio

Minden beépülő modult a saját mappájába kell telepíteni. A beépülő modul belépési pontja a telepített mappa neve lesz, a .NET Core .dll bővítményeivel és a .NET-keretrendszer .exe kiterjesztésével.

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

PATH-felderítés

A NuGet 6.13-tól kezdve a NuGet a PATH környezeti változóban megadott összes könyvtárban megkeresi a mintának nuget-plugin-*megfelelő fájlokat. A mintaegyeztetés megkülönbözteti a kis- és nagybetűket, és nuget-plugin- teljes egészében kisbetűkkel kell írni. Windows rendszeren a fájlnak .exe vagy .bat kiterjesztéssel kell rendelkeznie. Linux és Mac rendszeren a fájlnak rendelkeznie kell a végrehajtható bitkészlettel.

Ez lehetővé teszi a NuGet beépülő modulok telepítését dotnet tool parancsokkal, WinGet-sel, Linux-disztribúció csomagkezelőjével vagy bármely más olyan módszerrel, amely végrehajtható fájlokat helyezhet el a felhasználó PATH-ján. Ez azt is lehetővé teszi, hogy a NuGet beépülő modulok bármilyen programozási nyelven íródjanak (korábban Linux és Mac beépülő moduloknak .NET-ben kell írniuk).

Javasoljuk, hogy a beépülő modulokat .NET-ben fejlesszék, lehetővé téve a NuGet.Protocol csomag használatát, elkerülendő, hogy json RPC-kódot kelljen írni, és hogy az ügyfelek felfedezhessék a beépülő modult a dotnet package search nuget-plugin segítségével.

Támogatott műveletek

Az új beépülő modulprotokoll két műveletet támogat.

Művelet neve	Minimális protokollverzió	A NuGet-ügyfél minimális verziója
Csomag letöltése	1.0.0	4.3.0
hitelesítés	2.0.0	4.8.0

Beépülő modulok futtatása a megfelelő futtatókörnyezetben

A NuGet esetében dotnet.exe forgatókönyvekben a beépülő moduloknak képesnek kell lenniük a dotnet.exeadott futtatókörnyezetében végrehajtani. A bővítmény szolgáltatójának és a fogyasztónak gondoskodnia kell arról, hogy kompatibilis dotnet.exe/bővítmény kombinációt használjanak. Lehetséges probléma merülhet fel a felhasználói hely bővítményekkel, ha például egy dotnet.exe a 2.0-s futtatókörnyezetben a 2.1-re írt bővítményt próbál használni.

Képességek gyorsítótárazása

A beépülő modulok biztonsági ellenőrzése és példányosítása költséges. A letöltési művelet sokkal gyakrabban történik, mint a hitelesítési művelet, de az átlagos NuGet-felhasználó valószínűleg csak hitelesítési beépülő modult használ. A felhasználói élmény javítása érdekében a NuGet gyorsítótárazza az adott kéréshez tartozó műveleti jogcímeket. Ez a gyorsítótár beépülő modulonként van, ahol a beépülő modulkulcs a beépülő modul elérési útját jelenti, és a képességek gyorsítótára 30 nap után lejár.

A gyorsítótár a %LocalAppData%/NuGet/plugins-cache helyen található, és a NUGET_PLUGINS_CACHE_PATH környezeti változóval felülírható. A gyorsítótár törléséhez futtassa a locals parancsot a plugins-cache beállítással. A all helyi beállítások mostantól a beépülő modulok gyorsítótárát is törlik.

Protokollüzenetek listája

Protokoll 1.0.0-s verziójú üzenetek:

1. Bezárás

   • Kérés iránya: NuGet –> beépülő modul
   • A kérelem nem tartalmaz tartalmat.
   • Nem várható válasz. A megfelelő válasz az, hogy a beépülő modul folyamata azonnal kilép.

2. Fájlok másolása csomagban

   • Kérés iránya: NuGet –> beépülő modul
   • A kérelem a következőket tartalmazza:
     • a csomag azonosítója és verziója
     • a csomag forrásadattárának helye
     • célkönyvtár elérési útja
     • a csomagban található fájlok számba vehető száma, amelyek a célkönyvtár elérési útjára másolhatók
   • A válasz a következőket tartalmazza:
     • a művelet eredményét jelző válaszkód
     • a célkönyvtárban másolt fájlok teljes elérési útjainak számbavétele, ha a művelet sikeres volt

3. Csomagfájl másolása (.nupkg)

   • Kérés iránya: NuGet –> beépülő modul
   • A kérelem a következőket tartalmazza:
     • a csomag azonosítója és verziója
     • a csomag forrásadattárának helye
     • a célfájl elérési útja
   • A válasz a következőket tartalmazza:
     • a művelet eredményét jelző válaszkód

4. Hitelesítő adatok lekérése

   • Kérés iránya: beépülő modul –> NuGet
   • A kérelem a következőket tartalmazza:
     • a csomag forrásadattárának helye
     • a csomag forrásadattárából az aktuális hitelesítő adatokkal beszerzett HTTP-állapotkód
   • A válasz a következőket tartalmazza:
     • a művelet eredményét jelző válaszkód
     • felhasználónév, ha elérhető
     • jelszó, ha elérhető

5. Fájlok megszerzése csomagban

   • Kérés iránya: NuGet –> beépülő modul
   • A kérelem a következőket tartalmazza:
     • a csomag azonosítója és verziója
     • a csomag forrásadattárának helye
   • A válasz a következőket tartalmazza:
     • a művelet eredményét jelző válaszkód
     • a csomagban található fájlelérési utak számbavétele, ha a művelet sikeres volt

6. Műveleti jogcímek lekérése

   • Kérés iránya: NuGet –> beépülő modul
   • A kérelem a következőket tartalmazza:
     • a szolgáltatás index.json egy csomagforrás számára
     • a csomag forrásadattárának helye
   • A válasz a következőket tartalmazza:
     • a művelet eredményét jelző válaszkód
     • a támogatott műveletek számbavétele (például csomagletöltés), ha a művelet sikeres volt. Ha egy beépülő modul nem támogatja a csomag forrását, a beépülő modulnak üres támogatott műveleteket kell visszaadnia.

Megjegyzés:

Ez az üzenet a 2.0.0-s verzióban frissült. Az ügyfélen van, hogy megőrizze a visszamenőleges kompatibilitást.

7. Csomagkivonat lekérése

   • Kérés iránya: NuGet –> beépülő modul
   • A kérelem a következőket tartalmazza:
     • a csomag azonosítója és verziója
     • a csomag forrásadattárának helye
     • a kivonatoló algoritmus
   • A válasz a következőket tartalmazza:
     • a művelet eredményét jelző válaszkód
     • egy csomagfájl kivonata a kért kivonatoló algoritmus használatával, ha a művelet sikeres volt

8. Csomagverziók lekérése

   • Kérés iránya: NuGet –> beépülő modul
   • A kérelem a következőket tartalmazza:
     • a csomagazonosító
     • a csomag forrásadattárának helye
   • A válasz a következőket tartalmazza:
     • a művelet eredményét jelző válaszkód
     • a csomagverziók számbavétele, ha a művelet sikeres volt

9. Szolgáltatásindex lekérése

   • Kérés iránya: beépülő modul –> NuGet
   • A kérelem a következőket tartalmazza:
     • a csomag forrásadattárának helye
   • A válasz a következőket tartalmazza:
     • a művelet eredményét jelző válaszkód
     • a szolgáltatásindexet, ha a művelet sikeres volt

10. Kézfogás

    • Kérés iránya: NuGet <-> bővítmény
    • A kérelem a következőket tartalmazza:
      • a beépülő modul protokolljának aktuális verziója
      • a beépülő modulprotokoll minimális támogatott verziója
    • A válasz a következőket tartalmazza:
      • a művelet eredményét jelző válaszkód
      • a tárgyalásos protokoll verziója, ha a művelet sikeres volt. A hiba a beépülő modul leállítását eredményezi.

11. Inicializál

    • Kérés iránya: NuGet –> beépülő modul
    • A kérelem a következőket tartalmazza:
      • a NuGet-ügyféleszköz verziója
      • a NuGet ügyféleszköz hatékony nyelve. Ez figyelembe veszi a ForceEnglishOutput beállítást, ha használják.
      • az alapértelmezett kérés időtúllépése, amely meghaladja a protokoll alapértelmezett értékét.
    • A válasz a következőket tartalmazza:
      • a művelet eredményét jelző válaszkód. A hiba a beépülő modul leállítását eredményezi.

12. Rendszernapló

    • Kérés iránya: beépülő modul –> NuGet
    • A kérelem a következőket tartalmazza:
      • a kérés naplószintje
      • naplózni kívánt üzenet
    • A válasz a következőket tartalmazza:
      • a művelet eredményét jelző válaszkód.

13. NuGet-folyamat kilépésének figyelése

    • Kérés iránya: NuGet –> beépülő modul
    • A kérelem a következőket tartalmazza:
      • a NuGet folyamatazonosítója
    • A válasz a következőket tartalmazza:
      • a művelet eredményét jelző válaszkód.

14. Előletöltési csomag

    • Kérés iránya: NuGet –> beépülő modul
    • A kérelem a következőket tartalmazza:
      • a csomag azonosítója és verziója
      • a csomag forrásadattárának helye
    • A válasz a következőket tartalmazza:
      • a művelet eredményét jelző válaszkód

15. Hitelesítő adatok beállítása

    • Kérés iránya: NuGet –> beépülő modul
    • A kérelem a következőket tartalmazza:
      • a csomag forrásadattárának helye
      • az utolsó ismert csomagforrás felhasználóneve, ha elérhető
      • az utolsó ismert csomagforrás jelszava, ha elérhető
      • az utolsó ismert proxynév, ha elérhető
      • az utolsó ismert proxyjelszó, ha elérhető
    • A válasz a következőket tartalmazza:
      • a művelet eredményét jelző válaszkód

16. Naplószint beállítása

    • Kérés iránya: NuGet –> beépülő modul
    • A kérelem a következőket tartalmazza:
      • az alapértelmezett naplószint
    • A válasz a következőket tartalmazza:
      • a művelet eredményét jelző válaszkód

Verzió 2.0.0 protokollüzenetek

17. Műveleti jogcímek lekérése

• Kérés iránya: NuGet –> beépülő modul

  • A kérelem a következőket tartalmazza:
    • a szolgáltatás index.json egy csomagforrás számára
    • a csomag forrásadattárának helye
  • A válasz a következőket tartalmazza:
    • a művelet eredményét jelző válaszkód
    • a támogatott műveletek számbavétele, ha a művelet sikeres volt. Ha egy beépülő modul nem támogatja a csomag forrását, a beépülő modulnak üres támogatott műveleteket kell visszaadnia.

  Ha a szolgáltatásindex és a csomagforrás null értékű, akkor a beépülő modul hitelesítéssel válaszolhat.

18. Hitelesítési adatok lekérése

• Kérés iránya: NuGet –> beépülő modul
• A kérelem a következőket tartalmazza:
  • Úri
  • újraPróbálkozik
  • Neminteraktív
  • Meg tudja jeleníteni a párbeszédpanelt
• A válasz tartalmazza
  • Felhasználónév
  • Jelszó
  • Üzenet
  • Hitelesítési típusok listája
  • MessageResponseCode