Плагины Datacol

Создание плагинов экспорта. Инструкция для сторонних разработчиков

Важно! Перед прочтением:
1. Ознакомьтесь с общими принципами работы с Datacol (хотя бы первые 5 видео).
2. Загрузите проект-пример плагина D7_ExportPluginTemplate с Bitbucket.

Функция обработчик

Основная функция обработчик плагина — pluginHandler. В переменной-словаре parameters она принимает входные параметры плагина. Информация о том какие ключи словаря соответствуют каким параметрам будет представлена ниже. В переменной error плагин возвращает ошибку, если таковая произошла при работе плагина.

Функция обработчик

Входные параметры

В целом у плагинов Datacol есть 2 типа входных параметров: Runtime (данные, возникающие в процессе работы программы, например, выгруженная с сайта источника информация) и фиксированные (заданные пользователем). В случае с плагинами экспорта, заданные пользователем параметры также делятся на 2 типа: текстовые и визуальные.

Входные параметры

Пользовательские параметры

Визуальные пользовательские параметры

Примеры форматов

Для удобства пользователей входные параметры плагина экспорта можно в так называемом визуальном формате. Под визуальным форматом подразумевается PropertyGrid. Его можно увидеть выбрав в Datacol плагин экспорта D7_ExportPluginTemplate.

Визуальные пользовательские параметры

В процессе создания класса конфигурации (который проецируется в PropertyGrid) есть возможность уточнять конкретный контрол, который используется для редактирования конкретного члена класса (конкретной опции). Примеры контролов:

Выпадающий список для редактирования bool переменной

Выпадающий список для редактирования bool переменной

Окно задания пути к файлу (аналогично для папки)

Окно задания пути к файлу

Редактирование списка как многострочного текста

Редактирование списка как многострочного текста

Неисключающий список значений (выпадающий список чекбоксов)

Неисключающий список значений

Исключающий список значений (выпадающий список чекбоксов)

Исключающий список значений

Визуальные параметры в коде

Важный момент! Если вы хотите, чтобы плагину передавались визуальные параметры, то в проекте плагина должен присутствовать класс, производный от PluginStaticSetting. Но такой производный класс, должен быть в проекте конкретного плагина только один! Пример задания оформления визуальных опций в коде показан в проекте D7_ExportPluginTemplate в классе TestPluginStaticSetting.

Визуальные параметры в коде

Доступ к визуальным параметрам из кода обработчика

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

(parameters[PluginMiscStr.VisualConfigParameterName] as TestPluginStaticSetting)

Собственно визуальные параметры передаются в одном из значений словаря parameters. Ключ этого значения — PluginMiscStr.VisualConfigParameterName.

Текстовые пользовательские параметры

От использования текстовых пользовательских параметров мы постепенно уходим, поэтому описание их использования опускаем.

Runtime параметры

Напомню, это данные, возникающие в процессе работы программы. Для плагина экспорта набор данных следующий:

  • Название текущей запущенной кампании (настройки/конфигурации) парсинга: parameters[«campaignname»] (тип строка);
  • Тип плагина: parameters[«type»] (тип строка). Для плагина экспорта передается “export_plugin”. Соответственно, в случае плагина экспорта актуальна следующая проверка:

    • Runtime параметры

  • Таблица собранными данными: parameters[«datatable»] (тип DataTable);
  • Список названий колонок таблицы с собранными данными: parameters[«columnnames»] (тип List);

Пример pluginHandler (функции обработчика)

Пример фукнции обработчика pluginHandler из заготовки плагина экспорта приведен ниже (также доступен в проекте D7_ExportPluginTemplate, файл main.cs). В нем видно как обрабатываются различные типы входных параметров.

Пример pluginHandler

Выходные значения

На выходе функция-обработчик для плагина экспорта возвращает пустую строку. Если в процессе экспорта произошла ошибка, то она сохраняется в переменной error.

Компиляция плагина

Обработите внимание, если вы используете нашу заготовку для создания плагина D7_ExportPluginTemplate, в ней отрабатывает Post Build событие, вызывающее специальный bat файл. Это сделано для того, чтобы скомпилированный плагин автоматически (при первой компиляции) импортировался в Datacol (и его можно было выбирать в соответствующих опция окна настройки кампании) и автоматически обновлялся при последующей перекомпиляции. Скрипт в bat файле осуществляет следующие шаги:

    1. копирует содержимое текущей папки со скомпилированными файлами в папку %APPDATA%Datacol7Plugins

    2. если файлы уже там есть — перезаписывает их (за исключением файла plugin_convention.txt)

    3. в папке %APPDATA%Datacol7Plugins находит файло plugin_convention.txt и смотрит в нем есть ли строка, содержащая название основного файла текущей компиляции (например D5Plugin_ExportBitrix.dll ). Если есть — ничего не делает; если нет — дописывает название вниз файла plugin_convention.txt отдельной строкой

Важно! Если у вас запущена программа Datacol и в ней уже вызывался плагин (при тестировании или в процессе запуска кампании), то для того чтобы его перекомпилировать, необходимо закрыть программу.

Создание архива с плагином для распространения

Для того, чтобы распространять плагин необходимо сделать следующее:

    1. Копируем папку, в которую билдится проект в файлами плагина. Называем ее по названию плагина, например D7_ExportPluginTemplate

    2. Создаем в папке файл plugin_convention.txt

    3. Записываем в него название главного dll файла плагина, например: D7_ExportPluginTemplate.dll

    4. Создаем ZIP архив. В нем должна лежать папка, созданная ранее.

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

Протестировать созданный плагин можно прямо в Datacol. Также это можно сделать с помощью Unit тестов.

Тестирование в Datacol

Чтобы протестировать плагин в Datacol:

    1. Откройте настройки кампании (к которой предполагается подключать плагин)

    2. Включите опцию Плагин на вкладке Экспорт

    Включите опцию Плагин на вкладке Экспорт

    3. На вкладке Форматы экспорта > Плагин в выпадающем списке выберите плагин, который хотите протестировать.

    Выберите плагин, который хотите протестировать

    Важно! Это получится сделать, если в файле %APPDATA%Datacol7Pluginsplugin_convention.txt в одной из строк есть наименование главного dll файла плагина (например D7_ExportPluginTemplate.dll). Оно там должно появиться автоматически: либо в процессе компиляции исходников плагина, либо в процессе импорта плагина из ранее созданного архива.

    4. Установите ссылку для тестирования (ее можно скопировать на вкладке Сбор данных) и нажмите кнопку Тестировать.

Нажмите кнопку Тестировать

С помощью Unit тестов

Для тестирования функции pluginHandler вне Datacol создан Unit-тест проект TestPlugin. Он имитирует запуск плагина из Datacol, передавая параметры, описанные выше.

Unit тест

В зависимости от настройки сбора данных у вас может меняться структура и набор входных данных. Их можно корректировать в переменных columnames и dt.

Переменные columnames и dt