Плагины NuGet для кроссплатформенной работы

В NuGet 4.8+ добавлена поддержка кроссплатформенных подключаемых модулей. Это было достигнуто путем создания новой модели расширяемости подключаемого модуля, которая должна соответствовать строгому набору правил операции. Подключаемые модули являются автономными исполняемыми файлами (запускаемыми в мире .NET Core), которые клиенты NuGet запускают в отдельном процессе. Это действительно плагин "один раз написать, запускать везде". Он будет работать со всеми клиентскими средствами NuGet. Подключаемые модули можно написать на любом языке программирования, но самый простой интерфейс разработки и установки подключаемых модулей будет использовать .NET. Определяется протокол обмена версиями между клиентом NuGet и подключаемым модулем. Во время рукопожатия при запуске два процесса согласовывают версию протокола.

Как это работает

Рабочий процесс высокого уровня можно описать следующим образом:

1. NuGet обнаруживает доступные плагины.
2. При необходимости NuGet будет выполнять итерацию по подключаемым модулям в порядке приоритета и запускает их по одному.
3. NuGet будет использовать первый плагин, который может обслуживать запрос.
4. Подключаемые модули будут отключены, когда в них больше не будет необходимости.

Общие требования к подключаемым модулям

Текущая версия протокола 2.0.0.0. В этой версии требования приведены ниже.

• Поддержка запуска без отслеживания состояния в текущем контексте безопасности клиентских средств NuGet. Например, клиентские средства NuGet не будут выполнять повышение или дополнительную инициализацию за пределами протокола подключаемого модуля, описанного далее.
• Не взаимодействуйте, если не указано явно.
• Соблюдайте согласованную версию протокола подключаемого модуля.
• Отвечайте на все запросы в течение разумного периода времени.
• Удовлетворяйте запросы на отмену для любой операции, находящейся в процессе выполнения.

Подключаемые модули, обнаруженные через переменную окружения PATH (например, установленные с помощью dotnet tool), также должны соответствовать шаблону имени файла nuget-plugin-*. Часть nuget-plugin- должна быть написана полностью в строчных буквах.

NuGet 6.12 (MSBuild 17.12 и .NET SDK 9.0.100), а также более ранние версии также требовали, чтобы подключаемые модули были подписаны с помощью Authenticode в Windows.

Техническая спецификация подробно описана в следующих спецификациях:

• подключаемый модуль для загрузки пакетов NuGet
• подключаемый модуль проверки подлинности для кроссплатформенного использования NuGet
• плагины Dotnet Tools

Клиент — взаимодействие плагина

Клиентские средства NuGet и подключаемые модули взаимодействуют с JSON через стандартные потоки (stdin, stdout, stderr). Все данные должны быть закодированы в кодировке UTF-8. Подключаемые модули запускаются с аргументом "-Plugin". Если пользователь непосредственно запускает плагин как исполняемый файл без этого аргумента, плагин может выдать информативное сообщение, а не ожидать согласования протокола. Время ожидания подтверждения протокола составляет 5 секунд. Плагин должен завершить настройку за минимально короткое время. Клиентские средства NuGet запрашивают поддерживаемые операции подключаемого модуля, передав индекс службы для источника NuGet. Подключаемый модуль может использовать индекс службы для проверки наличия поддерживаемых типов служб.

Обмен данными между клиентскими средствами NuGet и подключаемым модулем является двунаправленным. Каждый запрос имеет время ожидания в 5 секунд. Если операции должны занять больше времени, соответствующий процесс должен отправить сообщение о ходе выполнения, чтобы предотвратить истечение времени ожидания запроса. Через 1 минуту бездействия подключаемый модуль считается неактивным и отключается.

Установка и обнаружение подключаемого модуля

NuGet ищет подключаемые модули из структуры каталогов на основе соглашений и сканирует переменную среды PATH.

Обнаружение на основе соглашений

