Plattformsoberoende insticksprogram för NuGet

2025-10-31

I NuGet 4.8+ har stöd för plattformsoberoende plugin-program lagts till. Detta uppnåddes med genom att skapa en ny utökningsmodell för plugin-program, som måste följa en strikt uppsättning regler för drift. Plugin-program är fristående körbara filer (runnables i .NET Core-världen), som NuGet-klienterna startar i en separat process. Detta är ett äkta skriv en gång, körs överallt insticksprogram. Det fungerar med alla NuGet-klientverktyg. Plugin-programmen kan skrivas på valfritt programmeringsspråk, men det enklaste plugin-programmets utveckling och installation är med .NET. Ett versionsprotokoll för kommunikation mellan NuGet-klienten och plugin-programmet definieras. Under handskakningen för start förhandlar de två processerna om protokollversionen.

Hur fungerar det

Arbetsflödet på hög nivå kan beskrivas på följande sätt:

NuGet identifierar tillgängliga plugin-program.
När det är tillämpligt itererar NuGet över plugin-program i prioritetsordning och startar dem en i taget.
NuGet använder det första plugin-programmet som kan hantera begäran.
Plugin-program stängs av när de inte längre behövs.

Allmänna krav för plugin-program

Den aktuella protokollversionen är 2.0.0. I den här versionen är kraven följande:

Stöder tillståndslös start under den aktuella säkerhetskontexten för NuGet-klientverktygen. NuGet-klientverktyg utför till exempel inte utökade eller ytterligare initieringar utanför plugin-protokollet som beskrivs senare.
Vara icke-interaktiv, såvida inte uttryckligen anges.
Följ den förhandlade versionen av plugin-protokollet.
Svara på alla begäranden inom en rimlig tidsperiod.
Respektera annulleringsbegäranden för pågående åtgärder.

Plugin-program som identifieras från PATH-miljövariabeln (till exempel installerade via dotnet tool) måste dessutom matcha filnamnsmönstret nuget-plugin-*. Den del av nuget-plugin- måste skrivas helt med små bokstäver.

NuGet 6.12 (MSBuild 17.12 och .NET SDK 9.0.100) och tidigare krävde också att plugin-program var Authenticode-signerade i Windows.

Den tekniska specifikationen beskrivs mer detaljerat i följande specifikationer:

Klient – Interaktion med plugin-program

NuGet-klientverktyg och plugin-program kommunicerar med JSON via standardströmmar (stdin, stdout, stderr). Alla data måste vara UTF-8-kodade. Plugin-program startas med argumentet "-Plugin". Om en användare direkt startar ett körbart plugin-program utan det här argumentet kan pluginen ge ett informativt meddelande i stället för att vänta på ett protokollhandslag. Tidsgränsen för protokollhandskakning är 5 sekunder. Plugin-programmet bör slutföra installationen på så kort tid som möjligt. NuGet-klientverktyg kommer att fråga om vilka operationer som stöds av ett plugin-program genom att överföra tjänstindexet för en NuGet-källa. Ett plugin-program kan använda tjänstindexet för att kontrollera om det finns tjänsttyper som stöds.

Kommunikationen mellan NuGet-klientverktygen och plugin-programmet är dubbelriktad. Varje begäran har en tidsgräns på 5 sekunder. Om åtgärderna ska ta längre tid bör respektive process skicka ut ett förloppsmeddelande för att förhindra att begäran överskrider tidsgränsen. Efter 1 minuts inaktivitet anses ett plugin-program vara inaktivt och stängs av.

Installation och identifiering av plugin-program

NuGet söker efter plugin-program från en konventionsbaserad katalogstruktur och söker igenom PATH-miljövariabeln.

Konventionsbaserad upptäckning

CI/CD-scenarier och energianvändare kan använda miljövariabler för att åsidosätta beteendet. När du använder miljövariabler tillåts endast absoluta sökvägar. Observera att NUGET_NETFX_PLUGIN_PATHS och NUGET_NETCORE_PLUGIN_PATHS endast är tillgängliga med 5,3+ version av NuGet-verktyget och senare.

NUGET_NETFX_PLUGIN_PATHS – definierar de plugin-program som ska användas av .NET Framework-baserade verktyg (NuGet.exe/MSBuild.exe/Visual Studio). Har företräde framför NUGET_PLUGIN_PATHS. (Endast version 5.3 av NuGet+)
NUGET_NETCORE_PLUGIN_PATHS – definierar de plugin-program som ska användas av .NET Core-baserade verktyg (dotnet.exe). Har företräde framför NUGET_PLUGIN_PATHS. (Endast version 5.3 av NuGet+)
NUGET_PLUGIN_PATHS – definierar de plugin-program som ska användas för den NuGet-processen, prioritet bevarad. Om den här miljövariabeln anges åsidosätter den konventionsbaserade identifieringen. Ignoreras om någon av de ramverksspecifika variablerna har angetts.
Användarplats, NuGet-hemplatsen i %UserProfile%/.nuget/plugins. Den här platsen kan inte åsidosättas. En annan rotkatalog används för .NET Core- och .NET Framework-plugin-program.

