Platformoverschrijdende invoegtoepassingen van NuGet

In NuGet 4.8+ ondersteuning voor platformoverschrijdende invoegtoepassingen is toegevoegd. Dit is bereikt met het bouwen van een nieuw uitbreidingsmodel voor invoegtoepassingen, dat moet voldoen aan een strikte set operationele regels. De invoegtoepassingen zijn zelfstandige uitvoerbare bestanden (runnables in de wereld van .NET Core) die de NuGet-clients in een afzonderlijk proces starten. Dit is een echte "write once, run everywhere" plug-in. Het werkt met alle NuGet-clienthulpprogramma's. De invoegtoepassingen kunnen in elke programmeertaal worden geschreven, maar de eenvoudigste ontwikkel- en installatie-ervaring van de invoegtoepassing is met .NET. Er wordt een versie van het communicatieprotocol tussen de NuGet-client en de invoegtoepassing gedefinieerd. Tijdens de opstarthanddruk onderhandelen de 2 processen over de protocolversie.

Hoe werkt het?

De werkstroom op hoog niveau kan als volgt worden beschreven:

1. NuGet detecteert beschikbare invoegtoepassingen.
2. Indien van toepassing, zal NuGet de invoegtoepassingen in volgorde van prioriteit herhalen en één voor één starten.
3. NuGet gebruikt de eerste invoegtoepassing die de aanvraag kan verwerken.
4. De invoegtoepassingen worden afgesloten wanneer ze niet meer nodig zijn.

Algemene vereisten voor invoegtoepassingen

De huidige protocolversie is 2.0.0. Onder deze versie zijn de vereisten als volgt:

• Ondersteuning voor het stateless lanceren onder de huidige beveiligingsinstelling van NuGet-clienthulpprogramma's. NuGet-hulpprogramma's voeren bijvoorbeeld geen verhoging of extra initialisatie uit buiten het later beschreven protocol.
• Wees niet interactief, tenzij expliciet opgegeven.
• Voldoen aan de onderhandelingen over de protocolversie van de invoegtoepassing.
• Reageer binnen een redelijke periode op alle aanvragen.
• Honoreren annuleringsaanvragen voor elke lopende bewerking.

Invoegtoepassingen die zijn gedetecteerd uit de omgevingsvariabele PATH (bijvoorbeeld geïnstalleerd via dotnet tool) moeten ook overeenkomen met het bestandsnaampatroon nuget-plugin-*. Het nuget-plugin- onderdeel moet volledig in kleine letters worden geschreven.

NuGet 6.12 (MSBuild 17.12 en .NET SDK 9.0.100) en eerder vereist ook dat invoegtoepassingen Authenticode zijn ondertekend in Windows.

De technische specificatie wordt gedetailleerder beschreven in de volgende specificaties:

• NuGet Package Download-plug-in
• NuGet-platformoverschrijdende authenticatieplug-in
• Invoegtoepassingen voor Dotnet Tools

Client - Interactie tussen invoegtoepassingen

NuGet-clienthulpprogramma's en de invoegtoepassingen communiceren met JSON via standaardstreams (stdin, stdout, stderr). Alle gegevens moeten UTF-8 gecodeerd zijn. De invoegtoepassingen worden gestart met het argument '-Plugin'. Als een gebruiker een uitvoerbare invoegtoepassing rechtstreeks start zonder dit argument, kan de invoegtoepassing een informatief bericht geven in plaats van te wachten op een protocolhanddruk. De time-out voor de protocolhanddruk is 5 seconden. De invoegtoepassing moet de installatie zo kort mogelijk voltooien. NuGet-clienthulpprogramma's voeren een query uit op de ondersteunde bewerkingen van een invoegtoepassing door de serviceindex voor een NuGet-bron door te geven. Een invoegtoepassing kan de serviceindex gebruiken om te controleren op de aanwezigheid van ondersteunde servicetypen.

De communicatie tussen de NuGet-clienthulpprogramma's en de invoegtoepassing is bidirectioneel. Elke aanvraag heeft een time-out van 5 seconden. Als bewerkingen langer moeten duren, moet het betreffende proces een voortgangsbericht verzenden om te voorkomen dat de aanvraag een time-out krijgt. Na 1 minuut inactiviteit wordt een plug-in beschouwd als niet-actief en wordt afgesloten.

Installatie en ontdekking van invoegtoepassingen

