Plug-ins multiplateformes NuGet

Article
02/22/2025

La prise en charge des plug-ins multiplateformes a été ajoutée dans NuGet 4.8 et versions ultérieures. Cela a été réalisé avec la création d’un nouveau modèle d’extensibilité de plug-in, qui doit se conformer à un ensemble strict de règles d’opération. Les plug-ins sont des exécutables autonomes (exécutables dans le monde .NET Core), que les clients NuGet lancent dans un processus distinct. Il s’agit d’un plug-in qui, une fois écrit, fonctionne partout. Il fonctionne avec tous les outils clients NuGet. Les plug-ins peuvent être .NET Framework (NuGet.exe, MSBuild.exe et Visual Studio) ou .NET Core (dotnet.exe). Un protocole de communication avec version entre le client NuGet et le plug-in est défini. Lors de la poignée de main au démarrage, les 2 processus négocient la version du protocole.

Pour couvrir tous les scénarios d’outils clients NuGet, il faudrait à la fois un .NET Framework et un plug-in .NET Core. La section ci-dessous décrit les combinaisons client/framework des plug-ins.

Outil client	Cadre
Visual Studio	.NET Framework
dotnet.exe	.NET Core
NuGet.exe	.NET Framework
MSBuild.exe	.NET Framework
NuGet.exe sur Mono	.NET Framework

Comment fonctionne-t-il ?

Le flux de travail de haut niveau peut être décrit comme suit :

NuGet découvre les plug-ins disponibles.
Le cas échéant, NuGet effectue une itération sur les plug-ins dans l’ordre de priorité et les démarre un par un.
NuGet utilise le premier plug-in qui peut traiter la requête.
Les plug-ins seront arrêtés lorsqu’ils ne sont plus nécessaires.

Exigences générales du plug-in

La version actuelle du protocole est 2.0.0. Dans cette version, les exigences sont les suivantes :

Disposez d’assemblys de signature Authenticode valides et approuvés qui s’exécuteront sur Windows et Mono. Il n’existe pas encore de conditions d’approbation particulières pour les assemblys exécutés sur Linux et Mac. problème pertinent
Soutenir le lancement sans état dans le contexte de sécurité actuel des outils client de NuGet. Par exemple, les outils clients NuGet n’effectuent pas d’élévation ou d’initialisation supplémentaire en dehors du protocole de plug-in décrit ultérieurement.
Ne pas être interactif, sauf indication explicite.
Respectez la version négociée du protocole de plug-in.
Répondez à toutes les demandes dans un délai raisonnable.
Honorez les demandes d’annulation pour toute opération en cours.
À partir de NuGet 6.13, les plug-ins exécutables (y compris les outils .NET globaux) doivent respecter les exigences suivantes :
- Convention d’affectation de noms : doit suivre le modèle nuget-plugin-*.
- Windows:
  - Doivent être des fichiers .exe ou .bat.
- Linux:
  - Les permissions d'exécution doivent être activées.

La spécification technique est décrite plus en détail dans les spécifications suivantes :

Client - Interaction du plug-in

Les outils clients NuGet et les plug-ins communiquent avec JSON sur des flux standard (stdin, stdout, stderr). Toutes les données doivent être encodées en UTF-8. Les plug-ins sont lancés avec l’argument « -Plugin ». Si un utilisateur lance directement un exécutable de plug-in sans cet argument, le plug-in peut donner un message informatif au lieu d’attendre une négociation de protocole. Le délai d’expiration du handshake protocolaire est de 5 secondes. Le plug-in doit terminer la configuration aussi vite que possible. Les outils clients NuGet interrogent les opérations prises en charge par un plug-in en passant l’index de service pour une source NuGet. Un plug-in peut utiliser l’index de service pour vérifier la présence des types de service pris en charge.

La communication entre les outils clients NuGet et le plug-in est bidirectionnelle. Chaque requête a un délai d’expiration de 5 secondes. Si les opérations sont censées prendre plus de temps, le processus respectif doit envoyer un message de progression pour empêcher la demande d’expirer. Après 1 minute d’inactivité, un plug-in est considéré comme inactif et est arrêté.

Installation et découverte du plug-in

Les plug-ins seront découverts via une structure de répertoires basée sur une convention. Les scénarios CI/CD et les utilisateurs avancés peuvent utiliser des variables d’environnement pour modifier le comportement. Lorsque vous utilisez des variables d’environnement, seuls les chemins absolus sont autorisés. Notez que NUGET_NETFX_PLUGIN_PATHS et NUGET_NETCORE_PLUGIN_PATHS sont disponibles uniquement avec la version 5.3+ des outils NuGet et versions ultérieures.