Сценарии CI/CD и опытные пользователи могут использовать переменные среды для переопределения поведения. При использовании переменных среды разрешены только абсолютные пути. Обратите внимание, что NUGET_NETFX_PLUGIN_PATHS и NUGET_NETCORE_PLUGIN_PATHS доступны только с 5.3+ версией инструментов NuGet и более поздних версий.

• NUGET_NETFX_PLUGIN_PATHS — определяет используемые плагины средствами, основанными на .NET Framework (NuGet.exe/MSBuild.exe/Visual Studio). Имеет приоритет над NUGET_PLUGIN_PATHS. (Только версии NuGet 5.3+ )
• NUGET_NETCORE_PLUGIN_PATHS — определяет плагины, которые будут использоваться средствами на основе .NET Core (dotnet.exe). Имеет приоритет над NUGET_PLUGIN_PATHS. (Только версии NuGet 5.3+ )
• NUGET_PLUGIN_PATHS — определяет подключаемые модули, которые будут использоваться для этого процесса NuGet, с учетом приоритетов. Если эта переменная среды установлена, она переопределяет обнаружение, основанное на соглашении. Игнорируется, если указана любая из определенных переменных платформы.
• Расположение пользователя, домашнее расположение NuGet в %UserProfile%/.nuget/plugins. Это расположение нельзя переопределить. Для подключаемых модулей .NET Core и .NET Framework будет использоваться другой корневой каталог.

Каркас	Расположение обнаружения корней	Используется кем-либо
.NET Core	%UserProfile%/.nuget/plugins/netcore	CLI dotnet
Платформа .NET Framework	%UserProfile%/.nuget/plugins/netfx	MSBuild, NuGet.exe, Visual Studio

Каждый подключаемый модуль должен быть установлен в своей папке. Точка входа подключаемого модуля будет именем установленной папки с расширениями .dll для .NET Core и расширением .exe для .NET Framework.

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

Обнаружение пути

Начиная с NuGet 6.13 NuGet будет выполнять поиск по каждому каталогу, указанному в переменной среды PATH, для файлов, соответствующих шаблону nuget-plugin-*. Сопоставление шаблонов чувствительно к регистру, и nuget-plugin- должно быть написано полностью строчными буквами. В Windows файл должен иметь .exe или .bat расширение. На Linux и macOS файл должен иметь разрешение на выполнение.

Это позволяет устанавливать подключаемые модули NuGet с помощью команд dotnet tool, WinGet, диспетчера пакетов Linux-дистрибутива или любого другого метода, который может добавить исполняемые файлы в переменную окружения PATH пользователя. Это также позволяет создавать подключаемые модули NuGet на любом языке программирования (ранее подключаемые модули для Linux и Mac должны быть написаны в .NET).

Мы рекомендуем разрабатывать подключаемые модули в .NET, чтобы использовать пакет NuGet.Protocol , чтобы избежать необходимости писать код RPC json и разрешать клиентам обнаруживать подключаемый модуль через dotnet package search nuget-plugin.

Поддерживаемые операции

В новом протоколе подключаемого модуля поддерживаются две операции.

Имя операции	Минимальная версия протокола	Минимальная версия клиента NuGet
Скачивание пакета	1.0.0	4.3.0
проверки подлинности	2.0.0	4.8.0

Запуск подключаемых модулей в правильной среде выполнения

Для NuGet в dotnet.exe сценариях подключаемые модули должны быть в состоянии выполняться в этой конкретной среде выполнения dotnet.exe. На стороне поставщика плагина и потребителя лежит ответственность за то, чтобы использовать совместимое сочетание dotnet.exe/плагин. Потенциальная проблема может возникнуть с плагинами местоположения пользователя, например, когда dotnet.exe в среде выполнения 2.0 пытается использовать плагин, написанный для среды выполнения 2.1.

Кэширование возможностей