Ramverk	Plats för rotupptäckning	Används av
.NET Core	`%UserProfile%/.nuget/plugins/netcore`	dotnet CLI
.NET Framework	`%UserProfile%/.nuget/plugins/netfx`	MSBuild, NuGet.exe, Visual Studio

Varje plugin-program bör installeras i en egen mapp. Startpunkten för plugin-programmet är namnet på den installerade mappen, med .dll tillägg för .NET Core och .exe-tillägget för .NET Framework.

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

PATH-upptäckning

Från och med NuGet 6.13 söker NuGet i varje katalog i PATH-miljövariabeln efter filer som matchar mönstret nuget-plugin-*. Mönsterjämförelsen är skiftlägeskänslig och nuget-plugin- måste skrivas helt med små bokstäver. På Windows måste filen ha ett .exe- eller .bat-tillägg. På Linux och Mac måste filen ha den körbara bituppsättningen.

Detta gör att NuGet-plugin-program kan installeras via dotnet tool kommandon, WinGet, en Linux-distributions pakethanterare eller någon annan metod som kan placera körbara filer på användarens PATH. Detta gör också att NuGet-plugin-program kan skrivas på valfritt programmeringsspråk (tidigare måste plugin-program för Linux och Mac skrivas i .NET).

Vi rekommenderar att plugin-program har utvecklats i .NET, så att du kan använda NuGet.Protocol-paketet för att undvika att behöva skriva json RPC-koden och låta kunderna identifiera plugin-programmet via dotnet package search nuget-plugin.

Åtgärder som stöds

Två åtgärder stöds under det nya plugin-protokollet.

Operationsnamn	Lägsta protokollversion	Lägsta NuGet-klientversion
Ladda ned paket	1.0.0	4.3.0
autentisering	2.0.0	4.8.0

Köra tillägg under rätt körmiljö

För NuGet i dotnet.exe-scenarier måste plugin-program kunna köras under den specifika körmiljön av dotnet.exe. Det är upp till pluginleverantören och konsumenten att se till att en kompatibel dotnet.exe/plugin-kombination används. Ett potentiellt problem kan uppstå med användarlokaliseringsplugin när till exempel en dotnet.exe under 2.0 runtime-miljön försöker använda ett plugin skrivet för 2.1 runtime-miljön.

Cachelagring av kapaciteter

Säkerhetsverifieringen och instansieringen av plugin-program är kostsam. Nedladdningsåtgärden sker mycket oftare än autentiseringsåtgärden, men den genomsnittliga NuGet-användaren har sannolikt bara ett plugin-program för autentisering. För att förbättra upplevelsen cachelagrar NuGet åtgärdsanspråken för den angivna begäran. Den här cachen är per insticksprogram där insticksprogrammets nyckel är insticksprogrammets sökväg, och utgångstiden för denna cache för funktioner är 30 dagar.

Cachen finns i %LocalAppData%/NuGet/plugins-cache och åsidosätts med miljövariabeln NUGET_PLUGINS_CACHE_PATH. Om du vill rensa cacheminnet kan du köra kommandot locals med alternativet plugins-cache . Alternativet all locals tar nu också bort plugin-cachen.

Index för protokollmeddelanden

Protokollversion 1.0.0 meddelanden:

Stänga
- Begäranderiktning: NuGet –> plugin-program
- Begäran innehåller ingen nyttolast
- Inget svar förväntas. Rätt svar är att plugin-processen omedelbart avslutas.
Kopiera filer i paketet
- Begäranderiktning: NuGet –> plugin-program
- Begäran innehåller:
  - paket-ID och version
  - paketkällans depåplats
  - målkatalogsökväg
  - en lista över filer i paketet som ska kopieras till sökvägen för målkatalogen
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden
  - en uppräkning av fullständiga sökvägar för kopierade filer i målkatalogen om åtgärden lyckades
Kopiera paketfil (.nupkg)
- Begäranderiktning: NuGet –> plugin-program
- Begäran innehåller:
  - paket-ID och version
  - paketkällans depåplats
  - målfilens sökväg
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden
Hämta autentiseringsuppgifter
- Begäran om riktning: plugin -> NuGet
- Begäran innehåller:
  - paketkällans depåplats
  - HTTP-statuskoden som hämtas från paketkällans lagringsplats med aktuella autentiseringsuppgifter
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden
  - ett användarnamn, om det är tillgängligt
  - ett lösenord, om det är tillgängligt