NUGET_NETFX_PLUGIN_PATHS : définit les plug-ins qui seront utilisés par les outils .NET Framework (NuGet.exe/MSBuild.exe/Visual Studio). Est prioritaire sur NUGET_PLUGIN_PATHS. (NuGet version 5.3+ uniquement)
NUGET_NETCORE_PLUGIN_PATHS : définit les plug-ins qui seront utilisés par les outils .NET Core (dotnet.exe). Est prioritaire sur NUGET_PLUGIN_PATHS. (NuGet version 5.3+ uniquement)
NUGET_PLUGIN_PATHS
- définit les plug-ins qui seront utilisés pour ce processus NuGet, priorité conservée. Si cette variable d’environnement est définie, elle remplace la découverte basée sur la convention. Ignoré si l’une des variables spécifiques à l’infrastructure est spécifiée.
- à partir de NuGet 6.13 :
  - Peut spécifier des chemins d’accès aux fichiers de plug-in exécutables, y compris les plug-ins d’outils .NET.
  - Prend en charge les chemins d’accès et les dossiers de fichiers contenant des fichiers de plug-in.
  - Windows : prend en charge les fichiers .exe et .bat.
  - Linux : nécessite des autorisations exécutables (chmod +x).
Emplacement utilisateur, emplacement principal de NuGet dans %UserProfile%/.nuget/plugins. Cet emplacement ne peut pas être substitué. Un autre répertoire racine sera utilisé pour les plug-ins .NET Core et .NET Framework.

Cadre	Emplacement de découverte de la racine
.NET Core	`%UserProfile%/.nuget/plugins/netcore`
.NET Framework	`%UserProfile%/.nuget/plugins/netfx`

Chaque plug-in doit être installé dans son propre dossier. Le point d’entrée du plug-in sera le nom du dossier installé, avec les extensions .dll pour .NET Core et .exe extension pour .NET Framework.

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

Note

Il n’existe actuellement aucun article utilisateur pour l’installation des plug-ins. Il est aussi simple que de déplacer les fichiers requis vers l’emplacement prédéterminé.

Opérations prises en charge

Deux opérations sont prises en charge sous le nouveau protocole de plug-in.

Nom de l’opération	Version minimale du protocole	Version minimale du client NuGet
Télécharger le package	1.0.0	4.3.0
d’authentification	2.0.0	4.8.0

Exécution de plug-ins sous le runtime correct

Pour les scénarios NuGet dans dotnet.exe scénarios, les plug-ins doivent être en mesure d’exécuter sous ce runtime spécifique du dotnet.exe. Il incombe au fournisseur du plug-in et au consommateur de s'assurer qu'une combinaison compatible de dotnet.exe/plug-in est utilisée. Un problème potentiel peut survenir avec les plug-ins d’emplacement utilisateur quand, par exemple, une dotnet.exe sous le runtime 2.0 tente d’utiliser un plug-in écrit pour le runtime 2.1.

Mise en cache des fonctionnalités

La vérification de la sécurité et l’instanciation des plug-ins sont coûteuses. L’opération de téléchargement se produit plus fréquemment que l’opération d’authentification, mais l’utilisateur NuGet moyen est susceptible d’avoir un plug-in d’authentification. Pour améliorer l’expérience, NuGet met en cache les revendications d’opération pour la demande donnée. Ce cache est par plug-in avec la clé de plug-in étant le chemin du plug-in, et l’expiration de ce cache de fonctionnalités est de 30 jours.

Le cache se trouve dans %LocalAppData%/NuGet/plugins-cache et doit être substitué par la variable d’environnement NUGET_PLUGINS_CACHE_PATH. Pour effacer cette de cache, vous pouvez exécuter la commande locale avec l’option plugins-cache. L’option all locals supprime désormais également le cache des plug-ins.

Index des messages de protocole

Version de protocole 1.0.0 messages:

Fermer
- Demande de direction : NuGet - plugin>
- La requête ne contiendra aucune charge utile
- Aucune réponse n’est attendue. La réponse appropriée est que le processus de plug-in se ferme rapidement.
Copier des fichiers dans le package
- Direction de la demande : NuGet - plug-in>
- La demande contient les éléments suivants :
  - l’ID de package et la version
  - emplacement du référentiel source du package
  - chemin d’accès au répertoire de destination
  - une liste de fichiers contenus dans le package à copier dans le chemin du répertoire de destination
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération
  - Un énumérable de chemins complets pour les fichiers copiés dans le répertoire de destination si l’opération s'est bien déroulée.
Copier le fichier de package (.nupkg)
- Demande de direction : NuGet - plugin>
- La demande contient les éléments suivants :
  - l’ID de package et la version
  - emplacement du référentiel source du package
  - chemin du fichier de destination
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération
Obtenir les informations d’identification
- Demander la direction : plug-in -> NuGet
- La demande contient les éléments suivants :
  - emplacement du référentiel source du paquet
  - le code d’état HTTP obtenu à partir du référentiel source du package à l’aide des informations d’identification actuelles
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération
  - un nom d’utilisateur, le cas échéant
  - un mot de passe, le cas échéant
