Plug-in di NuGet multipiattaforma
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
.
- Devono essere file
- Linux:
- Devono avere i permessi di esecuzione abilitati.
- Convenzione di denominazione: deve seguire il modello
La specifica tecnica è descritta in modo più dettagliato nelle specifiche seguenti:
- Plug-in NuGet per il download dei pacchetti
- Plug-in di autenticazione cross-platform di NuGet
- Plugin degli strumenti .NET
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 suNUGET_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 suNUGET_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.
- La richiesta conterrà:
- 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