Hämta filer i paket
- Begäranderiktning: NuGet –> plugin-program
- Begäran innehåller:
  - paket-ID och version
  - paketkällans depåplats
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden
  - en lista över filsökvägar inom paketet om åtgärden lyckades
Hämta åtgärdsanspråk
- Begäranderiktning: NuGet –> plugin-program
- Begäran innehåller:
  - tjänsten index.json för en paketkälla
  - paketkällans depåplats
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden
  - en uppräkning av åtgärder som stöds (t.ex. paketnedladdning) om åtgärden lyckades. Om ett plugin-program inte stöder paketkällan måste plugin-programmet returnera en tom uppsättning av stödda åtgärder.

Anmärkning

Det här meddelandet har uppdaterats i version 2.0.0. Det är klientens ansvar att bevara bakåtkompatibilitet.

Hämta pakethash
- Begäranderiktning: NuGet –> plugin-program
- Begäran innehåller:
  - paket-ID och version
  - paketkällans depåplats
  - hash-algoritmen
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden
  - en paketfilshash med den begärda hash-algoritmen om åtgärden lyckades
Hämta paketversioner
- Begäranderiktning: NuGet –> plugin-program
- Begäran innehåller:
  - paket-ID
  - paketkällans depåplats
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden
  - en uppräkning av paketversioner om åtgärden lyckades
Hämta tjänstindex
- Begäran om riktning: plugin -> NuGet
- Begäran innehåller:
  - paketkällans depåplats
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden
  - tjänstindexet när åtgärden är lyckad
Handskakning
- Begäranderiktning: NuGet <–> plugin-program
- Begäran innehåller:
  - den aktuella versionen av plugin-protokollet
  - den lägsta version av plugin-protokollet som stöds
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden
  - den förhandlade versionen av protokollet om åtgärden lyckades. Ett fel resulterar i att plugin-programmet avslutas.
Initialisera
- Begäranderiktning: NuGet –> plugin-program
- Begäran innehåller:
  - NuGet-klientverktygets version
  - NuGet-klientverktygets effektiva språk. Detta tar hänsyn till inställningen ForceEnglishOutput, om den används.
  - den förvalda tidsgränsen för begäran, som ersätter protokollstandardvärdet.
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden. Ett fel resulterar i att plugin-programmet avslutas.
Logg
- Begäran om riktning: plugin -> NuGet
- Begäran innehåller:
  - loggnivån för begäran
  - ett meddelande som ska loggas
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden.
Övervaka NuGet-processavslut
- Begäranderiktning: NuGet –> plugin-program
- Begäran innehåller:
  - NuGet-process-ID
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden.
Prefetch-paket
- Begäranderiktning: NuGet –> plugin-program
- Begäran innehåller:
  - paket-ID och version
  - paketkällans depåplats
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden
Ange autentiseringsuppgifter
- Begäranderiktning: NuGet –> plugin-program
- Begäran innehåller:
  - paketkällans depåplats
  - det senast kända användarnamnet för paketkällan, om det är tillgängligt
  - det senast kända paketkällans lösenord, om det är tillgängligt
  - det senast kända proxyanvändarnamnet, om det är tillgängligt
  - det senast kända proxylösenordet, om det är tillgängligt
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden
Ange loggnivå
- Begäranderiktning: NuGet –> plugin-program
- Begäran innehåller:
  - förvald loggnivå
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden

Protokollversion 2.0.0-meddelanden

Hämta operationella krav

Begäranderiktning: NuGet –> plugin-program
- Begäran innehåller:
  - tjänsten index.json för en paketkälla
  - paketkällans depåplats
- Ett svar innehåller:
  - en svarskod som anger resultatet av åtgärden
  - en uppräkning av åtgärder som stöds om åtgärden lyckades. Om ett plugin-program inte stöder paketkällan måste plugin-programmet returnera en tom uppsättning av stödda åtgärder.
Om tjänstindexet och paketkällan är null kan plugin-programmet svara med autentisering.

Hämta autentiseringsuppgifter

Begäranderiktning: NuGet –> plugin-program
Begäran innehåller:
- Uri
- isRetry
- IckeInteraktiv
- CanShowDialog
Ett svar kommer att innehålla
- Användarnamn
- Lösenord
- Meddelande
- Lista över autentiseringstyper
- MeddelandeSvarskod

Feedback

Var den här sidan till hjälp?