Obtenir des fichiers dans le paquet
- Demande de direction : NuGet - plug-in>
- La demande contient les éléments suivants :
  - l’ID de package et la version
  - emplacement du référentiel source du paquet
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération
  - une liste des chemins de fichiers dans le package si l'opération a réussi
Obtenir les demandes d’opération
- Demande de direction : NuGet - plugin>
- La demande contient les éléments suivants :
  - le service index.json pour une source de paquet
  - emplacement du référentiel source du paquet
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération
  - une énumération des opérations prises en charge (par exemple, téléchargement de paquets) si l'opération est réussie. Si un plug-in ne prend pas en charge la source du package, le plug-in doit retourner un ensemble vide d’opérations prises en charge.

Note

Ce message a été mis à jour dans la version 2.0.0. Il incombe au client de préserver la compatibilité rétroactive.

Obtenir le hachage de paquet
- Demander une direction : NuGet - module>
- La demande contient les éléments suivants :
  - l’ID de package et la version
  - emplacement du référentiel source du paquet
  - algorithme de hachage
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération
  - un hachage de fichier de package en utilisant l’algorithme de hachage demandé si l’opération a réussi
Obtenir les versions du package
- Direction de la demande : NuGet - module>
- La demande contient les éléments suivants :
  - l'ID de paquet
  - emplacement du référentiel source du paquet
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération
  - un énumérable des versions de paquet si l’opération a réussi
Obtenir l’index de service
- Direction de la demande : Plugin -> NuGet
- La demande contient les éléments suivants :
  - emplacement du dépôt source du paquet
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération
  - l’index de service si l’opération a réussi
Poignée de main
- Demande d'orientation : plug-in NuGet <->
- La demande contient les éléments suivants :
  - version actuelle du protocole de plug-in
  - version minimale prise en charge du protocole de plug-in
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération
  - version de protocole négociée si l’opération a réussi. Une défaillance entraîne l’arrêt du plug-in.
Initialiser
- Orientation de la demande : NuGet - plugin>
- La demande contient les éléments suivants :
  - version de l’outil client NuGet
  - langue de fonctionnement de l’outil client NuGet. Cela prend en compte le paramètre ForceEnglishOutput, s’il est utilisé.
  - délai d'expiration par défaut de la demande, qui remplace le délai par défaut du protocole.
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération. Une défaillance entraîne l’arrêt du plug-in.
Rapport
- Direction de la demande : plug-in -> NuGet
- La demande contient les éléments suivants :
  - le niveau de journalisation pour la demande
  - un message à consigner
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération.
Surveiller la sortie du processus NuGet
- Demande de direction : NuGet - module>
- La demande contient les éléments suivants :
  - l’ID de processus NuGet
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération.
Package de préchargement
- Direction de la demande : NuGet - plug-in>
- La demande contient les éléments suivants :
  - l’ID de package et la version
  - emplacement du référentiel source du package
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération
Définir les informations d’identification
- Demande de direction : NuGet - plug-in>
- La demande contient les éléments suivants :
  - emplacement du référentiel source du paquet
  - le dernier nom d’utilisateur source du package connu, le cas échéant
  - le dernier mot de passe source du package connu, le cas échéant
  - le dernier nom d’utilisateur proxy connu, le cas échéant
  - le dernier mot de passe proxy connu, le cas échéant
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération
Définir le niveau de journal
- Direction de la demande : NuGet - plug-in>
- La demande contient les éléments suivants :
  - niveau de journal par défaut
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération

Version du protocole 2.0.0 messages

Obtenir les réclamations d’opération

Demande d'instructions : NuGet - plug-in>
- La demande contient les éléments suivants :
  - le service index.json pour une source de paquet
  - emplacement du référentiel source du package
- Une réponse contient :
  - code de réponse indiquant le résultat de l’opération
  - un ensemble des opérations prises en charge si l’opération a réussi. Si un plug-in ne prend pas en charge la source du package, le plug-in doit retourner un ensemble vide d’opérations prises en charge.
Si l’index de service et la source du package sont null, le plug-in peut répondre avec l’authentification.

Obtenir les informations d’identification

Direction de la demande : NuGet -> plug-in
La demande contient les éléments suivants :
- URI
- estReessayer
- NonInteractif
- CanShowDialog
Une réponse contiendra
- Nom d’utilisateur
- Mot de passe
- Message
- Liste des types d’authentification
- CodeDeRéponseDuMessage

Partager via