Модуль расширения Консоли настройки

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

Такими действиями, в частности, могут являться:

  • Работа с базой данных.

  • Установка или конфигурирование NT-сервисов.

  • Создание Web-сайтов или виртуальных папок в IIS.

  • Взаимодействие с другими компонентами или решениями.

  • Изменение параметров работы решения после окончания установки.

  • Прочие действия.

Чтобы упростить решение этих задач, предоставляется возможность разработки специального программного компонента — модуля расширения (Snap-In) для программы Консоль настройки Docsvision.

Консоль настройки Docsvision — универсальный инструмент для конфигурирования и администрирования сервера Docsvision. Подробнее его использование рассмотрено в документации по администрированию модуля Платформа.

Механизм модулей расширения (Snap-Ins) является способом динамического расширения функциональности Консоли настройки новыми возможностями, которые могут появляться при установке в системе дополнительных модулей или решений. Аналогами подобного механизма могут выступать оснастки консоли администрирования (MMC) в Microsoft Windows или механизм плагинов (Plug-ins) в других программных средах.

В частности, средства конфигурирования стандартных решений "Управление процессами" и "Процессы WWF" также реализованы в виде модулей расширения для Консоли настройки — их можно рассматривать в качестве примера реализации.
Консоль настройки может работать в двух режимах:

  • Режим конфигурирования (Мастера) — этот режим активируется при первичной установке или удалении конкретного решения (или сервера Docsvision в целом).

  • Режим администрирования — этот режим активируется на рабочем сервере для изменения конкретных параметров работы сервера и/или конкретных решений.

Соответственно, каждый Snap-In для Консоли настройки также имеет возможность использовать один или оба режима. Например, можно реализовать Snap-In для собственного решения, который будет активироваться как при его установке (для выполнения каких-то сложных действий по регистрации компонент), так и позволит администратору системы менять какие-то параметры в процессе его работы.

В качестве Snap-In Консоли настройки может выступать любой программный компонент, реализующий ряд специальных интерфейсов (по аналогии с компонентами карточек Docsvision).

В коде компонента Snap-In могут быть реализованы следующие интерфейсы (все интерфейсы объявлены в сборке DocsVision.Tools.ServerConsole.Interfaces.dll, которую необходимо подключить к проекту):

DocsVision.Tools.ServerConsole.ISnapIn — обязательный интерфейс для любого модуля расширения.

Предполагает реализацию следующих свойств и методов:

  • Name — свойство, которое должно возвращать отображаемое имя модуля расширения.

  • Initialize(IEnvironment environment) — метод, который вызывается при первичной инициализации модуля расширения. На вход метода передается объект, описывающий контекст исполнения (Консоль Настройки).

  • QueryInterface(SnapInInterfacesEnum itfType) — метод, который вызывается при запросе конкретных функций модуля расширения.

    Модуль расширения может выполнять следующие функции:

    • SnapInInterfacesEnum.CONFIGURATOR — первичная инсталляция решения.

    • SnapInInterfacesEnum.WIZARD_CONTROL — инсталляция в режиме мастера.

    • SnapInInterfacesEnum.CONSOLE_CONTROL — режим администрирования (настройки).

    • SnapInInterfacesEnum.TOOLS — дополнительные инструменты.

    • SnapInInterfacesEnum.UNINSTALL_SNAP_IN — режим деинсталляции решения.

    • SnapInInterfacesEnum.DB_INFORMATION — режим обновления базы данных.

      При запросе конкретной функции модуль расширения может либо вернуть ссылку на объект, реализующий соответствующий интерфейс (если он выполняет эту функцию), либо вернуть null (если он не выполняет эту функцию).

DocsVision.Tools.ServerConsole.IDBInformation — данный интерфейс является обязательным для модулей расширения, которые выполняют функции конфигурации или удаления решения. Методы данного интерфейса предназначены для загрузки каких-либо значений в базу данных (это необходимо, например, при установке новых библиотек карточек, или шлюзов Workflow).

