Распространение плагинов

• Термины и определения
• Эталонный реестр плагинов
• Эталонный плагин
• Локальный реестр плагинов
• Добавление/обновление плагина
• Исключение плагина из распространения

Термины и определения

Целевая программа - программный продукт, для которого предназначены плагины, например, Autodesk Revit, Autodesk Navisworks и т.д.

Версия Целевой программы - конкретный релиз Целевой программы, например, Autodesk Revit 2019, Autodesk Revit 2021 и т.д.

Менеджер плагинов - приложение, предназначенное для централизованного управления жизненным циклом плагинов, включая их установку, обновление и удаление.

Эталонный реестр плагинов

Общая информация

Для каждой поддерживаемой версии Целевой программы используется отдельный файл-реестр плагинов, предназначенный для централизованного распространения через Менеджер плагинов.

Файл располагается по следующему пути:

Z:\BIM\7. Дополения\1. Внутренние\3. Данные\{ЦЕЛЕВАЯ ПРОГРАММА}_{ВЕРСИЯ}.dat

Данный файл является единственным источником истины для Менеджера плагинов при определении:

• какие плагины должны быть установлены пользователю;

• какие версии плагинов являются актуальными;

• откуда загружать .addin и конфигурационные файлы;

• для каких ролей пользователей доступны конкретные плагины.
  

Структура файла

Корневым элементом является коллекция:

<ArrayOfAddinInfo>

Каждый отдельный плагин описывается элементом:

<AddinInfo>

Каждый элемент <AddinInfo> описывает один плагин и содержит в себе следующие поля:

• <Name> - Уникальный идентификатор плагина, который соответствует наименованию Проекта плагина.
• <Version> - Версия плагина, которая используется для определения необходимости обновления. Формат версии — ВЕРСИЯ ЦЕЛЕВОЙ ПРОГРАММЫ.МАЖОР.МИНОР.ПАТЧ, например, 2019.10.2.43.
  МАЖОР - Увеличивается при внесении изменений, нарушающих обратную совместимость. При изменении обнуляется МИНОН и ПАТЧ.
  МИНОР - Увеличивается, если добавлен новый функционал, но без нарушения обратной совместимости. При изменении обнуляется ПАТЧ.
  ПАТЧ - Увеличивается при исправлении ошибок, без изменения функционала приложения.
• <Path> - Полный сетевой путь к .addin файлу плагина. Данное поле может отсутствовать для пакетов Dynamo и других компонентов, которые не используют .addin файлы.
• <ConfigurationFilePath> - Путь к конфигурационному файлу плагина (.fst).
• <ValidUserType> - Тип пользователя (роль), для которого доступен плагин.

Пример файла:

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfAddinInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <AddinInfo>
        <Name>CollisionGrouper</Name>
        <Version>2019.0.0.31</Version>
        <Path>{ПУТЬ ДО ADDIN ФАЙЛА}</Path>
        <ConfigurationFilePath>{ПУТЬ ДО FST ФАЙЛА}</ConfigurationFilePath>
        <ValidUserType>AllUsers</ValidUserType>
    </AddinInfo>
</ArrayOfAddinInfo>

Правила работы с файлом

• Любое обновление плагина требует обновления версии.
• Изменение сетевой структуры без обновления файла приведёт к неработоспособности Менеджера плагинов.
• Для исключения плагина из распространения достаточно удалить соответствующий <AddinInfo> из файла.
• Файл должен оставаться корректным XML-документом. Любая ошибка структуры приводит к невозможности загрузки списка плагинов.

• Перед сохранением файла необходимо проверять XML на корректность с помощью Notepad++ плагина XML Tools функцией Check XML syntax now.
  

Эталонный плагин

Папка с эталонными плагинами для версии Целевой программы

Для каждой версии Целевой программы в сетевом хранилище предусмотрена отдельная папка, содержащая эталонные версии плагинов, используемые Менеджером плагинов для централизованного распространения.

Базовый путь к каталогу эталонных плагинов:

Z:\BIM\7. Дополения\1. Внутренние\{ЦЕЛЕВАЯ ПРОГРАММА}

Внутри данного каталога для каждой версии Revit создаётся отдельная папка:

Z:\BIM\7. Дополения\1. Внутренние\{ЦЕЛЕВАЯ ПРОГРАММА}\{ВЕРСИЯ}

Содержимое папки версии Целевой программы

Каталог конкретной версии Целевой программы содержит:

• Каталоги со сборками плагинов;
• Файлы конфигурации Менеджера плагинов (.fst);
• Файлы манифесты плагинов (.addin) при необходимости.

