Plug-in di NuGet multipiattaforma

Articolo
02/22/2025

In NuGet 4.8+ è stato aggiunto il supporto per plug-in multipiattaforma. Ciò è stato ottenuto creando un nuovo modello di estendibilità del plug-in, che deve essere conforme a un set rigoroso di regole di funzionamento. I plugin sono applicazioni eseguibili autonome, chiamate eseguibili nel contesto di .NET Core, che i client NuGet lanciano in un processo separato. Questo è un plugin davvero scrivi una volta, eseguibile ovunque. Funzionerà con tutti gli strumenti client NuGet. I plug-in possono essere .NET Framework (NuGet.exe, MSBuild.exe e Visual Studio) o .NET Core (dotnet.exe). Viene definito un protocollo di comunicazione con controllo delle versioni tra il client NuGet e il plug-in. Durante la stretta di mano all'avvio, i due processi negoziano la versione del protocollo.

Per coprire tutti gli scenari degli strumenti client NuGet, è necessario un plug-in .NET Framework e un plug-in .NET Core. Di seguito vengono descritte le combinazioni client/framework dei plug-in.

Strumento client	Struttura
Visual Studio	.NET Framework
dotnet.exe	.NET Core
NuGet.exe	.NET Framework
MSBuild.exe	.NET Framework
NuGet.exe su Mono	.NET Framework

Come funziona

Il flusso di lavoro di alto livello può essere descritto come segue:

NuGet individua i plug-in disponibili.
Quando applicabile, NuGet eseguirà l'iterazione dei plug-in in ordine di priorità e li avvierà uno per uno.
NuGet userà il primo plug-in in in grado di eseguire la richiesta.
I plug-in verranno arrestati quando non sono più necessari.

Requisiti generali del plug-in

La versione corrente del protocollo è 2.0.0. In questa versione, i requisiti sono i seguenti:

Disporre di assembly con firma Authenticode valida e attendibile che possono essere eseguiti su Windows e Mono. Non esiste ancora un requisito di attendibilità speciale per gli assembly eseguiti in Linux e Mac. problema rilevante
Supportare l'avvio senza stato nel contesto di sicurezza corrente degli strumenti client NuGet. Ad esempio, gli strumenti client NuGet non eseguiranno l'elevazione dei privilegi o l'inizializzazione aggiuntiva all'esterno del protocollo del plug-in descritto più avanti.
Essere non interattivo, a meno che non sia specificato in modo esplicito.
Attenersi alla versione del protocollo del plug-in negoziata.
Rispondere a tutte le richieste entro un periodo di tempo ragionevole.
Rispettare le richieste di annullamento per qualsiasi operazione in corso.
A partire da NuGet 6.13, i plug-in eseguibili (inclusi gli strumenti .NET globali) devono soddisfare questi requisiti:
- Convenzione di denominazione: deve seguire il modello nuget-plugin-*.
- Windows:
  - Devono essere file .exe o .bat.
- Linux:
  - Devono avere i permessi di esecuzione abilitati.

La specifica tecnica è descritta in modo più dettagliato nelle specifiche seguenti:

Client - Interazione con plug-in

Gli strumenti client NuGet e i plug-in comunicano con JSON su flussi standard (stdin, stdout, stderr). Tutti i dati devono essere codificati con UTF-8. I plug-in vengono avviati con l'argomento "-Plugin". Nel caso in cui un utente avvii direttamente un eseguibile del plug-in senza questo argomento, il plug-in può mostrare un messaggio informativo invece di attendere un protocollo di handshake. Il timeout dell'handshake del protocollo è di 5 secondi. Il plug-in dovrebbe completare la configurazione nel minor tempo possibile. Gli strumenti client NuGet interrogheranno le operazioni supportate di un plug-in passando l'indice del servizio per una sorgente NuGet. Un plug-in può usare l'indice del servizio per verificare la presenza di tipi di servizio supportati.