NuGet zoekt naar invoegtoepassingen van een op conventie gebaseerde mapstructuur en scant de omgevingsvariabele PATH.

Detectie op basis van conventies

CI/CD-scenario's en energiegebruikers kunnen omgevingsvariabelen gebruiken om het gedrag te overschrijven. Wanneer u omgevingsvariabelen gebruikt, zijn alleen absolute paden toegestaan. Houd er rekening mee dat NUGET_NETFX_PLUGIN_PATHS en NUGET_NETCORE_PLUGIN_PATHS alleen beschikbaar zijn met 5.3+ versie van de NuGet-hulpprogramma's en hoger.

• NUGET_NETFX_PLUGIN_PATHS - definieert de invoegtoepassingen die worden gebruikt door de .NET Framework-hulpprogramma's (NuGet.exe/MSBuild.exe/Visual Studio). Heeft voorrang op NUGET_PLUGIN_PATHS. (Alleen NuGet versie 5.3+
• NUGET_NETCORE_PLUGIN_PATHS - definieert de invoegtoepassingen die worden gebruikt door de op .NET Core gebaseerde hulpprogramma's (dotnet.exe). Heeft voorrang op NUGET_PLUGIN_PATHS. (Alleen NuGet versie 5.3+
• NUGET_PLUGIN_PATHS - definieert de invoegtoepassingen die worden gebruikt voor dat NuGet-proces, prioriteit behouden. Als deze omgevingsvariabele is ingesteld, wordt de detectie op basis van conventies overschreven. Genegeerd als een van de frameworkspecifieke variabelen is opgegeven.
• Gebruikerslocatie: de NuGet Home-locatie in %UserProfile%/.nuget/plugins. Deze locatie kan niet worden overschreven. Er wordt een andere hoofdmap gebruikt voor .NET Core- en .NET Framework-invoegtoepassingen.

Elke invoegtoepassing moet in een eigen map worden geïnstalleerd. Het ingangspunt van de invoegtoepassing is de naam van de geïnstalleerde map, met de .dll-extensies voor .NET Core en .exe-extensie voor .NET Framework.

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

PATH-detectie

Vanaf NuGet 6.13 zoekt NuGet in elke map in de omgevingsvariabele PATH naar bestanden die overeenkomen met het patroon nuget-plugin-*. De patroonkoppeling is hoofdlettergevoelig en nuget-plugin- moet volledig in kleine letters worden geschreven. In Windows moet het bestand een .exe of .bat extensie hebben. Op Linux en Mac moet het bestand de uitvoerbare bitset hebben.

Hierdoor kunnen NuGet-invoegtoepassingen worden geïnstalleerd via dotnet tool opdrachten, WinGet, pakketbeheer van een Linux-distributie of een andere methode die uitvoerbare bestanden op het PAD van de gebruiker kan plaatsen. Hierdoor kunnen NuGet-invoegtoepassingen ook worden geschreven in elke programmeertaal (voorheen plug-ins voor Linux en Mac moeten worden geschreven in .NET).

We raden invoegtoepassingen aan die zijn ontwikkeld in .NET, zodat u het NuGet.Protocol-pakket kunt gebruiken om te voorkomen dat u de json RPC-code hoeft te schrijven en om klanten in staat te stellen uw invoegtoepassing te detecteren via dotnet package search nuget-plugin.

Ondersteunde bewerkingen

Er worden twee bewerkingen ondersteund onder het nieuwe protocol van de invoegtoepassing.

Invoegtoepassingen uitvoeren onder de juiste runtime

Voor de NuGet in dotnet.exe scenario's moeten invoegtoepassingen kunnen worden uitgevoerd onder die specifieke runtime van de dotnet.exe. Het is de verantwoordelijkheid van de provider van de plugin en de consument om ervoor te zorgen dat een compatibele combinatie van dotnet.exe/ plugin wordt gebruikt. Er kan een mogelijk probleem optreden met de invoegtoepassingen van de gebruikerslocatie wanneer bijvoorbeeld een dotnet.exe onder de runtime 2.0 probeert een invoegtoepassing te gebruiken die is geschreven voor de runtime 2.1.

Mogelijkheden in cache opslaan