Таким образом, типовое содержимое каталога версии Целевой программы выглядит следующим образом:

Z:\BIM\7. Дополения\1. Внутренние\2. Revit\2021\
 ├─ adm_MarksDigital.addin
 ├─ adm_MarksDigital.fst
 ├─ adm_MarksDigital\
 ├─ gen_ModelExporter.addin
 ├─ gen_ModelExporter.fst
 ├─ gen_ModelExporter\
 └─ ...

Файл конфигурация .fst

Файл .fst описывает правила развертывания плагина на рабочем месте пользователя и представляет из себя XML документ со следующей структурой:

<FileConfiguration>

Каждый файл описывает один плагин и содержит следующие элементы.

• <FilePath> - Полный сетевой путь к .addin файлу эталонного плагина.
• <FileDestination> - Относительный путь назначения для .addin файла на локальной машине пользователя. Путь задаётся относительно профиля пользователя (%APPDATA%).
• <DirectoryPath> - Полный сетевой путь к каталогу эталонного плагина.
• <DirectoryDestination> - Относительный путь назначения каталога плагина на локальной машине пользователя. Путь задаётся относительно профиля пользователя (%APPDATA%).

Пример файла:

<?xml version="1.0" encoding="utf-8"?>
<FileConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <FilePath>{ПУТЬ ДО ЭТАЛОННОГО ADDIN ФАЙЛА}</FilePath>
    <FileDestination>{ПУТЬ ПОЛЬЗОВАТЕЛЬСКОГО ADDIN ФАЙЛА}</FileDestination>
    <DirectoryPath>{ПУТЬ ДО ЭТАЛОННОЙ ПАПКИ ПЛАГИНА}</DirectoryPath>
    <DirectoryDestination>{ПУТЬ ДО ПОЛЬЗОВАТЕЛЬСКОЙ ПАПКИ ПЛАГИНА}</DirectoryDestination>
</FileConfiguration>

Правила работы с файлом

• Пути в файле должны полностью соответствовать фактической структуре сетевого каталога.
• Каждый .fst файл, указанный в реестре эталонных файлов, должен физически существовать в каталоге версии Целевой программы.
• При обновлении плагина необходимо заменить содержимое каталога эталонного плагина и версию плагина в эталонном реестре плагинов.
• Перед сохранением файла необходимо проверять XML на корректность с помощью Notepad++ плагина XML Tools функцией Check XML syntax now.
  

  

Локальный реестр плагинов

Общая информация

Для каждой установленной у пользователя Целевой программы Менеджер плагинов ведёт локальный файл реестр плагинов, содержащий информацию о фактически установленных плагинах и их версиях на данном рабочем месте. По своей структуре и формату данный файл аналогичен файлу эталонного реестра плагинов. Локальные реестры расположены по пути:

%AppData%\MarksDigital\AddinManager\Settings

Обновление и сопровождение локального файла

При запуске Целевой программы через Менеджер плагинов выполняется следующий алгоритм:

1. Загружается эталонный реестр Целевой программы.
2. Загружается локальный реестр Целевой программы.
3. Для каждого плагина из эталонного файла выполняется проверка:

   • Плагин отсутствует в локальном файле - Плагин считается неустановленным и помечается к установке.

   • Плагин присутствует в локальном файле, но версия ниже эталонной - Плагин помечается к обновлению.
   • Версия плагина совпадает с эталонной - Действия не требуются.

4. Для всех плагинов, помеченных к установке или обновлению, Менеджер плагинов выполняет проверку доступности файлов. проверяется, не заблокированы ли файлы плагина процессом Целевой программы.

5. В зависимости от результата проверки:

   • Файлы плагина не заняты процессом Целевой программы - обновление плагина в соответствии с .fst файлом;

   • Файлы плагина заняты процессом Целевой программы -  обновление плагина откладывается до освобождения файлов.

6. После успешной установки или обновления:

   • локальный файл конфигурации пользователя обновляется;

   • в нём фиксируется актуальная версия плагина;

   • состояние плагина считается синхронизированным с эталоном.

Сброс плагинов

Менеджер плагинов предоставляет функцию «Сброс плагинов», предназначенную для принудительного удаления локальных реестров плагинов. Сброс плагинов является безопасной процедурой и не приводит к потере пользовательских данных. При выполнении функции:

• удаляются локальные реестры плагинов всех Целевых программ;

• информация о версиях плагинов, установленных у пользователя, полностью сбрасывается;

• физические файлы плагинов не удаляются.

После сброса, при следующем запуске соответствующей Целевой программы:

• Менеджер плагинов не обнаруживает локальный реестр плагинов Целевой программы;

• считает все плагины неустановленными;