La comunicazione tra gli strumenti client NuGet e il plug-in è bidirezionale. Ogni richiesta ha un timeout di 5 secondi. Se le operazioni devono richiedere più tempo, il rispettivo processo deve inviare un messaggio di stato per impedire il timeout della richiesta. Dopo 1 minuto di inattività, un plug-in viene considerato inattivo e viene arrestato.

Installazione e individuazione dei plug-in

I plug-in verranno individuati tramite una struttura di directory basata su convenzioni. Gli scenari CI/CD e gli utenti esperti possono usare le variabili di ambiente per eseguire l'override del comportamento. Quando si usano variabili di ambiente, sono consentiti solo percorsi assoluti. Si noti che NUGET_NETFX_PLUGIN_PATHS e NUGET_NETCORE_PLUGIN_PATHS sono disponibili solo con la versione 5.3+ degli strumenti NuGet e versioni successive.

NUGET_NETFX_PLUGIN_PATHS: definisce i plug-in che verranno usati dagli strumenti basati su .NET Framework (NuGet.exe/MSBuild.exe/Visual Studio). Ha la precedenza su NUGET_PLUGIN_PATHS. (solo NuGet versione 5.3+)
NUGET_NETCORE_PLUGIN_PATHS : definisce i plug-in che verranno usati dagli strumenti basati su .NET Core (dotnet.exe). Ha la precedenza su NUGET_PLUGIN_PATHS. (solo NuGet versione 5.3+)
NUGET_PLUGIN_PATHS
- definisce i plug-in che verranno usati per il processo NuGet, con priorità mantenuta. Se questa variabile di ambiente è impostata, sostituisce l'individuazione basata sulla convenzione. Ignorato se viene specificata una delle variabili specifiche del framework.
- a partire da NuGet 6.13:
  - Può specificare i percorsi dei file di plug-in eseguibili, inclusi i plug-in degli strumenti .NET.
  - Supporta sia i percorsi di file che le cartelle contenenti file plug-in.
  - Windows: supporta file di .exe e .bat.
  - Linux: richiede permessi di esecuzione (chmod +x).
Posizione utente, posizione della home page NuGet in %UserProfile%/.nuget/plugins. Impossibile eseguire l'override di questa posizione. Verrà utilizzata una diversa directory principale per i plug-in di .NET Core e .NET Framework.

Struttura	Posizione di individuazione della radice
.NET Core	`%UserProfile%/.nuget/plugins/netcore`
.NET Framework	`%UserProfile%/.nuget/plugins/netfx`

Ogni plug-in deve essere installato nella propria cartella. Il punto di ingresso del plug-in sarà il nome della cartella installata, con le estensioni .dll per .NET Core e l'estensione .exe per .NET Framework.

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

Nota

Attualmente non esiste alcuna storia utente per l'installazione dei plug-in. È semplice come spostare i file necessari nella posizione predeterminata.

Operazioni supportate

Nel nuovo protocollo plug-in sono supportate due operazioni.

Nome operazione	Versione minima del protocollo	Versione minima del client NuGet
Scaricare il pacchetto	1.0.0	4.3.0
Autenticazione	2.0.0	4.8.0

Esecuzione di plug-in nel runtime corretto

Per gli scenari NuGet in dotnet.exe, i plug-in devono essere in grado di essere eseguiti sotto quel runtime specifico di dotnet.exe. È responsabilità del provider del plug-in e del consumatore assicurarsi che venga utilizzata una combinazione compatibile di dotnet.exe/plug-in. Un potenziale problema potrebbe verificarsi con i plug-in di posizione utente quando, ad esempio, un dotnet.exe nel runtime 2.0 tenta di usare un plug-in scritto per il runtime 2.1.

Memorizzazione nella cache delle funzionalità