Обратите внимание на то, что для работы (например, обновление базы данных) с собственной библиотекой карточек из программы Консоль настройки Docsvision, необходимо разработать и загрузить в Консоль настройки Docsvision расширение Windows-клиента, которое реализует интерфейс IDBInformation. Данное расширение должно возвращать схему разработанной библиотеки карточек.
Интерфейс предполагает реализацию следующих свойств и методов:

  • GetScript(ScriptTypeEnum type) — Консоль настройки Docsvision может вызвать данный метод при выполнении каких-либо действий с базой данных.

    В зависимости от типа действия, модуль расширения должен вернуть одно из следующих значений:

    • INSTALL_TABLES — путь к файлу SQL-скрипта создания таблиц (для библиотек карточек).

    • INSTALL_ACTIONS — путь к файлу SQL-скрипта создания хранимых процедур (для библиотек карточек).

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

    • UNINSTALL_FT_CATALOGS — путь к файлу SQL-скрипта удаления полнотекстовых каталогов.

    • UNREGISTER_CARD_LIBRARY — путь к файлу SQL-скрипта удаления библиотеки карточек.

    • UNINSTALL_ALL — путь к файлу SQL-скрипта удаления других данных решения.

  • GetCardPackage() — возвращает путь к файлу — пакету инсталлируемых XML-описаний карточек. Это может потребоваться в случае, если для корректной работы решения необходимо наличие в базе данных каких-то предопределённых значений — заполненных справочников, шаблонов карточек и прочих.

    Файл с описанием пакета имеет следующий формат:
    <?xml version="1.0" encoding="UTF-8"?>
<CardPackage>
 <Card Path="xmlpath" ID="cardid" Replace="1"/> (1)
 …
</CardPackage>
    1 xmlpath — Путь к файлу .xml.

    cardid — ID карточки.

    Replace="1" — если карточка должна заменить существующую, Replace="0" — если дополнить.

  • ContainsCardLib — признак, содержит ли данное решение библиотеку карточек (нужно ли запрашивать SQL-скрипты для создания таблиц и хранимых процедур).

DocsVision.Tools.ServerConsole.IConfigurator — необязательный интерфейс. Может быть реализован в модуле расширения, выполняющем функции первичной конфигурации решения (SnapInInterfacesEnum.CONFIGURATOR).

Интерфейс предполагает реализацию следующего метода:

  • Execute() — единственный метод, который должен выполнять все задачи по корректной инсталляции решения. Возвращаемое значение показывает успешность (true) или неудачу (false) установки.

DocsVision.Tools.ServerConsole.IUninstallSnapIn — необязательный интерфейс. Может быть реализован в модуле расширения, выполняющем функции удаления решения (SnapInInterfacesEnum.UNINSTALL_SNAP_IN).

Интерфейс предполагает реализацию следующего метода:

  • Uninstall(Boolean) — единственный метод, который должен выполнять все задачи по корректному удалению решения. Входящий параметр указывает на необходимость удалить (true) или сохранить (false) настройки решения.

DocsVision.Tools.ServerConsole.ITools — необязательный интерфейс. Может быть реализован в модуле расширения, дополняющим Консоль настройки Docsvision специфическими Инструментами (SnapInInterfacesEnum.TOOLS).

Интерфейс предполагает реализацию следующего свойства:

  • Controls — возвращает массив элементов управления для конкретных инструментов. Элемент управления для реализации каждого инструмента должен реализовывать интерфейс IControl (IControl2).

DocsVision.Tools.ServerConsole.IConsoleControl — необязательный интерфейс. Может быть реализован в элементе управления, который будет отображаться пользователю при установке в режиме мастера (SnapInInterfacesEnum.WIZARD_CONTROL) или в режиме администрирования (SnapInInterfacesEnum.CONSOLE_CONTROL).

Интерфейс предполагает реализацию следующих свойств и методов:

  • ControlChanged — событие, которое элемент управления должен инициировать при изменении данных.

  • Caption — свойство, возвращающее отображаемое имя элемента управления.

  • Instance — свойство, возвращающее ссылку на элемент управления WinForms.

  • Changed — признак изменения настроек решения.

  • Valid — признак корректности указанных настроек решения.

  • Initialize() — метод первичной инициализации элемента управления.

  • Execute() — метод, вызываемый при завершении конфигурирования.

Пример кода модуля расширения с реализацией этих интерфейсов:
namespace DocsVision.Sample.SnapIn
{
 public class SnapIn : ISnapIn, IConfigurator, IUninstallSnapIn
 {
  private IEnvironment _environment;