Процесс проверки безопасности и создания экземпляров подключаемых модулей обходится дорого. Операция скачивания происходит чаще, чем операция проверки подлинности, однако средний пользователь NuGet, скорее всего, имеет подключаемый модуль проверки подлинности. Чтобы улучшить работу, NuGet кэширует утверждения операции для данного запроса. Кэш выделяется для каждого подключаемого модуля, где ключом модуля является путь модуля, а срок действия кэша возможностей составляет 30 дней.

Кэш находится в %LocalAppData%/NuGet/plugins-cache и переопределяется с помощью переменной среды NUGET_PLUGINS_CACHE_PATH. Чтобы очистить этот кэш, можно выполнить команду locals с параметром plugins-cache. Функция «Локальные параметры all» теперь также удаляет кэш плагинов.

Индекс сообщений протокола

Сообщения версии протокола 1.0.0:

1. Закрывать

   • Направление запроса: NuGet — плагин>
   • Запрос не будет содержать полезную нагрузку
   • Ответ не ожидается. Правильное действие заключается в том, чтобы процесс плагина немедленно завершился.

2. Копирование файлов в пакете

   • Направление запроса: NuGet — плагин>
   • Запрос будет содержать следующее:
     • Идентификатор пакета и версия
     • Расположение исходного репозитория пакета
     • Путь к каталогу назначения
     • Перечисляемые файлы в пакете, которые необходимо скопировать в целевую директорию.
   • Ответ будет содержать следующее:
     • код ответа, указывающий результат операции
     • Перечисление полных путей для скопированных файлов в целевом каталоге, если операция выполнена успешно.

3. Копировать файл пакета (NUPKG)

   • Направление запроса: NuGet — плагин>
   • Запрос будет содержать следующее:
     • Идентификатор пакета и версия
     • Расположение исходного репозитория пакета
     • Путь к целевому файлу
   • Ответ будет содержать следующее:
     • код ответа, указывающий результат операции

4. Получение учетных данных

   • Запрос направления: плагин —> NuGet
   • Запрос будет содержать следующее:
     • Расположение исходного репозитория пакета
     • Код состояния HTTP, полученный из исходного репозитория пакета с использованием текущих учетных данных
   • Ответ будет содержать следующее:
     • код ответа, указывающий результат операции
     • имя пользователя, если доступно
     • пароль, если он доступен

5. Получить файлы в пакете

   • Направление запроса: NuGet — плагин>
   • Запрос будет содержать следующее:
     • Идентификатор пакета и версия
     • Расположение исходного репозитория пакета
   • Ответ будет содержать следующее:
     • код ответа, указывающий результат операции
     • Перечисление путей к файлам в пакете при успешном выполнении операции

6. Получение утверждений операции

   • Направление запроса: NuGet — плагин>
   • Запрос будет содержать следующее:
     • служба index.json для источника пакета
     • Расположение исходного репозитория пакета
   • Ответ будет содержать следующее:
     • код ответа, указывающий результат операции
     • Перечисление поддерживаемых операций (например, скачивание пакета), если операция выполнена успешно. Если подключаемый модуль не поддерживает источник пакета, то он должен вернуть пустой набор поддерживаемых операций.

Заметка

Это сообщение было обновлено в версии 2.0.0.0. Задача клиента — обеспечить обратную совместимость.

7. Получение хэша пакета

   • Направление запроса: NuGet — плагин>
   • Запрос будет содержать следующее:
     • Идентификатор пакета и версия
     • Расположение исходного репозитория пакета
     • хэш-алгоритм
   • Ответ будет содержать следующее:
     • код ответа, указывающий результат операции
     • Хэш файла пакета, полученный с использованием запрошенного алгоритма хэша, если операция выполнена успешно.

8. Получить версии пакетов

   • Направление запроса: NuGet — плагин>
   • Запрос будет содержать следующее:
     • идентификатор пакета
     • Расположение исходного репозитория пакета
   • Ответ будет содержать следующее:
     • код ответа, указывающий результат операции
     • список доступных версий пакетов, если операция завершилась успешно