La verifica di sicurezza e la creazione di istanze dei plug-in è costosa. L'operazione di download avviene più frequentemente rispetto all'operazione di autenticazione, ma è probabile che l'utente NuGet medio abbia solo un plug-in di autenticazione. Per migliorare l'esperienza, NuGet memorizza nella cache le attestazioni dell'operazione per la richiesta specificata. Questa cache è per plug-in con la chiave del plug-in che rappresenta il percorso del plug-in e la scadenza per questa cache delle funzionalità è di 30 giorni.

La cache si trova in %LocalAppData%/NuGet/plugins-cache e può essere sovrascritta con la variabile di ambiente NUGET_PLUGINS_CACHE_PATH. Eseguire il comando locals con l'opzione plugins-cache per cancellare questa cache. L'opzione all variabili locali ora eliminerà anche la cache dei plug-in.

Indice dei messaggi del protocollo

Versione protocollo 1.0.0 messaggi:

Chiudi
- Direzione richiesta: NuGet - plugin>
- La richiesta non conterrà alcun payload
- Non è prevista alcuna risposta. La risposta corretta è che il processo di plug-in venga immediatamente chiuso.
Copiare i file nel pacchetto
- Direzione richiesta: NuGet - plug-in>
- La richiesta conterrà:
  - ID e versione del pacchetto
  - percorso del repository di origine del pacchetto
  - percorso della directory di destinazione
  - un elenco di file nel pacchetto da copiare nel percorso della directory di destinazione
- Una risposta conterrà:
  - un codice di risposta che indica il risultato dell'operazione
  - un elenco enumerabile di percorsi completi per i file copiati nella directory di destinazione se l'operazione riesce
Copiare il file del pacchetto (con estensione nupkg)
- Direzione richiesta: NuGet - plugin>
- La richiesta conterrà:
  - ID e versione del pacchetto
  - percorso del repository di origine del pacchetto
  - percorso del file di destinazione
- Una risposta conterrà:
  - un codice di risposta che indica il risultato dell'operazione
Ottenere le credenziali
- Direzione richiesta: plug-in -> NuGet
- La richiesta conterrà:
  - percorso del repository di origine del pacchetto
  - il codice di stato HTTP ottenuto dal repository di origine del pacchetto usando le credenziali correnti
- Una risposta conterrà:
  - un codice di risposta che indica il risultato dell'operazione
  - un nome utente, se disponibile
  - una password, se disponibile
Recuperare i file nel pacchetto
- Direzione richiesta: NuGet - plug-in>
- La richiesta conterrà:
  - ID e versione del pacchetto
  - percorso del repository di origine del pacchetto
- Una risposta conterrà:
  - un codice di risposta che indica il risultato dell'operazione
  - un enumerabile di percorsi dei file nel pacchetto se l'operazione ha avuto esito positivo
Ottenere le attestazioni dell'operazione
- Direzione richiesta: NuGet - plug-in>
- La richiesta conterrà:
  - il servizio index.json per una sorgente del pacchetto
  - percorso del repository di origine del pacchetto
- Una risposta conterrà:
  - un codice di risposta che indica il risultato dell'operazione
  - enumerabile di operazioni supportate (ad esempio: download di pacchetti) se l'operazione ha avuto esito positivo. Se un plug-in non supporta l'origine del pacchetto, il plug-in deve restituire un set vuoto di operazioni supportate.

Nota

Questo messaggio è stato aggiornato nella versione 2.0.0. Spetta al client mantenere la compatibilità con le versioni precedenti.

Ottenere l'hash del pacchetto
- Direzione richiesta: NuGet - plug-in>
- La richiesta conterrà:
  - ID e versione del pacchetto
  - percorso del repository di origine del pacchetto
  - algoritmo hash
- Una risposta conterrà:
  - un codice di risposta che indica il risultato dell'operazione
  - l'hash del file del pacchetto utilizzando l'algoritmo hash richiesto se l'operazione è riuscita
Ottenere le versioni dei pacchetti
- Richiesta di direzione: plug-in> di NuGet
- La richiesta conterrà:
  - l'ID del pacchetto
  - percorso del repository di origine del pacchetto