• выполняет установку плагинов в соответствии с эталонным реестром плагинов.

Добавление/обновление плагина

1. Вытянуть мастер

   • Получить актуальную версию исходного проекта из репозитория.
   • Мастер содержит исходный код, конфигурации и структуру всех плагинов для разных версий Целевой программы.
2. Проверить состав решения перед сборкой
   • Проекты adm_Core и adm_CoreCommon должны быть обязательно загружены в решение и участвовать в сборке.
3. Если в рамках выполнения задачи вносились изменения в adm_Core или adm_CoreCommon, то перед публикацией новой версии плагина необходимо выполнить сборку и публикацию обновлённой версии плагина adm_MarksDigital. Алгоритм обновления плагина adm_MarksDigital аналогичен обновлению других плагинов см. далее.

4. Собрать проект под все версии Целевой программы

   • Выполнить сборку проекта для каждой версии Целевой программы.

   • Результатом сборки являются:

     • .addin-манифесты для каждой версии;
     • бинарные файлы плагинов;
     • сопутствующие ресурсы.

   • Проверить успешность сборки и отсутствие ошибок для каждой версии локально на компьютере разработчика.

5. Скопировать содержимое папок в эталон с заменой

   • Для каждой версии Целевой программы скопировать скомпилированные файлы и манифесты в эталонную папку:
     Z:\BIM\7. Дополения\1. Внутренние\{ЦЕЛЕВАЯ ПРОГРАММА}\{ВЕРСИЯ}\

   • Если это обновление существующего плагина, то просто заменяем файлы в папке плагина.

   • Если это новый плагин, то:

     1. Создаём файл конфигурации .fst для нового плагина;
     2. Кладём .addin-манифест и папку плагина в эталон;
     3. Добавляем запись AddinInfo эталонные реестр плагинов для версии Целевой программы {ЦЕЛЕВАЯ ПРОГРАММА}_{ВЕРСИЯ}.dat.

6. Поднять версию во всех версиях эталонных реестрах плагинов Целевой программы {ЦЕЛЕВАЯ ПРОГРАММА}_{ВЕРСИЯ}.dat.

   • Обновление версии выполняется одновременно для всех версий Целевой программы.
   • Итоговые номера версий плагинов должны различаться только частью, соответствующей версии Целевой программы.

7. Особые условия при обновлении у пользователей

   • Обновление файлов плагина происходит только если файлы не заняты процессом Целевой программы.

Исключение плагина из распространения

Общая информация

Для управления выводом плагинов из использования применяется механизм исключения плагинов из распространения. Для каждой версии Целевого продукта создаётся отдельный файл исключений:

Z:\BIM\7. Дополения\1. Внутренние\3. Данные\{ЦЕЛЕВОЙ ПРОДУКТ}Invalid_{ВЕРСИЯ}.dat

Файл содержит перечень плагинов, которые не должны присутствовать у пользователей для данной версии Целевого продукта.

Файл Invalid

Файл представляет собой XML-документ со списком имён плагинов:

• каждый элемент <InvalidAddin> содержит:

  • <Name> — уникальное имя плагина;

• имя плагина должно совпадать:

  • с именем папки плагина;

  • и/или с именем .addin-манифеста.

Пример файла:

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfInvalidAddin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <InvalidAddin>
        <Name>{НАИМЕНОВАНИЕ ПЛАГИНА}</Name>
    </InvalidAddin>
</ArrayOfInvalidAddin>

Логика работы Менеджера плагинов

При запуске Целевого продукта через Менеджер плагинов выполняется следующий алгоритм:

1. Загружается Invalid файл Целевого продукта .

2. Для каждого плагина из списка исключений:

   • проверяется наличие локальной папки плагина и/или .addin-манифеста с указанным именем;

   • выполняется проверка, не заняты ли файлы плагина процессом Целевого продукта.

3. В зависимости от результата проверки:

   • файлы плагина не заняты процессом Целевого продукта - плагин удаляется локально у пользователя (папка и манифест);

   • файлы плагина заняты процессом Целевого продукта - удаление плагина откладывается до освобождения файлов.

Порядок действия для исключения плагина

Для полного вывода плагина из распространения необходимо:

1. Добавить плагин в Invalid файл для версии Целевого продукта.

2. Удалить плагин из эталонного реестра версии Целевого продукта.

Если удалить плагин из эталонного реестра, но не добавить его в Invalid файл, то уже установленный у пользователя плагин останется без изменений и продолжит работать, однако он больше не будет обновляться или переустанавливаться.

В противном случае, если плагин не внесён в Invalid, он будет повторно устанавливаться при последующих запусках.