De beveiligingsverificatie en instantiëring van de invoegtoepassingen zijn kostbaar. De downloadbewerking vindt veel vaker plaats dan de verificatiebewerking, maar de gemiddelde NuGet-gebruiker heeft waarschijnlijk alleen een verificatieinvoegtoepassing. Om de ervaring te verbeteren, slaat NuGet de bewerkingsclaims voor de opgegeven aanvraag in de cache op. Deze cache is per invoegtoepassing, waarbij de sleutel van de invoegtoepassing het pad van de invoegtoepassing is. De vervaldatum voor deze mogelijkheden-cache is 30 dagen.

De cache bevindt zich in %LocalAppData%/NuGet/plugins-cache en wordt overschreven met de omgevingsvariabele NUGET_PLUGINS_CACHE_PATH. Om deze cache te wissen, kunt u de locals-opdracht uitvoeren met de plugins-cache optie. De all locals-optie zal nu ook de plugins cache verwijderen.

Protocolberichtenindex

Protocolversie 1.0.0: berichten

1. Sluiten

   • Aanvraagrichting: NuGet -> invoegtoepassing
   • De aanvraag bevat geen inhoud
   • Er wordt geen antwoord verwacht. Het juiste antwoord is dat het invoegtoepassingsproces onmiddellijk wordt afgesloten.

2. Bestanden in pakket kopiëren

   • Aanvraagrichting: NuGet -> invoegtoepassing
   • De aanvraag bevat:
     • de pakket-ID en versie
     • de locatie van de bronopslagplaats van het pakket
     • pad naar doelmap
     • een opsomming van bestanden in het pakket die moeten worden gekopieerd naar de doelmap
   • Een antwoord bevat:
     • een antwoordcode die het resultaat van de bewerking aangeeft
     • een opsomming van volledige paden voor gekopieerde bestanden in de doelmap als de bewerking is geslaagd

3. Pakketbestand kopiëren (.nupkg)

   • Aanvraagrichting: NuGet -> invoegtoepassing
   • De aanvraag bevat:
     • de pakket-ID en versie
     • de locatie van de bronopslagplaats van het pakket
     • het pad naar het doelbestand
   • Een antwoord bevat:
     • een antwoordcode die het resultaat van de bewerking aangeeft

4. Referenties ophalen

   • Aanvraagrichting: invoegtoepassing -> NuGet
   • De aanvraag bevat:
     • de locatie van de bronopslagplaats van het pakket
     • de HTTP-statuscode die is verkregen uit de pakketbronrepository met behulp van de huidige inloggegevens
   • Een antwoord bevat:
     • een antwoordcode die het resultaat van de bewerking aangeeft
     • een gebruikersnaam, indien beschikbaar
     • een wachtwoord, indien beschikbaar

5. Bestanden in pakket ophalen

   • Aanvraagrichting: NuGet -> invoegtoepassing
   • De aanvraag bevat:
     • de pakket-ID en versie
     • de locatie van de bronopslagplaats van het pakket
   • Een antwoord bevat:
     • een antwoordcode die het resultaat van de bewerking aangeeft
     • een opsomming van bestandspaden in het pakket als de bewerking is geslaagd

6. Operatieclaims ophalen

   • Aanvraagrichting: NuGet -> invoegtoepassing
   • De aanvraag bevat:
     • de service index.json voor een pakketbron
     • de locatie van de bronopslagplaats van het pakket
   • Een antwoord bevat:
     • een antwoordcode die het resultaat van de bewerking aangeeft
     • een opsomming van ondersteunde bewerkingen (bijvoorbeeld pakketdownload) als de bewerking is geslaagd. Als een invoegtoepassing de pakketbron niet ondersteunt, moet de invoegtoepassing een lege set ondersteunde bewerkingen retourneren.

7. Pakket-hash ophalen

   • Aanvraagrichting: NuGet -> invoegtoepassing
   • De aanvraag bevat:
     • de pakket-ID en versie
     • de locatie van de bronopslagplaats van het pakket
     • het hash-algoritme
   • Een antwoord bevat:
     • een antwoordcode die het resultaat van de bewerking aangeeft
     • een pakketbestandshash met behulp van het aangevraagde hash-algoritme als de bewerking is geslaagd

8. Pakketversies ophalen

   • Aanvraagrichting: NuGet -> invoegtoepassing
   • De aanvraag bevat:
     • de pakket-ID
     • de locatie van de bronopslagplaats van het pakket
   • Een antwoord bevat:
     • een antwoordcode die het resultaat van de bewerking aangeeft
     • een opsomming van pakketversies als de bewerking is geslaagd