- Una risposta conterrà:
  - un codice di risposta che indica il risultato dell'operazione
  - un enumerabile di versioni di pacchetti nel caso in cui l'operazione abbia avuto esito positivo
Ottenere l'indice del servizio
- Direzione richiesta: plug-in -> NuGet
- La richiesta conterrà:
  - percorso del repository di origine del pacchetto
- Una risposta conterrà:
  - un codice di risposta che indica il risultato dell'operazione
  - indice del servizio se l'operazione ha avuto esito positivo
Stretta di mano
- Direzione richiesta: plugin NuGet <->
- La richiesta conterrà:
  - versione corrente del protocollo del plug-in
  - versione minima del protocollo di plug-in supportato
- Una risposta conterrà:
  - un codice di risposta che indica il risultato dell'operazione
  - versione del protocollo negoziata se l'operazione ha avuto esito positivo. Un errore comporterà la chiusura del plug-in.
Inizializzare
- Direzione richiesta: NuGet - plug-in>
- La richiesta conterrà:
  - Versione dello strumento client NuGet
  - il linguaggio efficace dello strumento client NuGet. Questa impostazione prende in considerazione l'impostazione ForceEnglishOutput, se usata.
  - timeout della richiesta predefinito, che sostituisce l'impostazione predefinita del protocollo.
- Una risposta conterrà:
  - codice di risposta che indica il risultato dell'operazione. Un errore comporterà la chiusura del plug-in.
Registro
- Direzione richiesta: plug-in -> NuGet
- La richiesta conterrà:
  - livello di registro per la richiesta
  - un messaggio da registrare
- Una risposta conterrà:
  - codice di risposta che indica il risultato dell'operazione.
Monitorare l'uscita del processo NuGet
- Direzione richiesta: NuGet - plug-in>
- La richiesta conterrà:
  - ID del processo NuGet
- Una risposta conterrà:
  - codice di risposta che indica il risultato dell'operazione.
Pacchetto di prelettura
- Direzione richiesta: NuGet - plugin>
- La richiesta conterrà:
  - ID e versione del pacchetto
  - percorso del repository di origine del pacchetto
- Una risposta conterrà:
  - un codice di risposta che indica il risultato dell'operazione
Impostare le credenziali
- Direzione richiesta: NuGet - plug-in>
- La richiesta conterrà:
  - percorso del repository di origine del pacchetto
  - l'ultimo nome utente dell'origine del pacchetto noto, se disponibile
  - l'ultima password di origine del pacchetto nota, se disponibile
  - l'ultimo nome utente proxy noto, se disponibile
  - l'ultima password proxy nota, se disponibile
- Una risposta conterrà:
  - un codice di risposta che indica il risultato dell'operazione
Impostare il livello di log
- Direzione richiesta: NuGet - plug-in>
- La richiesta conterrà:
  - livello di log predefinito
- Una risposta conterrà:
  - un codice di risposta che indica il risultato dell'operazione

Messaggi del protocollo versione 2.0.0

Ottenere attestazioni dell'operazione

Direzione richiesta: NuGet - plug-in>
- La richiesta conterrà:
  - il servizio index.json per una fonte del pacchetto
  - percorso del repository di origine del pacchetto
- Una risposta conterrà:
  - un codice di risposta che indica il risultato dell'operazione
  - un elenco di operazioni supportate se l'operazione ha avuto esito positivo. Se un plug-in non supporta l'origine del pacchetto, il plug-in deve restituire un set vuoto di operazioni supportate.
Se l'indice del servizio e l'origine del pacchetto sono Null, il plug-in può rispondere con l'autenticazione.

Ottenere le credenziali di autenticazione

Direzione richiesta: NuGet - plugin>
La richiesta conterrà:
- Uri
- isRetry
- Non Interattivo
- PuòMostrareDialogo
Una risposta conterrà
- Nome utente
- Parola d’ordine
- Messaggio
- Elenco dei tipi di autenticazione
- MessageResponseCode

Condividi tramite