  public SnapIn() { } (1)

  public string Name
  {
   get { return "My Snap-In"; }
  }

  public string LibraryID
  {
   get { return "00000000-0000-0000-0000-000000000000"; }
  }

  public void Initialize(IEnvironment environment)
  {
   _environment = environment;
  }

  public object QueryInterface(SnapInInterfacesEnum itfType)
  {
   object result = null;
   switch (itfType)
   {
    case SnapInInterfacesEnum.CONFIGURATOR:
    case SnapInInterfacesEnum.UNINSTALL_SNAP_IN:
     result = this;
     break;
   }
   return result;
  }

  public bool Execute() (2)
  {

   return true; (3)
  }

  public void Uninstall(bool removeSettings) (4)
  {
(5)
  }
 }
}
1 Реализация интерфейса ISnapIn.
2 Реализация интерфейса IConfigurator.
3 Регистрация компонент решения.
4 Реализация интерфейса IUninstallSnapIn.
5 Разрегистрация компонент решения.

В коде модуля расширения, можно обращаться к различным вспомогательным сервисам, которые предоставляет Консоль настройки Docsvision для упрощения решения типовых задач. Чтобы обратиться к сервисам, воспользоваться ссылкой на объект контекста (IEnvironment), ссылка передается модулю расширения при инициализации. Этот объект имеет единственный метод: QueryService(EnvironmentServiceEnum service) — возвращающий ссылку на конкретный вспомогательный сервис, запрошенный в параметре.

Доступны следующие сервисы:

  • EnvironmentServiceEnum.LOg — возвращает ссылку на сервис ILog, позволяющий записывать сообщения в общий журнал работы Консоли настройки.

  • EnvironmentServiceEnum.COMMON_SETTINGS — возвращает ссылку на сервис ICommonSettings2, позволяющий прочитать и/или изменить основные настройки сервера Docsvision.

  • EnvironmentServiceEnum.WORKER_PROCESS — возвращает ссылку на сервис IWorkerProcess, позволяющий модулю расширения корректно функционировать при выполнении длительных операций (например, отображать индикатор прогресса выполнения). Для реализации таких операций, соответствующие объекты модуля расширения должны реализовывать интерфейс ILengthyOperation3.

  • EnvironmentServiceEnum.DB_INSTALLER — возвращает ссылку на сервис IDbInstaller, позволяющий выполнять операции с базой данных (например исполнить сценарий SQL из строки или из файла).

  • EnvironmentServiceEnum.CARD_LIB_CONFIGURATOR — возвращает ссылку на сервис ICardLibConfigurator2, позволяющий корректно установить или удалить описание библиотеки карточек.

  • EnvironmentServiceEnum.CARD_IMPORTER — возвращает ссылку на сервис ICardImporter, позволяющий загрузить в базу данных предопределённые значения (экспортированные в формат XML).

  • EnvironmentServiceEnum.MANAGEMENT — возвращает ссылку на сервис IManagement, позволяющий управлять работой других сервисов и решений.

Пример использования вспомогательного сервиса Консоли настройки в модуле расширения для записи сообщения в журнал:

ILog log = (ILog)_environment.QueryService(EnvironmentServiceEnum.LOG);
log.WriteMessage("Конфигурирование решения успешно завершено");

Разработанный модуль расширения необходимо зарегистрировать на сервере в процессе инсталляции серверной части решения. Для этого программа инсталляции должна создать в реестре ключ в ветке HKEY_LOCAL_MACHINE\Software\DocsVision\ВЕРСИЯ\Console\Snap-Ins.

Необходимо создать ключ с именем своего модуля расширения, в котором создать два строковых значения:

  • Path — полный путь к сборке, в которой реализован модуль расширения.

  • TypeName — имя основного класса, реализующего интерфейс ISnapIn в разработанном модуле расширения (например, DocsVision.Sample.SnapIn.SnapIn).

Чтобы запустить Консоль настройки Docsvision в режиме конфигурирования нового модуля расширения, необходимо запустить её исполняемый файл с ключами: ServerConsole.exe /c /n ИМЯ_РЕШЕНИЯ. Вызов этой команды можно сделать последним шагом программы инсталляции серверной части решения.