9. Получение индекса службы

   • Запрос направления: плагин —> NuGet
   • Запрос будет содержать следующее:
     • Расположение исходного репозитория пакета
   • Ответ будет содержать следующее:
     • код ответа, указывающий результат операции
     • Индекс службы, если операция выполнена успешно

10. Рукопожатие

    • Запрос направления для плагина NuGet <—>
    • Запрос будет содержать следующее:
      • текущая версия протокола подключаемого модуля
      • минимальная поддерживаемая версия протокола подключаемого модуля
    • Ответ будет содержать следующее:
      • код ответа, указывающий результат операции
      • согласованная версия протокола, если операция выполнена успешно. Сбой приведет к прекращению работы подключаемого модуля.

11. Инициализировать

    • Направление запроса: NuGet — плагин>
    • Запрос будет содержать следующее:
      • Версия клиентского средства NuGet
      • Эффективный язык клиентского средства NuGet. Следует учитывать параметр ForceEnglishOutput, если он используется.
      • Время ожидания запроса по умолчанию, которое заменяет стандартное значение протокола.
    • Ответ будет содержать следующее:
      • код ответа, указывающий на результат операции. Сбой приведет к прекращению работы подключаемого модуля.

12. Лог

    • Запрос направления: плагин —> NuGet
    • Запрос будет содержать следующее:
      • Уровень логов для запроса
      • сообщение для входа
    • Ответ будет содержать следующее:
      • код ответа, указывающий на результат операции.

13. Отслеживание завершения процесса NuGet

    • Направление запроса: NuGet — плагин>
    • Запрос будет содержать следующее:
      • Идентификатор процесса NuGet
    • Ответ будет содержать следующее:
      • код ответа, указывающий на результат операции.

14. Пакет предварительной выборки

    • Направление запроса: NuGet — плагин>
    • Запрос будет содержать следующее:
      • Идентификатор пакета и версия
      • Расположение исходного репозитория пакета
    • Ответ будет содержать следующее:
      • код ответа, указывающий результат операции

15. Настройка учетных данных

    • Направление запроса: NuGet — плагин>
    • Запрос будет содержать следующее:
      • Расположение исходного репозитория пакета
      • последнее известное имя пользователя источника пакета, если доступно
      • Последний известный пароль источника пакета, если он доступен
      • последнее известное имя пользователя прокси-сервера, если оно доступно
      • последний известный пароль прокси-сервера, если он доступен
    • Ответ будет содержать следующее:
      • код ответа, указывающий результат операции

16. Настройка уровня журнала

    • Направление запроса: NuGet — плагин>
    • Запрос будет содержать следующее:
      • Уровень журнала по умолчанию
    • Ответ будет содержать следующее:
      • код ответа, указывающий результат операции

Версия протокола 2.0.0 сообщения

17. Получение утверждений операции

• Направление запроса: NuGet — плагин>

  • Запрос будет содержать следующее:
    • служба index.json для источника пакета
    • Расположение исходного репозитория пакета
  • Ответ будет содержать следующее:
    • код ответа, указывающий результат операции
    • перечисление поддерживаемых операций, если операция выполнена успешно. Если подключаемый модуль не поддерживает источник пакета, то он должен вернуть пустой набор поддерживаемых операций.

  Если индекс службы и источник пакета имеют значение NULL, тогда подключаемый модуль может ответить с аутентификацией.

18. Получение учетных данных аутентификации

• Направление запроса: NuGet — плагин>
• Запрос будет содержать следующее:
  • Ури
  • повторнаяПопытка
  • неинтерактивный
  • МожетПоказатьДиалог
• Ответ будет содержать
  • Имя пользователя
  • Пароль
  • Сообщение
  • Список типов проверки подлинности
  • КодОткликаСообщения