9. Service-index ophalen

   • Aanvraagrichting: invoegtoepassing -> NuGet
   • De aanvraag bevat:
     • de locatie van de bronopslagplaats van het pakket
   • Een antwoord bevat:
     • een antwoordcode die het resultaat van de bewerking aangeeft
     • de serviceindex als de bewerking is geslaagd

10. Handdruk

    • Aanvraagrichting: NuGet <-> invoegtoepassing
    • De aanvraag bevat:
      • de huidige protocolversie van de invoegtoepassing
      • de minimaal ondersteunde versie van het invoegtoepassingsprotocol
    • Een antwoord bevat:
      • een antwoordcode die het resultaat van de bewerking aangeeft
      • de onderhandelde protocolversie indien de bewerking is geslaagd. Een fout leidt tot beëindiging van de invoegtoepassing.

11. Initialiseren

    • Aanvraagrichting: NuGet -> invoegtoepassing
    • De aanvraag bevat:
      • de versie van het NuGet-clienthulpprogramma
      • de effectieve taal van het NuGet-clienthulpprogramma. Hierbij wordt rekening gehouden met de forceEnglishOutput-instelling, indien gebruikt.
      • de standaard time-out voor aanvragen, die de standaardwaarde van het protocol vervangt.
    • Een antwoord bevat:
      • een antwoordcode die het resultaat van de bewerking aangeeft. Een fout leidt tot beëindiging van de invoegtoepassing.

12. Logbestand

    • Aanvraagrichting: invoegtoepassing -> NuGet
    • De aanvraag bevat:
      • het logniveau voor de aanvraag
      • een bericht om vast te leggen
    • Een antwoord bevat:
      • een antwoordcode die het resultaat van de bewerking aangeeft.

13. Bewaak de beëindiging van het NuGet-proces

    • Aanvraagrichting: NuGet -> invoegtoepassing
    • De aanvraag bevat:
      • de NuGet-proces-id
    • Een antwoord bevat:
      • een antwoordcode die het resultaat van de bewerking aangeeft.

14. Prefetch-pakket

    • Aanvraagrichting: NuGet -> invoegtoepassing
    • De aanvraag bevat:
      • de pakket-ID en versie
      • de locatie van de bronopslagplaats van het pakket
    • Een antwoord bevat:
      • een antwoordcode die het resultaat van de bewerking aangeeft

15. Inloggegevens instellen

    • Aanvraagrichting: NuGet -> invoegtoepassing
    • De aanvraag bevat:
      • de locatie van de bronopslagplaats van het pakket
      • de laatst bekende gebruikersnaam van de pakketbron, indien beschikbaar
      • het laatst bekende pakketbronwachtwoord, indien beschikbaar
      • de laatst bekende proxygebruikersnaam, indien beschikbaar
      • het laatst bekende proxywachtwoord, indien beschikbaar
    • Een antwoord bevat:
      • een antwoordcode die het resultaat van de bewerking aangeeft

16. Logboekniveau instellen

    • Aanvraagrichting: NuGet -> invoegtoepassing
    • De aanvraag bevat:
      • het standaardlogboekniveau
    • Een antwoord bevat:
      • een antwoordcode die het resultaat van de bewerking aangeeft

Protocolversie 2.0.0 berichten

17. Operationele claims ophalen

• Aanvraagrichting: NuGet -> invoegtoepassing

  • De aanvraag bevat:
    • de service index.json voor een pakketbron
    • de locatie van de bronopslagplaats van het pakket
  • Een antwoord bevat:
    • een antwoordcode die het resultaat van de bewerking aangeeft
    • een opsomming van ondersteunde bewerkingen als de bewerking is geslaagd. Als een invoegtoepassing de pakketbron niet ondersteunt, moet de invoegtoepassing een lege set ondersteunde bewerkingen retourneren.

  Als de serviceindex en pakketbron null zijn, kan de invoegtoepassing antwoorden met verificatie.

18. Verificatiereferenties ophalen

• Aanvraagrichting: NuGet -> invoegtoepassing
• De aanvraag bevat:
  • Uri
  • isRetry
  • Niet-interactief
  • CanShowDialog
• Een antwoord zal bevatten
  • Gebruikersnaam
  • Wachtwoord
  • Bericht
  • Lijst met verificatietypen
  • MessageResponseCode