Руководство разработчика на платформе DocsVision
реклама
DocsVision 4.5
Руководство разработчика
на платформе
Пособие для партнёров DocsVision
Copyright © DocsVision, 2002–2008. Все права защищены
v.4.5.0
СОДЕРЖАНИЕ
Введение ............................................................................................................... 6
1
Основные задачи разработки на платформе ................................................. 7
2
Компоненты платформы DocsVision .............................................................. 7
3
2.1
Архитектура системы .................................................................................... 7
2.2
Модули системы ........................................................................................... 8
2.2.1
Сервер хранилища ................................................................................. 8
2.2.2
Менеджер прав ...................................................................................... 9
2.2.3
Менеджер объектов ................................................................................ 9
2.2.4
Системные объекты .............................................................................. 10
Разработка карточек и решений .................................................................. 12
3.1
Основные понятия ...................................................................................... 12
3.2
Разработка схемы данных ........................................................................... 13
3.2.1
Подготовка базы данных ...................................................................... 14
3.2.2
Подготовка библиотеки карточек .......................................................... 18
3.2.3
Создание и редактирование схемы данных ............................................ 20
3.2.4
Погрузка схемы в базу данных .............................................................. 38
3.3
3.3.1
Реализация стандартных интерфейсов .................................................. 40
3.3.2
Обработка событий .............................................................................. 43
3.3.3
Использование элементов управления ................................................... 47
3.4
4
Разработка компонента карточки ................................................................ 39
Компонент библиотеки карточек ................................................................. 72
Решение типовых задач ............................................................................... 74
4.1
Управление сессиями ................................................................................. 75
4.2
Описание мета-данных ............................................................................... 78
4.3
Доступ к данным ........................................................................................ 81
4.3.1
Типы и экземпляры карточек ................................................................ 82
4.3.2
Иерархия строк .................................................................................... 83
4.3.3
Загрузка данных .................................................................................. 84
4.3.4
Данные карточки ................................................................................. 85
4.3.5
Данные секции .................................................................................... 86
4.3.6
Данные подсекции ............................................................................... 87
4.3.7
Строка данных ..................................................................................... 88
4.3.8
Коллекция строк .................................................................................. 90
4.3.9
Поле строки ......................................................................................... 90
4.3.10
4.4
Кэширование данных ........................................................................ 91
Использование ссылок ............................................................................... 91
4.4.1
Простая ссылка .................................................................................... 91
4.4.2
Слабая ссылка ..................................................................................... 92
DocsVision 4.5: Руководство разработчика на платформе
2
4.4.3
Сильная ссылка ................................................................................... 92
4.4.4
Автоматическая ссылка ........................................................................ 93
4.4.5
Ссылки на строки ................................................................................. 93
4.5
Работа с папками и ярлыками ..................................................................... 93
4.5.1
Карточка папок .................................................................................... 93
4.5.2
Папка .................................................................................................. 95
4.5.3
Ярлык ................................................................................................. 99
4.6
Режим отложенных изменений ................................................................... 101
4.7
Реализация блокировок ............................................................................. 103
4.8
Использование поиска ............................................................................... 105
4.8.1
Серверный поиск ................................................................................ 105
4.8.2
Карточка сохраненных поисковых запросов.......................................... 114
4.8.3
Утилита Search Utility .......................................................................... 115
4.8.4
Клиентская фильтрация ...................................................................... 118
4.9
Работа с файлами...................................................................................... 119
4.9.1
Системный объект — файл................................................................... 120
4.9.2
Внешнее хранение файлов .................................................................. 121
4.9.3
Системный объект — версия файла ...................................................... 122
4.9.4
Системная карточка файла .................................................................. 123
4.10
Использование нумераторов ................................................................... 124
4.10.1
Карточка нумератора ....................................................................... 125
4.10.2
Зона нумератора .............................................................................. 126
4.10.3
Диапазон нумератора ....................................................................... 126
4.11
Экспорт, импорт и печать ...................................................................... 127
4.11.1
Экспорт ........................................................................................... 127
4.11.2
Импорт ............................................................................................ 128
4.11.3
Печать ............................................................................................ 130
4.12
Работа с правами ................................................................................... 131
4.12.1
Администрирование прав ................................................................. 131
4.12.2
Программное назначение прав .......................................................... 133
4.13
ЭЦП и шифрование ................................................................................ 139
4.14
Журналирование .................................................................................... 141
4.14.1
Стратегия журнала ........................................................................... 143
4.14.2
Запись в журнал .............................................................................. 144
4.14.3
Получение сообщений ...................................................................... 145
4.14.4
Удаление сообщений ........................................................................ 146
4.14.5
Экспорт и импорт журнала ............................................................... 147
4.15
Работа с представлениями ...................................................................... 147
4.15.1
Описание (схема) данных представления .......................................... 148
DocsVision 4.5: Руководство разработчика на платформе
3
4.15.2
Описание (схема) форматирования ................................................... 155
4.15.3
Получение данных представления .................................................... 158
4.16
Хранимые процедуры ............................................................................. 160
4.16.1
Создание хранимой процедуры ......................................................... 160
4.16.2
Вызов хранимых процедур и получение данных ................................. 162
4.17
5
Расширения Навигатора ......................................................................... 163
4.17.1
Интерфейс карточки-расширения ..................................................... 163
4.17.2
Расширение виртуальных папок ........................................................ 165
4.17.3
Расширение экспорта ....................................................................... 165
4.17.4
Командное расширение .................................................................... 166
4.17.5
Обработчик событий ........................................................................ 168
4.17.6
Пикер .............................................................................................. 168
4.17.7
Контроль папки ............................................................................... 169
4.17.8
Страницы свойств ............................................................................ 170
4.17.9
Расширение типов карточек.............................................................. 171
4.17.10
Расширение типов папок .................................................................. 172
4.18
Серверные расширения .......................................................................... 172
4.19
Пользовательские сценарии.................................................................... 175
4.20
Методы контейнера карточек .................................................................. 179
Отладка и тестирование ............................................................................. 183
5.1
Соединение с сервером ............................................................................. 183
5.2
Список сессий ........................................................................................... 184
5.3
Настройки сессии ...................................................................................... 185
5.4
Список блокировок ................................................................................... 185
5.5
Системный журнал .................................................................................... 186
5.6
Права доступа к объектам ......................................................................... 186
5.7
Работа с файлами...................................................................................... 187
5.8
Информация о файле ................................................................................ 188
5.9
Описания карточек ................................................................................... 188
5.9.1
Структура секций карточки ................................................................. 189
5.9.2
Действия и режимы карточки ............................................................... 189
5.9.3
XML-описание карточки ....................................................................... 190
5.9.4
XSD-описание данных карточки ........................................................... 190
5.9.5
Трансформации карточки .................................................................... 191
5.9.6
Работа с экземплярами карточек .......................................................... 191
5.9.7
Поиск карточек ................................................................................... 192
5.9.8
Просмотр XML-представления данных карточки .................................... 193
5.9.9
Просмотр HTML-представления данных карточки .................................. 193
5.9.10
Просмотр ссылок на карточку ........................................................... 194
DocsVision 4.5: Руководство разработчика на платформе
4
6
7
5.9.11
Работа с данными карточки .............................................................. 195
5.9.12
Работа с компонентом карточки ........................................................ 196
Распространение решения ......................................................................... 197
6.1
Инсталляция серверной части решения ...................................................... 197
6.2
Модуль расширения Консоли настройки ..................................................... 198
6.3
Инсталляция клиентской части решения ..................................................... 202
Приложения ................................................................................................ 205
7.1
Параметры соединения .............................................................................. 205
7.2
Свойства сессии ........................................................................................ 206
7.3
Параметры выбора справочников ............................................................... 207
DocsVision 4.5: Руководство разработчика на платформе
5
ВВЕДЕНИЕ
Настоящий документ предназначен для разработчиков приложений на платформе
DocsVision.
Документ освещает следующие вопросы:
обзор архитектуры платформы;
правила разработки, отладки и использования карточек и решений;
описания интерфейсов, свойств и методов объектов системы;
примеры кода.
Документ содержит следующие разделы:
в разделе 1 «Основные задачи разработки на платформе» приводится перечень
типовых задач разработки на платформе DocsVision;
раздел 2 «Компоненты платформы DocsVision» содержит описания архитектуры и
основных модулей системы;
раздел 3 «Разработка карточек и решений» посвящён описанию процедур создания
новых решений путём разработки новых или модификации существующих карточек;
раздел 4 «Решение типовых задач» содержит описания работы с сессиями, доступа
к данным карточек, использования ссылок, работы с папками и ярлыками, работы с
файлами, управления правами и других типовых задач;
раздел 4.20 «Методы контейнера карточек
При разработке визуального интерфейса карточек или приложений, работающих с
DocsVision, часто возникает необходимость взаимодействия с контейнером карточек
(Навигатором) для решения одной из следующих задач:
Выбор карточки
Выбор папки
Отображение конкретной карточки
Навигация по дереву папок
И т.д.
Для решения этих задач можно использовать методы объекта – контейнера
карточек (DocsVision.Platform.WinForms.CardHost).
Ссылку на этот объект все карточки получают в момент инициализации, и
впоследствии она доступна в любой момент жизненного цикла карточки через
соответствующее свойство базового класса – CardControl.CardHost.
В случае разработки внешних приложений и утилит, которые работают вне
контекста Навигатора, этот объект необходимо создавать явно. Для этого предназначен
метод CreateInstance(DocsVision.Platform.ObjectManager.UserSession session). На вход метода
достаточно передать ссылку на текущую сессию (session). Пример создания объектаконтейнера карточек:
SessionManager manager = SessionManager.CreateInstance();
manager.Connect("http://localhost/DocsVision41/StorageServer/StorageServerSer
vice.asmx", string.Empty);
UserSession session = manager.CreateSession();
CardHost host = CardHost.CreateInstance(session);
Объект контейнера карточек предлагает следующие методы:
DocsVision 4.5: Руководство разработчика на платформе
6
System.Guid SelectCard(string caption) – открытие на выбор экземпляра любой карточки. Окно
выбора будет иметь заголовок caption
System.Guid SelectCard(string caption, string filter) – открытие на выбор экземпляра карточки
по фильтру filter (XML поискового запроса) . Окно выбора будет иметь заголовок caption
System.Guid[] SelectCards(string caption) - открытие на выбор нескольких экземпляров любых
карточек. Окно выбора будет иметь заголовок caption
System.Guid[] SelectCards(string caption, string filter) - открытие на выбор нескольких
экземпляров карточек по фильтру filter (XML поискового запроса) . Окно выбора будет иметь
заголовок caption
System.Guid SelectFolder(string caption) – выбор папки
System.Guid SelectFolder(string caption, int allowedTypes) – выбор папки конкретного типа
(allowedTypes – битовая маска из значений
DocsVision.Platform.ObjectManager.SystemCards.FolderTypes)
System.Guid SelectFolder(string caption, int allowedTypes, System.Guid currentFolderId) - выбор
папки конкретного типа (allowedTypes), при этом изначальная позиция определяется папкой
currentFolderId
object SelectFromCard(System.Guid cardId, string caption) – отображение карточки (cardId) в
режиме выбора значений (строк). Для работы с этим методом, в описании карточки должен
быть установлен признак “Из этой карточки могут быть выбраны элементы”
object SelectFromCard(System.Guid cardId, string caption, object activateParams) - отображение
карточки (cardId) в режиме выбора значений (строк) с передачей дополнительных параметров
выбора (activateParams). Метод возвращает выбранне значения (строку) или несколько строк
ПРИМЕЧАНИЕ
Примеры параметров для выбора значений из справочников типового решения
Делопроизводство приведены в приложении 7.3
object SelectFromCard(System.Guid cardId, string caption, object activateParams, out object
resultParams) - отображение карточки (cardId) в режиме выбора значений (строк) с передачей
дополнительных параметров выбора (activateParams). Метод возвращает выбранне значения
(строку) или несколько строк, а также дополнительные данные (resultParams)
ПРИМЕЧАНИЕ
1. Параметры активации (ActivateParams) указываются вызывающей
стороной и доступны в карточке через соответствующее свойство.
2. Результат открытия (SelectedValue) указывается в коде карточки при
помощи вызова FinishSelection или CloseAndCreateNew. Вызывающая
сторона получает его как возвращаемое значение метода SelectFromCard.
Если для открытия карточки используется другой метод – значение
теряется.
3. Возвращаемые параметры (ResultParams) также передаются при помощи
вызова FinishSelection или CloseAndCreateNew. Вызывающая сторона
получает их как Out-параметр метода SelectFromCard. Вы также можете
использовать вариант метода SelectFromCard без этого параметра – в этом
случае значение теряется.
4. Если для открытия карточки используется метод ShowCardModal, то
возвращаемое значение будет True в том случае, если в обработчике
события CardClosing карточка выставила флаг ActionFlags.CommittedData.
Во всех остальных случаях вернется False.
ShowCard(System.Guid cardId, DocsVision.Platform.WinForms.ActivateMode activateMode) –
отображает (немодально) пользовательский интерфейс карточки cardId в режиме контейнера
activateMode
DocsVision 4.5: Руководство разработчика на платформе
7
ShowCard(System.Guid cardId, System.Guid modeId,
DocsVision.Platform.WinForms.ActivateMode activateMode) - отображает (немодально)
пользовательский интерфейс карточки cardId в режиме самой карточки modeid и режиме
контейнера activateMode
ShowCard(System.Guid cardId, System.Guid modeId,
DocsVision.Platform.WinForms.ActivateMode activateMode, object activateParams) - отображает
(немодально) пользовательский интерфейс карточки cardId в режиме самой карточки modeid и
режиме контейнера activateMode, с дополнительными параметрами activateParams
(вызываемая карточка трактует эти параметры по своему усмотрению)
bool ShowCardModal(System.Guid cardId, DocsVision.Platform.WinForms.ActivateMode
activateMode) - отображает модально пользовательский интерфейс карточки cardId в режиме
контейнера activateMode
bool ShowCardModal(System.Guid cardId, System.Guid modeId,
DocsVision.Platform.WinForms.ActivateMode activateMode) - отображает модально
пользовательский интерфейс карточки cardId в режиме самой карточки modeid и режиме
контейнера activateMode
bool ShowCardModal(System.Guid cardId, System.Guid modeId,
DocsVision.Platform.WinForms.ActivateMode activateMode, object activateParams) - отображает
модально пользовательский интерфейс карточки cardId в режиме самой карточки modeid и
режиме контейнера activateMode, с дополнительными параметрами activateParams
(вызываемая карточка трактует эти параметры по своему усмотрению)
DocsVision.Platform.WinForms.MessageResult ShowMessage(string caption, string text, string
details, DocsVision.Platform.WinForms.MessageType messageType,
DocsVision.Platform.WinForms.MessageButtons buttons, System.IntPtr hWnd) – отображение
контейнером сообщения:
o
Caption – заголовок сообщения
o
Text – текст сообщения
o
Details – детали сообщения (отображаются по кнопке Подробно)
o
messageType – тип сообщения (Error, Information, Question, Warning)
o
buttons – кнопки сообщения
o
hWnd –хэндл текущего окна (для правильного определения модальности сообщения)
System.Uri GetCardUrl(System.Guid cardId, System.Guid modeId) – получение полного URLадреса карточки с идентификатором cardId в режиме modeId
System.Uri GetShortcutUrl(System.Guid folderId, System.Guid viewId, System.Guid shortcutId) –
получение полного URL-адреса ярлыка shortcutId лежащего в папке folderId и представлении
viewed
Помимо контейнера, в карточку также передается ссылка на другой объект –
текущее окно, в котором открыта карточка (CardFrame). Этот объект позволяет
выполнять действия с окном:
-
Закрыть окно
-
Задать заголовок окна
-
Открыть карточку в новом окне
-
И т.д.
ПРИМЕЧАНИЕ
При разработке внешних приложений и утилит получить ссылку на объект
CardFrame невозможно, т.к. они работают вне контекста контейнера
DocsVision 4.5: Руководство разработчика на платформе
8
(Навигатора).
Основные свойства и методы объекта CardFrame:
string Caption – свойство позволяет прочитать или установить заголовок окна
bool Visible – свойство позволяет показать или скрыть текущее окно
System.IntPtr Handle – hWnd окна
Close() – немедленное закрытие текущего окна
CloseAndCreateNew(System.Guid modeId) – закрытие этого окна, и создание нового
экземпляра карточки в новом окне (аналог команды ”Сохранить и создать новую” в
карточку Делопроизводства)
CloseAndCreateNew(System.Guid modeId, object resultParams) – то же что и предыдущий,
но с передачей новой карточке дополнительных параметров
Commit(DocsVision.Platform.WinForms.ActionFlags flags) – завершает работу карточки с
сохранением изменений
FinishSelection(object selectedValue) – завершает выбор, если карточка была открыта на
выбор (SelectFromCard); параметр selectedValue – возвращаемое значение выбора
FinishSelection(object selectedValue, object resultParams) – то же что и предыдущий, но
позволяет вернуть несколько результатов выбора
Refresh() – обновление окна
DocsVision.Platform.WinForms.MessageResult ShowMessage(string caption, string text,
string details, DocsVision.Platform.WinForms.MessageType messageType,
DocsVision.Platform.WinForms.MessageButtons buttons) – отображение сообщения,
модального по отношению к текущему окну (остальные параматеры аналогичны
соответствующему методу CardHost)
Пример кода работы с окном:
private void txtName_TextChanged(object sender, EventArgs e)
{
// при изменении названия карточки меняется заголовок окна
CardFrame.Caption = txtName.Text;
isChanged = true;
}
Отладка и тестирование» посвящён описанию процедур отладки и тестирования
разработанных решений;
раздел 6 «Распространение решения» содержит рекомендации по разработке
инсталляционных пакетов для распространения и установки серверных и
клиентских компонентов созданных решений;
раздел 7 «Приложения» содержит справочную информацию об используемых
терминах, описания стандартных интерфейсов и свойств пользовательской сессии.
Перед использованием данного руководства рекомендуется ознакомиться с
документом «Руководство пользователя DocsVision», раздел «Платформа». Желательно
также наличие навыков разработки кода в среде Microsoft .NET.
Дополнительное справочное руководство, описывающее поля системных карточек
платформы, а также стандартных карточек типовых решений «Делопроизводство» и
«Управление процессами», содержится в документе «Описание полей стандартных
карточек».
DocsVision 4.5: Руководство разработчика на платформе
9
1
ОСНОВНЫЕ ЗАДАЧИ РАЗРАБОТКИ НА ПЛАТФОРМЕ
Разработка на платформе DocsVision чаще всего выполняется в целях решения
одной из следующих задач:
Создание собственных карточек и решений (наборов карточек).
Это наиболее распространенная задача. Она возникает в тех случаях, когда
функциональности карточек, входящих в стандартную поставку системы,
недостаточно для решения конкретных бизнес-задач (необходимо наличие
дополнительных полей, логики их обработки, элементов пользовательского
интерфейса и т.д.).
Разработка сценариев в карточках.
Сценарии (VBA) в стандартных карточках приложения «Делопроизводство»
позволяют
расширить
их
функциональность
штатным
образом,
без
необходимости разработки собственных решений.
Разработка сценариев в бизнес-процессах.
Сценарии (скрипты) в бизнес-процессах являются одним из способов
реализации специфических действий, не предусмотренных стандартными
функциями бизнес-процессов. Если сценарий должен оперировать с данными в
системе DocsVision на низком уровне, потребуется знание объектной модели
платформы.
Разработка прикладных приложений (утилит).
Разработка внешних по отношению к DocsVision приложений, выполняющих
какие-либо действия в системе. Чаще всего ими являются средства интеграции с
другими системами (синхронизация справочных данных). Примерами таких
утилит могут выступать приложения для импорта данных в справочники
сотрудников и контрагентов, входящие в пакет разработчика.
ВНИМАНИЕ
Модификация карточек и решений, входящих в стандартную поставку системы
DocsVision («Делопроизводство» и «Управление процессами»), не допускается ни
при каких условиях. Их исходный код не подлежит распространению.
2
2.1
КОМПОНЕНТЫ ПЛАТФОРМЫ DOCSVISION
АРХИТЕКТУРА СИСТЕМЫ
Система DocsVision предназначена для построения решений автоматизации
документооборота внутри предприятий и организаций. Она обеспечивает максимально
быструю подготовку и удобное развертывание решений у заказчика. Это достигается
тремя способами:
установка и модификация системы на клиентском компьютере осуществляется
автоматически;
подготовка решений сводится к созданию объектов, соответствующих сущностям
целевой системы (далее — карточек). Эти готовые объекты легко встраиваются в
систему, благодаря поддержке единых интерфейсов и методов доступа;
разработка объектов (карточек) упрощена за счет того, что платформа
предоставляет полноценную объектную модель для автоматизации типовых
операций.
Кроме того,
поддерживать:
в
систему
заложены
возможности
расширения,
позволяющие
большие документы (содержащие большие объёмы данных);
DocsVision 4.5: Руководство разработчика на платформе
10
большое количество документов;
большое количество одновременных пользовательских сессий.
2.2
МОДУЛИ СИСТЕМЫ
Система DocsVision состоит из трех частей:
ядро;
системные модули;
прикладные модули.
Рис. 2.1. Архитектура системы
Ядро системы представляет собой компактную часть системы, которая выполняет
все служебные и сервисные задачи. Функции ядра:
обеспечить доступ к данным системы;
обеспечить взаимодействие модулей между собой;
обеспечить
исполнение
предопределённых
модификации и извлечения данных.
алгоритмов
в
процессе
Системные модули реализуют базовую функциональность, такую как управление
пользователями и правами, управление объектами, работа с журналом событий,
базовые функции работы с файлами и прочие.
Прикладные модули (пользовательские карточки) предназначены для решения
конкретных прикладных задач, например, автоматизации архива, канцелярии или
приложения класса CRM.
2.2.1 Сервер хранилища
Сервер системы хранит данные карточек, возвращает или обновляет данные по
запросу клиента. Логические структуры данных и хранимые процедуры для доступа к
ним создаются программно на основе мета-информации о типе и строении данных
карточки.
DocsVision 4.5: Руководство разработчика на платформе
11
Сервер хранилища — это промежуточный уровень между сервером SQL и
клиентским приложением.
Сервер реализует:
Управление сессиями клиентов.
Доступ к данным и контроль доступа — блокировки уровня сессии и уровня
check-in/check-out.
Работу с курсором и постраничную выдачу результата клиенту.
Управление наборами данных активных карточек.
Сервисные функции.
2.2.2 Менеджер прав
Сервер осуществляет проверку прав пользователя при доступе к каждому
ресурсу. Система поддерживает многоуровневую систему прав доступа к отдельным
элементам системы: папки, карточки, секции и строки карточек, режимы,
представления, действия карточек и прочее. При входе в систему пользователь
проходит аутентификацию, после чего наличие соответствующего уровня прав
(авторизация) проверяется при доступе к каждому ресурсу.
Удобным методом поддержания многоуровневых прав является встроенная
система безопасности Windows. Эта система позволяет создавать и использовать
пользовательскую иерархию прав, которые могут наследоваться. При этом объекты, с
которыми ассоциируются описатели прав (security descriptors), находятся целиком в
ведении пользователя. Каждый дескриптор содержит список (ACL) отдельных прав
(ACE) на доступ к ресурсу.
Более подробно о подобной схеме организации прав можно прочесть в MSDN.
2.2.3 Менеджер объектов
Менеджер объектов (Object Manager) используется всеми клиентскими
компонентами системы в качестве источника информации и является единственным
средством взаимодействия с сервером хранилища. Он также обеспечивает открытие и
закрытие сессии пользователя.
Менеджер объектов (OM) обеспечивает:
поддержку сессий;
доступ к данным (реализует клиентскую часть диалога с сервером хранилища);
управление объектами (в том числе запуск карточек).
менеджер объектов состоит из следующих подсистем:
менеджер сессий (SessionManager);
менеджер карточек (CardManager);
менеджер объектов безопасности (AccessManager);
менеджер файлов (FileManager);
менеджер блокировок (LockManager);
менеджер журнала (LogManager);
менеджер пользовательских профилей (ProfileManager);
менеджер хранимых процедур (ReportManager);
менеджер расширений (ExtensionManager).
Интерфейсы и методы менеджера объектов используются
пользовательских карточек для взаимодействия с ядром системы.
DocsVision 4.5: Руководство разработчика на платформе
при
разработке
12
2.2.4 Системные объекты
Системные объекты — это модули, реализованные в виде карточек, которые
исполняют системные функции и необходимы для корректной работы системы.
К числу системных карточек относятся:
Навигатор;
Папки;
Нумераторы;
Представления;
Файл с версиями;
Поиск;
Настройки пользователя (профиль).
2.2.4.1 Навигатор
Навигатор — важнейшая карточка системы, предоставляющая пользователю
интерфейс для просмотра хранимых в системе объектов и организации их в иерархии
при помощи папок. Папки содержат ярлыки, ссылающиеся на карточки (аналогично
ярлыкам файлов в системе Windows).
Навигатор позволяет пользователю и администратору системы создавать и
настраивать папки, представления и другие аспекты работы Навигатора. Возможности
настройки и видимость ресурса определяются наложенными на него правами.
Навигатор отвечает за отображение иерархии пользовательских карточек и
предоставляет пользователю интерфейс, обеспечивающий:
использование и активизацию карточек и их функций;
создание и удаление карточек;
поиск карточек.
Интерфейс Навигатора похож на интерфейс приложений Outlook и Windows
Explorer: на левой панели отображается дерево ресурсов (папок с карточками), а в
правой представление текущего ресурса (папки). Кроме этого, на правой панели может
быть включено окно предварительного просмотра для отображения карточки,
выбранной в данный момент в таблице представления. Это окно предоставляет
подмножество функций «полного» пользовательского интерфейса карточки.
2.2.4.2 Нумератор
Эта карточка предоставляет компонентам системы интерфейсы для использования
функций работы с сериями уникальных номеров-идентификаторов, которые могут быть
применены для нумерации документов.
Часто необходимо сформировать номер до сохранения документа в базе данных,
основываясь на определённом алгоритме выдачи номеров. Кроме того, в прикладных
задачах распространено «резервирование» блока номеров – закрепление некоторого
интервала номеров за определённым пользователем.
Таким образом, номера могут быть либо заняты (использованы), либо
зарезервированы (для будущего использования). В последнем случае вместе с номером
хранится информация о пользователе, который зарезервировал этот номер.
2.2.4.3 Представления
Представление имеет вид таблицы с заранее определёнными полями, которая
отображает информацию о карточках. В основу предсталений DocsVision положены
представления из MS Outlook. Каждая строка представления описывает одну карточку.
В колонках представления отображаются данные. Это могут быть как
непосредственно данные самой карточки (извлеченные из её полей), так и данные
DocsVision 4.5: Руководство разработчика на платформе
13
других карточек или вычисляемые значения. Правила получения и форматирования
этих данных определяются настройками представления.
Для представлений существует возможность сортировки по нескольким столбцам,
а также группировки по нескольким стобцам (максимум по четырем). Также существует
возможность показа в представлении агрегированной информации по какому-либо
столбцу представления. Если осуществляется группировка, то агрегацию можно задать
также и для групп.
2.2.4.4 Файл с версиями
Эта карточка предоставляет компонентам системы интерфейсы для использования
расширенных функций работы с файлами - в частности, возможность поддерживать
иерархию версий файлов с комментариями.
Для каждого файла иерархии сохраняются пользовательский номер версии в
формате MAJOR.MINOR, а также автоматический порядковый номер версии. Этот номер
присваивается и увеличивается при сохранении каждой новой версии и не может быть
изменен пользователем.
Система DocsVision предлагает четыре варианта создания версий файла:
автоматически
(при
каждом
сохранении
файла)
обновляется
линейная
последовательность версий. Если обновляется одна из промежуточных версий, то
она становится последней версией файла;
автоматически (при каждом сохранении файла) обновляется дерево версий, так что,
если изменяется одна из предыдущих версий, она становится потомком того файла,
из которого получена;
поддерживается линейная последовательность
сохраняются только по запросу пользователя;
поддерживается дерево версий, но новые версии сохраняются только по запросу
пользователя.
версий,
но
новые
версии
2.2.4.5 Поиск
Модуль поиска предназначен для формирования описания последовательности
элементарных запросов к хранилищу данных системы, результатом которых является
определённое множество карточек. Этот же модуль является и хранилищем для
результатов запроса. Пользователи могут хранить составленный заранее запрос и по
необходимости вызывать его с новыми параметрами.
Модуль атрибутивного поиска позволяет производить поиск по множеству
карточек при помощи фильтров. Модуль хранит фильтры, так чтобы их можно было
вызвать по необходимости.
DocsVision 4.5: Руководство разработчика на платформе
14
3
3.1
РАЗРАБОТКА КАРТОЧЕК И РЕШЕНИЙ
ОСНОВНЫЕ ПОНЯТИЯ
Расширение системы происходит путем добавления новых пользовательских
модулей — карточек. Система изначально содержит ряд карточек, необходимых для её
работы. Такие карточки называются системными объектами.
В логическом смысле карточка представляет собой описание пользовательского
бизнес-объекта, содержащее в себе все необходимые данные и возможности для
выполнения операций над ними. Физически карточка — это совокупность программных
объектов (компонент), объектов в базе данных системы (таблиц и хранимых процедур),
а также мета-описание структур данных в XML формате.
Каждая карточка относится к одному из типов. Тип карточки — логическое
понятие, введенное с целью отличать разнородные карточки друг от друга. Каждый тип
имеет уникальное имя и идентификатор. При необходимости не только различать
отдельные карточки, но и группировать сходные карточки вместе, типы карточек
объединяются в библиотеки по их схожести для пользователя. Принадлежность типа
карточки к какой-либо библиотеке определяется автором карточки.
Следует различать тип карточки и экземпляр карточки. Регистрация новой
карточки в системе добавляет один новый тип, для которого впоследствии может быть
создано неограниченное количество экземпляров карточек. Все созданные экземпляры
будут принадлежать одному типу, то есть использовать для работы одни и те же
программные компоненты и структуры данных.
Все
экземпляры
карточек
обладают
уникальными
идентификаторами.
Идентификаторы используются для получения данных от сервера, для ссылок на
другие карточки и на данные карточек. Идентификатор — это обязательный атрибут
объектов системы, поддерживаемый самой платформой (то есть разработчик карточки
не должен явно резервировать место для хранения идентификаторов).
Программные
компоненты
карточки
реализуют
ряд
предопределенных
интерфейсов, предназначенных для их интеграции в среду DocsVision. Карточка может
также реализовывать собственные интерфейсы (например, для связи с другими
карточками). Как правило, модуль карточки также реализует пользовательский
интерфейс, позволяющий пользователю просматривать и редактировать содержимое
карточки.
Каждый тип карточки также может декларировать ряд действий, применимых для
данного типа. Под действиями в данном случае понимаются определённые команды,
«понятные» карточке - которые, будучи инициированы пользователем, приведут к
выполнению программными компонентами карточки некоторых операций.
Помимо карточек в системе определяется иерархия для их организации. Каждый
узел иерархии — это контейнер-папка, содержащая ссылки на карточки. Папка также
может содержать в себе подпапки. С точки зрения пользователя – это иерархия «папок,
содержащих карточки и другие папки», что очень похоже на представление
размещения файлов в файловой системе. Администратор может задавать категории или
типы карточек, которые могут храниться в конкретной папке. Вся информация о папках
и их иерархии хранится в области данных одной из системных карточек — карточке
папок.
Папки ссылаются на карточки посредством их идентификаторов, а также ряда
дополнительных атрибутов. Совокупность всех сведений об одной карточке в папке
представляет собой ярлык. Для каждого экземпляра карточки может существовать
неограниченное количество ярлыков, размещенных в разных папках.
Содержимое папки может быть представлено пользователю несколькими
способами, которые определяет администратор системы или сам пользователь.
Отображение содержимого папки одним из способов называется представлением.
Представление строится из отдельных элементов представления каждой карточки.
DocsVision 4.5: Руководство разработчика на платформе
15
Элемент представления — это набор данных карточки, который может отображаться в
папке одновременно.
При помощи представлений и связанного с ними интерфейса пользователь может
просматривать список карточек, осуществлять поиск, выбирать отдельные карточки и
исполнять над ними определённые действия, в том числе, «открывать» карточки —
запускать их пользовательский интерфейс. Карточка может поддерживать несколько
вариантов
пользовательского
интерфейса
или
способов
взаимодействия
с
пользователем — режимов. Информация о возможных режимах хранится в ярлыке
карточки. В разных режимах над карточками могут выполняться различные операции,
определённые разработчиком карточки.
Пользователь системы может создавать новые карточки известных системе типов
или удалять существующие карточки.
Рис. 3.1. Структура объектов
Сплошные стрелки соответствуют отношению «содержит» или «включает», а
пунктирные — ссылке или использованию.
3.2
РАЗРАБОТКА СХЕМЫ ДАННЫХ
Архитектура
DocsVision
предусматривает
строго
определённый
способ
взаимодействия ядра системы с пользовательскими карточками. Чтобы карточку можно
было использовать в системе, структуры данных карточки и её программные
компоненты должны соответствовать определённым стандартам.
Хранилище для данных карточки создается в базе данных DocsVision
автоматически. При этом в качестве исходных данных используется XML-файл с
описанием структуры данных - схема карточки, который должен быть подготовлен
заранее. Файл содержит сведения о количестве данных в карточке, их типах и связях
между ними. Фактически этот файл используется и при разработке программных
компонент карточки, так как многие функции системы используют в качестве
параметров вызова идентификаторы (GUID), которые закреплены за определёнными
секциями данных в файле описания структуры.
Схема данных карточки описывает разделы (секции), которые в свою очередь
состоят из строк. Под секциями понимаются группы данных, объединенных по общим
признакам (полям или атрибутам). Строки секций могут ссылаться на другие секции
(подчинённые секции). Для удобства организации данных выделяются три вида
секций:
Плоская секция – набор единичных значений атрибутов (полей);
DocsVision 4.5: Руководство разработчика на платформе
16
Коллекционная секция – таблица значений,
несколько строк с однотипными полями;
которая
может
содержать
Иерархическая секция – таблица, строки которой ссылаются друг на друга,
образуя древовидную (иерархическую) структуру. Поскольку каждая строкаузел может ссылаться на несколько дочерних строк, иерархическую секцию
можно представить себе как иерархию секций одного типа.
Рис. 3.2. Виды секций
Каждая секция имеет собственный уникальный идентификатор.
Схема также может определять виртуальные поля, которые используются при
построении представлений (отчётов). Каждое виртуальное поле описывает логическую
единицу данных карточки, значимую для пользователя (например, «Исполнители» или
«Статус связанного процесса»).
Кроме этого, схема карточки описывает возможные действия карточки с
указанием их уникальных идентификаторов, режимы работы карточки — возможные
варианты отображения её пользовательского интерфейса, преобразования данных
карточки — варианты трансформации данных в другой формат при помощи XSLT и
InfoPath-преобразований.
Разработка схемы карточки состоит из четырех основных этапов:
подготовка базы данных;
подготовка библиотеки карточек;
создание и редактирование схемы данных;
загрузка готовой схемы в базу данных.
Для выполнения всех этих операций используется приложение CardManager.
3.2.1 Подготовка базы данных
База данных DocsVison строится на платформе Microsoft SQL Server и состоит из
набора таблиц, индексов и хранимых процедур. Логически база данных содержит в
себе три вида объектов:
системные таблицы и хранимые процедуры, необходимые для корректной
работы ядра DocsVision;
данные системных карточек;
данные пользовательских карточек.
При стандартной установке сервера DocsVision из инсталляционного пакета база
данных создается автоматически и содержит системные карточки и карточки
стандартных
приложений
«Делопроизводство»
и
«Управление
процессами».
DocsVision 4.5: Руководство разработчика на платформе
17
Разработчик имеет возможность добавлять в установленную базу данных собственные
карточки или создать собственную базу данных и работать с ней.
Для создания, удаления и редактирования баз данных DocsVision используется
приложение CardManager (из пакета Resource Kit). Основное окно приложения
делится на две панели: дерево объектов и панель детальной информации. Дерево
объектов содержит информацию о зарегистрированных базах данных и библиотеках
карточек:
Рис. 3.3. Основное окно приложения CardManager
Перед началом работы с приложением необходимо подключиться к существующей
базе данных DocsVision или создать новую базу данных. Для этого нужно выбрать пункт
меню Register database и указать реквизиты подключения:
DocsVision 4.5: Руководство разработчика на платформе
18
Рис. 3.4. Подключение к базе данных
Необходимо указать название SQL-сервера, наименование базы данных DocsVision
(имя базы данных выбирается в процессе установки сервера DocsVision), имя
пользователя и пароль.
Для создания новой базы данных нужно выбрать пункт меню New database:
DocsVision 4.5: Руководство разработчика на платформе
19
Рис. 3.5. Создание новой базы данных
Необходимо указать имя создаваемой базы данных, имя сервера, на котором
создается база, язык полнотекстового индексирования (он будет использоваться для
полнотекстового поиска по данным карточек) и механизм аутентификации.
Дополнительные опции можно указать в диалоге по кнопке Advanced.
Удалить регистрацию базы данных из окна приложения можно при помощи
команды Unregister database. При этом сама база данных удалена не будет. Для того,
чтобы удалить её с SQL Server, необходимо выбрать пункт меню Delete database.
При создании новой базы данных требуется погрузить в неё необходимые для
работы ядра DocsVision таблицы и хранимые процедуры. Для этого нужно
воспользоваться командой Update database (см. рис. 3.6).
Этой же командой следует пользоваться при ручном обновлении ядра DocsVision.
После создания системных таблиц и хранимых процедур в базу данных
необходимо погрузить стандартные библиотеки карточек: «Системные карточки» (они
необходимы для корректного функционирования Навигатора), «Делопроизводство» и
«Управление процессами» (если предполагается использование карточек стандартных
решений).
DocsVision 4.5: Руководство разработчика на платформе
20
Рис. 3.6. Обновление системных объектов
3.2.2 Подготовка библиотеки карточек
Описания схем карточек хранятся в библиотеках карточек.
Библиотека объединяет несколько описаний карточек в одну логическую единицу
– решение. Например, системные карточки объединяются в одну библиотеку, а
карточки решения «Делопроизводство» - в другую. В большинстве случаев одно
разрабатываемое решение на платформе DocsVision соответствует одной библиотеке.
При последующем распространении библиотеки карточек устанавливаются на
клиентские компьютеры целиком. Библиотека отображается в качестве родительской
ветки для входящих в неё карточек в дереве карточек в Навигаторе (ветка Карточки).
Каждая библиотека карточек имеет описание (схему), собственный программный
компонент, иконку и установочный пакет (подробнее о компонентах библиотек — в
разделе «Все параметры также доступны для последующего изменения в виде свойств
объекта ReportDataSource:
ReportID – идентификатор хранимой процедуры
Parameters – коллекция значений параметров процедуры
3.2.2.1 Элементы управления DocsVision
Как показывает практика, далеко не все задачи можно решить при помощи
технологии связывания данных Data Binding. Например, невозможно корректно
отобразить иерархические данные в виде дерева – потому что стандартный элемент
управления TreeView просто не поддерживает Data Binding. Кроме того, область
применения источников данных ограничена задачами просмотра и редактирования
упорядоченных наборов данных (строк, карточек) – тогда как типичные практики
предусматривают и другие способы взаимодействия с пользователем (например, выбор
каких-либо объектов при помощи специализированного браузера).
DocsVision 4.5: Руководство разработчика на платформе
21
Для решения некоторых из этих задач, DocsVision предлагает несколько
вспомогательных элементов управления собственной разработки. В их числе:
o
BoundChooseBox – универсальный элемент управления для выбора
значений ссылочных полей
o
CardChooseBox – специализированный элемент управления для выбора
карточек
o
FolderChooseBox
выбора папок
o
RowChooseBox – элемент управления для выбора любых объектов
o
BoundTreeView – элемент управления для работы с иерархической
секцией
o
NavigationToolStrip – навигационная панель инструментов
o
WizardControl – вспомогательный элемент управления для создания
Мастеров
–
специализированный
элемент
управления
для
3.2.2.2 Элемент управления BoundChooseBox
Элемент управления BoundChooseBox предназначен для выбора значений
ссылочных полей при помощи унифицированного интерфейса (Рисунок 3-19).
В стандартном виде, элемент управления ChooseBox представляет из себя
поле для отображения результатов выбора, и связанную с ним кнопку “…”,
инициирующую новый выбор:
Рисунок 3-19
BoundChooseBox использует технологию Data Binding (что отражено в его
названии) для автоматической привязки к одному из полей карточки ссылочного
типа (RefID или RefCardID). При этом он автоматически определяет тип ссылки,
и в зависимости от этого отображает соответствующий интерфейс для выбора
значения:
RefCardID – если поле является ссылкой на карточку, то для выбора
значения BoundChooseBox отображает интерфейс Навигатора, в котором
разрешено выбирать карточки;
RefID – для типизированной ссылки на строку другой карточки (или
справочника), на выбор открывается пользовательский интерфейс этой
карточки (например, если поле является ссылкой на строку секции
справочника сотрудников – то на выбор будет открыт справочник
сотрудников). Особым случаем является ссылка на строку секции карточки
папок – в этом случае элемент управления откроет на выбор Навигатор, в
котором разрешено выбирать папки.
ПРИМЕЧАНИЕ
Если поле RefID карточки является нетипизированным (не указаны значения типа
и секции связанной карточки) – то BoundChooseBox не сможет работать с таким
полем! В этом случае рекомендуетя использовать элемент управления
CustomChooseBox.
При работе в режиме связывания, элемент управления BoundChooseBox
автоматически выполняет чтение данных из поля карточки и первичную
инициализацию; а также автоматически сохраняет выбранное значение в поле
карточки в процессе использования. Таким образом, разработчику нужно
DocsVision 4.5: Руководство разработчика на платформе
22
выполнить только предварительную настройку элемента управления в Design
Time, и нет необходимости писать код обработчиков событий.
Кроме этого, элемент управления BoundChooseBox имеет дополнительные
сервисные функции:
Поддержка быстрого поиска и выбора объектов по нажатию горячих
клавиш “Ctrl+K”
Возможность ассоциации дополнительного контекстного меню для поля
результатов выбора (Рисунок 3-20)
Рисунок 3-20
Возможность ассоциации дополнительного контекстного меню для кнопки
выбора (Рисунок 3-21)
Рисунок 3-21
Прежде чем приступить к использованию элемента управления BoundChooseBox,
необходимо подготовить источник данных для него. В качестве источника данных
может выступать объект RowDataSource, предназначенный для работы со строками
секции карточки. Однако здесь необходимо учесть один ньанс: источник данных
RowDataSource может возвращать сразу несколько строк (например, для секции
коллекционного типа); а элемент управления BoundChooseBox может отображать
только значение конкретного поля одной конкретной строки. Чтобы разрешить это
противоречие, вводится еще один промежуточный объект – BindingSource, который
предназначен как раз для того, чтобы выбрать одну конкретную строку из набора,
возвращаемого RowDataSource. Таким образом, общую картину связывания данных в
данном случае можно представить следующим образом (Рисунок 3-22):
Объект BindingSource входит в число стандартных элементов управления
Microsoft, и доступен на панели инструментов (Toolbox) в группе “Data”. Использовать
его достаточно просто, он содержит всего одно значимое свойство – DataSource, где
нужно разместить ссылку на уже подготовленный источник данных RowDataSource.
После создания и настройки источников данных (RowDataSource и
BindingSource) можно приступать к настройке собственно элемента управления
BoundChooseBox.
В свойстве BindingSource необходимо указать ссылку на предварительно
настроенный объект BindingSource. После этого, в свойстве DataMember появится
возможность выбрать (или ввести вручную) название конкретного поля карточки, с
которыми связывается элемент управления BoundDataSource. Именно описание этого
DocsVision 4.5: Руководство разработчика на платформе
23
поля в схеме карточки будет являться определяющим для дальнейшей работы элемента
управления (что конкретно он будет выбирать).
Дополнительно можно указать свойство FormatString – определяющее, как
именно BoundChooseBox будет отрображать выбранное значение. Формировать
отобржаемое значение можно при помощи комбинации строковых констант и значений
любых полей той строки, из которой производится выбор. Имена полей оформляются в
строке отображения в фигурных скобках; а строковые константы – напрямую. Таким
образом, пример строки отображения для вывода данных о сотруднике (строка секции
Emploees из справочника сотрудникорв – RefStaff) может выглядеть так:
Фамилия:{LastName}_Имя:{FirstName}_Отчество:{MiddleName}
Свойства CommandMenuStrip и ContextMenuStrip позволяют сформировать
контекстные меню для кнопки выбора и отображаемого значения соответственно. Для
реализации самих контекстных меню используется стандартный элемент управления
Microsoft ContextMenuStrip. Его необходимо предварительно добавить на форму
карточки и настроить его свойства (добавить пункты меню), а также создать
обработчики для событий выбора пунктов меню. Готовый и настроенный элемент
управления можно указать в качестве значения свойства CommandMenuStrip или
ContextMenuStrip.
ПРИМЕЧАНИЕ
В случае использования меню команд выбора CommandMenuStrip, стандартный
значок кнопки выбора «…» будет заменен на иконку первого из пунктов
контекстного меню.
Другие свойства элемента управления BoundChooseBox:
Caption – заголовок окна выбора
HideNotAvailable – признак не показывать скрытые элемиенты для выбора
SearchDelimiter – разделительный символ для быстрого поиска (элемент управления
позволяет выполнять быстрый поиск по всем полям, указанным в строке отображения, в
порядке их следования; а для разделения этих полей при вводе используется этот символ).
По умолчанию это пробел.
SearchSubstring – для бытрого поиска (по Ctrl+K) признак, искать ли вхождение подстроки
только сначала или любом месте. По умолчанию значение равно false, то есть поиск ведется
только по первым символам.
Text – отображаемое значение элемента управления
Value – выбранное значение (идентификатор)
Методы объекта BoundChooseBox:
System.Guid ChooseValue() – инициирует процесс выбора значения
QuickSearch() – инициирует быстрый поиск по введенному тексту
3.2.2.3 Элемент управления CardChooseBox
Элемент управления CardChooseBox является специализированной версией
ChooseBox, предназначенной только для выбора карточек. Этот элемент управления
не поддерживает технологию Data Binding, поэтому для его использования потребуется
вручную написать код для инициализации существующими данными, и для сохранения
результата выбора. Вместе с тем, данный элемент управления предоставляет гораздо
DocsVision 4.5: Руководство разработчика на платформе
24
большую гибкость по сравнению с BoundChooseBox, за счет того что позволяет
разработчику управлять особенностями своей работы, в том числе – указывать
поисковый запрос для фильтрации карточек, доступных на выбор. Это позволит,
например, ограничить область выбора конкретным типом карточек.
Для указания фильтра используется свойство CardsFilter, которое доступно
только программно (в run-time). В качестве значения свойства необходимо установить
ссылку на поредварительно созданный объект SearchQuery (подробнее об
использовании поиска в соответствующей главе).
Остальные свойства элемента управления
аналогичным свойствам BoundChooseBox.
CardChooseBox
соответствуют
Для чтения выбранного значения из элемента управления можно использовать
свойства Text (отображаемое значение) и Value (идентификатор выбранного значения);
а также событие OnValueChanged(object sender, System.EventArgs e) – которое инициируется
после завершения нового выбора.
Пример инициализации элемента управления CardChooseBox ограничивающий
возможность выбора только карточками файла:
const string FILE_CARD_TYPE = "{2BBD0A41-265E-4FF8-82D6-C6342F34B1AF}";
SearchQuery query = session.CreateSearchQuery();
query.AttributiveSearch.CardTypeQueries.AddNew(new Guid(FILE_CARD_TYPE));
cardChooseBox1.CardsFilter = query;
3.2.2.4 Элемент управления FolderChooseBox
Как и CardChooseBox, элемент управления FolderChooseBox является
специлизированной версий ChooseBox, предназначенной для выбора папок. Он имеет
cпецифическую возможность ограничивать тип папок, которые разрешается выбирать –
для этого предназначено свойство
DocsVision.Platform.ObjectManager.SystemCards.FolderTypes AllowedFolderTypes
Значение свойства является битовой маской, которая может быть сочетанием
следующих значений:
FolderTypes.All – все типы одновременно;
FolderTypes.None – тип не определен;
FolderTypes.Regular – обычная папка;
FolderTypes.Root – корневая папка;
FolderTypes.Virtual – виртуальная папка;
FolderTypes.Delegate – папка-делегат;
FolderTypes.SystemHidden – системная папка;
FolderChooseBox также не поддерживает Data Binding, поэтому код по
загрузке/сохранению данных из этого элемента управления необходимо будет написать
самосотоятельно.
3.2.2.5 Элемент управления RowChooseBox
Последний вариант элемента управления для выбора значений, RowChooseBox,
является
специализированным
средством
для
выбора
строк
из
карточек
DocsVision 4.5: Руководство разработчика на платформе
25
(справочников). От BoundChooseBox его отличает отсутствие поддержки Data Binding,
но бОльшая гибкость в настройке и использовании за счет дополнительных свойств:
System.Guid CardTypeId – идентификатор типа карточки, из которой нужно выбирать
строки
System.Guid SectionTypeId – идентификатор типа секции, из которой нужно выбирать
строки
System.Guid CardInstanceId – идентификатор конкретного экземпляра карточки, из которой
нужно выбирать строки (используется в случае если карточка НЕ является справочником)
Значения этих свойств нужно указать в design-time, или программно при
инициализации элемента управления;
а также добавить обработчики для
чтения/записи значений из элемента управления.
3.2.2.6 Элемент управления BoundTreeView
Элемент управления BoundTreeView предназначен для отображения данных
иерархической секции. Как следует из его названия, этот элемент поддерживает
технологию Data Binding – то есть позволяет настроить его без необходимости
написания какого-либо кода. Это же объясняет и сам факт его появления – он вызван
тем, что стандартный элемент управления TreeView не поддерживает технологию Data
Binding. Внешний вид элемента управления BoundTreeView (Рисунок 3-23):
Рисунок 3-23
По способу использования, элемент управления BoundTreeView похож на
BoundChooseBox – он привязывается к источнику данных секции (RowDataSource) с
использованием вспомогательного объекта BindingSource:
Ссылка на BindingSource
BoundTreeView.
записывается
в
одноименное
свойство
объекта
Кроме этого, необходимо заполнить следующие свойства элемента управления:
DataMember – имя поля секции, к которому будет привязываться элемент управления.
Значение этого поля будет формировать значение (Value) каждого узла в дереве.
RootNodeText – имя корневого узла (если это свойство не указать, то имя корневого узла
будет пустым)
FormatString – отображаемое значение имен узлов. Формировать отобржаемое значение
можно при помощи комбинации строковых констант и значений любых полей той строки, с
DocsVision 4.5: Руководство разработчика на платформе
26
которой связан элемент управления. Имена полей оформляются в строке отображения в
фигурных скобках; а строковые константы – напрямую.
3.2.2.7 Элемент управления WizardConrol
Элемент управления WizardControl позволяет облегчить процесс создания
стандартных Мастеров (последовательность форм с возможнотью навигации
вперед/назад). Внешний вид элемента управления (Рисунок 3-24):
Рисунок 3-24
WizardControl имеет ряд свойств, определяющих его внешний вид и
поведение:
int ButtonHeight – высота стандартных кнопок (Back, Next, Cancel, Finish)
int ButtonWidth - ширина стандартных кнопок (Back, Next, Cancel, Finish)
int HorizontalSpacing – расстояние между кнопками по горизонтали
int VerticalSpacing – расстояние между кнопками по вертикали
string BackButtonText – текст кнопки “Back”
string CancelButtonText – текст кнопки “Cancel”
string FinishButtonText – текст кнопки “Finish”
string HelpButtonText – текст кнопки “Help”
System.Drawing.Size DefaultSize – начальный размер элемента управления
System.Windows.Forms.FlatStyle FlatStyle – стиль отрисовки элемента управления
bool HelpButtonVisible – признак, отображать ли кнопку помощи (Help)
Собственно шабор шагов Мастера задается при помощи коллекции
WizardPages – которую можно редактировать при помощи специального
визуального редактора (Рисунок 3-25):
DocsVision 4.5: Руководство разработчика на платформе
27
Рисунок 3-25
Редактор позволяет добавить произвольное количество страниц (шагов
Мастера); а также менять порядок их следования. Каждая страница имеет
единственное значимое свойство – Text, которое позволяет определить
заголовок страницы.
После определения всех страниц, они появляются в Мастере; и можно
добавлять интерактивные элементы управления непосредственно на них.
Переход между страницами при этом осуществляется при помощи стандартных
навигационных кнопок Мастера.
Для завершения
основных событий:
разработки
Мастера,
остается
добавить
обработчики
OnWizardFinished(System.EventArgs e) – событие инициируется при нажатии на кнопку
Finish, и позволяет реализовать необходимые действия по завершению его работы
(сохранить результаты работы, выполнить какие-то действия, и т.д.)
OnWizardCanceled(System.EventArgs e) событие инициируется при нажатии на кнопку
Cancel, и позволяет реализовать необходимые действия по аварийному прерыванию его
работы (закрыть форму на которой расположен Мастер)
OnSelectedIndexChanging(DocsVision.Platform.WinForms.Controls.WizardControl.Selected
IndexChangingEventArgs e) – событие инициируется ДО смены вкладки (при перемещении
вперед или назад), и позволяет в случае необходимости воспрепятствовать этому переходу
(это может быть полезно для реализации проверки ввода всех необходимых параметров,
прежде чем разрешить переход к следующему шагу)
OnSelectedIndexChanged(System.EventArgs e) – это событие возникает ПОСЛЕ перехода на
новый шаг (вперед или назад), и позволяет выполнить какие-то действия по инциализации
элементов управления на новом шаге
Компонент библиотеки карточек»).
DocsVision 4.5: Руководство разработчика на платформе
28
Схему карточки можно добавить в уже существующую библиотеку или создать
новую библиотеку карточек при помощи команды New library. При этом нужно указать
имя файла, который будет содержать описание библиотеки, и указать её свойства (см.
рис. 3.7):
Alias – псевдоним библиотеки, с помощью которого к ней можно обращаться в
коде;
Name – локализованное имя библиотеки, отображаемое пользователю;
ID – уникальный идентификатор библиотеки, определённый на этапе разработки
(кнопка Новый позволяет сгенерировать новый идентификатор);
Version – номер версии библиотеки (его необходимо изменять вручную при
необходимости обновить библиотеку на всех клиентах);
Рис. 3.7. Описание библиотеки
ProgID – программный идентификатор компонента библиотеки;
Activation string – идентификатор класса или программный идентификатор CLSID
компонента библиотеки;
DocsVision 4.5: Руководство разработчика на платформе
29
MSI product code – код
автоматической установки;
установочного
компонента
библиотеки
для
MSI package name – путь к установочному компоненту библиотеки;
Icon file – иконка библиотеки (отображается в Навигаторе).
После создания и описания всех свойств библиотеки её название появится в левой
панели окна CardManager. После этого можно приступать к описанию схем данных
карточек, входящих в библиотеку.
ПРИМЕЧАНИЕ
Работа с вкладкой Reports подробно описана в разделе «Хранимые процедуры»,
с вкладкой Installers - в разделе «Распространение решения», а с вкладкой Log
– в разделе “Журналирование”
DocsVision 4.5: Руководство разработчика на платформе
30
3.2.3 Создание и редактирование схемы данных
Чтобы добавить новую схему данных (карточку) в библиотеку, нужно выбрать
необходимую библиотеку в левой панели и выполнить команду New card. Если схема
данных была подготовлена ранее, её можно включить в библиотеку при помощи
команды Open card. После этого надо указать имя XML-файла, содержащего описание
схемы данных карточки.
Рис. 3.8. Добавление карточки в библиотеку
После создания карточки можно приступать к редактированию схемы данных (для
редактирования существующей карточки нужно выбрать пункт меню Edit->Card
Propeties).
Редактирование схемы данных представляет собой описание атрибутов карточки в
нескольких различных разделах:
Card description - общая информация. В данном разделе описываются общие
свойства карточки: её имя, описание, идентификатор, иконка, системные
атрибуты;
Sections — описание секций, входящих в карточку, их полей, свойств и связей
между ними;
Virtual fields — логические элементы данных карточки, доступные для вывода в
представления;
Actions — описывает возможные действия карточки;
Modes — возможные режимы
отображения её интерфейса);
Transformations — варианты трансформации данных в другой формат при
помощи XSLT и InfoPath-преобразований.
работы
карточки
DocsVision 4.5: Руководство разработчика на платформе
(например,
варианты
31
Рис. 3.9. Общая информация карточки
Общее описание карточки предполагает заполнение следующих полей:
Alias – псевдоним карточки, с помощью которого к ней можно обращаться в коде.
Псевдоним должен быть уникальным в рамках библиотеки;
Revision – номер версии карточки;
Names – локализованные названия карточки, отображаемые пользователю;
ID – уникальный идентификатор данного типа карточек. Этот идентификатор
генерируется автоматически при создании новой карточки. Идентификатор должен
быть уникален в рамках всей базы данных карточек;
Library ID – идентификатор
Заполняется автоматически;
ProgID
–
программный
функциональность карточки;
Activation string – строка активизации компонента карточки. Может содержать
программный идентификатор (ProgID), идентификатор класса (CLSID) и данные о
лицензировании;
Icon file – иконка данного типа карточек, отображаемая для пользователя.
Рекомендуется использовать относительные пути при указании иконки;
Fefault fetch mode – позволяет выбрать механизм чтения данных карточки. Этот
режим позволяет оптимизировать скорость работы с карточкой для клиентских
приложений. Возможны следующие варианты режима чтения:
библиотеки,
идентификатор
которой
принадлежит
компонента,
DocsVision 4.5: Руководство разработчика на платформе
карточка.
реализующего
32
FETCH_CARD (карточка целиком) – при обращении к карточке все её данные
будут переданы клиенту;
FETCH_SECTION (секция) – при обращении к данным карточки будет прочитана
целиком соответствующая секция;
FETCH_SUBSECTION (подсекция) – чтение только данных подсекций;
FETCH_LEVEL (уровень) – чтение только данных одного уровня дерева (для
иерархических секций);
FETCH_ROW – чтение только данных одной строки;
Attributes – позволяют определить особенности поведения карточки в системе.
Доступны следующие атрибуты:
Do not mark card as unread – по умолчанию при создании экземпляра карточки
ярлык на неё помечается как «непрочитанный» (выделяется жирным шрифтом
в окне Навигатора). Данный атрибут позволяет отключить эту возможность;
Card can be marked as template – данный атрибут позволяет использовать
механизм шаблонов для данного типа карточек;
Instances can be copied – разрешает или запрещает копирование данных
карточки;
Card needs custom XML export procedure – карточки этого типа используют
нестандартную процедуру выгрузки в XML (стандартные пункты меню будут
недоступны);
Dictionary (only one instance allowed) – разрешается существование в системе
только одного экземпляра карточки. Используется для справочников;
Can work as folder card – для карточек, реализующих функциональность папок
(такую функциональность реализует системная карточка папок, которую
разработчик может подменить собственной);
Items can be selected from this card – карточку можно использовать для выбора
её элементов (запускать в режиме выбора);
Do not create hard shortcuts – атрибут регулирует механизм создания ярлыков
для экземпляров карточек. По умолчанию при создании экземпляра карточки
для неё создается «сильный» ярлык, при удалении которого удаляется и сама
карточка. Данный атрибут позволяет отключить эту возможность;
Do not lock the card when opened – разрешает или запрещает автоматическую
блокировку данных карточки при её открытии из Навигатора. Если блокировка
установлена, то одновременная работа пользователей с одним экземпляром
карточки запрещается на системном уровне. Если блокировка отключена, то
разработчик карточки должен сам контролировать ситуации одновременного
доступа к данным;
Non-archivable – разрешает или запрещает перемещание данных карточки в
архивные таблицы или архивную базу данных (при использовании
дополнительного модуля архивации);
System (user cannot create instance) – пользователь не может создать
экземпляр
карточки.
Используется
для
карточек,
не
имеющих
пользовательского интерфейса, и утилит. Экземпляры таких карточек
создаются только программно;
User cannot delete card instances – карточки данного типа не могут удаляться
пользователями (соответствующие пункты меню и панели инструментов будут
недоступны);
Card cannot be replicated – данная опция регулирует возможность репликации
всех экземпляров данной карточки;
Non-searchable – карточка не участвует в поиске и не индексируется;
DocsVision 4.5: Руководство разработчика на платформе
33
Hidden – экземпляры данного типа карточек не отображаются пользователю.
Обычно используется совместно с атрибутом «Системная»;
Replicate only card templates – в процессе репликации будут участвовать
только те карточки данного типа, которые помечены в качестве шаблонов;
Allow to open as linked card – атрибут для связанных карточек. Разрешает или
запрещает открытие пользовательского интерфейса карточки из других
карточек;
Card is securable – регулирует механизм выдачи прав на данные карточки. При
наличии данного признака, права могут быть назначены на все структурные
элементы карточки (секции, строки секций). При отсутствии данного признака
используется так называемый упрощённый режим - права выдаются только на
карточку целиком.
ВНИМАНИЕ
Для повышения производительности крайне НЕ рекомендуется устанавливать
этот признак для карточек без особой необходимости!
Provides UI Extension – атрибут для карточек, которые интегрируются с
интерфейсом Навигатора для реализации прикладных функций;
Default security descriptor – позволяют определить набор прав по умолчанию,
который будут назначаться на экземпляры карточки при их создании.
ВНИМАНИЕ
В этом дескрипторе можно использовать только константные идентификаторы
объектов (well-known security identifiers), т.к. при создаваться экземпляры
карточки будут в другом домене чем тот, где она разрабатывается.
Заполнение данных о секциях предполагает создание структуры (иерархии)
секций данных карточки, указание их свойств и полей. Для добавления новой секции
нужно воспользоваться командой New section в секции Sections. После этого
необходимо указать свойства новой секции и список входящих в нее полей (см. рис.
3.10).
ВНИМАНИЕ
Для корректной работы карточки требуется наличие у неё, как минимум, одной
секции.
DocsVision 4.5: Руководство разработчика на платформе
34
Рис. 3.10. Описание секции карточки
Описание секции содержит следующие свойства:
Alias – псевдоним секции, с помощью которого к ней можно обращаться в коде.
Псевдоним должен быть уникальным в рамках карточки;
Singular – строка, указывающая наименнование соответствующего класса при
использовании утилит авто-генерации кода по описанию карточки (в данном
руководстве не рассматриваются)
Names – локализованные названия секции, отображаемые для пользователя;
ID – уникальный идентификатор данной секции. Этот идентификатор генерируется
автоматически при добавлении новой секции и может быть сгенерирован заново при
нажатии кнопки New;
Tyme – тип организации данных в секции. Допустимы следующие типы организации
данных:
struct (структрура)
coll (коллекция)
tree (дерево)
Format string – формат описания (дайджеста) строки секции. Дайджесты строк это текстовые комментарии, уникальным образом характеризующие конкретную
строку внутри секции. В основном, они используеются в элементах управления,
предназначенных для выбора строк секции (ChooseBox);
DocsVision 4.5: Руководство разработчика на платформе
35
ПРИМЕЧАНИЕ
В текущей версии формат описания строки не применяется и зарезервирован для
будущего использования.
Display fields – поля, из которых составляются описания (дайджесты) строк
секции. Значения этих полей приводятся к строчному выражению, конкатенируются
в порядке их описания и отделяются друг от друга пробелом;
ПРИМЕЧАНИЕ
Например, секция содержит данные о сотрудниках организации и имеет
несколько полей, среди которых есть Name (Имя), SurName (фамилия) и
MiddleName (Отчество). В этом случае, если выбрать эти три поля в качестве
полей для отображения строки, то во всех элементах управления выбранная
строка данной секции будет отображаться как Фамилия_Имя_Отчество.
Contains card properties – атрибут для секций свойств. Это специальный вид
секций, содержащих ряд предопределённых полей, которые могут выступать в
качестве пользовательских атрибутов карточки (свойств). Платформа позволяет
обрабатывать свойства карточки специальным образом – например, выводить их в
представления или синхронизировать их значения со свойствами файлов Office.
При отметке какой-либо секции как содержащей
дополнительно указать ключевые поля этой секции:
свойства,
требуется
Name – поле, содержащее название свойства (строка);
Value – поле, содержащее значение свойства (чаще всего – variant);
DisplayValue – поле, содержащее отображаемое значение свойства (строка);
Type – поле, определяющее тип свойства (перечисляемое);
Sort fields – описание полей секции, по которым производится сортировка строк
при обращении к данным секции. Можно указать прямой или обратный порядок
сортировки для конкретных полей. Число полей для сортировки не ограничено.
Сортировка производится в порядке следования этих полей в описании;
Indexes and constraints – ограничения на поля секции. Каждое ограничение
устанавливает одно требование к одному полю или набору полей секции. Можно
указать следующие ограничения:
Unique globally – значение поля (или набора полей) уникально в рамках сервера
DocsVision;
Unique within card – значение поля (или набора полей) уникально в рамках
экземпляра карточки;
Unique within section – значение поля (или набора полей) уникально в рамках
секции;
Unique within tree – значение поля (или набора полей) уникально в рамках всех
уровней иерархической секции;
Clastered index – по полю строится кластерный индекс;
Non-clastered index – по полю строится некластерный индекс;
Unique clastered index – по полю строится уникальный кластерный индекс;
Unique non-clastered index – по полю строится уникальный некластерный
индекс;
ВНИМАНИЕ
Необходимо внимательно отнеститись к созданию индексов, так как их
неоптимальное создание (или попросту отсутствие) способно значительно
DocsVision 4.5: Руководство разработчика на платформе
36
понизить производительность всей системы.
Allows concurrent access – допускается одновременная работа нескольких
пользователей с данными секции (чаще всего этот признак устанавливается для
справочников и требует отказа от блокировки карточки);
Suppress search – поля секции не будут отображаться в диалоге поиска;
Secton has selectable items – секцию можно использовать для выбора строк (чаще
всего этот признак устанавливается для секций справочников);
Log optional – сообщение об изменении строки секции не будет записываться в
системный журнал;
ВНИМАНИЕ
Для повышения производительности крайне рекомендуется устанавливать этот
режим для секций, с которыми производится интенсивная работа (например, для
секций с данными журналирования).
Do not copy section data – при копировании карточки строки данной секции не
будут копироваться.
Section is securable – признак наличия собственных дескрипторов у строк секции
(используется в случае полной безопасности на карточке в целом)
Items are pinned – признак, показывающий что строки из данной секции не могут
быть удалены
Создание секции также включает в себя добавление полей и дочерних секций.
Для этого следует выбрать нужную секцию и воспользоваться командой New field или
New section. Дочерние секции содержат те же свойства, что и секции первого уровня.
DocsVision 4.5: Руководство разработчика на платформе
37
Рис. 3.11. Редактирование поля секции
Описание поля содержит следующие свойства:
Alias – псевдоним поля, с помощью которого к нему можно обращаться в коде.
Псевдоним должен быть уникальным в рамках секции;
Description – словесное описание поля, будет отображаться в виде подсказки к
полю в диалогах поиска и представлений;
Type – тип (формат) данных в поле. Возможные типы полей:
int — целое;
bool — булевское значение (Да/Нет);
datetime — дата и время;
date — дата;
time — время;
enum — перечисление (предопределённый набор уникальных значений);
bitmask — битовая маска;
uniqueid — уникальный идентификатор (GUID);
userid — идентификатор пользователя;
string — строка;
unistring — строка в формате Unicode;
DocsVision 4.5: Руководство разработчика на платформе
38
fileid — идентификатор файла DocsVision;
float — число с плавающей точкой;
refid — ссылка на строку другой секции;
refcardid — ссылка на карточку;
text — текст;
unitext — текст в формате Unicode;
binary — двоичные данные;
image — изображение;
sdid — идентификатор безопасности;
decimal — десятичное число;
variant – значение переменного типа;
Size – ограничение длины поля (используется в основном для полей строчного
типа);
Link type – указание типа ссылки для ссылочных полей (refid, refcardid).
Тип ссылки характеризует поведение объектов, связанных ссылкой. Возможны
следующие типы ссылок:
Weak – связанный объект разрешено удалять;
содержащего ссылку, связанный объект останется;
при
удалении
объекта,
Hard - связанный объект запрещено удалять, пока на него существует ссылка;
при удалении объекта, содержащего ссылку, связанный объект также будет
автоматически удален;
None – при удалении связанного объекта значение ссылочного поля будет
очищено;
Auto - при удалении связанного объекта будет удалена вся строка секции,
содержащей ссылку;
Copy behavior – режим копирования данных поля. Возможны следующие режимы:
Null — значение поля при копировании обнуляется;
Copy — значение поля копируется;
CreateNew — создание нового значения (используеются для ссылок);
Names – локализованные названия поля, отображаемые у пользователя;
ID – уникальный идентификатор поля;
Default value – значение поля, которое будет автоматически задаваться при
создании новых экземпляров карточки;
Required – значение данного поля не может быть пустым (система не позволит
сохранить карточку без задания значения этого поля);
Depends on user – значение поля сопоставляется с конкретным пользователем
системы (таким образом, для каждого пользователя может храниться собственное
уникальное значение этого поля);
Suppress search – поле не участвует в поиске (не отображается в диалоге поиска);
Delete linked row on value change – признак удаления связанных строк в случае
изменения значения этого поля (используется для ссылочных полей);
Appers on the card form – поле может быть сопоставлено с элементом
пользовательского интерфейса (этот признак используется в справочнике типов,
если данная карточка обеспечивает возможность «тонкой» настройки);
DocsVision 4.5: Руководство разработчика на платформе
39
System – признак того, что поле является системным (учитывается при некоторых
операциях с данными);
Referenced type ID – уникальный идентификатор типа карточки, с полями или
секциями которой связано данное поле. Тип карточки можно выбрать в диалоге
типов;
Referenced section ID – идентификатор секции связанной карточки, с полями
которого осуществляется связь;
References – поля связанной карточки, значения которых ассоциируются со
строкой этой секции (используются для ссылочных полей). Данная возможность
позволяет при обращении к данным секции вернуть не только значения его
собственных полей, но и ряда полей связанных карточек или секций. Это может
быть удобным, например, чтобы снизить число обращений к серверу при чтении
данных карточки или при её экспорте и печати.
После описания секций и полей карточки можно переходить к описанию
виртуальных полей. Виртуальные поля представляют собой правила для формирования
данных, которые физически не хранятся в самой карточке, но могут быть интересны
при построении представлений (отчётов) с участием карточек такого типа.
В качестве источника данных для виртуального поля могут выступать:
физическое поле самой карточки;
физическое поле карточки другого типа, которая по каким-то признакам связана с
данной;
системные данные о карточке (например, дата последнего изменения);
результат вычислений, произведённых над любым из вышеперечисленных полей.
ПРИМЕЧАНИЕ
Виртуальные поля, определённые в схеме карточки, будут всегда доступны в
рамках соответствующих секций в диалоге настройки представлений. Помимо
этого, пользователи смогут самостоятельно доопределить дополнительные
виртуальные поля уже в процессе работы с системой.
Для создания нового виртуального поля нужно перейти в раздел Virtual fields и
выбрать соответствующий пункт контекстного меню.
DocsVision 4.5: Руководство разработчика на платформе
40
Рис. 3.12. Свойства виртуального поля
Основные свойства виртуального поля:
Alias – псевдоним виртуального поля, с помощью которого к нему можно
обращаться в коде. Псевдоним должен быть уникальным в рамках карточки;
Names – локализованные названия виртуального
пользователя (в диалоге настройки представлений);
Description – словесное описание виртуального поля, будет отображаться в виде
подсказки к полю в диалогах поиска и представлений;
ID – уникальный идентификатор виртуального поля;
Main section ID – идентификатор секции, на основе данных которой строится
виртуальное поле. Из этой секции будут выбираться физические поля для
вычислений, и к ней будут последовательно присоединяться другие секции или
таблицы;
Type – результирующий тип данных виртуального поля. Доступны только простые
типы:
поля,
отображаемые
у
int — целое;
bool — булевское значение (Да/Нет);
datetime — дата и время;
uniqueid — уникальный идентификатор (GUID);
DocsVision 4.5: Руководство разработчика на платформе
41
string — строка;
unistring — строка в формате Unicode;
float — число с плавающей точкой;
unitext — текст в формате Unicode;
decimal — десятичное число;
binary — двоичные данные;
Field definition – источник данных для виртуального поля. Доступные источники:
Section field – физическое поле основной или присоединённой секции;
Computed field – правила вычислений над физическим полем основной или
присоединённой секции;
Joins – позволяет определить связи основной секции виртуального поля с другими
секциями или таблицами. Секции связываются между собой по определённому
полю (обычно — уникальному идентификатору).
Рис. 3.13. Присоединение секции
При присоединении секции, необходимо указать следующие значения:
Alias – уникальный (в
присоединяемой секции;
рамках
определения
Source section – секция, к которой производится присоединение (основная секция
виртуального поля или ранее присоединенная);
Source field – поле
присоединение (JOIN);
Target section – секция другой карточки или системная таблица;
Target field – поле присоединяемой секции, по которому производится JOIN;
Conditions – условия фильтрации записей присоединённой секции;
оригинальной
виртуального
секции,
по
поля)
которому
псевдоним
производится
После присоединения всех необходимых секций можно задать правила построения
вычисляемых полей.
DocsVision 4.5: Руководство разработчика на платформе
42
Рис. 3.14. Свойства вычисляемого поля
Описание вычисляемого поля по сути представляет собой совокупность атомарных
операций (элементов), выполняющихся в определённом порядке, который задаётся
через иерархические группы. Внутри каждой группы элементы могут объединяться
арифметической операцией (+,-,*,/), логической операцией (AND, OR) или агрегацией.
ВНИМАНИЕ
Вычисления одного уровня исполняются строго последовательно, поэтому важно
контролировать порядок их выполнения. Для этого можно перемещать элементы
внутри группы кнопками Up и Down.
Каждый элемент вычислений, в свою очередь, может быть одним из следующих
видов:
Simple - значение физического поля секции, предопределённое значение или
результат применения к нему простейшей функции;
DocsVision 4.5: Руководство разработчика на платформе
43
Рис. 3.15. Простой элемент вычисления
Switch – результат селекции, сопоставляющей конкретным данным физического
поля предопределённые значения;
Рис. 3.16. Набор вариантов
Conditions
- условный оператор, формирующий
зависимости от значений других элементов.
DocsVision 4.5: Руководство разработчика на платформе
значение
элемента
в
44
Рис. 3.17. Набор условий
ВНИМАНИЕ
Важно контролировать типы конкретных элементов вычислений и их групп,
чтобы избежать ошибок в вычислениях и получить правильный тип
результирующего значения.
В разделе Actions можно указать действия (команды), «понятные» данной
карточке. В качестве команд могут выступать, например, такие действия как «Открыть
в другом режиме», «Переслать», «Списать в архив» и т. д. Разработчик сам определяет
перечень этих команд, их названия и семантику. Фактически, все описанные команды
появляются в меню действий над карточкой в окне Навигатора. При выборе
пользователем одной из команд будет вызван клиентский компонент карточки с
указанием идентификатора активированной команды и требуемые операции нужно
будет запрограммировать самостоятельно в коде этого компонента.
Для добавления действий следует перейти в раздел Actions и выбрать пункт
меню New action.
DocsVision 4.5: Руководство разработчика на платформе
45
Рис. 3.18. Описание действий над карточкой
Свойства действия (метода) включают в себя:
Alias – псевдоним действия, с помощью которого к нему можно обращаться в коде.
Псевдоним должен быть уникальным в рамках карточки;
Names – локализованные названия команды, отображаемые у пользователя в меню
действий над карточкой;
ID – уникальный идентификатор метода.
В разделе Modes можно определить возможные режимы работы карточки. Режим
работы
карточки
проще
всего
воспринимать,
как
вариант
реализации
пользовательского интерфейса карточки. Можно, например, представить себе
финансовый документ — бюджет, который может использоваться в различных
вариантах:
Подготовка;
Принятие;
Модификация поправками.
У карточки такого документа будет три соответствующих режима работы. Для
каждого режима разработчик карточки сам определяет вид пользовательского
интерфейса и семантику работы. Выбрать конкретный режим открытия экземпляра
карточки можно либо при помощи контекстного меню Навигатора, либо режим может
быть жёстко определен в ярлыке карточки.
Для добавления новых режимов работы следует перейти в раздел Modes и
воспользоваться командой New mode. Далее нужно определить свойства режима.
DocsVision 4.5: Руководство разработчика на платформе
46
Рис. 3.19. Свойства режима работы карточки
Свойства режима следующие:
Alias – псевдоним режима, с помощью которого к нему можно обращаться в коде.
Псевдоним должен быть уникальным в рамках карточки;
Names – локализованные названия режима, отображаемые у пользователя;
ID – уникальный идентификатор режима.
В секции Transformations можно определить возможные преобразования данных
карточки. Преобразования применяются для трансформации данных карточки в другой
формат, описанный в преобразовании. Например, преобразования могут применяться
при печати карточек, экспорте данных в другие системы или при публикации карточек
на web-страницах. Системой поддерживаются два типа преобразований: XSLTпреобразования (они используются для получения HTML-представления данных
карточки при выводе на печать) и преобразования Microsoft InfoPath.
Для определения преобразований следует перейти в раздел Transformations и
выбрать пункт меню New transformation. Затем нужно определить свойства
преобразования.
DocsVision 4.5: Руководство разработчика на платформе
47
Рис. 3.20. Свойства преобразования
Для преобразования предусмотрены следующие свойства:
Alias – псевдоним преобразования, с помощью которого к нему можно обращаться в
коде. Псевдоним должен быть уникальным в рамках карточки;
Names
–
локализованные
пользователя;
ID – уникальный идентификатор преобразования;
Transofmation type:
названия
преобразования,
отображаемые
у
Xslt — XSLT;
InfoPath — Microsoft InfoPath;
Custom — пользовательский тип;
Language – язык локализации преобразования (каждое преобразование относится
только к конретному языку; нельзя использовать одно и тоже преобразование сразу
для всех языков)
Content type – тип данных преобразования (выбирается только для
пользовательских преобразований). Может иметь одно из следующих значений:
Text — текст;
Xml — XML;
Binary — двоичные данные;
Transformation file – путь к файлу с данными преобразования (например, XSLT);
DocsVision 4.5: Руководство разработчика на платформе
48
Default – признак основного преобразования.
Преобразования, укзаанные в схеме карточки, будут присутствовать в её типе по
умолчанию. Впоследствии (в конкретной базе данных) этот набор преобразований
может быть дополнен силами пользователей.
После завершения
сохранить.
редактирования
схемы
данных карточки
её необходимо
3.2.4 Погрузка схемы в базу данных
Готовую схему данных карточки (или библиотеки карточек) необходимо погрузить
в базу данных DocsVision, чтобы создать в ней необходимую инфраструктуру таблиц,
индексов и хранимых процедур. CardManager предоставляет возможность погрузить в
базу данных описание библиотеки карточек с промощью команды Load library to
database. При этом необходимо выбрать библиотку для загрузки (из списка библиотек,
подключенных к CardManager).
ВНИМАНИЕ
Для корректной загрузки собственных библиотек карточек в базу данных, в
CardManager должны быть подключены описания всех стандартных библиотек,
входящих в комплект поставки системы (SystemCardLib, ManagedCardLib.
TakeOfficeCardLib, WorkflowCardLib). Эти библиотки включены в состав пакета
разработчика, и находятся в папке CardDefs.
Рис. 3.21. Погрузка схемы карточки в базу данных DocsVision
Если описание карточки уже присутствует в указанной базе данных,
существующие структуры данных будут автоматически обновлены согласно внесённым
в схему изменениям.
При необходимости можно удалить созданные структуры данных и экземпляры
карточек из базы данных. Для этого нужно воспользоваться командами Delete card
DocsVision 4.5: Руководство разработчика на платформе
49
или Delete library. Не рекомендуется удалять из базы данных описания системных
карточек.
ВНИМАНИЕ
При изменении схемы карточки, чтобы получить возможность использовать
модифицированную схему на клиенте, нужно обязательно выполнить следующие
действия:
перекомпилировать компонент библиотеки карточек (он кэширует схемы всех
карточек библиотеки для ускорения доступа к ним и без перекомпиляции
будет возвращать старое описание);
перезапустить сервер DocsVision (NT-сервис DocsVision Storage Server и/или
IIS) – запущенный сервер также кэширует схемы всех карточек и без
перезапуска будет возвращать старые описания.
3.3
РАЗРАБОТКА КОМПОНЕНТА КАРТОЧКИ
После завершения проектирования схемы данных карточки и погрузки её в базу
данных DocsVision необходимо разработать соответствующий программный компонент
карточки.
ПРИМЕЧАНИЕ
Карточка может и не иметь пользовательского интерфейса – например, если она
используется только в качестве хранилища данных для других карточек. В этом
случае данный этап может быть пропущен.
Программный компонент карточки представляет собой элемент управления
ActiveX, предоставляющий пользовательский интерфейс для работы с данными
карточки. Элемент управления вызывается Навигатором при активации карточки
(«открытии») или выполнении команд карточки.
Можно выделить несколько типов программных компонент карточек:
карточки документов — программные компоненты, реализующие только
интерфейс для ввода и редактирования данных. Типичными примерами карточек
документов
являются
карточки
стандартного
решения
DocsVision
«Делопроизводство»: Входящий документ, Исходящий документ и другие;
карточки справочников — программные компоненты, предназначенные для
редактирования данных справочников. Помимо средств для ввода и редактирования
данных,
предоставляют
специальный
интерфейс
для
выбора
элементов
справочника;
карточки расширения — программные компоненты, реализующие расширения
функциональности Навигатора. Например, при помощи карточек расширения можно
реализовать специфические механизмы поиска, экспорта и импорта данных или
интеграции с внешними системами;
специализированные карточки — системные карточки, служебные компоненты
или утилиты, предназначенные для использования в составе других карточек или
реализации специфической функциональности. К числу таких карточек можно
отнести системную карточку файла, карточку Список файлов из стандартного
решения DocsVision «Делопроизводство» и другие.
Разработка программного компонента состоит из нескольких этапов:
реализация стандартных интерфейсов — программирование кода карточки в
соответствии со стандартами платформы DocsVision для обеспечения её корректной
работы в системе;
DocsVision 4.5: Руководство разработчика на платформе
50
реализация пользовательского интерфейса — включает в себя проектирование и
реализацию вариантов взаимодействия кода карточки с пользователем, дизайн и
расположение элементов управления на форме карточки;
реализация дополнительной функциональности
карточки, связанные с её назначением;
отладка и тестирование — проверка корректной работы разработанного компонента
в составе системы.
—
дополнительные
функции
В качестве инструмента для создания карточки может быть использована любая
среда программирования, позволяющая реализовывать компоненты стандарта ActiveX и
осуществлять взаимодействие с COM-компонентами.
ПРИМЕЧАНИЕ
Примерный перечень сред и языков, в которых может быть разработана карточка
DocsVision:
Microsoft Visual Studio 6.0 (Visual Basic, Visual C++);
Microsoft Visual Studio 2003 (VB.NET, C#);
Microsoft Visual Studio 2005 (VB.NET, C#);
Borland Delphi и другие.
В данном Руководстве примеры кода приведены для Microsoft .NET (C#).
3.3.1 Реализация стандартных интерфейсов
Сначала необходимо создать новый проект — компонент, который будет
реализовывать визуальную часть карточки. Проект должен иметь тип «Windows Forms
Control Library»:
DocsVision 4.5: Руководство разработчика на платформе
51
Рис. 3.22. Создание проекта
Перед началом работы с проектом следует подключить все необходимые библиотеки:
Рис. 3.23. Подключение библиотек
В число необходимых входят следующие объектные библиотеки:
DocsVision.Platform.WinForms.dll — содержит интерфейс для взаимодействия с
контейнером карточек (средой, в которой запускаются и работают компоненты
карточек), а также элементы управления DocsVision для карточек в среде WinForms;
DocsVision 4.5: Руководство разработчика на платформе
52
ПРИМЕЧАНИЕ
Вместо DocsVision.Platform.WinForms.dll, можно использовать библиотеку
DocsVision.Platform.WPF.dll – она позволяет разрабатывать карточки по
технологии Windows Presentation Foundation (WPF). При этом основные принципы
разработки и интерфейсы остаются точно такими же, как и в случае WinForms поэтому далее в данном Руководстве они не рассматриваются отдельно.
DocsVision.Platform.ObjectManager.dll — библиотека менеджера объектов. В этой
библиотеке определены основные интерфейсы для взаимодействия с сервером и
другими объектами системы (API).
ПРИМЕЧАНИЕ
Эти сборки входят в состав как серверной, так и клиентской программ
инсталляции; однако устанавливаются они в GAC (Global Assembly Cache) –
специальную
системную
папку,
предназначенную
для
размещения
общедоступных сборок. К сожалению, Visual Studio не позволяет напрямую
добавить ссылки на библиотеки, расположенные в GAC. Поэтому может
понадобиться вручную скопировать из GAC (\Windows\assembly\GAC_MSIL\) в
папку проекта, для последующей установки ссылок на них.
Очевидно, следует также подключить пространства имен этих сборок в область
видимости текущего проекта при помощи директивы using:
using DocsVision.Platform.WinForms;
using DocsVision.Platform.ObjectManager;
Поскольку Навигатор активирует компонент карточки через COM-интерфейс,
следует сразу добавить в основной класс специальный атрибут <ComVisible>,
позволяющий другим приложениям взаимодействовать с .NET-сборкой по технологии
COM. Вместе с этим атрибутом необходимо сразу указать уникальный идентификатор
класса (CLSID), который будет однозначно идентифицировать этот класс среди прочих.
Этот идентификатор необходимо сгенерировать самостоятельно (например, при помощи
утилиты GuidGen из состава Visual Studio). Этот же идентификатор нужно будет указать
в XML-описании карточки в качестве строки активизации компонента карточки.
Эти атрибуты объявлены в пространстве имен System.Runtime.InteropServices,
поэтому нужно подключить его к своему проекту:
using System.Runtime.InteropServices;
Пример описания класса с установленным атрибутом:
[ComVisible(true)]
[Guid("221D8441-BEE9-4CAE-A59B-2007B6EEF5CF")]
[ClassInterface(ClassInterfaceType.None)]
public sealed partial class TestCard : UserControl
Для того чтобы карточка могла быть использована совместно с другими
компонентами платформы, ее программный компонент должен реализовывать набор
предопределенных интерфейсов. Все эти интерфейсы уже реализованы в специальном
классе DocsVision.Platform.WinForms.CardControl, поэтому разработчик избавлен от
их непосредственной имплементации. Все что остается сделать – это унаследовать
основной класс своей карточки от базового класса CardControl (вместо стандартного
UserControl):
public sealed partial class TestCard : CardControl
{
}
После этого в коде карточки автоматически появится доступ к членам базового
класса, среди которых самые важные:
DocsVision 4.5: Руководство разработчика на платформе
53
CardData – объект данных текущей карточки
CardHost – объект контейнера карточек
Session – текущая сессия (точка входа к остальным объектам API)
Дополнительные свойства, доступные из базового класса:
FolderID – идентификатор папки, из которой открыта карточка
ShortcutID – идентификатор ярлыка, из которого открыта карточка
ModeID – идентификатор текущего режима карточки
Таким образом, готовый код компонента карточки может выглядеть следующим
образом (такая карточка будет создаваться и активироваться, но не несет в себе
никакой полезной функциональности):
using System;
using System.Runtime.InteropServices;
using System.Windows.Forms;
using DocsVision.Platform.ObjectManager;
using DocsVision.Platform.WinForms;
using DocsVision.Platform.WinForms.DataSource;
namespace DocsVision.Test
{
[ComVisible(true)]
[Guid("221D8441-BEE9-4CAE-A59B-2007B6EEF5CF")]
[ClassInterface(ClassInterfaceType.None)]
public sealed partial class TestCard : CardControl
{
/// <summary>
/// Default constructor
/// </summary>
public TestCard()
{
InitializeComponent();
}
}
}
ПРИМЕЧАНИЕ
Готовый компонент карточки необходимо зарегистрировать как COM-библиотеку
при помощи утилиты regasm.exe (утилита входит в состав .NET Framework). При
этом, если компнент имеет strong name, то его можно установить в GAC
(утилитой gacutil.exe), и зарегистрировать вызовом regasm.exe. Если же сборка
не имеет strong name, то регистрацию необходимо выполнить утилитой
regasm.exe с ключом /codebase.
3.3.2 Обработка событий
Жизненный цикл компонента карточки предусматривает ряд ключевых событий,
которые могут быть обработаны в коде компонента. Обработчики для этих событий уже
существуют в базовом классе CardControl, и содержат код, необходимый для
нормального функционирования компонента карточки. Однако при желании
DocsVision 4.5: Руководство разработчика на платформе
54
разработчик может переопределить одно или несколько из этих событий, чтобы
реализовать в них собственную логику.
ПРИМЕЧАНИЕ
При переопределении событий,
класса!
нужно не забыть вызвать обработчик базового
Базовый класс предусматривает всего 8 основных событий:
OnCardInitialized(EventArgs e) – это событие инициируется после
создания компонента карточки, и передачи ей актуальных данных
(инициализируются объекты CardData и UserSession). Аргументы события
(EventArgs) – стандартные.
OnCardActivating(CardActivatingEventArgs e) – событие инициируется до
активации
компонента
карточки
Навигатором
(отображения
пользовательского интерфейса). В этом событии можно выполнить
первичную инициализацию элементов управления. Аргументы события
(CardActivatingEventArgs) содержат:
o
o
o
o
ActivateMode – режим активации карточки:
Edit = 1 (редактирование)
ReadOnly = 2 (только чтение)
Preview = 3 (предварительный просмотр в Навигаторе)
Select = 4 (открытие справочника на выбор)
ActivateFlags – дополнительные флаги активации карточки (битовая
маска):
None = 0 (флаги отсутствуют)
ModalWindow = 0x01 (карточка открыта модально)
FolderPanel = 0x02 (карточка папки)
New = 0x04 (создан новый экземпляр данных карточки)
NewFromTemplate = 0x08 (новая карточка из шаблона)
ByShortcut = 0x10 (карточка открыта по ярлыку)
ByUrl = 0x20 (карточка открыта по ссылке)
ReadOnly = 0x40 (карточка открыта только для чтения)
NoCreateNew = 0x80 (запрет создания новых карточек в этой
же папке)
ActivateParams – дополнительные параметры, которые были
переданы карточке вызывающей стороной при ее открытии методом
CardHost.SelectFromCard. Вызывающая сторона при этом может
передать параметры, уточняющие область выбора, начальное
значение, и т.д.
ActionFlags – действия, которые должен выполнить Навигатор после
обаботки события (битовая маска):
None = 0x0000 (ничего не делать)
ContinueAction = 0x0001 (продолжить текущее действие, если
этот флаг не установить – то действие будет прервано!)
CommittedData = 0x0002 (данные карточки сохранены, можно
закрывать)
NoShortcuts = 0x0100 (не создавать ярлык для карточки при
ее закрытии)
WantReturn = 0x0200 (передавать карточке нажатия клавиши
Enter – тогда как в стандртном режиме Навигатор сам
перехватывает эти нажатия, и использует их как сигнал к
закрытию карточки)
HideFrame = 0x0400 (скрыть окно карточки)
ChangeWantReturn = 0x0800 (признак, что карточка хочет
изменить поведение Enter)
DocsVision 4.5: Руководство разработчика на платформе
55
WantAllKeys = 0x1000 (передавать карточке коды всех
нажатых клавиш – тогда как в стандартном режиме Навигатор
перехватывает нажатия системныъх клавиш, таких как Tab,
Esc и т.д.)
ChangeWantAllKeys = 0x2000 (признак, что карточка хочет
изменить поведение системных клавиш)
HideStatusBar = 0x4000 (скрыть строку статуса в окне
карточки)
OnCardActivated(CardActivatedEventArgs e) - событие инициируется после
активации компонента карточки Навигатором. Аргументы события
(CardActivatedEventArgs) аналогичны предыдущему, за исключением
ActionFlags т.к. данное событие инициируется уже пост-фактум, и
карточка уже не может изменить поведение Навигатора
OnCardClosing(CardClosingEventArgs e) – событие возникает до закрытия
пользовательского интерфейса карточки. Позволяет воспрепятствовать
закрытию, если не выполнены все необходимые для этого условия.
Аргументы события (CardClosingEventArgs) содержат параметр ActionFlags,
управляющий поведением Навигатора (см. выше)
OnCardClosed(EventArgs e) - событие возникает после закрытия
пользовательского интерфейса карточки, и позволяет, например, очистить
элементы управления. Аргументы события (EventArgs) – стандартные
OnCardLoaded(EventArgs e) - событие возникает после загрузки
компонента карточки в память. Так как Навигатор кэширует загруженные
карточки – то это событие возникает только один раз за время ее жизни, но
после этого может произвольное количество раз происходить активация
карточки для разных объектов данных. Аргументы события (EventArgs) –
стандартные
OnCardUnloaded(EventArgs e) – событие инициируется при выгрузке
компонента карточки из памяти, и позволяет освободить задействованные
ресурсы. Аргументы события (EventArgs) – стандартные
OnCardAction(CardActionEventArgs e) – специальное событие, которое
инициируется при активации пользователем одного из методов карточки.
Аргументы события (CardActionEventArgs) содержат следующие значения:
o
ActionID – идентификатор задействованного метода
o
ModeID – идентификатор текущего режима открытия карточки
Последовательность вызова событий в жизненном цикле карточки представлена на
схеме:
DocsVision 4.5: Руководство разработчика на платформе
56
OnCardLoaded
OnCardInitialized
OnCardActivating
OnCardActivated
OnCardClosing
OnCardClosed
OnCardUnloaded
Внешний контур схемы охватывает полный жизненный цикл компонента карточки, от
момента его создания до момента выгрузки из памяти. Внутренний контур содержит
последовательность событий, возникающий при активации компонента карточки для
каждого независимого экземпляра данных.
ВНИМАНИЕ
Следует всегда помнить о том, что Навигатор кэширует компонент карточки в
памяти после первого обращения к нему, и впоследствии активирует этот же
самый компонент при открытии всех карточек такого типа. Поэтому важно не
забывать всегда инициализировать и очищать элементы управления – чтобы в
них не осталось данных со времени предыдущей активации.
Пример кода карточки с обработчиками событий:
using System;
using System.Runtime.InteropServices;
using System.Windows.Forms;
using DocsVision.Platform.ObjectManager;
using DocsVision.Platform.WinForms;
using DocsVision.Platform.WinForms.DataSource;
namespace DocsVision.Test
{
[ComVisible(true)]
[Guid("221D8441-BEE9-4CAE-A59B-2007B6EEF5CF")]
[ClassInterface(ClassInterfaceType.None)]
public sealed partial class TestCard : CardControl
{
private bool isReadOnly;
private bool isChanged;
DocsVision 4.5: Руководство разработчика на платформе
57
public TestCard()
{
}
protected override void OnCardInitialized(EventArgs e)
{
base.OnCardInitialized(e);
InitializeComponent();
}
protected override void OnCardActivated(CardActivatedEventArgs e)
{
base.OnCardActivated(e);
isReadOnly = (e.ActivateMode != ActivateMode.Edit);
isChanged = ((e.ActivateFlags & ActivateFlags.New) ==
ActivateFlags.New);
}
protected override void OnCardClosing(CardClosingEventArgs e)
{
base.OnCardClosing(e);
if (!isReadOnly && isChanged)
{
e.ActionFlags = ActionFlags.None;
MessageResult result = ShowMessage(“Сохранить изменения?”,
“Карточка”,
null,
MessageType.Question,
MessageButtons.YesNoCancel);
switch (result)
{
case MessageResult.Yes:
e.ActionFlags = ActionFlags.ContinueAction |
ActionFlags.CommittedData;
break;
case MessageResult.No:
e.ActionFlags = ActionFlags.ContinueAction;
break;
default:
break;
}
}
}
}
}
3.3.3 Использование элементов управления
После завершения реализации стандартных интерфейсов, следующим шагом в
разработке компонента карточки является расположение на контрольном элементе
карточки различных элементов, предназначенных для управления поведением
карточки; ввода, редактирования и удаления данных; и прочих необходимых функций.
В качестве элементов управления могут быть использованы стандартные элементы
DocsVision 4.5: Руководство разработчика на платформе
58
управления Visual Studio, дополнительные контрольные элементы сторонних
производителей, или специализированные элементы управления DocsVision.
Элементы управления DocsVision реализованы в уже знакомой библиотеке
DocsVision.Platform.WinForms.dll. Однако для начала работы с ними, следует
выполнить дополнительные действия по включению их в набор текущих инструментов
Visual Studio.
ПРИМЕЧАНИЕ
Для карточек, разрабатываемых по технологии WPF, элементы управления
DocsVision пока не предусмотрены. Поэтому разработчику такой карточки можно
пользоваться только стандартными элементами.
На панели инструментов Visual Studio (Toolbox) имеет смысл организовать новую
вкладку для размещения элементов управления DocsVision, чтобы легче находить их
среди остальных элементов правления. Для этого нужно выполнить команду “Add tab”,
и указать название новой вкладки (Рис. 3-1)
Рисунок 3-1
После создания вкладки, на нее можно добавить элементы управления при
помощи команды “Choose items” (рис. 3-2):
Рисунок 3-2
В диалоге необходимо указать путь к файлу DocsVision.Platform.WinForms.dll,
после чего в списке появятся доступные элементы управления их этой библиотеки
(рис. 3-3):
DocsVision 4.5: Руководство разработчика на платформе
59
Рисунок 3-3
После выбора всех элементов управления и закрытия диалога, они отобразятся на
панели инструментов и будут доступны для использования (рис. 3-4):
Рисунок 3-4
Элементы управления из библиотеки
условно разделить на три группы:
DocsVision.Platform.WinForms.dll
DocsVision 4.5: Руководство разработчика на платформе
можно
60
Источники данных – эти элементы управления сами не отображаются на
форме и не взаимодействуют с пользователем; а служат только в качестве
источников данных для других элементов управления. К этой группе относятся:
o
SessionSource – соединение с сервером DocsVision
o
CardDataSource – набор данных карточек
o
RowDataSource – набор строк секции карточки
o
InfoRowDataSource – данные представления
o
ReportDataSource – данные хранимой процедуры
Интерактивные элементы управления – элементы управления, которые
размещаются на форме и с которыми напрямую взаимодействует пользователь. К
этой группе относятся:
o
BoundChooseBox – универсальный элемент управления для выбора
значений ссылочных полей
o
CardChooseBox – специализированный элемент управления для выбора
карточек
o
FolderChooseBox
выбора папок
o
RowChooseBox – элемент управления для выбора любых объектов
o
BoundTreeView – элемент управления для работы с иерархической
секцией
o
WizardControl – вспомогательный элемент управления для создания
Мастеров
o
NavigationToolStrip – навигационная панель инструментов
–
специализированный
элемент
управления
для
Диалоги – вспомогательные диалоги, которые могут быть вызваны из текущей
формы, и открываются в новом окне:
o
SelectDirectoryEntryDialog
Directory
–
диалог
выбора
пользователя
Active
o
SelectOrganisationalUnitDialog – диалог выбора подразделения Active
Directory
o
SelectDomainDialog – диалог выбора домена Active Directory
o
SelectIconDialog – диалог выбора иконки из файла на диске
Ниже подробно описано использование каждого из элементов управления.
3.3.3.1 Источники данных
Основная идея
разработки визуальных
форм карточек
DocsVision
заключается в максимальном использовании стандартных элементов управления
Visual Studio (TextBox, ComboBox, ListView и т.д.) – вместо того, чтобы предлагать
собственные
элементы
управления,
которые
разработчику
понадобится
дополнительно изучать... Этот подход имеет свои преимущества:
Стандартные элементы управления хорошо документированы (MSDN)
У разработчиков обычно есть навыки работы с ними
Совместимость элементов управления гарантируется Microsoft
DocsVision 4.5: Руководство разработчика на платформе
61
Однако недостатком подобного подхода является тот факт, что стандартные
элементы управления ничего “не знают” о DocsVision. Соответственно, при их
использовании разработчику придется каждый раз писать один и тот же код по
загрузке данных из DocsVision в элемент управления; и обратному сохранению
данных из элемента управления в DocsVision.
Данную проблему предлагается решать при помощи Data Binding –
технологии Microsoft для динамического связывания элемента управления с
источником данных (базой данных, внешней системой, провайдером и т.д.). Она
дает следующие ключевые преимущества:
Настройка в design-time (позволяет создать полнофункциональный элемент
управления для обработки данных без написания какого-либо кода)
Автоматизация рутинных операций по загрузке данных в элемент управления
и сохранению изменений (разработчик избавлен от необходимости
дублировать этот код для каждого элемента)
Поддерживается
подавляющим
большинством
стандартных
элементов
управления Visual Studio, а также элементами сторонних производителей
Для того, чтобы сделать подобное связываение возможным, требуется
наличие специального объекта – источника данных. Библиотека элементов
управления DocsVision предусматривает четыре таких объекта для разных типов
данных в системе; а также один вспомогательный объект – SessionSource.
3.3.3.2 Объект SessionSource
Объект SessionSource является вспомогательным для других источников
данных, и обеспечивает им соединение с сервером DocsVision. Его наличие
является обязательным при использовании механизма связывания (Data
Binding).
Для начала использования объекта SessionSource, его нужно поместить с
панели инструментов на форму карточки. При этом, откроется форма настройки,
позволяющая удобно сконфигурировать параметры соединения с сервером (рис.
3-5):
DocsVision 4.5: Руководство разработчика на платформе
62
Рис. 3-5
На форме можно указать следующие параметры:
Address – адрес сервера DocsVision (SOAP или PIPE)
Database – имя базы данных (можно не указывать, в этом случае будет использована
база данных по умолчанию)
Connect with clear text authentification
аутентификации вместо встроенной
–
признак
использования
базовой
User Name – имя пользователя для базовой аутентификации
Password – пароль для базовой аутентификации
Use the card session at runtime – на этом признаке стоит остановиться подробнее.
Если он НЕ установлен – то будет создана новая сессия с указанным в настройках
сервером и базой данных. Если же он установлен – то параметры соединения с
сервером будут проигнорированы; а сессия будет использована та, что передана в
объект карточки (CardControl.Session). Таким образом, можно установить следующее
простое правило:
-
При разработке карточек, нужно чтобы этот признак был установлен
-
При разработке внешних приложений и утилит, нужно чтобы этот
признак был снят
Нажатие на кнопку “Test connection” позволяет проверить правильность введенных
данных (будет произведена попытка создания новой сессии с указанным сервером).
Если все данные указаны верно – будет выдано сообщение (Рис. 3-6):
DocsVision 4.5: Руководство разработчика на платформе
63
3-6
При нажатии на кнопку Advanced, откроется окно, позволяющее задать
дополнительные настройки сессии (их также можно задать позже в окне свойств
объекта SessionSource) (Рис. 3-7)
3-7
Свойства объекта SessionSource соответствуют типовым параметрам соединения
(приложение 7.1)
3.3.3.3 Источник данных CardDataSource
Объект CardDataSource является уже непосредственным источником данных для
элементов управления. Он позволяет работать с коллекцией данных карточек
(CardDataCollection).
При первичном размещении этого источника данных на форме карточке,
откроется специальный Мастер, которые позволит сконфигурировать источник данных
за несколько простых шагов.
Первый шаг Мастера настройки (рис. 3-8) позволяет указать сессию, с которой
будет работать источник данных CardDataSource:
DocsVision 4.5: Руководство разработчика на платформе
64
3-8
В выпадающем списке представлены все имеющиеся в проекте объекты-сессии
(SessionSource), из которых нужно выбрать тот, который будет использован для
получения данных. При выборе конкретного объекта сессии, в поле “Connection string”
отображаются детальные сведения о выбранном соединении. Кнопка “New session
source” позволяет создать новый объект сессии, если он еще не добавлен в проект.
После выбора соединения и перехода на следующий шаг, предлагается указать
тип карточек, с которыми будет работать данный источник данных (рис 3-9). В дереве
приведены все типы карточек, зарегистрированные в текущей базе данных,
сгруппированные согласно своим библиотекам. Источник данных CardDataSource
может работать только с одним конкретным типом единовременно.
DocsVision 4.5: Руководство разработчика на платформе
65
3-9
Для выбранного типа карточек, источник данных CardDataSource может
получить либо ВСЕ имеющиеся в базе данных экземпляры карточек такого типа (по
аналогии с системной веткой “Карточки” в Навигаторе); либо ограничить количество
возвращаемых карточек по фильтру (поисковому запросу).
ВНИМАНИЕ
Источник данных CardDataSource при получении данных карточек закачивает
ВСЕ данные для КАЖДОЙ найденной карточки на клиента! При большом
количестве карточек, это может привести к существенным задержкам и нагрузке
на канал. Поэтому рекомендуется максимально ограничивать количество
получаемых карточек при помощи ограничений поискового запроса.
По
умолчанию,
Мастер
настройки
источника
данных
CardDataSource
предполагает, что получаются все карточки указанного типа. Поэтому сразу после
выбора конкретного типа карточек становится доступной кнопка Finish, завершающая
работу Мастера.
Для того чтобы конкретизировать список возвращаемых карточек при помощи
поискового запроса, нужно установить признак “Add the search query string”. В этом
случае, становится доступным следующий шаг Мастера (рис. 3-10), который позволяет
указать поисковый запрос для отбора карточек:
DocsVision 4.5: Руководство разработчика на платформе
66
3-10
Можно выбрать уже готовый запрос из числа сохраненных, так и ввести
непосредственно текст запроса в виде XML – для этого необходимо установить курсор
на специальную ветку (Custom), тогда в правой части станет доступным элемент
управления для редактирования запроса (подробнее см. Использование поиска).
ПРИМЕЧАНИЕ
При выборе сохраненного поискового запроса, источник данных копирует и
сохраняет его непосредственный текст, а не ссылку! Поэтому последующие
изменения этого сохраненного запроса в базе данных уже не отразятся на
источнике данных – его придется переконфигурировать явно.
После указания запроса и нажатия кнопки Finish, конфигурирование источника
данных завершается. Впоследствии все установленные при помощи Мастера параметры
можно изменить – в окне свойств (Properties) в Visual Studio, или в run-time в виде
свойств объекта CardDataSource.
Доступен следующий набор свойств:
CardTypeId (Guid) – идентификатор типа карточек
SessionSource – объект сессии (соединение) для источника данных
QueryString (string) – строка поискового запроса
После создания и настройки источника данных, можно приступать к привязке
готового источника к элементу управления. Рассмотрим пример использования объекта
CardDataSource в качестве источника данных для стандартного элемента управления
ComboBox.
Прежде всего, необходимо поместить элемент управления на форму карточки, и
задать значения основных атрибутов (название, расположение, и т.д.). После этого,
можно приступить к связыванию элемента управления с источником данных (Рис. 311):
DocsVision 4.5: Руководство разработчика на платформе
67
3-11
Для этого требуется задать значения следующих свойств:
Data Source - источник данных для элемента управления (выбираем
созданный и настроенный CardDataSource)
Dispay Member – поле источника данных, значение которого будет
использоваться для отображения в элементе управления. Поскольку в
данном случае используется источник данных карточек DocsVision
(CardDataSource), то в качестве полей данных возвращается набор
стандартных системных атрибутов карточек (описание, дата создания, дата
изменения, и т.д.)
Value member – поле источника данных, которое будет определять
значение выбранного элемента. В случае CardDataSource, уместо в
качестве такого поля использовать идентификатор карточки (ID)
Selected Value – выбранное по умолчанию значение в списке
После указания значений данных свойств, привязка элемента управления к
источнику данных завершена, и он готов к работе. Если после этого сразу
запустить разработанную карточку – то в выпадающем списке появятся карточки
выбранного типа. Как легко увидеть, для этого не понадобилось написать ни
одной строки кода!
3.3.3.4 Источник данных RowDataSource
Источник данных RowDataSource предназначен для работы с набором строк
секции карточки (RowDataCollection). При этом, он позволяет не только
просматривать – то и изменять, добавлять и удалять строки в секции.
Как и в случае описанного выше источника CardDataSource, первичную
конфигурацию источника данных можно выполнить при помощи Мастера.
Первый шаг Мастера полностью аналогичен предыдущему, и позволяет указать
сессию, с которой будет работать источник данных.
На втором шаге (рис. 3-12) Мастер предлагает указать секцию, строки из которой
будет получать источник данных. Допускается работа с секциями любых типов
(плоская, табличная, древовидная). По умолчанию Мастер предполагает, что будут
использоваться все строки указанной секции. Если же необходимо отфильтровать
набор строк – то необходимо установить признак “Add the search query string”. Тогда
следующий шаг Мастера позволит указать поисковый запрос для отбора строк секции
(подробнее см. Использование поиска). Дополнительный признак “Get all section
rows” на этой же странице указывает на необходимость получения всех строк
DocsVision 4.5: Руководство разработчика на платформе
68
иерархической секции, без учета уровня иерархии (пример:
подразделения и организации из справочника сотрудников).
получить
все
ПРИМЕЧАНИЕ
При использовании этого признака, результирующий набор строк в источнике
данных НЕ будет доступен для добавления и удаления строк!
3-12
На следующем шаге (рис. 3-13) предлагается выбрать конкретный экземпляр
карточки, из которой будут получаться строки (в случае если выбрана секция
справочника, которые всегда существуют в системе в единственном экземпляре –
в таком выборе нет необходимости, и можно пропустить этот шаг). Для выбора
конкретной карточки можно воспользоваться кнопкой “Select card”. Признак
“Use the card data from runtime” сигнализирует о том, что для получения
данных будет использоваться динамический объект, доступный через свойство
CardData в контексте данной формы. В случае разработки компонента карточки,
это будут данные самой этой карточки.
DocsVision 4.5: Руководство разработчика на платформе
69
3-13
Наконец, последний шаг предназначен для указания запроса фильтрации данных
(он становится доступен при установке признака “Add the search query string”). Как
и в случае CardDataSource, на этом шаге можно выбрать сохраненный поисковый
запрос; или указать текст запроса напрямую.
После этого
использованию.
работа
Мастера
завершается,
и
источник
данных
готов
к
Все параметры, установленные для источника данных при помощи Мастера,
можно впоследствии изменить через свойства объекта RowDataSource:
CardInstanceID – идентификатор экземпляра карточки, из которой будут
получаться строки
CardTypeID – идентификатор типа карточки, из которой будут получаться
строки
SectionTypeID – идентификатор типа секции карточки, из которой будут
получаться строки
SearchQuery – текст поискового запроса для фильтрации строк
ParentRowID – идентификатор родительской строки (для подчиненной секции)
ParentTreeRowID – идентификатор родительской строки в иерархической
секции
SessionSource – объект сессии
Пример использования источника данных RowDataSource: разместим на форме
карточки таблицу со списком всех сотрудников из справочника сотрудников. Для
DocsVision 4.5: Руководство разработчика на платформе
70
этого необходимо настроить источник данных на соответствующую секцию; а также
установить признак «Get all section rows», чтобы получить все строки секции
независимо от уровня в иерархи.
В качестве элемента управления для работы со строками целесообразно
использовать стандартный табличный элемент управления DataGridView – который
позволяет не только просматривать строки, но и редактировать их. После указания
элементу управления источника данных, он автоматически получает заголовки
столбцов как имена соответствующих полей секции (рис. 3-14):
3-14
Сразу после этого элемент управления готов к работе, и позволяет
просматривать данные справочника сотрудников.
3.3.3.5 Источник данных InfoRowDataSource
Источник данных InfoRowDataSource предназначен для работы с данными
представлений. В отличие от предыдущего источника данных, он позволяет только
просматривать данные – и не предоставляет возможности их редактирования.
Конфигурирование этого источника данных, как и во всех остальных случаях,
осуществляется в режиме Мастера. На первом шаге предлагается выбрать объект
сессии для установки соединения. На втором шаге необходимо указать представление
из числа сохраненных описаний представлений на данном сервере, или создать новое
(custom) (рис. 3-15):
DocsVision 4.5: Руководство разработчика на платформе
71
Рисунок 3-15
Поскольку представление описывает всего лишь способ отображения данных, а не
сами данные – то необходимо указать еще источник данных для представления. Это
можно сделать на следующем шаге Мастера (Рисунок 3-16). Возможны следующие
варианты:
Card Type – в представлении будут отображены все карточки указанного типа
(необходимо выбрать конкретный тип карточки в дереве типов)
Folder – в представлении будут отображены данные карточек, лежащих в
конкретной папке (необходимо указать папку в дереве папок)
Recycle Bin – отображает содержимое корзины (все удаленные карточки)
Search – представление применяется к результатам выполнения поискового
запроса (необходимо выбрать сохраненный поисковый запрос, или ввести его
текст)
Здесь же можно указать дополнительные признаки, влияющие на формирование
представления:
Show arсhived – выводить в представлении архивные карточки
Show deleted – выводить также удаленные карточки
Show hidden – выводить скрытые и системные типы карточек
Это признаки могут быть установлены совместно в любых сочетаниях.
DocsVision 4.5: Руководство разработчика на платформе
72
Рисунок 3-16
После определения данных представления, работа Мастера заканчивается, и
источник данных готов к использованию. Все параметры также доступны для
последующего изменения в виде свойств объекта InfoRowDataSource:
ItemId – идентификатор выбранной папки, при использовании папки в качестве
источника данных; либо идентификатор типа карточек.
SearchQuery – текст поискового запроса, если НЕ используется сохраненный
(при использовании поиска в качестве источника данных)
SearchQueryID – идентификатор сохраненного поискового запроса для выборки
карточек (при использовании поиска в качестве источника данных)
ViewID – идентфикатор сохраненного описания представления
ViewQuery – XML-описание представления, если НЕ используется сохраненное
ViewSourceType – тип данных в представлении (Card Type, Folder, Recycle Bin,
Search)
3.3.3.6 Источник данных ReportDataSource
Последний источник данных ReportDataSource предназначен для работы с
данными хранимых процедур.
Как и в остальных случаях, первичное конфигурирование источника данных
выполняется при помощи Мастера. После выбора активного соединения на первом
шаге, Мастер предлагает указать хранимую процедуру из числа зарегистрированных в
базе данных (отображаются хранимые процедуры сразу из всех загруженных в БД
библиотек карточек!) (Рисунок 3-17)
DocsVision 4.5: Руководство разработчика на платформе
73
Рисунок 3-17
По умолчанию в базе данных присутствуют только системные хранимые
процедуры из решения “Управление процессами”, названия которых приведены на
рисунке.
После выбора процедуры, Мастер предлагает указать значения всех ее
параметров (Рисунок 3-18). У каждой хранимой процедуры собственный уникальный
набор параметров, определенный на этапе ее разработки. Часть из них может быть
обязательной, часть – нет. Для облегчения процесса заполнения параметров, Мастер
подсказывает тип каждого из них в строке статуса.
DocsVision 4.5: Руководство разработчика на платформе
74
Рисунок 3-18
После ввода всех обязательных параметров и завершения работы Мастера,
источник данных готов к работе.
Все параметры также доступны для последующего изменения в виде свойств
объекта ReportDataSource:
ReportID – идентификатор хранимой процедуры
Parameters – коллекция значений параметров процедуры
3.3.3.7 Элементы управления DocsVision
Как показывает практика, далеко не все задачи можно решить при помощи
технологии связывания данных Data Binding. Например, невозможно корректно
отобразить иерархические данные в виде дерева – потому что стандартный элемент
управления TreeView просто не поддерживает Data Binding. Кроме того, область
применения источников данных ограничена задачами просмотра и редактирования
упорядоченных наборов данных (строк, карточек) – тогда как типичные практики
предусматривают и другие способы взаимодействия с пользователем (например, выбор
каких-либо объектов при помощи специализированного браузера).
Для решения некоторых из этих задач, DocsVision предлагает несколько
вспомогательных элементов управления собственной разработки. В их числе:
o
BoundChooseBox – универсальный элемент управления для выбора
значений ссылочных полей
o
CardChooseBox – специализированный элемент управления для выбора
карточек
DocsVision 4.5: Руководство разработчика на платформе
75
o
FolderChooseBox
выбора папок
–
специализированный
элемент
управления
для
o
RowChooseBox – элемент управления для выбора любых объектов
o
BoundTreeView – элемент управления для работы с иерархической
секцией
o
NavigationToolStrip – навигационная панель инструментов
o
WizardControl – вспомогательный элемент управления для создания
Мастеров
3.3.3.8 Элемент управления BoundChooseBox
Элемент управления BoundChooseBox предназначен для выбора значений
ссылочных полей при помощи унифицированного интерфейса (Рисунок 3-19).
В стандартном виде, элемент управления ChooseBox представляет из себя
поле для отображения результатов выбора, и связанную с ним кнопку “…”,
инициирующую новый выбор:
Рисунок 3-19
BoundChooseBox использует технологию Data Binding (что отражено в его
названии) для автоматической привязки к одному из полей карточки ссылочного
типа (RefID или RefCardID). При этом он автоматически определяет тип ссылки,
и в зависимости от этого отображает соответствующий интерфейс для выбора
значения:
RefCardID – если поле является ссылкой на карточку, то для выбора
значения BoundChooseBox отображает интерфейс Навигатора, в котором
разрешено выбирать карточки;
RefID – для типизированной ссылки на строку другой карточки (или
справочника), на выбор открывается пользовательский интерфейс этой
карточки (например, если поле является ссылкой на строку секции
справочника сотрудников – то на выбор будет открыт справочник
сотрудников). Особым случаем является ссылка на строку секции карточки
папок – в этом случае элемент управления откроет на выбор Навигатор, в
котором разрешено выбирать папки.
ПРИМЕЧАНИЕ
Если поле RefID карточки является нетипизированным (не указаны значения типа
и секции связанной карточки) – то BoundChooseBox не сможет работать с таким
полем! В этом случае рекомендуетя использовать элемент управления
CustomChooseBox.
При работе в режиме связывания, элемент управления BoundChooseBox
автоматически выполняет чтение данных из поля карточки и первичную
инициализацию; а также автоматически сохраняет выбранное значение в поле
карточки в процессе использования. Таким образом, разработчику нужно
выполнить только предварительную настройку элемента управления в Design
Time, и нет необходимости писать код обработчиков событий.
Кроме этого, элемент управления BoundChooseBox имеет дополнительные
сервисные функции:
Поддержка быстрого поиска и выбора объектов по нажатию горячих
клавиш “Ctrl+K”
DocsVision 4.5: Руководство разработчика на платформе
76
Возможность ассоциации дополнительного контекстного меню для поля
результатов выбора (Рисунок 3-20)
Рисунок 3-20
Возможность ассоциации дополнительного контекстного меню для кнопки
выбора (Рисунок 3-21)
Рисунок 3-21
Прежде чем приступить к использованию элемента управления BoundChooseBox,
необходимо подготовить источник данных для него. В качестве источника данных
может выступать объект RowDataSource, предназначенный для работы со строками
секции карточки. Однако здесь необходимо учесть один ньанс: источник данных
RowDataSource может возвращать сразу несколько строк (например, для секции
коллекционного типа); а элемент управления BoundChooseBox может отображать
только значение конкретного поля одной конкретной строки. Чтобы разрешить это
противоречие, вводится еще один промежуточный объект – BindingSource, который
предназначен как раз для того, чтобы выбрать одну конкретную строку из набора,
возвращаемого RowDataSource. Таким образом, общую картину связывания данных в
данном случае можно представить следующим образом (Рисунок 3-22):
RowDataSource
BindingSource
BoundChooseBox
e
Рисунок 3-22
Объект BindingSource входит в число стандартных элементов управления
Microsoft, и доступен на панели инструментов (Toolbox) в группе “Data”. Использовать
его достаточно просто, он содержит всего одно значимое свойство – DataSource, где
нужно разместить ссылку на уже подготовленный источник данных RowDataSource.
После создания и настройки источников данных (RowDataSource и
BindingSource) можно приступать к настройке собственно элемента управления
BoundChooseBox.
В свойстве BindingSource необходимо указать ссылку на предварительно
настроенный объект BindingSource. После этого, в свойстве DataMember появится
возможность выбрать (или ввести вручную) название конкретного поля карточки, с
которыми связывается элемент управления BoundDataSource. Именно описание этого
поля в схеме карточки будет являться определяющим для дальнейшей работы элемента
управления (что конкретно он будет выбирать).
Дополнительно можно указать свойство FormatString – определяющее, как
именно BoundChooseBox будет отрображать выбранное значение. Формировать
отобржаемое значение можно при помощи комбинации строковых констант и значений
любых полей той строки, из которой производится выбор. Имена полей оформляются в
строке отображения в фигурных скобках; а строковые константы – напрямую. Таким
DocsVision 4.5: Руководство разработчика на платформе
77
образом, пример строки отображения для вывода данных о сотруднике (строка секции
Emploees из справочника сотрудникорв – RefStaff) может выглядеть так:
Фамилия:{LastName}_Имя:{FirstName}_Отчество:{MiddleName}
Свойства CommandMenuStrip и ContextMenuStrip позволяют сформировать
контекстные меню для кнопки выбора и отображаемого значения соответственно. Для
реализации самих контекстных меню используется стандартный элемент управления
Microsoft ContextMenuStrip. Его необходимо предварительно добавить на форму
карточки и настроить его свойства (добавить пункты меню), а также создать
обработчики для событий выбора пунктов меню. Готовый и настроенный элемент
управления можно указать в качестве значения свойства CommandMenuStrip или
ContextMenuStrip.
ПРИМЕЧАНИЕ
В случае использования меню команд выбора CommandMenuStrip, стандартный
значок кнопки выбора «…» будет заменен на иконку первого из пунктов
контекстного меню.
Другие свойства элемента управления BoundChooseBox:
Caption – заголовок окна выбора
HideNotAvailable – признак не показывать скрытые элемиенты для выбора
SearchDelimiter – разделительный символ для быстрого поиска (элемент управления
позволяет выполнять быстрый поиск по всем полям, указанным в строке отображения, в
порядке их следования; а для разделения этих полей при вводе используется этот символ).
По умолчанию это пробел.
SearchSubstring – для бытрого поиска (по Ctrl+K) признак, искать ли вхождение подстроки
только сначала или любом месте. По умолчанию значение равно false, то есть поиск ведется
только по первым символам.
Text – отображаемое значение элемента управления
Value – выбранное значение (идентификатор)
Методы объекта BoundChooseBox:
System.Guid ChooseValue() – инициирует процесс выбора значения
QuickSearch() – инициирует быстрый поиск по введенному тексту
3.3.3.9 Элемент управления CardChooseBox
Элемент управления CardChooseBox является специализированной версией
ChooseBox, предназначенной только для выбора карточек. Этот элемент управления
не поддерживает технологию Data Binding, поэтому для его использования потребуется
вручную написать код для инициализации существующими данными, и для сохранения
результата выбора. Вместе с тем, данный элемент управления предоставляет гораздо
большую гибкость по сравнению с BoundChooseBox, за счет того что позволяет
разработчику управлять особенностями своей работы, в том числе – указывать
поисковый запрос для фильтрации карточек, доступных на выбор. Это позволит,
например, ограничить область выбора конкретным типом карточек.
Для указания фильтра используется свойство CardsFilter, которое доступно
только программно (в run-time). В качестве значения свойства необходимо установить
DocsVision 4.5: Руководство разработчика на платформе
78
ссылку на поредварительно созданный объект
использовании поиска в соответствующей главе).
Остальные свойства элемента управления
аналогичным свойствам BoundChooseBox.
SearchQuery
(подробнее
CardChooseBox
об
соответствуют
Для чтения выбранного значения из элемента управления можно использовать
свойства Text (отображаемое значение) и Value (идентификатор выбранного значения);
а также событие OnValueChanged(object sender, System.EventArgs e) – которое инициируется
после завершения нового выбора.
Пример инициализации элемента управления CardChooseBox ограничивающий
возможность выбора только карточками файла:
const string FILE_CARD_TYPE = "{2BBD0A41-265E-4FF8-82D6-C6342F34B1AF}";
SearchQuery query = session.CreateSearchQuery();
query.AttributiveSearch.CardTypeQueries.AddNew(new Guid(FILE_CARD_TYPE));
cardChooseBox1.CardsFilter = query;
3.3.3.10 Элемент управления FolderChooseBox
Как и CardChooseBox, элемент управления FolderChooseBox является
специлизированной версий ChooseBox, предназначенной для выбора папок. Он имеет
cпецифическую возможность ограничивать тип папок, которые разрешается выбирать –
для этого предназначено свойство
DocsVision.Platform.ObjectManager.SystemCards.FolderTypes AllowedFolderTypes
Значение свойства является битовой маской, которая может быть сочетанием
следующих значений:
FolderTypes.All – все типы одновременно;
FolderTypes.None – тип не определен;
FolderTypes.Regular – обычная папка;
FolderTypes.Root – корневая папка;
FolderTypes.Virtual – виртуальная папка;
FolderTypes.Delegate – папка-делегат;
FolderTypes.SystemHidden – системная папка;
FolderChooseBox также не поддерживает Data Binding, поэтому код по
загрузке/сохранению данных из этого элемента управления необходимо будет написать
самосотоятельно.
3.3.3.11 Элемент управления RowChooseBox
Последний вариант элемента управления для выбора значений, RowChooseBox,
является
специализированным
средством
для
выбора
строк
из
карточек
(справочников). От BoundChooseBox его отличает отсутствие поддержки Data Binding,
но бОльшая гибкость в настройке и использовании за счет дополнительных свойств:
System.Guid CardTypeId – идентификатор типа карточки, из которой нужно выбирать
строки
System.Guid SectionTypeId – идентификатор типа секции, из которой нужно выбирать
строки
DocsVision 4.5: Руководство разработчика на платформе
79
System.Guid CardInstanceId – идентификатор конкретного экземпляра карточки, из которой
нужно выбирать строки (используется в случае если карточка НЕ является справочником)
Значения этих свойств нужно указать в design-time, или программно при
инициализации элемента управления;
а также добавить обработчики для
чтения/записи значений из элемента управления.
3.3.3.12 Элемент управления BoundTreeView
Элемент управления BoundTreeView предназначен для отображения данных
иерархической секции. Как следует из его названия, этот элемент поддерживает
технологию Data Binding – то есть позволяет настроить его без необходимости
написания какого-либо кода. Это же объясняет и сам факт его появления – он вызван
тем, что стандартный элемент управления TreeView не поддерживает технологию Data
Binding. Внешний вид элемента управления BoundTreeView (Рисунок 3-23):
Рисунок 3-23
По способу использования, элемент управления BoundTreeView похож на
BoundChooseBox – он привязывается к источнику данных секции (RowDataSource) с
использованием вспомогательного объекта BindingSource:
RowDataSource
Ссылка на BindingSource
BoundTreeView.
BindingSource
записывается
BoundTreeView
в
одноименное
свойство
объекта
Кроме этого, необходимо заполнить следующие свойства элемента управления:
DataMember – имя поля секции, к которому будет привязываться элемент управления.
Значение этого поля будет формировать значение (Value) каждого узла в дереве.
RootNodeText – имя корневого узла (если это свойство не указать, то имя корневого узла
будет пустым)
FormatString – отображаемое значение имен узлов. Формировать отобржаемое значение
можно при помощи комбинации строковых констант и значений любых полей той строки, с
которой связан элемент управления. Имена полей оформляются в строке отображения в
фигурных скобках; а строковые константы – напрямую.
3.3.3.13 Элемент управления WizardConrol
DocsVision 4.5: Руководство разработчика на платформе
80
Элемент управления WizardControl позволяет облегчить процесс создания
стандартных Мастеров (последовательность форм с возможнотью навигации
вперед/назад). Внешний вид элемента управления (Рисунок 3-24):
Рисунок 3-24
WizardControl имеет ряд свойств, определяющих его внешний вид и
поведение:
int ButtonHeight – высота стандартных кнопок (Back, Next, Cancel, Finish)
int ButtonWidth - ширина стандартных кнопок (Back, Next, Cancel, Finish)
int HorizontalSpacing – расстояние между кнопками по горизонтали
int VerticalSpacing – расстояние между кнопками по вертикали
string BackButtonText – текст кнопки “Back”
string CancelButtonText – текст кнопки “Cancel”
string FinishButtonText – текст кнопки “Finish”
string HelpButtonText – текст кнопки “Help”
System.Drawing.Size DefaultSize – начальный размер элемента управления
System.Windows.Forms.FlatStyle FlatStyle – стиль отрисовки элемента управления
bool HelpButtonVisible – признак, отображать ли кнопку помощи (Help)
Собственно шабор шагов Мастера задается при помощи коллекции
WizardPages – которую можно редактировать при помощи специального
визуального редактора (Рисунок 3-25):
DocsVision 4.5: Руководство разработчика на платформе
81
Рисунок 3-25
Редактор позволяет добавить произвольное количество страниц (шагов
Мастера); а также менять порядок их следования. Каждая страница имеет
единственное значимое свойство – Text, которое позволяет определить
заголовок страницы.
После определения всех страниц, они появляются в Мастере; и можно
добавлять интерактивные элементы управления непосредственно на них.
Переход между страницами при этом осуществляется при помощи стандартных
навигационных кнопок Мастера.
Для завершения
основных событий:
разработки
Мастера,
остается
добавить
обработчики
OnWizardFinished(System.EventArgs e) – событие инициируется при нажатии на кнопку
Finish, и позволяет реализовать необходимые действия по завершению его работы
(сохранить результаты работы, выполнить какие-то действия, и т.д.)
OnWizardCanceled(System.EventArgs e) событие инициируется при нажатии на кнопку
Cancel, и позволяет реализовать необходимые действия по аварийному прерыванию его
работы (закрыть форму на которой расположен Мастер)
OnSelectedIndexChanging(DocsVision.Platform.WinForms.Controls.WizardControl.Selected
IndexChangingEventArgs e) – событие инициируется ДО смены вкладки (при перемещении
вперед или назад), и позволяет в случае необходимости воспрепятствовать этому переходу
(это может быть полезно для реализации проверки ввода всех необходимых параметров,
прежде чем разрешить переход к следующему шагу)
OnSelectedIndexChanged(System.EventArgs e) – это событие возникает ПОСЛЕ перехода на
новый шаг (вперед или назад), и позволяет выполнить какие-то действия по инциализации
элементов управления на новом шаге
DocsVision 4.5: Руководство разработчика на платформе
82
3.4
КОМПОНЕНТ БИБЛИОТЕКИ КАРТОЧЕК
Так же как и для карточки, реализация библиотеки предусматривает два
основных этапа: создание описания (схемы) библиотеки в формате XML и реализация
программного компонента.
Основная задача компонента библиотеки карточек – это кэширование XMLописаний (схем) и иконок всех карточек, входящих в библиотеку. Это избавляет
клиентов от необходимости выполнять запрос к серверу при каждом обращении к
метаданным карточек и, таким образом, существенно повышает производительность их
работы.
Помимо этого, по наличию или отсутствию регистрации данного компонента на
клиентской машине определяется сам факт установки решения в целом. Если решение
зарегистрировано в базе данных, но при запуске Навигатор не может создать
компонент библиотеки карточек, им будет предпринята попытка заново установить
инсталляционный пакет решения на данной машине, а в случае неудачи - выдано
сообщение о том, что библиотека карточек некорректно установлена.
ПРИМЕЧАНИЕ
По этой причине компонент библиотеки карточек является обязательной частью
законченного решения.
Его создание может быть пропущено или отложено в процессе разработки
карточек решения (в пределах одной разработческой машины), но к нему
обязательно необходимо будет вернуться при распространении созданного
решения.
С точки зрения реализации, компонент библиотеки — это очень простой класс,
реализующий интерфейс ICardLibraryInfo из библиотеки ObjectManager. Он
возвращает информацию о библиотеке, а также описания и иконки для каждой
карточки этой библиотеки. Данный интерфейс уже реализован в базовом классе
DocsVision.Platform.WinForms.CardLibrary, поэтому достаточно унаследовать свою
реализацию от этого класса, и переопределить соответствующие методы:
GetIcon – метод возвращает иконку самой библиотеки карточек (отображается в
Навигаторе в ветке Карточки)
GetCardIcon (CardTypeID) – должен вернуть иконку типа карточки с указанным
идентификатором
GetCardDefinition (CardTypeID) – должен вернуть XML-описание карточки с
указанным идентификатором
ВНИМАНИЕ
Номер версии в сборке библиотеки (assemblyVersion.FileVersion), должен
совпадать с номером версии, который указан в XML-описании библиотеки. В
противном случае будет появляться предупреждение о несовпадении версий
библиотеки на сервере и на клиенте.
В код проекта также необходимо включить ресурсный файл, который будет
содержать иконки и XML-описания карточек, входящих в библиотеку. Такой файл
можно создать при помощи встроенного редактора Visual Studio. А чтобы избежать
дублирования, можно просто вставить в ресурсный файл ссылки на файлы из проекта
– например, так:
<data name="Icon_TestCard" type="System.Resources.ResXFileRef,
System.Windows.Forms">
<value>..\..\CardDefs\Icons\TestCard.ico;System.Drawing.Icon,
System.Drawing, Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a</value>
</data>
<data name="Definition_TestCard" type="System.Resources.ResXFileRef,
System.Windows.Forms">
DocsVision 4.5: Руководство разработчика на платформе
83
<value>..\..\CardDefs\TestCard.xml;System.String, mscorlib,
Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089;utf8</value>
</data>
ПРИМЕЧАНИЕ
У ресурсного файла обязательно необходимо установить атрибут build action –
embedded recource!
Пример реализации самого класса библиотеки карточек:
using System;
using System.Drawing;
using System.Runtime.InteropServices;
using DocsVision.Platform.WinForms;
namespace DocsVision.Test
{
[ComVisible(true)]
[Guid("9FD12D2E-F17F-4CCC-8598-38A52513E970")]
[ClassInterface(ClassInterfaceType.None)]
public class TestCardLib : CardLibrary
{
public TestCardLib()
{
}
public override Icon GetIcon()
{
return Resources.TestCardLibIcon;
}
public override Icon GetCardIcon(Guid cardTypeID)
{
if (cardTypeID == CardIDs.TestCard.ID)
return Resources.TestCardIcon;
}
public override string GetCardDefinition(Guid cardTypeID)
{
if (cardTypeID == CardIDs.TestCard.ID)
return Resources.TestCardDefinition;
}
}
}
DocsVision 4.5: Руководство разработчика на платформе
84
4
РЕШЕНИЕ ТИПОВЫХ ЗАДАЧ
Объектная модель (API) платформы является единым средством для решения
любых классов задач – от разработки прикладных утилит до полноценных решений
(библиотек карточек).
Для удобства разработчика все функции API расположены в одном модуле –
DocsVision.Platform.ObjectManager.dll
ПРИМЕЧАНИЕ
Библиотека
DocsVision.Platform.ObjectManager
является
managedсборкой, и поэтому может быть использована при разработке приложений и
карточек на платформе Microsoft .NET Framework (на языках C# или VB.NET).
Также доступна COM-версия этой библиотеки – objectmanaged.dll, которая может
использоваться при разработке приложений и карточек на базе технологии COM
(сохранена для совместимости с предыдущими версиями).
Поскольку библиотека ObjectManager содержит сотни различных классов и тысячи
методов – создавать подробное руководство по всем этим объектам было бы непомерно
сложной задачей. Вместо этого, в данном руководстве сделан основной упор на
сценарии использования API для решения конкретных задач, с которыми чаще всего
приходится сталкиваться разработчикам на платформе.
Для
каждого
сценария
указан
перечень
объектов,
которыми
можно
воспользоваться, приведено описание их свойств и методов, даны примеры кода и
рекомендации по построению оптимального решения.
ПРИМЕЧАНИЕ
Назначение и функции остальных методов, не упомянутых в данном руководстве,
чаще всего очевидны из их названия и/или контекстной подсказки. Если этого
недостаточно, или требуется какая-то дополнительная информация по
использованию объектной модели, то заказчики могут её получить у партнеров
DocsVision в рамках договоров на оказание консультационных услуг (партнеры –
у компании DocsVision по аналогичным договорам).
Для изолированных областей функциональности в рамках объектной модели
выделены специальные объекты, которые дают единую «точку доступа» к этой
функциональности и упрощают её использование. Все эти объекты доступны из
главного объекта - пользовательской сессии (UserSession) в виде его свойств. Отличить
их легко по наличию в названии объекта служебного слова «Manager»:
AccessManager – управление правами (дескрипторами безопасности) на объекты
системы;
CardManager – чтение, изменение, создание и удаление данных (карточек);
ExtensionManager – работа с серверными расширениями.
FileManager – работа с файлами;
LockManager – управление блокировками на объекты;
LogManager – операции с журналом работы системы;
ProfileManager – мендежер пользовательских профилей (настроек);
ReportManager – доступ к хранимым процедурам;
DocsVision 4.5: Руководство разработчика на платформе
85
Также в состав платформы входят дополнительные библиотеки и сборки, которые
содержат те или иные функции для работы с системой. Среди них:
DocsVision.Platform.dll –сборка, содержащая функции общего назначения
(функции для работы с безопасностью, вспомогательные функции для работы со
свойствами файлов Office)
DocsVision.Platform.WinForms.dll – сборка, содержащая классы и элементы
управления для разработки карточек в среде Windows Forms
DocsVision.Platform.WPF.dll – сборка, содержащая
управления для разработки карточек по технологии WPF
4.1
классы
и
элементы
УПРАВЛЕНИЕ СЕССИЯМИ
Пользовательская сессия (UserSession) является главным объектом в API системы,
обеспечивающим единую точку доступа ко всем остальным функциям объектной
модели.
С физической точки зрения сессия представляет собой контекст сеанса связи с
сервером для конкретного пользователя. Сессия ассоциируется с конкретной доменной
учетной записью, от имени которой установлено соединение, – и в дальнейшем все
привилегии на доступ к данным из этой сессии будут проверяться именно для этой
учетной записи.
ПРИМЕЧАНИЕ
Для выполнения операции с привилегиями другого пользователя требуется явно
создать новую сессию от имени этого пользователя.
В рамках сессии также кэшируются все данные, к которым производилось
обращение, для ускорения последующего доступа к ним. Размер кэша и
продолжительность
пребывания
в
нём
данных
регулируются
ObjectManager
автоматически, на основании внутренних алгоритмов. Разработчик может только явно
потребовать удаления из кэша конкретных объектов (при помощи соответствующих
методов этих объектов).
Создание сессии является первоочередной задачей при разработке любых
внешних приложений, работающих с DocsVision (при разработке внутрисистемных
объектов – таких как карточек или сценариев – необходимости в явном создании
сессии нет, так как готовая сессия уже передаётся этим объектам).
Для управления сессиями предназначен специальный объект – SessionManager.
Это один из немногих объектов в API системы, который требует явного создания. Он
позволяет создавать новые сессии, получать информацию о других открытых сессиях
или закрывать их.
ПРИМЕЧАНИЕ
В связи с этим, для вызова некоторых методов менеджера сессий требуются
административные привилегии.
DocsVision 4.5: Руководство разработчика на платформе
86
Создать экземпляр менеджера сессий можно при помощи статического метода
CreateInstance в самом клаcсе SessionManager:
SessionManager manager = SessionManager.CreateInstance();
После этого, необходимо задать менеджеру сессий параметры соединения с
сервером DocsVision. Для этого предусмотрен метод Connect, принимающий на вход
различные наборы параметров:
Connect(string connectionString) – устанавливает соединение с сервером на основании
универсальной строки соединения. Строка соединения позволяет указать значения
параметров соединения, разделенных точкой с запятой. Полный список параметров
соединения приведен в приложении 7.1
Connect(string connectAddress, string baseName) - установка
указанием строки соединения и имени базы
Connect(string connectAddress, string baseName, string userName, string password) – установка
соединения с явным указанием строки соединения, имени базы, имени пользователя
и пароля.
соединения
с
явным
Пример установки соединения с использованием строки соединения:
string connect =
"ConnectAddress=http://localhost/DocsVision41/StorageServer/StorageServerServ
ice.asmx;BaseName=DocsVision41";
SessionManager manager = SessionManager.CreateInstance();
manager.Connect(connect);
Пример установки соединения с явным указанием реквизитов:
SessionManager manager = SessionManager.CreateInstance();
manager.Connect("\\.\Pipe\DocsVision41\StorageServer", string.Empty, "User",
"Pass");
После успешной установки соединения можно приступать к созданию новой
сессии. Это делается при помощи метода CreateSession, который вернет в качестве
параметра ссылку на объект сессии (UserSession):
UserSession session = manager.CreateSession();
Помимо этого, объект менеджера сессий содержит ряд вспомогательных методов
для управления сессиями:
CloseSession(System.Guid sessionId) – принудительное закрытие любой сессии (для
использования этого метода требуются административные привелегии!);
GetOpenSessions() – получение списка всех открытых сессий.
Также объект UserSession предоставляет возможность получить дополнительные
сведения о контексте выполнения или сохранить там собственные данные. Для этого
предназначена коллекция свойств сессии, доступная через свойство Properties.
Эта коллекция содержит предопределённый набор значений по умолчанию,
автоматически задаваемых для всех новых сессий (подробный перечень этих
стандартных свойств можно найти в приложении 7.2). При необходимости, некоторые
из этих параметров можно изменить в процессе работы.
ВНИМАНИЕ
При сохранении собственных данных в свойствах сессии время их жизни
ограничено временем существования сессии. Сохранение этих данных в базе
между разными сессиями не производится.
Пример работы со свойствами сессии:
SessionManager manager = SessionManager.CreateInstance();
DocsVision 4.5: Руководство разработчика на платформе
87
manager.Connect("http://localhost/DocsVision41/StorageServer/StorageServerSer
vice.asmx", string.Empty);
UserSession session = manager.CreateSession();
MessageBox.Show("IP-адрес клиента: " +
session.Properties["ComputerAddress"].Value.ToString());
DocsVision 4.5: Руководство разработчика на платформе
88
4.2
ОПИСАНИЕ МЕТА-ДАННЫХ
Важная часть объектной модели предназначена для работы с мета-данными – то
есть с описаниями структур данных карточек и библиотек. Эти описания, как уже
рассматривалось выше, создаются при помощи утилиты CardManager. В свою очередь
программные объекты для работы с этими описаниями практически полностью
соответствуют их элементам:
CardLibrary
CardTypes
Installers
CardType
Actions
CardAction
Modes
CardMode
Views
CardView
Transforms
CardTransform
Sections
Section
Чаще
всего,
описания
мета-данных
используются
для
построения
в
пользовательском интерфейсе браузеров объектов – примерами которых могут служить
стандартные диалоги поиска и настройки представлений (Рисунок 4-1):
Рисунок 4-1
DocsVision 4.5: Руководство разработчика на платформе
89
Получить доступ к описаниям карточек и библиотек
соответствующих свойств менеджера объектов (CardManager):
можно
при
помощи
DocsVision.Platform.ObjectManager.Metadata.CardLibraryCollection CardLibraries —
возвращает коллекцию библиотек карточек, зарегистрированных в текущей базе данных.
DocsVision.Platform.ObjectManager.Metadata.CardTypeCollection CardTypes — возвращает
коллекцию типов карточек, зарегистрированных в текущей базе данных.
Поскольку динамически изменять схемы данных в системе невозможно (т.к. это
потребует генерации новых структур в базе данных) – то все объекты для работы с
мета-данными доступны только для чтения, и практически не имеют методов; а вся
работа с ними ведется через свойства.
Ниже рассмотрены свойства основных объектов мета-данных.
Свойства объекта CardLibrary – описания библиотеки карточек:
string Alias – псевдоним библиотеки
DocsVision.Platform.ObjectManager.Metadata.CardTypeCollection
коллекция описаний карточек, входящих в библиотеку
System.Guid Clsid – CLSID программного компонента библиотеки
System.Drawing.Icon Icon – иконка библиотеки
System.Guid Id – уникальный идентификатор библиотеки
DocsVision.Platform.ObjectManager.Metadata.CardLibraryInstallerCollection
Installers – сведения о пакетах инсталляции библиотеки
string Name – название библиотеки
string ProgId – ProgID компонента библиотеки
int Version – версия библитеки
CardTypes
–
Свойства объекта CardType – описания типа карточки:
DocsVision.Platform.ObjectManager.Metadata.CardActionCollection
коллекция методов карточки
string Alias – псевдоним типа карточки
DocsVision.Platform.ObjectManager.Metadata.CardSectionCollection
коллекция всех секций карточки (без учета иерархии)
System.Guid Clsid – CLSID программного компонента карточки
string Definition –полное XML-описание карточки
DocsVision.Platform.ObjectManager.Metadata.FetchMode FetchMode – тип чтения
данных карточки
DocsVision.Platform.ObjectManager.Metadata.CardTypeFlags
дополнительные атрибуты карточки
System.Drawing.Icon Icon – иконка типа карточки
System.Guid Id – уникальный идентификатор типа
System.Guid LibraryId – идентификатор библиотеки, которой принадлежит карточка
string LicenseKey - лицензионный ключ для активации COM-компонента библиотеки
DocsVision.Platform.ObjectManager.Metadata.CardModeCollection
коллекция режимов работы карточки
string Name – название типа
DocsVision 4.5: Руководство разработчика на платформе
Actions
–
AllSections
–
Flags
Modes
–
–
90
string ProgId – ProgID компонента карточки
string Schema – XSD-схема описания карточки
DocsVision.Platform.ObjectManager.Metadata.CardSectionCollection
коллекция секций карточки верхнего уровня
DocsVision.Platform.ObjectManager.Metadata.CardTransformationCollection
Transformations – коллекция преобразований карточки
DocsVision 4.5: Руководство разработчика на платформе
Sections
–
91
4.3
ДОСТУП К ДАННЫМ
Для работы с данными карточек в библиотеке менеджера объектов
(ObjectManager) предусмотрен набор специальных объектов, соответствующих
различным уровням данных:
тип карточки (CardType) — этот уровень описывает мета-данные, то есть структуру
данных карточки;
данные экземпляра карточки (CardData) —совокупность всех данных секций и
атрибутов конкретного экземпляра карточки;
секция (SectionData) — секция карточки. Физически – это набор всех строк
принадлежащих данной карточке из SQL таблицы, содержащей строки секций
данного типа. Секции бывают нескольких типов:
Структура — может содержать одну единственную строку. При попытке создать
вторую возникнет ошибка;
Коллекция — содержит плоский набор строк;
Дерево — содержит иерархию строк. Таким образом, у строки в дереве может
быть набор дочерних строк из той же секции.
подсекция (SubSectionData) — подсекция секции карточки. Подмножество строк
секции, подчинённых определённой строке из родительской секции;
строка (RowData) — собственно строка данных. Соответствует одной строке в SQL
таблице;
поле (Field) — значение конкретного поля строки. Для полей секции соответствует
полю строки соответствующей SQL таблицы, однако строка может содержать также
значения связанных полей, полученных по ссылке;
коллекция строк (RowDataCollection) — коллекция строк. Может представлять собой
набор строк на определённом уровне в иерархии строк секции (и в этом случае это
«живая» коллекция, то есть при создании/удалении строки изменения в коллекции
будут видны сразу же); а может быть получена в результате поиска (в этом случае
эта коллекция является «моментальным снимком» данных, и доступна только на
чтение).
Ниже приведены описания методов и приёмов работы для каждого из объектов
данных.
DocsVision 4.5: Руководство разработчика на платформе
92
4.3.1 Типы и экземпляры карточек
Для работы с описаниями и экземплярами карточек предназначены методы
объекта менеджера карточек (CardManager) из библиотеки менеджера объектов. Эти
методы достаточно просты, их значение, во многом, очевидно из названия.
По функциональности методы можно разделить на несколько групп.
Получение/создание экземпляра карточки:
DocsVision.Platform.ObjectManager.CardData GetCardData(System.Guid cardId) —
возвращает по идентификатору карточки объект для работы с её данными. Если карточка
не существует или была помечена как удаленная, возникает соответствующая ошибка.
DocsVision.Platform.ObjectManager.CardData GetCardData(System.Guid cardId, bool
refresh) - возвращает данные карточки с указанным идентификатором. Второй параметр
указывает на необходимость переполучения данных с сервера (если данные карточки уже
лежат в КЭШе, и необходимо получить их актуальную копию).
DocsVision.Platform.ObjectManager.CardData GetCardData(System.Guid rowId,
System.Guid sectionId) - возвращает данные карточки, у которой в секции с типом
sectionId присутствует строка с идентификатором rowId. Этот метод удобно использовать,
если идентификатор самой карточки неизвестен; но известна одна из ее строк.
object GetCard(System.Guid cardId) — возвращает ссылку на программный интерфейс
карточки (используется для работы с системными карточками – папками, нумераторами,
файлами)
object GetCard(System.Guid cardId, bool refresh) — то же самое, но с возможностью
обновления данных в КЭШе;
DocsVision.Platform.ObjectManager.CardData GetDictionaryData(System.Guid
cardTypeId) - возвращает данные справочника указанного типа. Т.к. каждый справочник
существует в системе в единственном экземпляре, то в данном случае можно получить
экземпляр, основываясь на типе
DocsVision.Platform.ObjectManager.CardData GetDictionaryData(System.Guid
cardTypeId, bool refresh) – то же самое, но с возможностью обновления данных в КЭШе;
object GetDictionary(System.Guid cardTypeId) — возвращает ссылку на программный
интерфейс карточки (используется для работы с системными справочниками)
object GetDictionary(System.Guid cardTypeId, bool refresh) - то же самое, но с
возможностью обновления данных в КЭШе;
DocsVision.Platform.ObjectManager.CardData CreateCardData(System.Guid cardTypeId) –
создание нового экземпляра карточки указанного типа
object CreateCard(System.Guid cardTypeId) – то же самое, но вовзращает ссылку на
интерфейс компонента карточки
DocsVision.Platform.ObjectManager.CardData CreateCardData(System.Guid cardTypeId,
System.Guid cardId) - создание нового экземпляра карточки указанного типа с
предопределенным идентификатором
object CreateCard(System.Guid cardTypeId, System.Guid cardId) - то же самое, но
возвращает ссылку на программный интерфейс карточки
Поиск карточек в базе:
DocsVision.Platform.ObjectManager.CardDataCollection GetCards(System.Guid cardTypeId) —
возвращает коллекцию всех карточек данного типа;
DocsVision.Platform.ObjectManager.CardDataCollection FindCards(string queryXml) — ищет
карточки, удовлетворяющие поисковому запросу. Подробнее работа поиска описана в
соответствующей главе.
Удаление/восстановление экземпляра карточки:
DocsVision 4.5: Руководство разработчика на платформе
93
DocsVision.Platform.ObjectManager.ObjectState GetCardState(System.Guid cardId) —
позволяет проверить статус карточки в базе. Принимает одно из нескольких значений:
ObjectState.NotExisting — карточки с указанным идентификатором не существует;
ObjectState.Existing — карточка существует и может быть получена;
ObjectState.Deleted — карточка существует, но помечена как удаленная, работа с ней
невозможна;
DeleteCard(System.Guid cardId, bool permanently) — удаляет указанную карточку. При этом
используется двухступенчатое удаление: при помощи параметра permanently можно
указать, что карточка лишь помечается как удаленная, но её данные в базе еще остаются.
Впоследствии карточку можно восстановить.
DeleteCard(System.Guid cardId) – удаляет карточку навсегда.
RestoreCard(System.Guid cardId) — восстанавливает карточку, помеченную на удаление.
PurgeCards(System.DateTime startDate) — позволяет навсегда удалить карточки, помеченные
как удаленные. Для выбора карточек, подлежащих удалению, можно использовать дату
удаления (для карточки это будет дата последнего изменения);
PurgeCards(System.DateTime startDate, System.Guid cardTypeId) - позволяет навсегда удалить
карточки, помеченные как удаленные. Для выбора карточек, подлежащих удалению,
можно использовать дату удаления и тип карточки.
Работа со ссылками на карточку:
DocsVision.Platform.ObjectManager.CardDataCollection GetLinksToCard(System.Guid cardId,
DocsVision.Platform.ObjectManager.LinkType linkType, int recurseDepth) — возвращает
коллекцию карточек, ссылающихся на данную. Можно специфицировать тип ссылки
(сильная или слабая); а также глубину вложенности ссылок (recurseDepth).
DocsVision.Platform.ObjectManager.CardDataCollection GetLinksFromCard(System.Guid
cardId, DocsVision.Platform.ObjectManager.LinkType linkType, int recurseDepth) —
возвращает коллекцию карточек, на которые ссылается данная карточка. Можно
специфицировать тип ссылки (сильная или слабая); а также глубину вложенности ссылок
(recurseDepth).
ClearLink(System.Guid sectionId, System.Guid rowId, string fieldAlias) — позволяет очистить
ссылку, хранящуюся в указанном поле указанной строки.
Экспорт/импорт карточек в XML:
DocsVision.Platform.ObjectManager.CardDataCollection ImportCards(System.IO.Stream
stream) – импортирует одну или несколько карточек из XML-файла, передаваемого в
качестве параметра stream. Подробнее экспорт и импорт данных рассмотрены в
соответствующей главе.
DocsVision.Platform.ObjectManager.CardDataCollection ImportCards(System.IO.Stream
stream, DocsVision.Platform.ObjectManager.ImportCardInspector cardInspector) импортирует одну или несколько карточек из XML-файла, с использованием собственного
алгоритма импорта (cardInspector)
4.3.2 Иерархия строк
Секции данных карточки сами по себе могут быть упорядочены иерархически
(иерархия секций определяется в описании карточки). В этом случае, у строки из
родительской секции может быть набор дочерних строк из подчинённой секции. Вместе
с тем, в иерархических секциях каждая строка может иметь дочерний набор строк из
той же секции, что и она сама. Таким образом, существует два важных служебных
атрибута строки: ParentRowID (идентификатор строки в родительской секции) и
DocsVision 4.5: Руководство разработчика на платформе
94
ParentTreeRowID (идентификатор родительской строки в той же секции иерархического
типа). В совокупности эти атрибуты позволяют адресовать плоский набор строк
(уровень) в иерархии строк секции (которая сама по себе есть плоский набор строк —
таблица). При этом:
у строк из плоской (структура, коллекция) секции ParentTreeRowID = Guid.Empty
у строк из секции, находящейся на верхнем уровне в дереве, ParentTreeRowID =
Guid.Empty;
у строк из секции, находящихся не на верхнем уровне в дереве, ParentTreeRowID
<> Guid.Empty;
у строк из секции верхнего уровня (нет родительской секции) ParentRowID =
Guid.Empty;
у строк из подчинённой секции ParentRowID <> Guid.Empty.
4.3.3 Загрузка данных
Как отмечено выше, подсекция — это совокупность строк из подчинённой секции,
относящихся к одной и той же строке родительской секции (объединенных общим
значением ParentRowID), тогда как уровень — это логическое объединение строк из
секций, дочерних по отношению к одной и той же строке в дереве (объединенных
общим значением ParentTreeRowID).
Это важно учитывать, когда речь идет о получении данных секции от сервера.
Для повышения производительности данные читаются не по одной строке, а блоками —
уровнями или подсекциями. Сделано это по вполне очевидным соображениям:
задержки на передачу данных содержат в себе константу — стоимость сетевого вызова.
Таким образом, иногда выгоднее получить больше данных за один раз, чем несколько
раз обращаться к серверу за маленькими порциями. С другой стороны, могут
существовать карточки, которые содержат сотни тысяч строк (например, справочники).
Попытка загрузить все данные такой карточки за один вызов приведёт к чрезмерной
задержке – поэтому в такой ситуации более оптимальным было бы получать данные
несколькими мелкими порциями, по мере их востребованности.
Режим загрузки данных определяется для всей карточки в целом на этапе
создания схемы данных (в приложении CardManager) и распространяется на все её
секции. Однако, в режиме исполнения (runtime) разработчик может переопределить это
поведение (для карточки или для конкретных секций). Для этого служит свойство
FetchMode объектов CardData и SectionData.
Доступны
следующие
режимы
(DocsVision.Platform.ObjectManager.Metadata.FetchMode):
загрузки
данных
FetchMode.Card — загружаются все данные из всех секций карточки (этот режим
актуален только для карточки в целом);
FetchMode.Section — при первом же обращении к коллекции строк секции её
данные будут загружены полностью;
FetchMode.SubSection — загружаеются только данные конкретой подсекции;
FetchMode.Level — загружаются данные подсекции только для конкретного уровня
в дереве.
ПРИМЕЧАНИЕ
Режим построчной загрузки (FetchMode.Row) в данный момент не реализован.
Однако получить данные для отдельных строк все же можно - для этого у объекта
SectionData есть набор методов, работающих с одиночной строкой. Их
использование позволяет не загружать на клиента ненужную информацию, что,
конечно же, предпочтительнее с точки зрения производительности.
DocsVision 4.5: Руководство разработчика на платформе
95
4.3.4 Данные карточки
Точка входа к данным карточки — это объект CardData (для того, чтобы его
получить, необходимо использовать CardManager — сервис ObjectManager для работы с
данными). Рассмотрим его свойства:
DocsVision.Platform.ObjectManager.ArchiveState ArchiveState – признак архивности карточки.
System.DateTime ChangeDate — дата последнего изменения;
System.DateTime CreateDate — дата создания карточки;
string Description — описание экземпляра карточки (дайджест);
DocsVision.Platform.ObjectManager.Metadata.FetchMode FetchMode — режим загрузки
данных карточки;
System.Guid Id — идентификатор экземпляра карточки;
DocsVision.Platform.ObjectManager.Metadata.CardType Type — тип карточки (описание
метаданных);
bool IsTemplate — является ли карточка шаблоном;
DocsVision.Platform.ObjectManager.SectionDataCollection Sections — коллекция секций
карточки;
string Topic — тема карточки (read-write);
System.Guid TopicId — идентификатор темы карточки;
int TopicIndex – индекс (позиция) карточки внутри темы обработки
bool WasRead – признак прочитанности ярлыка;
Также CardData содержит ряд специальных методов:
AddToTopicChain(System.Guid cardId) – добавляет текущую карточку к теме обработки другой
карточки (cardid)
Archive(DocsVision.Platform.ObjectManager.ArchiveOptions archiveOptions) – перемещает
карточку в архив. При этом возможно использование следующих опций:
ArchiveOptions.IncludeLinkedFiles – архивируются также связанные с карточкой файлы
ArchiveOptions.IncludeLinkedCards – архивируются также другие карточки, связанные с
данной по ссылке
ArchiveOptions.Delay – отложенная архивация (по расписанию)
DocsVision.Platform.ObjectManager.CardData Copy() – серверное копирование данных
карточек. В результат получается новый независимый экземпляр карточки с другим
идентификатором.
Dearchive(DocsVision.Platform.ObjectManager.ArchiveOptions archiveOptions) –
восстанавливает карточку из архива
PurgeCache – удаление данных карточки из кэша ObjectManager (приведёт к принудительному
перечитыванию данных с сервера при следующем обращении).
Refresh – принудительное обновление данных карточки с сервера (данные будут переполучены
только при наличии в них изменений с момента предыдущего обновления).
Refresh(bool ignoreTimestamp) – принудительное обновление данных карточки с сервера,
независимо от наличия или отсутствия изменений в ней.
SaveXml(System.IO.Stream stream) – экспорт данных карточки в XML
DocsVision 4.5: Руководство разработчика на платформе
96
SaveXml(System.IO.Stream stream, DocsVision.Platform.ObjectManager.ExportFlags exportFlags)
– расширенный экспорт в XML с возможностью указать дополнительные опции:
ExportFlags.LinkedCards – экспортировать связанные карточки
ExportFlags.LinkedFiles – экспортировать связанные файлы
ExportFlags.LinkedRows – экспортировать связанные строки из карточек
ExportFlags.Namespace – учитывать пространство имен
Пример работы с данными карточки:
// Получение с сервера данных карточки с известным идентификатором
CardData card = session.CardManager.GetCardData(new
System.Guid("идентификатор_карточки"));
// Проверка даты последнего изменения
if (card.ChangeDate.Year < DateTime.Now.Year -1)
{
card.Archive(ArchiveOptions.IncludeLinkedCards);
}
4.3.5 Данные секции
Как нетрудно заметить, карточка является всего лишь контейнером для своих
секций (с некоторыми атрибутами, описывающими конкретный экземпляр). Основную
функциональную нагрузку в работе с данными выполняет объект SectionData.
Для получения
свойствами:
информации о секции можно воспользоваться следующими
DocsVision.Platform.ObjectManager.CardData Card – карточка, которой принадлежит секция
DocsVision.Platform.ObjectManager.Metadata.FetchMode FetchMode - режим
данных секции.
DocsVision.Platform.ObjectManager.RowFieldCollection
(включая связанные поля из других секций);
DocsVision.Platform.ObjectManager.RowData FirstRow - возвращает первую строку
секции (на верхнем уровне, если он есть). Если такой строки нет — она будет
создана. Самое частое использование этого свойства — получение строки из секции
типа структура (например, общее описание карточки).
System.Guid Id — идентификатор типа секции
DocsVision.Platform.ObjectManager.RowDataCollection Rows – коллекция строк секции
DocsVision.Platform.ObjectManager.Metadata.CardSection Type – тип секции (описание
метаданных)
Fields
-
поля
строки
загрузки
секции
Для работы с отдельными строками используются следующие методы объекта
SectionData:
DocsVision.Platform.ObjectManager.RowData CreateRow() – создает новую строку в секции
DocsVision.Platform.ObjectManager.RowData CreateRow(System.Guid rowId) – создает в
секции новую строку с предопределенным идентификатором
DocsVision.Platform.ObjectManager.RowData CreateRow(System.Guid parentTreeRowId,
System.Guid parentRowId, System.Guid rowId) – создает в секции новую строку с
предопределенным идентификатором, а также с конкретными значениями родительской строки
секции и родительской строки дерева.
DeleteRow(System.Guid rowId) – удаляет из секции строку с идентификатором rowid
DocsVision 4.5: Руководство разработчика на платформе
97
DocsVision.Platform.ObjectManager.RowData FindRow(string filter) – серверный поиск строки в
секции. Подробнее о поиске написание в соответствующей главе.
DocsVision.Platform.ObjectManager.RowDataCollection FindRows(string queryXml) –
клиентская фильтрация строк в секции с использованием XPath-запроса. Подробнее о поиске
написание в соответствующей главе.
DocsVision.Platform.ObjectManager.RowDataCollection GetAllRows() – получение всех строк
секции
DocsVision.Platform.ObjectManager.RowDataCollection GetAllRows(System.Guid parentRowId)
– получение всех строк в секции для конкретной строки родительской секции
DocsVision.Platform.ObjectManager.RowDataCollection GetAllRows(System.Guid parentRowId,
bool traverseHierarchy) - получение всех строк в секции для конкретной строки родительской
секции, без учета уровня иерархии (игноририрование ParentTreeRowID)
DocsVision.Platform.ObjectManager.RowData GetRow(System.Guid rowId) – получение данных
строки с идентификатором RowID
bool RowExists(System.Guid rowId) – проверка существования в секции строки с заданным
идентификатором
DocsVision.Platform.ObjectManager.SectionDataReader
OpenSectionReader(DocsVision.Platform.ObjectManager.Metadata.FetchMode fetchMode,
System.Guid parentRowId, System.Guid parentTreeRowId) – открывает серверный курсор для
чтения данных секции (клиент далее сможет читать данные построчно)
ПРИМЕЧАНИЕ
Данный метод рекомендуется использовать при чтении данных секции с очень
большим количеством строк. Основное отличие данного метода заключается в
построчном чтении данных, без сохранения их в кэше.
Дополнительные методы:
Refresh() — обновление данных секции;
PurgeCache() – удаление данных секции из кэша ObjectManager (приведёт к
принудительному перечитыванию данных с сервера при следующем обращении).
Пример работы с данными секции:
// Получение с сервера данных карточки с известным идентификатором
CardData card = oSession.CardManager.GetCardData(new
System.Guid("идентификатор_карточки"));
// Получение данных секции с именем ”MainInfo”
SectionData section = card.Sections[card.Type.Sections["MainInfo"].Id];
// Перебор всех строк секции
foreach(RowData row in section.Rows)
{
//...
}
4.3.6 Данные подсекции
Свойства подчинённой секции (SubSectionData) практически полностью совпадают
со свойствами секций верхнего уровня (SectionData), с незначительными ограничениями
и дополнительными свойствами:
DocsVision.Platform.ObjectManager.SectionData Section —секция верхнего уровня, которой
принадлежит подсекция;
DocsVision 4.5: Руководство разработчика на платформе
98
DocsVision.Platform.ObjectManager.RowData ParentRow — родительская строка из
родительской секции.
4.3.7 Строка данных
Для работы с данными
предусмотрен объект RowData.
конкретной
строки
секции
в
объектной
модели
Положение строки в общей структуре данных карточки определяется следующими
свойствами:
DocsVision.Platform.ObjectManager.CardData Card – карточка, которой принадлежит строка
DocsVision.Platform.ObjectManager.SectionData Section — секция, которой принадлежит
строка;
DocsVision.Platform.ObjectManager.SubSectionData SubSection — подсекция, которой
принадлежит строка;
DocsVision.Platform.ObjectManager.RowData ParentRow — родительская строка в иерархии
строк секции (имеет смысл только для строк из иерархических секций).
System.Guid[] GetHierarchy — получение иерархии строки (идентификаторы всех родительских
строк вплоть до самого верхнего уровня).
Для изменения положения строки служит метод Move:
Move(System.Guid parentTreeRowId, System.Guid parentRowId) — перемещает строку в иерархии
строк секции. При этом:
ParentTreeRowID — идентификатор новой родительской строки в дереве
ParentRowID —идентификатор новой родительской строки в родительской секции
Для создания копии строки служит метод Copy, который принимает на вход
координаты создаваемой строки-клона:
DocsVision.Platform.ObjectManager.RowData Copy(System.Guid parentTreeRowId, System.Guid
parentRowId) — создает копию строки и размешает её в указанном месте иерархии
строк секции.
Для работы с дочерними строками служат методы:
bool HasChildRows — признак наличия дочерних строк
DocsVision.Platform.ObjectManager.RowDataCollection ChildRows — дочерние строки в
дереве (один уровень иерархии)
DocsVision.Platform.ObjectManager.RowDataCollection AllChildRows — все дочерние строки
вниз по дереву (со всех уровней иерархии)
DocsVision.Platform.ObjectManager.SubSectionDataCollection ChildSections — подчинённые
подсекции.
Для обновления данных строки можно использовать все тот же метод Refresh с
небольшими дополнениями:
Refresh(bool linkedFieldsOnly) — обновление данных подсекции. Если LinkedFieldsOnly передан и
равен TRUE — обновляются только данные связанных полей. Вызывать этот метод с таким
параметром нужно в случае изменения значения ссылочного поля.
Другие свойства строки:
string DisplayString - отображаемое значение данных строки (формируется на основе
полей, помеченных для этой цели в метаданных секции)
System.Guid Id – уникальный идентификатор строки;
DocsVision 4.5: Руководство разработчика на платформе
99
DocsVision.Platform.ObjectManager.ObjectStatus Status – битовая маска, которая
характеризует текущее состояние объекта в режиме отложенных изменений. В
маске могут участвовать следующие флаги:
ObjectStatus.Normal = 0 – исходное состояние (объект не менялся);
ObjectStatus.New = 1 – новый (только что созданный) объект;
ObjectStatus.Deleted = 2 – объект удален;
ObjectStatus.Changed = 4 – данные объекта изменены;
ObjectStatus.Moved = 8 – изменено положение в иерархии;
Среди методов объекта RowData основную часть занимают методы для работы со
значениями полей строки. Их можно разбить на две большие группы:
1) Методы для чтения значения поля
Универсальный метод для получения непизированного значения:
object this[string alias] { set; get; } – получает значение поля с псевдонимом alias
Набор методов для получения типизированного значения:
GetBoolean(string alias)
GetByte(string alias)
GetChar(string alias)
… и т.д.
2) Методы для записи значения поля
Универсальный метод для записи значения поля:
SetValue(string alias, object value,
DocsVision.Platform.ObjectManager.Metadata.FieldType type) – записывает значение
value в поле с псевдонимом alias и типом type
Набор методов для записи типизированных значений:
SetBoolean(string alias, bool? value)
SetByte(string alias, byte? value)
SetChar(string alias, char? value)
… и т.д.
ПРИМЕЧАНИЕ
Использовать
методы
для
работы
с
нетипизированными
значениями
рекомендуется только в том случае, когда тип поля заранее неизвестен
(например, универсальный метод, перебирающий все поля строки). Во всех
прочих случаях рекомендуется использовать тиизированные методы, т.к. они
могут подстраховать разработчика от возможных ошибок записи в поле
некорректного значения.
Тип поля можно предварительно проверить методом GetValueType:
DocsVision.Platform.ObjectManager.Metadata.FieldType GetValueType(string
метод принимает на вход псевдоним поля, и возвращает его тип.
alias)
–
Пример кода для работы с данными строки:
// Получение с сервера данных карточки с известным идентификатором
CardData card = session.CardManager.GetCardData(new
System.Guid("идентификатор_карточки"));
DocsVision 4.5: Руководство разработчика на платформе
100
// Получение данных секции с именем ”MainInfo”
SectionData section = card.Sections[card.Type.Sections["MainInfo"].Id];
// Получение первой строки секции (если строки нет – она будет создана)
RowData row = section.FirstRow;
// Запись значения в поле “Number”
if (row.GetValueType("Number") == FieldType.Int)
{
row.SetInt32("Number", 10);
}
4.3.8 Коллекция строк
Объект RowDataCollection имеет набор стандартных для коллекций методов:
DocsVision.Platform.ObjectManager.RowData this[System.Guid rowId] — получение строки по
идентификатору или по индексу;
int Count — получение количества строк в коллекции;
bool Contains(System.Guid rowId) — проверка присутствия в коллекции строки с указанным
идентификатором;
DocsVision.Platform.ObjectManager.RowData AddNew() — создание новой строки;
DocsVision.Platform.ObjectManager.RowData AddNew(System.Guid rowId) – создание строки с
предопределенным идентфиикатором. Для выполнения этого метода требуются
административные привилегии!
Remove(System.Guid rowId) — удаление строки;
Clear() — удаление всех строк в коллекции.
Кроме того, есть ряд специфичных методов:
DocsVision.Platform.ObjectManager.RowData Find(string fieldAlias, object fieldValue) — поиск
строки в коллекции по значению указанного поля;
DocsVision.Platform.ObjectManager.RowDataCollection Filter(string filterXPath)— фильтрация
элементов коллекции (используется клиентская фильтрация);
DocsVision.Platform.ObjectManager.RowDataCollection Sort(string fieldAlias, bool ascending) —
сортировка элементов коллекции (клиентская сортировка);
Refresh(bool linkedFieldsOnly, bool ignoreTimestamp) — обновление данных строк коллекции.
ПРИМЕЧАНИЕ
Если коллекция строк получена как результат поиска, она будет доступна только
для чтения! При поптыке вызвать методы AddNew, Remove, Clear для такой
коллеции будет возвращена ошибка.
4.3.9 Поле строки
Для описания полей строки секции используется объект RowField (вся коллекция
полей секции доступна через свойство SectionData.Fields).
В отличие от описаний полей в схеме карточки, доступных через объекты
метаданных (CardType.Sections.Fields) – коллекция RowFieldCollection содержит описания
реальных полей секции, включая связанные поля других карточек и системные поля
(например, поле дайджеста – Description).
DocsVision 4.5: Руководство разработчика на платформе
101
Свойства объекта RowField перечислены ниже:
DocsVision.Platform.ObjectManager.Metadata.FieldType DataType — тип данных поля;
string Alias — название поля, под которым оно доступно в строке секции (может не
совпадать с родным названием, если это связанное поле получаемое по ссылке из
другой секции);
bool IsReadOnly - признак того, доступно ли поле для записи;
DocsVision.Platform.ObjectManager.Metadata.Field Type – ссылка на описание поля в
метаданных.
4.3.10 Кэширование данных
Говоря про загрузку данных, нельзя не упомянуть про кэширование. В
ObjectManager имеется кэш на чтение и, таким образом, повторное чтение строк вернёт
уже загруженные данные. При этом надо понимать, что строки в кэше могли быть
изменены на сервере, а это может привести к тому, что на клиенте окажутся
неактуальные данные. Для этого в ObjectManager предусмотрен механизм обновления
строк:
Явный — у всех объектов есть метод Refresh (возможно, с параметрами), с
помощью которого можно обновить данные вручную;
Неявный — при получении карточки (CardData) производится проверка наличия
данных карточки в кэше. Если данные есть, но они потеряли актуальность (на
сервере
произошло
изменение
строки,
принадлежащей
карточке) —
вызывается процедура обновления.
Неявный характер обновления данных во втором случае нужно всегда иметь в
виду и избегать частого переполучения данных карточки, так как в этом случае всегда
производится серверный вызов — обновляется информация о статусе карточки
(естественно, если такая карточка уже получалась ранее).
Существует также возможность очистить весь кэш одним вызовом – для этого
предназначен метод CardManager.PurgeCache.
4.4
ИСПОЛЬЗОВАНИЕ ССЫЛОК
Ссылка - это специальный тип поля, которое ссылается на другую карточку (тип
RefCardID) или на строку другой секции (RefID).
Ссылка на карточку может быть одного из четырех типов: простая, слабая,
сильная и автоматическая. Тип ссылки задаётся в описании карточки и, следовательно,
устанавливается один раз для всех экземпляров карточки такого типа. Управлять
поведением ссылки во время исполнения нельзя.
Тип ссылки влияет на поведение сервера в следующих случаях:
при изменении значения ссылочного поля;
при удалении карточки, на которую существуют ссылки.
Рассмотрим поведение различных типов ссылок подробнее.
4.4.1 Простая ссылка
Простая ссылка позволяет просто сохранить в поле идентификатор связанной
карточки и определить ссылочные поля. Сервер не выполняет никаких дополнительных
действий при записи или удалении значения в этом поле, а также при удалении
связанной карточки. В этом смысле, простая ссылка аналогична полю типа «uniqueid».
Контроль ссылочной целостности в этом случае полностью остается за разработчиком.
DocsVision 4.5: Руководство разработчика на платформе
102
4.4.2 Слабая ссылка
Слабая ссылка имеет отличие от простой – при удалении связанной карточки
соответствующее поле ссылки будет автоматически обнулено (установлено в значение
NULL). Это позволит разработчику не заботиться о проблеме «зависших» ссылок на
несуществующие карточки.
Дополнительно появляется возможность узнать, какие карточки ссылаются на
данную и на какие карточки ссылается она сама. Для этого предназначены следующие
методы CardManager:
DocsVision.Platform.ObjectManager.CardDataCollection GetLinksToCard(System.Guid cardId,
DocsVision.Platform.ObjectManager.LinkType linkType, int recurseDepth) — возвращает
список карточек, которые ссылаются на данную. Параметры метода:
cardId - идентификатор карточки;
linkType - маска типов ссылки:
LinkType.None – не указан
LinkType.Weak - слабая
LinkType.Hard - сильная
LinkType.Auto - авто
LinkType.All - все типы
recurseDepth — глубина рекурсии, т.е. на сколько шагов ссылающиеся карточки
могут отстоять от данной
DocsVision.Platform.ObjectManager.CardDataCollection GetLinksFromCard(System.Guid cardId,
DocsVision.Platform.ObjectManager.LinkType linkType, int recurseDepth) — возвращает
список карточек, на которые ссылаются данная. Параметры метода аналогичны
предыдущему
4.4.3 Сильная ссылка
Сильная ссылка выражает отношения владения — если карточка держит сильную
ссылку на другую карточку, то можно сказать, что она ею владеет или является
родительской по отношению к ней.
Характеристики сильных ссылок:
сильных ссылок на карточку может быть несколько — то есть несколько карточек
могут «владеть» одной карточкой;
при создании сильной ссылки на карточку на неё распространяются (наследуются)
права из карточки - владельца;
если на карточку владельца назначаются права, то при распространении прав вниз
по иерархии они распространяются и на подчинённую карточку. Таким образом,
подчинённая карточка имеет набор прав (и, соответственно, видимость) в
зависимости от того, на какую из карточек владельцев были последними назначены
права. Такой принцип используется потому, что в Windows нет множественного
наследования, и система сама поступает так при реализации аналога сильных
ссылок на файлы;
если на подчинённую карточку есть сильные ссылки, то её напрямую удалить
нельзя. При удалении карточки-владельца сервер отмечает удаление сильной
ссылки. Если это последняя сильная ссылка на карточку, то она сама тоже
удаляется. Таким образом, подчинённая карточка гарантированно живет столько,
сколько самый последний из её владельцев.
Если возникает необходимость очистить значение сильной ссылки, но при этом
сохранить карточку, то надо воспользоваться методом ClearLink:
DocsVision 4.5: Руководство разработчика на платформе
103
ClearLink(System.Guid sectionId, System.Guid rowId, string fieldAlias), где:
sectionId - идентификатор типа секции со ссылкой;
rowId - идентификатор строки со ссылкой;
fieldAlias — назавание (пседвоним) поля со ссылкой.
Итак, сильные ссылки нужны для реализации владения, контроля области
видимости и срока жизни карточек. Применение их для других целей приветствуется,
но потребует осторожности и внимания к возможным сторонним эффектам.
4.4.4 Автоматическая ссылка
Автоматическая ссылка по своему поведению подобна слабой, но обладает
следующим дополнительным свойством – при удалении связанной карточки из
исходной карточки будет удалена вся строка, содержащая ссылку.
Например, в стандартных карточках документов «Делопроизводства» есть секция
Файлы и ссылки, содержащая ссылки на другие карточки. Все ссылки там имеют тип
Авто. Таким образом, при удалении карточки из системы все существующие ссылки на
неё из карточек документов автоматически удаляются.
4.4.5 Ссылки на строки
Ссылка на строку (RefID), в отличие от ссылки на карточки, не имеет типа и
поэтому не обладает возможностями контроля целостности. Единственным способом
управлять поведением связанного объекта для такого рода полей является признак
«Удалять связанную строку при изменении значения». Если этот признак установлен,
то любое изменение значения заполненного ссылочного поля (установка нового
значения или сброс в Null) приведёт к тому, что связанная строка (другой карточки)
будет удалена.
ПРИМЕЧАНИЕ
Это поведение имеет смысл, если связанная
коллекционной или иерархической секции.
строка
расположена
в
Типичным сценарием применения этого поведения является, например, работа с
номерами в карточках «Делопроизводства». Если карточка занимает какой-то номер
(ей соответствует строка в секции занятых номеров карточки нумератора), то при
удалении карточки занятый ею номер автоматически освобождается (строка в карточке
нумератора удаляется).
4.5
РАБОТА С ПАПКАМИ И ЯРЛЫКАМИ
Папки в системе реализуются при помощи специальной системной карточки —
карточки папок. Карточка папок хранит иерархическое дерево папок, каждая из
которых имеет ряд собственных свойств (название, иконка и т.д.), а также ряд
дочерних элементов – подпапок и ярлыков.
4.5.1 Карточка папок
Разработчик
может
взаимодействовать
с
данными
карточки
папок
непосредственно через объект CardData – по тем же принципам, как с любой другой
карточкой системы. Однако для упрощения этой задачи в объектной модели
предусмотрен ряд специализированных объектов, лучше отражающих семантику
(Folder, Shortcut). Ключевым объектом этой модели является сама карточка папок –
объект FolderCard. Все объекты расположены в специальном пространстве имен для
работы с системными карточками - DocsVision.Platform.ObjectManager.SystemCards.
Как и все системные карточки, этот объект может быть получен через
стандартный интерфейс методами CardManager.GetCard или CardManager.GetDictionary.
DocsVision 4.5: Руководство разработчика на платформе
104
ПРИМЕЧАНИЕ
Так как карточка папок является справочником, то её идентификатор всегда
известен и неизменен – у справочников он всегда соответствует идентификатору
типа карточки.
// Получение карточки папок
const string FOLDER_CARD_TYPE = "{DA86FABF-4DD7-4A86-B6FF-C58C24D12DE2}";
FolderCard folderCard = (FolderCard)session.CardManager.GetDictionary(new
Guid(FOLDER_CARD_TYPE));
Свойства карточки папок:
DocsVision.Platform.ObjectManager.SystemCards.FolderCollection Folders – коллекция папок
верхнего уровня
DocsVision.Platform.ObjectManager.SystemCards.FolderIconCollection Icons –коллекция
иконок папок
System.Guid SearchCardId – идентификатор карточки сохраненных поисковых запросов
System.Guid ViewCardId - идентификатор текущей карточки сохраненных представлений
ПРИМЕЧАНИЕ
В ранних версиях системы (до 4.0) карточки сохраненных представлений и
поисковых запросов НЕ являлись справочниками - поэтому теоретически
возможно было существование нескольких экземпляров этих карточек. Тогда как
Навигатор одновременно может работать только с одним набором представлений
и поисковых запросов. Для получения идентфикаторов рабочих экземпляров
этих карточек и использовались эти два свойства. Сейчас в них уже нет прямой
необходимости, и они сохранены для совместимости ранних приложений.
Методы для работы с папками:
DocsVision.Platform.ObjectManager.SystemCards.Folder
CreateFolder(System.Guid
parentFolderId, string name) – создание папки с указанным именем в родительской папке
(parentFolderId)
DocsVision.Platform.ObjectManager.SystemCards.Folder GetFolder(System.Guid
получение объекта для работы с папкой по её идентификатору
DocsVision.Platform.ObjectManager.ObjectState
GetFolderState(System.Guid
проверка состояния папки с указанным идентификатором:
folderId)
folderId)
–
–
ObjectState.NotExisting — папки с указанным идентификатором не существует;
ObjectState.Existing — папка существует и может быть получена;
ObjectState.Deleted — папка существует, но помечена как удаленная, работа с ней
невозможна;
DeleteFolder(System.Guid folderId, bool permanently) – удаление папки по идентификатору;
RestoreFolder(System.Guid folderId) – восстановление папки, помеченной на удаление;
bool FolderExists(System.Guid folderId) – проверка существования папки с указанным
идентификатором (вернет True, если папка существует (даже если она помечена на удаление!), и
False, если не существует)
Методы для работы с ярлыками:
DocsVision.Platform.ObjectManager.SystemCards.Shortcut
CreateShortcut(System.Guid
folderId, System.Guid cardId, bool hardLink) – создание ярлыка на карточку cardId в папке folderId
DocsVision.Platform.ObjectManager.SystemCards.Shortcut GetShortcut(System.Guid shortcutId)
– получение объекта для работы с ярлыком по его идентификатору
DocsVision 4.5: Руководство разработчика на платформе
105
DocsVision.Platform.ObjectManager.SystemCards.ShortcutCollection GetShortcuts(System.Guid
cardId) – получение ВСЕХ ярлыков карточки с указанным идентификатором (и сильных и слабых)
DocsVision.Platform.ObjectManager.SystemCards.Shortcut FindHardLink(System.Guid cardId) –
получение сильного ярлыка на карточку (он всегда существует в единственном экземпляре);
DocsVision.Platform.ObjectManager.ObjectState GetShortcutState(System.Guid shortcutId) проверка состояния ярлыка с указанным идентификатором
ShortcutExists(System.Guid shortcutId) - проверка существования
идентификатором;
DeleteCard(System.Guid cardId, bool permanently)– удаление карточки по идентификатору (но в
отличие от соответствующего метода CardManager, этот метод одновременно удаляет и все
ярлыки на карточку)
DeleteShortcut(System.Guid shortcutId, bool permanently) – удаление ярлыка по идентификатору;
RestoreShortcut(System.Guid shortcutId) – восстановление ярлыка, помеченного на удаление;
ярлыка с указанным
Методы для работы с иконками папок:
DocsVision.Platform.ObjectManager.SystemCards.FolderIcon
icon, string description) – создание новой иконки
DeleteIcon(System.Guid iconId) – удаление иконки папки
DocsVision.Platform.ObjectManager.SystemCards.FolderIcon
получение иконки по идентификатору
CreateIcon(System.Drawing.Icon
GetIcon(System.Guid
iconId)
–
Пример кода работы с карточкой папок:
// Проверка существования папки
string folderID = "{идентификатор_папки}";
Folder folder;
switch (folderCard.GetFolderState(new Guid(folderID)))
{
case ObjectState.Existing:
// папка существует:
folder = folderCard.GetFolder(new Guid(folderID));
break;
case ObjectState.Deleted:
// Папка существует, но удалена - восстанавливаем её
folderCard.RestoreFolder(new Guid(folderID));
folder = folderCard.GetFolder(new Guid(folderID));
break;
case ObjectState.NotExisting:
// Папка не существует - её нужно создать
folder = folderCard.CreateFolder(folderCard.Folders["Папки"].Id,
"Новая папка");
break;
}
4.5.2 Папка
Папка содержит некоторое количество собственных свойств (название, иконка и
т.д.), а также ряд дочерних элементов, к числу которых относятся:
подпапки (дочерние папки);
ярлыки, лежащие в папки;
ограничения на типы карточек, которые могут быть созданы в папке;
ограничения на представления, которые могут быть применены
DocsVision 4.5: Руководство разработчика на платформе
106
У папки есть три режима работы — обычный (отображается содержимое в виде
списка карточек), URL (отображается страница) и карточка (в правой панели
отображается интерфейс карточки). Из объектной модели доступен переключатель
режима работы папки (Folder.CurrentStyle) и идентификатор карточки папки
(Folder.PropCardID). Также можно выполнить соответствующую настройку из
Навигатора.
При создании карточки папки надо учитывать, что она отображается
немодально, когда пользователь открывает папку; и скрывается, как только
пользователь переходит на другую папку. У карточки нет возможности отменить
закрытие (ей не приходит вызов CloseQuery), поэтому в её интерфейсе не должно
быть средств редактирования чего-либо, что может остаться несохраненным к моменту
перехода на другую папку. Лучше всего использовать интерфейс карточки для
отображения чего-либо, а всё редактирование вынести на отдельные формы, по
закрытии которых будет производиться сохранение данных.
Свойства папки:
DocsVision.Platform.ObjectManager.SystemCards.FolderCardTypeCollection AllowedCardTypes
– типы карточек, которые можно создавать в этой папке
ВНИМАНИЕ
Все подобные ограничения в папке предназначены исключительно для
повышения удобства использования системы, а не для ограничения
безопасности!!! Поэтому в данном случае они несут чисто информативную
функцию, и не накладывают к каким-либо физическим ограничений на работу
объектной модели. Таким образом, например, программно вполне можно создать
в папке ярлык на карточку того типа, который не входит в число разрешенных в
данной папке.
DocsVision.Platform.ObjectManager.SystemCards.FolderSubtypeCollection
AllowedFolderTypes – типы подпапок, которые можно создавать в этой папке
DocsVision.Platform.ObjectManager.SystemCards.FolderStyles
разрешенные к использованию в данной папке:
AllowedStyles
–
стили,
FolderStyles.All – все стили;
FolderStyles.None – стиль не определён;
FolderStyles.View – представление;
FolderStyles.Card – список карточек;
FolderStyles.Url – URL;
FolderStyles.Digest – дайджест;
DocsVision.Platform.ObjectManager.SystemCards.FolderTemplateCollection AllowedTemplates
– разрешенные к использованию в данной папке шаблоны экспорта
DocsVision.Platform.ObjectManager.SystemCards.FolderViewCollection
представления, которые можно использовать в этой папке
DocsVision.Platform.ObjectManager.SystemCards.FolderStyles CurrentStyle – текущий стиль
отображения содержимого папки
System.Guid CurrentViewId – идентификатор текущего представления папки (в рамках текущей
сессии)
DocsVision.Platform.ObjectManager.SystemCards.FolderStyles
DefaultStyle
отображения содержимого папки по умолчанию (в новой сессии)
System.Guid DefaultTemplateId – шаблон экспорта по умолчанию (в новой сессии)
System.Guid DefaultViewId – представление папки по умолчанию (в новой сессии)
DocsVision 4.5: Руководство разработчика на платформе
AllowedViews
-
–
стиль
107
bool Deleted
- признак удаления папки (свойство доступно только для чтения; для
восстановления удалённой папки нужно воспользоваться методом RestoreFolder карточки
папок)
System.Guid ExtTypeId – идентификатор типа папки (в справочнике типов папок)
DocsVision.Platform.ObjectManager.SystemCards.FolderFlags Flags– дополнительные атрибуты
папки:
FolderFlags.None – отсутствуют;
FolderFlags.VirtualWithSubfolders – показывать дочерние подпапки виртуальной папки;
FolderFlags.NoAutoRefresh – отключить авто-обновление содержимого папки;
FolderFlags.NoUnreadCards – отключить подсветку количества непрочитанных карточек в
папке;
DocsVision.Platform.ObjectManager.SystemCards.FolderCollection
дочерних папок для текущей
Folders
bool HasSubfolders – признак наличия дочерних папок
System.Guid IconId – идентификатор иконки папку (а саму иконку можно получить
последующим вызовом FolderCard.GetIcon(iconid))
System.Guid Id – идентификатор папки
string Name – имя папки
DocsVision.Platform.ObjectManager.SystemCards.Folder
родительскую папку
System.Guid PropCardId – идентификатор карточки папка (это карточка, ассоциированная с
данной папкой, которая может отображаться в правой части Навигатора при переходе в папку)
System.Guid RefId - для папки-делегата – идентификатор оригинальной папки
int RefreshTimeout – индивидуальный период обновления содержимого папки
DocsVision.Platform.ObjectManager.SystemCards.FolderRestrictions
наличия ограничений папки:
ParentFolder
–
–
Restrictions
коллекция
ссылка
–
на
признак
FolderRestrictions.None – ограничения отсутствуют;
FolderRestrictions.Views – есть ограничения на использование представлений;
FolderRestrictions.Types – есть ограничение на создание типов карточек;
FolderRestrictions.Templates – есть ограничение на использование шаблонов
экспорта;
DocsVision.Platform.ObjectManager.SystemCards.SavedParameterCollection SavedParameters
– коллекция сохраненных значений параметров поискового запроса (для виртуальной папки,
если с ней ассоциирован параметризованный запрос)
DocsVision.Platform.ObjectManager.SystemCards.ShortcutCollection Shortcuts – коллекция
ярлыков папки
ПРИМЕЧАНИЕ
Эта коллекция существует даже для виртуальных папок и делегатов, и доступна
для программного создания в ней новых объектов – хотя при помощи Навигатора
такая возможность ограничивается. Эта возможность может быть использована
при разработке приложений, имеющих собственную логику работы с такими
типами папок.
DocsVision 4.5: Руководство разработчика на платформе
108
DocsVision.Platform.ObjectManager.SystemCards.FolderTypes Type – тип папки (битовая
маска):
FolderTypes.All – все типы одновременно;
FolderTypes.None – тип не определен;
FolderTypes.Regular – обычная папка;
FolderTypes.Root – корневая папка;
FolderTypes.Virtual – виртуальная папка;
FolderTypes.Delegate – папка-делегат;
FolderTypes.SystemHidden – системная папка;
System.Uri Url – URL папки
int ViewCycleCount – ограничение на размер порции данных, отображемой в представлении
одновременно;
bool ViewCyclingEnabled
представления;
-
признак
наличия
ограничения
на
отображение
данных
Методы папки:
DocsVision.Platform.ObjectManager.SystemCards.Folder Copy(System.Guid parentFolderId) –
копирование папки к другому родителю (parentFolderId)
FillBySearch(string queryXml) – заполнение папки результатами поискового запроса (имитация
поведения виртуальных папок). В качестве параметра Search может быть передан
сформированный XML поискового запроса.
FillBySearch (System.Guid queryId) – заполнение папки результатами поискового запроса
(имитация поведения виртуальных папок). В качестве параметра Search может быть передан
идентификатор сохраненного поискового запроса.
System.Guid[] GetHierarchy() – получение иерахии (пути к папке, начиная от корневого уровня)
int GetUnreadCount() – получение количества непрочитанных карточек в папке;
int GetUnreadCount(bool includeArchived) – получение количества непрочитанных карточек в
папке с учетом архивных
Move(System.Guid parentFolderId) – перемещение папки к другому родителю (parentFolderId);
Purge(bool recursive, System.DateTime startDate) – окончательное удаление ярлыков,
принадлежащих этой папке, помеченных на удаление. Параметр recursive указывает на
необходимость учета дочерних папок; а startDate определяет минимальную дату удаления
объектов (будут очищены все объекты, удаленные ПОСЛЕ этой даты)
Пример кода работы с папкой:
// Получение папки по идентификатору
string folderID = "{идентификатор_папки}";
Folder folder = folderCard.GetFolder(new Guid(folderID));
// Проверка существования подпапки "Завершенные"
try
{
// Пытаемся получить подпапку по имени
Folder childFolder = folder.Folders["Завершенные"];
// ...
}
catch (Exception ex)
{
// Если возникло исключение - значит папки не существует, нужно создать
DocsVision 4.5: Руководство разработчика на платформе
109
folder.Folders.AddNew("Завершенные");
}
4.5.3 Ярлык
Физически ярлык – это просто строка карточки папок, которая хранит в себе
ссылку на карточку.
Как и ссылка, ярлыки бывают двух видов — слабые и сильные. Слабый ярлык
держит слабую ссылку на карточку и отображается с overlay-иконкой, аналогичной
ссылке в Windows. При удалении такого ярлыка удаляется только сам ярлык.
Сильный ярлык держит сильную ссылку на карточку, и отображается обычной
иконкой карточки. Для пользователя сильный ярлык полностью соответствует
нахождению карточки в этой папке, поэтому правомерно говорить о том, что «карточка
лежит в папке». При удалении ярлыка удаляется сама карточка, если на неё нет других
сильных ссылок. Если программно нужно удалить карточку, на которую могут быть
ярлыки, то надо воспользоваться методом FolderCard.DeleteCard, который удаляет
карточку с учетом существующих ярлыков.
ВНИМАНИЕ
Для каждой карточки можно создать только один сильный ярлык. В случае
повторного вызова метода создания сильного ярлыка для той же карточки —
метод вернет ошибку.
По аналогии с письмами Outlook ярлык на карточку обладает признаком
прочитанности. Непрочитанные ярлыки отображаются в Навигаторе жирным шрифтом.
Когда пользователь открывает карточку, он устанавливает этот признак в «прочитано».
Этот признак можно выставить программно, если необходимо сигнализировать
пользователю о том, что ему необходимо обратить внимание на новый ярлык.
Кроме этого, ярлык может содержать также дополнительные атрибуты –
например, режим открытия карточки (Mode). Таким образом, можно создать на одну
карточку несколько ярлыков с разными режимами открытия карточки.
В объектной модели для работы с ярлыками предназначен объект Shortcut.
Свойства объекта:
System.Guid CardId - идентификатор карточки, на которую ссылается ярлык
System.DateTime CreationDate - дата и время создания ярлыка
bool Deleted - признак удаления ярлыка (свойство доступно только для чтения; для
восстановления удалённого ярлыка нужно воспользоваться методом RestoreShortcut карточки
папок)
string Description – описание ярлыка
System.Guid FolderId– идентификатор родительской папки, в которой расположен ярлык
System.Guid Id – уникальный идентификатор ярлыка
bool IsHardLink - признак, является ли ярлык «сильным» (доступно только для чтения, для
смены типа ярлыка нужно воспользоваться методом TurnToHardLink)
System.Guid ModeId – идентификатор режима открытия карточки
bool Recalled - признак отозванности ярлыка (в настоящее время не используется)
Методы для работы с ярлыком:
DocsVision.Platform.ObjectManager.SystemCards.Shortcut Copy(System.Guid parentFolderId) –
копирование ярлыка в указанную папку (parentFolderId)
Move(System.Guid parentFolderId) – перемещение ярлыка в другую папку (parentFolderId)
DocsVision 4.5: Руководство разработчика на платформе
110
bool ShortcutEquals(DocsVision.Platform.ObjectManager.SystemCards.Shortcut
сравнение двух ярлыков
shortcut)
–
TurnToHardLink() – позволяет изменить тип ярлыка с слабого на сильный (обратного
метода не существует);
Пример работы с ярлыком:
// Получение всех ярлыков на карточку
string cardID = "{идентификатор_карточки}";
ShortcutCollection coll = folderCard.GetShortcuts(new Guid(cardID));
// Перебор ярлыков карточки, и удаление всех, кроме сильного
foreach (DocsVision.Platform.ObjectManager.SystemCards.Shortcut shortcut in
coll)
{
if (!shortcut.IsHardLink)
folderCard.DeleteShortcut(shortcut.Id, true);
}
DocsVision 4.5: Руководство разработчика на платформе
111
4.6
РЕЖИМ ОТЛОЖЕННЫХ ИЗМЕНЕНИЙ
В обычном режиме работы все изменения сразу же отправляются на сервер. Таким
образом, установка значения даже одного поля приведёт к серверному вызову (со
всеми связанными с ним накладными расходами).
Очевидно, что в случае массированного изменения данных необходима
буферизация изменений – когда все изменения накапливаются на клиенте, после чего
одним вызовом отправляются на сервер. Для этого в ObjectManager используется так
называемый режим отложенных изменений.
ПРИМЕЧАНИЕ
Следует сразу уяснить, что режим отложенных изменений вовсе не то же самое,
что поддержка транзакций! Несмотря на некоторую схожесть способов
применения, режим отложенных изменений все же не является полноценной
транзакцией, и не следует пользоваться им в таком контексте! В частности,
режим отложенных изменений обладает следующими особенностями:
в режиме отложенных изменений на клиенте не проверяется права на
изменяемые объекты, или ограничения уровня данных (constaints) – все
они начнут действовать только в момент «проигрывания» всех
накопленных изменений на сервере
изменения, внесенные в одни и те же данные на клиенте, не заменяют
друг друга, а накапливаются (например, если в режиме отложенных
изменений 10 раз изменить значение одного поля карточки – то все
десять операций запишутся в пакет изменений; этот пакет будет
отправлен на сервер; и там все 10 операций будут применены к данным
карточки)!
Поддержку режима отложенных изменений имеют следующие объекты данных:
CardData;
SectionData;
SubSectionData;
RowData;
RowDataCollection;
File
Folder
Shortcut
Для работы с отложенными изменениями каждый из этих объектов имеет
следующий набор методов:
BeginUpdate — включает режим отложенных изменений. Начиная с этого момента,
все изменения будут накапливаться на клиенте, и затем могут быть посланы на
сервер одним пакетом;
UpdateNow — отправляет накопленные изменения на сервер, на клиенте они
очищаются из КЭШа; но режим продолжает действовать, и все изменения
после этого момента также будут накапливаться
EndUpdate - сохраняет накопленные изменения, и выключает режим отложенных
изменений.
CancelUpdate — отменяет внесенные изменения (восстанавливая предыдущие
значения) и выключает режим отложенных изменений;
DocsVision 4.5: Руководство разработчика на платформе
112
bool InUpdate — признак того, включён ли режим отложенных изменений для
данного объекта
MarkCardForDeletion(System.Guid cardId) – позволяет установить для карточки с
идентификатором cardid признак, что она была создана в режиме отложенных изменений.
Тогда при отмене пакета изменений, эта карточка будет автоматически удалена. Этот
метод позволяет избавить разработчика от необходимости самому следить за жизненным
циклом объектов, которые он создает в режиме отложенных изменений.
При работе с режимом отложенных изменений нужно иметь в виду, что в пределах
секции он действует каскадно – если вызывать BeginUpdate на родителе, то в режиме
отложенных изменений окажутся все подчинённые объекты из той же секции.
ВНИМАНИЕ
Подчинённые объекты из других секций (а тем более из других карточек)
затронуты не будут!
Например, вызов BeginUpdate на секции приведёт к тому, что все её строки
окажутся в режиме отложенных изменений. При этом, если на части строк BeginUpdate
уже был вызван ранее, они будут добавлены к общему режиму родительского объекта.
Однако обратное неверно – если режим отложенных изменений включён на какой-то
строке, InUpdate для секции вернет false. Секция (остальные строки) в данном случае
работают, как обычно.
Если режим отложенных изменений включён для родительского объекта, нельзя
оперировать его более мелкой частью. Например, если режим включён на карточке,
вызов CancelUpdate на отдельной строке/секции вернёт ошибку.
Как правило, в коде карточек режим отложенных изменений включается сразу на
всей карточке (так как по умолчанию вся карточка блокируется пользователем для
изменения), но возможны случаи, когда это не так (например, работа со
справочниками).
Пример кода работы с режимом отложенных изменений:
// Получение с сервера данных карточки с известным идентификатором
CardData card = session.CardManager.GetCardData(new
System.Guid("идентификатор_карточки"));
// Включение режима отложенных изменений
if (!card.InUpdate) card.BeginUpdate();
try
{
// Получение данных секции с именем ”MainInfo”
SectionData section = card.Sections[card.Type.Sections["MainInfo"].Id];
// Получение первой строки секции (если строки нет – она будет создана)
RowData row = section.FirstRow;
// Запись значений в поля
row["Author"] = "Иванов";
row["Number"] = 11;
row["CreationDate"] = DateTime.Now;
// Выключение режима отложенных изменений (передача всех изменений на
севрер)
card.EndUpdate();
}
catch(Exception ex)
{
// При возникновении ошибки – отмена всех изменений
if (card.InUpdate) card.CancelUpdate();
DocsVision 4.5: Руководство разработчика на платформе
113
}
4.7
РЕАЛИЗАЦИЯ БЛОКИРОВОК
Для организации многопользовательской работы и предотвращения конфликтов
одновременного доступа к данным в системе предусмотрен механизм блокировок.
Данный механизм позволяет заблокировать от стороннего воздействия
конкретный объект системы (карточку или строку) на время работы с ней в рамках
конкретной пользовательской сессии, что предотвращает возможность параллельного
изменения этого же объекта из других сессий.
Установленная на объекте блокировка защищает его только от изменений и не
препятствует попыткам чтения его данных. При попытке изменения заблокированного
объекта инициатор действия получит исключение 0x600: Object is locked.
Блокировки бывают двух видов: постоянная и временная. Временная блокировка
(Lock) имеет время жизни, ограниченное существованием сессии, из которой эта
блокировка установлена. При завершении сессии, если заблокированный объект не
был освобожден, блокировка будет снята автоматически.
Постоянная блокировка (CheckOut), в свою очередь, сохраняется и после
завершения породившей её сессии. Снять такую блокировку можно только явно – тем,
кто её установил, или администратором системы.
ПРИМЕЧАНИЕ
В текущей версии системы постоянная блокировка может быть установлена
только на файл и не может быть установлена на карточку или строку.
Механизм работы с блокировками поддерживают следующие объекты системы:
CardData
RowData
FileData
Для работы с блокировками используется ряд методов:
PlaceLock() — установка временной блокировки;
PlaceLock(bool permanently) – установка постоянной или временной блокировки
RemoveLock() — снятие блокировки;
ForceUnlock() — принудительно снимает блокировку из другой сессии (метод
доступен только пользователям с административными привилегиями).
DocsVision.Platform.ObjectManager.LockStatus LockStatus – текущее состояние объекта:
LockStatus.Free – блокировка отсутствует;
LockStatus.Locked – временная блокировка другим пользователем;
LockStatus.ChekedOut – постоянная блокировка другим пользователем;
LockStatus.OwnerLocked – временная блокировка текущим пользователем;
LockStatus.OwnerCheckedOut – постоянная блокировка текущим пользователем;
string LockOwner – имя (учетная запись) владельца блокировки (если объект
заблокирован);
Пример кода работы с блокировками:
// Получение с сервера данных карточки с известным идентификатором
CardData card = session.CardManager.GetCardData(new
System.Guid("идентификатор_карточки"));
DocsVision 4.5: Руководство разработчика на платформе
114
// Проверка блокировки на карточке
if (card.LockStatus != LockStatus.Free)
{
// Объект заблокирован - проверка владельца
if (card.LockStatus == LockStatus.OwnerLocked)
{
card.RemoveLock();
}
else
{
MessageBox.Show("Объект заблокирован пользователем " +
card.LockOwner);
}
}
Для управления всеми блокировками в системе можно использовать специальный
объект – LockManager. Этот объект позволяет получить список всех объектов,
заблокированных в системе на данный момент; получить информацию о них и, при
необходимости, принудительно снять блокировку.
Свойства объекта LockManager:
DocsVision.Platform.ObjectManager.ILockable GetLockableObject(System.Guid
возвращает ссылку на заблокированный объект по его идентификатору;
objectId)
DocsVision.Platform.ObjectManager.LockedObjectCollection
GetLockedObjects(bool
currentUser, DocsVision.Platform.ObjectManager.LockedObjectType objectType) – получение
коллекции всех заблокированных объектов, с возможными условиями:
–
currentUser – только объекты, заблокированные текущим пользователем;
objectType – только объекты конкретного типа:
LockedObjectType.Unknown – неизвестный тип
LockedObjectType.Card – карточка
LockedObjectType.File – файл
LockedObjectType.Row – строка карточки
LockedObjectType.All – все типы
Для работы с конкретной блокировкой предназначен класс LockedObject со
следующими свойствами:
System.Guid Id – идентификатор объекта;
string Name – имя объекта;
DocsVision.Platform.ObjectManager.LockedObjectType ObjectType – тип объекта (значения
перечислены выше);
DocsVision.Platform.ObjectManager.LockStatus LockStatus – статус блокировки (значения
перечислены выше);
string LockOwner – владелец блокировки (учетная запись);
System.Guid CardTypeId – тип карточки (если заблокированный объект – карточка);
System.Guid CardId – идентификатор карточки (если заблокированный объект –
карточка);
System.Guid SectionId – тип секции (если заблокированный объект – строка);
DocsVision 4.5: Руководство разработчика на платформе
115
4.8
ИСПОЛЬЗОВАНИЕ ПОИСКА
Методы для поиска разбиваются на две совершенно противоположные по смыслу
группы:
Серверный поиск — наиболее мощный, выполняющийся на сервере метод. В
этом случае на сервер отправляется сформированный поисковый запрос; а в ответ
приходят данные строк, которые затем погружаются в кэш. Запрос описывается XMLстрокой, формат которой задается специальной схемой - однако разработчику не нужно
изучать этот формат, так как в ObjectManager доступна объектная модель для создания
поисковых запросов.
Клиентская фильтрация — внутри себя ObjectManager складывает получаемые
строки в XML-документ (один на всю секцию карточки). Клиенту предоставляется
возможность осуществлять выборку строк с использованием XPath-выражений.
Таким образом, очевидно, что в каждом конкретном случае необходимо очень
тщательно взвесить все «за и против» каждого метода, чтобы получить максимальную
производительность поиска.
4.8.1 Серверный поиск
Как было отмечено выше, поисковый запрос для выполнения серверного поиска
описывается строкой в формате XML. Он строится по специальной схеме (Search.xsd),
которая описывает все возможные комбинации условий поиска.
Конкретный XML поискового запроса может быть получен, например, при помощи
визуального редактора (диалог «Расширенный поиск» в Навигаторе), где пользователь
может оперировать семантически значимыми понятиями, такими как тип карточки –
секция – поле – значение. Но результатом работы этого визуального редактора все
равно в конечном счете станет XML-строка запроса, которая и будет передана на
сервер для выполнения. Этот XML-текст может быть скопирован из диалога и
использован в коде для выполнения аналогичных запросов.
Также текст поискового запроса может быть задан программно – например, при
помощи набора стандартных объектов для работы с XML (XML Parser). Однако, для
упрощения программного создания и редактирования запросов, в объектной модели
ObjectManager предусмотрен ряд специализированных объектов.
DocsVision 4.5: Руководство разработчика на платформе
116
Все объекты для работы с поиском расположены в выделенном пространстве имен
DocsVision.Platform.ObjectManager.SearchModel, поэтому для их использования нужно
подключить данное пространство имен к проекту:
using DocsVision.Platform.ObjectManager.SearchModel;
Базовым объектом для построения поискового запроса является объект
SearchQuery. Для создания этого объекта, предназначен специальный метод
пользовательской сессии (UserSession):
SearchQuery query = session.CreateSearchQuery();
Сам запрос состоит из двух частей — атрибутивного поиска (AttributiveSearch) и
полнотекстового запроса (FullTextSearch). Эти части независимы друг от друга и могут
фигурировать в запросе как по отдельности, так и одновременно. Возможно
объединение результатов этих частей по И/ИЛИ, для этого предназначен флаг
CombineResults.
Количество карточек в результатах поиска можно ограничить свойством Limit.
Пространство карточек, на котором исполняется запрос, ограничивается объектом
Scope. Это ограничение накладывается и на атрибутивную, и на полнотекстовую части
запроса и может включать в себя ограничение по конкретным типам карточек
(CardTypes) и по папкам, в которых расположены ярлыки карточек (Folders).
SearchQuery query = session.CreateSearchQuery();
// Установка ограничения по типам карточек
query.Scope.CardTypes.AddNew(new Guid("C1FED883-08DE-420F-8FB4C16CEFFC1630"));
query.Scope.CardTypes.AddNew(new Guid("FA0C389E-1095-4BC1-BEDC793463742571"));
// Установка ограничения по папкам
query.Scope.Folders.AddNew(new Guid("C0BCEB41-A19B-4813-A35582EB6FD4F5F0")).IncludeSubfolders = true;
Отменить наложенные ограничения может свойствo AllCards – при его установке
поиск производится по всем карточкам, независимо от указанных ограничений.
Свойство IncludeLinkedCard позволяет включить в результаты поиска карточки,
связанные с уже найденными по ссылкам на определённую глубину вложенности
(глубина задается в качестве значения свойства). Дополнительно можно ограничить
тип ссылок (LinkTypes) и их направление (LinkDirections).
Сходное по действию свойство IncludeTopicCards позволяет включить в результаты
поиска карточки, принадлежащие к одной теме обработки с найденными.
Признак IncludeArchived сигнализирует о необходимости включать в область
поиска также и все архивные карточки. Аналогичный признак IncludeDeleted позволяет
искать в том числе и в удаленных карточках.
Чтобы получить сформированную строку запроса в формате XML надо
воспользоваться методом GetXml(). В этом методе параметр ForSearch=true означает, что
строка получается для отсылки на сервер и не должна содержать неактивные
настройки (например, такие, как поисковые слова). Значение ForSearch=false означает,
что строка получается для сохранения где-либо и поэтому в неё включаются все
настройки поиска. Второй параметр метода — Parameters – содержит массив значений,
которые будут подставлены на место параметров, заданных в поиске.
Существует также обратный метод – ParseXml(string queryXml). С его помощью
можно проинициализировать объект SearchQuery из сохраненной строки XML-запроса.
Полнотекстовая часть поискового запроса (FullTextSearch) очень проста и
позволяет задать только саму строку для поиска (QueryString) и режим поиска (Mode),
DocsVision 4.5: Руководство разработчика на платформе
117
чтобы ограничить поиск только файлами или всеми карточками. Поиск возможен только
по карточкам, для которых в схеме разрешен поиск. В результате поиска по файлам
будут возвращены карточки-владельцы найденных файлов, а не сами файлы.
Пример кода построения полнотекстового запроса:
SearchQuery query = session.CreateSearchQuery();
// Условия полнотекстового поиска
query.FullTextSearch.QueryString = "Договор на обслуживание";
query.FullTextSearch.Mode = FullTextSearchMode.Files;
Атрибутивная часть описывает условия на значения полей карточек, которые
требуется найти. Она состоит из запросов к карточкам (CardTypeQuery). Если требуется
найти все карточки, следует выставить в true параметр AllCards. Каждый запрос к типу
карточки состоит из набора запросов к секциям карточки (SectionQuery).
Каждый запрос к секции состоит из набора условий (Condition), накладываемых на
конкретные
поля
секции.
Условия
организуются
в
иерархические группы
(ConditionGroup). Группа условий — это аналог скобок в выражении. Условия внутри
ConditionGroup объединяются операцией (И/ИЛИ), задаваемой свойством Operation.
Группы ConditionGroup могут быть вложенными.
Условие на конкретное
следующими свойствами:
поле
(Condition)
является
сложным
объектом
со
DocsVision.Platform.ObjectManager.SearchModel.ConditionGroup ConditionGroup – группа,
которой принадлежит условие;
string FieldAlias – псевдоним поля секции, по которому строится условие;
DocsVision 4.5: Руководство разработчика на платформе
118
DocsVision.Platform.ObjectManager.Metadata.FieldType FieldType – тип поля:
FieldType.Int - целое число;
FieldType.Bool - булевское значение (да/нет);
FieldType.DateTime - дата И время;
FieldType.Date – дата;
FieldType.Time – время;
FieldType.Enum - перечисление;
FieldType.Bitmask - битовая маска;
FieldType.UniqueID - уникальный идентификатор (GUID);
FieldType.UserID - идентификатор пользователя;
FieldType.String - строка (ANSI);
FieldType.Unistring - строка (UNICODE);
FieldType.FileID - идентификатор файла;
FieldType.Float – дробное;
FieldType.RefID - ссылка на строку;
FieldType.RefCardID - ссылка на карточку;
FieldType.Text - текст ANSI;
FieldType.Unitext - текст UNICODE;
FieldType.Binary - двоичные данные;
FieldType.Image - двоичные данные;
FieldType.SDID - описатель прав;
FieldType.Decimal - десятичное число;
FieldType.Variant – значение переменного типа;
int Index – порядковый индекс условия внутри группы;
bool IsParameter – если условие помечено этим флагом, тогда при получении
окончательной строки поиска на его место может быть подставлено конкретное
значение;
bool IsSearchWord – признак того, что в условии фигурирует специальное поисковое
слово, которое разрешается в актуальное значение самой карточкой (поисковые
слова задаются в схеме карточки- например, Today или I);
DocsVision.Platform.ObjectManager.SearchModel.ConditionOperation
сравнительная операция, которая выполняется в условии:
Operation
–
ConditionOperation.Between – значение внутри диапазона аргументов
ConditionOperation.Contains - значение содержит аргумент
ConditionOperation.EndsWith – заканчивается на
ConditionOperation.Equals - равно
ConditionOperation.GreaterEqual – больше или равно
ConditionOperation.GreaterThan – больше
ConditionOperation.IsChildOf – дочерний элемент в иерархии
DocsVision 4.5: Руководство разработчика на платформе
119
ConditionOperation.IsNotNull – не пустое значение
ConditionOperation.IsNull –пустое значение
ConditionOperation.IsParentOf – родительский элемент в иерархии
ConditionOperation.LessEqual –меньше или равно
ConditionOperation.LessThan –меньше
ConditionOperation.None –условие не указано
ConditionOperation.NotBetween – значение за пределами диапазона
ConditionOperation.NotContains –значение не содержит подстроку
ConditionOperation.NotEquals –не равно
ConditionOperation.NotOneOf – значение не в списке аргументов
ConditionOperation.OneOf – значение в списке аргументов
ConditionOperation.StartsWith – строка начинается с
ConditionOperation.StrEquals –строки равны
ConditionOperation.StrNotEquals – строки не равны
bool IsSystemField – признак, является ли поле системным (к числу таких полей
относятся поля системных таблиц, например, IsTemplate, Deleted, RowID и т.п.);
System.Guid ParameterId – уникальный идентификатор параметра, соответствующего
данному условию. Этот идентификатор автоматически генерируется при установке
соответствующего признака (IsParameter = true);
string ParameterName – имя параметра, соответствующего данному условию (это имя
будет отображаться пользователю в диалоге параметров при выполнении запроса);
string SectionAlias – псевдоним секции, к полям которой применяется данное условие
(если значение не указано – то это основная секция, запроса SectionQuery; в
противном случае – присоединенная секция);
object Value – значение, с которым производится сравнение (в зависимости от поля и
типа операции, значение может быть разного типа, но должно быть приведено к
строке);
DocsVision.Platform.ObjectManager.SearchModel.FieldSubtype
FieldSubtype
–
подтип
свойства. Используется для корректной типизации значений при поиске среди
стандартных свойств. Доступные следующие подтипы:
FieldSubtype.None – отсутствует;
FieldSubtype.String - строка;
FieldSubtype.Int - целое число;
FieldSubtype.Double - дробное число;
FieldSubtype.Date - дата;
FieldSubtype.Bool - булевское значение;
FieldSubtype.Employee - сотрудник;
FieldSubtype.Department – подразделение;
FieldSubtype.Group - группа;
FieldSubtype.Role – роль;
FieldSubtype.Universal - значение универсального справочника;
DocsVision 4.5: Руководство разработчика на платформе
120
FieldSubtype.Time - время;
FieldSubtype.DateTime - дата и время;
FieldSubtype.PartnerEmployee - сотрудник контрагента;
FieldSubtype.PartnerDepartment - контрагент;
FieldSubtype.CardRef - ссылка на карточку;
FieldSubtype.CardType - вид (из справочника типов);
FieldSubtype.CardState - состояние (из справочника типов);
System.Guid FieldSubtypeId – идентификатор
(используется при поиске по свойствам);
string AggregateFunction– имя агрегирующей функции для значения секции. В
качестве значений используются SQL-имена функций (например COUNT, MIN, MAX
и т.д.). Агрегация производится по основной секции запроса (SectionQuery).
Например, при помощи агрегирующих функций можно построить условия вида
«Количество связанных файлов = X», или «Количество согласующих лиц –
максимальное»;
bool AggregateDistinctValues – признак, должна ли агрегационная функция учитывать
только различные значения, или все;
DocsVision.Platform.ObjectManager.SearchModel.ConditionGroup AggregateConditionGroup
– подгруппа условий, которые будут накладываться на агрегируемые значения.
Например, с помощью таких условий можно построить запрос вида «Число
исполненных задач по документу = X»;
string Alias – псевдоним условия в рамках группы (может использоваться при
необходимости построить два разных условия по одному и тому же полю).
типа
универсального
справочника
Сформированный
поисковый
запрос
можно
выполнить,
вызвав
метод
CardManager.FindCards (в параметре метода передается XML-строка сформированного
запроса). Метод возвращает CardDataCollection – коллекцию найденных карточек,
соответствующих условиям запроса. Если же в результате выполнения запроса не было
найдено ни одной карточки – коллекция будет пуста.
В качестве примера рассмотрим построение запроса, который вернёт все карточки
типа «Входящий документ», у которых название равно «Doc1». Перед тем как строить
запрос, необходимо выяснить идентификаторы типа карточки, который собираемся
искать, а также идентификаторы секций, в полях которых производится поиск.
Целесообразно оформить эти идентификаторы в виде констант:
const string ID_CARDTYPE = "{C1FED883-08DE-420F-8FB4-C16CEFFC1630}";
const string ID_SECTION = "{8C77892A-21CC-4972-AD71-A9919BCA8187}";
SearchQuery searchQuery = session.CreateSearchQuery();
// Поиск по типу карточки
CardTypeQuery typeQuery =
searchQuery.AttributiveSearch.CardTypeQueries.AddNew(new Guid(ID_CARDTYPE));
// Поиск по секции
SectionQuery sectionQuery = typeQuery.SectionQueries.AddNew(new
Guid(ID_SECTION));
// Поиск по значению поля
sectionQuery.ConditionGroup.Conditions.AddNew("Name", FieldType.Unistring,
ConditionOperation.StrEquals, "Doc1");
// Получение текста запроса
string query = searchQuery.GetXml(true, null);
// Выполнение запроса
CardDataCollection coll = session.CardManager.FindCards(query);
DocsVision 4.5: Руководство разработчика на платформе
121
В результате будет выполнен вот такой запрос:
<Search Version="4100" CombineResults="OR">
<AttributiveSearch>
<CardTypeQuery CardTypeID="{C1FED883-08DE-420F-8FB4-C16CEFFC1630}">
<SectionQuery SectionTypeID="{8C77892A-21CC-4972-AD71-A9919BCA8187}">
<ConditionGroup Operation="OR">
<Condition>
<Field FieldType="unistring">Name</Field>
<Op>EQ</Op>
<Value>'Doc1'</Value>
</Condition>
</ConditionGroup>
</SectionQuery>
</CardTypeQuery>
</AttributiveSearch>
</Search>
При построении условий к секциям можно также использовать присоединенные
секции (JoinSections). Такая необходимость может возникнуть, если поле, по которому
нужно искать, физически содержится в секции другой карточки. В этом случае к
запросу по секции (SectionQuery) нужно присоединить секцию связанной карточки
(JoinSections.AddNew). Для присоединённой секции (JoinSection) необходимо указать
псевдоним (Alias), поле секции, по которому идёт соединение (SectionField), а также
идентификатор (ID) или псевдоним (JoinWith) присоединяемой секции или системной
таблицы (TableName) и имя её поля (WithField). А в самом условии (Condition)
необходимо, помимо имени поля, задать также псевдоним секции (SectionAlias),
которому это поле принадлежит.
Пример: основная секция карточки, по которой строится запрос, содержит поле
Регистратор – представляющее собой ссылку (REF_ID) на запись о сотруднике (из
справочника сотрудников) и нужно найти все карточки, у которых E-Mail регистратора
содержит подстроку «mail.ru». Такие детали, как E-Mail сотрудника, хранятся только в
соответствующей секции справочника сотрудников – поэтому её необходимо
присоединить при построении такого запроса:
// Идентификатор секции справочника сотрудников
const string REFSTAFF_EMPLOYEES = "{DBC8AE9D-C1D2-4D5E-978B-339D22B32482}";
// Присоединение секции справочника сотрудников
JoinSection join= sectionQuery.JoinSections.AddNew("RegisteredBy_Info");
join.Id = new Guid (REFSTAFF_EMPLOYEES);
join.SectionField = "RowID";
join.WithField = "RegisteredBy";
// Добавление условия на поле присоединенной секции
Condition condition = sectionQuery.ConditionGroup.Conditions.AddNew("Email",
FieldType.Unistring, ConditionOperation.EndsWith, "mail.ru");
condition.SectionAlias = "RegisteredBy_Info";
Таким образом,
несложный алгоритм:
при
построении
запросов
можно
использовать
следующий
1) Создать новый объект запроса (SectionQuery)
2) При необходимости – установить ограничения области поиска (Scope) на типы
карточек (CardTypes) и папки (Folders).
3) Если запрос полнотекстовый – то задать строку поиска (FullTextSearch.QueryString).
4) Если запрос содержит атрибутивные условия:
a) Определить тип карточки, которая должна являться результатом поиска
(CardTypeQuery).
DocsVision 4.5: Руководство разработчика на платформе
122
b) Определить, по какой секции карточки строится запрос (SectionQuery). Если
поле, по которому производится поиск, физически находится в секции другой
(связанной) карточки – то присоединить её (JoinSections).
c)
Сформировать как минимум одну группу условий (ConditionGroup) и определить
операцию для условий (Operation).
d) Добавить в группу условия (Condition), для каждого их которых:
i)
Определить имя поля, по которому производится сравнение (FieldAlias) и его
тип (FieldType), а если поле принадлежит связанной секции – то имя этой
секции (SectionAlias).
ii) Определить условие (Operation).
iii) Определить значение для сравнения (Value).
iv) Если условие использует агрегацию, то:
(a) – задать имя функции (AggregateFunctionName);
(b) – при необходимости, задать дополнительные условия на
агрегируемые значения (AggregateConditionGroup).
5) Выполнить запрос (CardManager.FindCards).
Помимо поиска экземпляров карточек, объектная модель может использоваться и
для поиска строк в конкретной секции карточки. Для этого предназначен метод
SectionData.FindRows, который возвращает коллекцию строк (RowDataCollection),
соответствующих условиям запроса, или пустую коллекцию, если ни одна строка не
подходит.
Текст запроса для поиска строк соответствует аналогичному запросу для поиска
карточек, но в несколько «урезанном» варианте – он начинается сразу с уровня
объекта
SectionQuery,
который
также
является
создаваемым
при
помощи
соответствующего метода объекта UserSession:
SectionQuery secQuery = session.CreateSectionQuery();
ПРИМЕЧАНИЕ
Очевидно, для поиска строк секций могут использоваться только атрибутивные (а
не полнотекстовые) условия.
При построении поисковых запросов внутри секции можно пользоваться всеми
возможностями поисковой модели – присоединенными секциями, агрегациями, и т.д.
Для этого используются те же самые объекты.
Пример: поиск всех строк в справочнике сотрудников c фамилией Иванов:
const string REFSTAFF_CARDTYPE = "6710B92A-E148-4363-8A6F-1AA0EB18936C";
const string REFSTAFF_EMPLOYEES = "DBC8AE9D-C1D2-4D5E-978B-339D22B32482";
// Получение данных справочника
CardData staffData = session.CardManager.GetDictionaryData(new
Guid(REFSTAFF_CARDTYPE));
// Получение секции сотрудников
SectionData section = staffData.Sections[new Guid(REFSTAFF_EMPLOYEES)];
// Создание поискового запроса по секции
SectionQuery query = session.CreateSectionQuery();
// Условие по полю фамилия
query.ConditionGroup.Conditions.AddNew("LastName", FieldType.Unistring,
ConditionOperation.StrEquals, "Иванов");
DocsVision 4.5: Руководство разработчика на платформе
123
// Выполнение запроса
RowDataCollection results = section.FindRows(query.GetXml(true, null));
DocsVision 4.5: Руководство разработчика на платформе
124
4.8.2 Карточка сохраненных поисковых запросов
Поисковый запрос, созданный вручную или с использованием объектной модели,
может быть сохранен в системе для дальнейшего использования (например, в
виртуальных папках).
Для хранения сформированных запросов в системе предусмотрена специальная
карточка
–
карточка
сохраненных
поисковых
запросов
(SavedSearchCard),
расположенная
в
системной
библиотеке
карточек
(DocsVision.Platform.ObjectManager.SystemCards).
Чтобы
избежать
необходимости
оперировать с данными этой карточки напрямую, в объектной модели реализован
соответствующий объект – SearchCard. Данная карточка являтся справочником, и
поэтому может быть получена по идентификатору типа:
const string SEARCH_CARD_TYPE = "{05E4BE46-6304-42A7-A780-FD07F7541AF0}";
CardData searchCard = session.CardManager.GetDictionaryData(new
Guid(SEARCH_CARD_TYPE));
Объектная модель карточки сохраненных запросов (SearchCard) проста и содержит
всего несколько свойств и методов:
DocsVision.Platform.ObjectManager.SystemCards.SavedSearchQueryCollection
коллекция сохраненных запросов
Queries
–
DocsVision.Platform.ObjectManager.SystemCards.SavedSearchGroupCollection
коллекция групп запросов
Groups
–
DocsVision.Platform.ObjectManager.SystemCards.SavedSearchGroup
CreateGroup(System.Guid parentGroupId, string name) – создание новой подгруппы у
родительской (parentGroupId) с именем name
DeleteGroup(System.Guid groupId) – удаление группы с указанным идентификатором (при
этом все запросы из данной группы будут также удалены!)
DeleteQuery(System.Guid
идентификатором
queryId)
–
удаление
сохраненного
запроса
с
указанным
DocsVision.Platform.ObjectManager.SystemCards.SavedSearchGroup GetGroup(System.Guid
groupId) – получение группы по идентификатору
DocsVision.Platform.ObjectManager.SystemCards.SavedSearchQuery
queryId) – получение запроса по идентификатору
GetQuery(System.Guid
bool GroupExists(System.Guid groupId) – проверка существования группы с указанным
идентификатором
bool QueryExists(System.Guid queryId) - проверка существования запроса с указанным
идентификатором
В свою очередь, для описания конкретного сохраненного запроса используется
объект SavedSearchQuery со следующими атрибутами:
System.Guid Id – идентификатор сохраненного запроса;
string Name – название запроса (его будут видеть пользователи);
DocsVision 4.5: Руководство разработчика на платформе
125
string Text – возвращает XML-описание запроса в виде строки;
bool Hidden – признак, влияющий на отображение сохраненного запроса в
диалогах Навигатора;
DocsVision.Platform.ObjectManager.SearchModel.SearchQuery
Export()
–
получить объект SearchQuery для редактирования условий запроса;
позволяет
Import(DocsVision.Platform.ObjectManager.SearchModel.SearchQuery
searchQuery)
позволяет получить XML-описание на основании объекта SearchQuery;
–
DocsVision.Platform.ObjectManager.SystemCards.SavedSearchLayoutCollection Layouts –
коллекция
настроек
расположения
параметров
поискового
запроса
(SavedSearchLayoutCollection).
Пример кода – создание нового поискового запроса и сохранение его в карточке:
// Формирование поискового запроса
SearchQuery query = session.CreateSearchQuery();
// …
// Получение карточки сохраненных запросов
const string SEARCH_CARD_TYPE = "{05E4BE46-6304-42A7-A780-FD07F7541AF0}";
SearchCard searchCard = (SearchCard)session.CardManager.GetDictionary(new
Guid(SEARCH_CARD_TYPE));
// Сохранение запроса в карточку
searchCard.Queries.AddNew("Мой новый запрос").Import(oQuery);
4.8.3 Утилита Search Utility
Начиная с версии 3.6 SR1, в пакет утилит разработчика DocsVision Resource Kit
включена полезная утилита Search Utility.
Эта утилита предназначена для трансляции сформированных поисковых запросов
на язык SQL, что может быть полезно при решении следующих задач:
поиск и диагностика ошибок в поисковом запросе (например, если запрос
возвращает не те данные, которые ожидаются);
оптимизация поисковых запросов с целью повышения эффективности их
выполнения (можно проанализировать план выполнения SQL-запроса в SQL Query
Analyzer и по его результатам модифицировать текст XML-запроса и/или построить
дополнительные индексы на таблицах).
Главное окно утилиты выглядит следующим образом:
DocsVision 4.5: Руководство разработчика на платформе
126
Рис. 4.1. Главное окно утилиты Search Utility
Для начала работы, необходимо нажать кнопку Connect и указать реквизиты
соединения с SQL Server:
Рис. 4.2. Подключение к SQL Server
Необходимо указать стандартный набор параметров соединения: имя SQLсервера, тип аутентификации, имя пользователя, пароль, имя конкретной базы данных.
После установки соединения, появится возможность изменить параметры работы
утилиты. Окно параметров открывает команда Settings:
Рис. 4.3. Параметры Search Utility
DocsVision 4.5: Руководство разработчика на платформе
127
Допускается изменение следующих параметров:
Generate extended preview script – данный признак позволяет в SQL-запросах,
генерируемых утилитой, выводить дополнительную информацию о найденных
карточках – ID типа, дайджест и т.д. Эта информация может быть полезна при
отладке запросов;
Generate fulltext queries – признак, указывающих на необходимость генерации
SQL-выражений для полнотекстового поиска (доступен только для баз данных с
включенными полнотекстовым поиском);
Use inflection in fulltext queries – признак, указывающий на необходимость
строить выражения для полнотекстового поиска с использованием словоформ
(доступен только для баз данных с включенными полнотекстовым поиском);
Limit search – позволяет ограничить количество данных в результатах запроса.
На вкладке Search XML можно вставить текст сформированного поискового
запроса для поиска карточек:
Рис. 4.4. Текст запроса в утилите Search Utility
Для трансляции текста запроса на язык SQL нужно нажать кнопку Translate.
Результат будет отображен на вкладке SQL:
DocsVision 4.5: Руководство разработчика на платформе
128
Рис. 4.5. SQL-выражение поискового запроса
Аналогичным образом можно сгенерировать SQL-выражение для поискового
запроса по данным секции. В этом случае XML запроса нужно вставить на вкладку
Section XML и воспользоваться кнопкой Translate section для генерации.
4.8.4 Клиентская фильтрация
Клиентская фильтрация позволяет осуществить выборку строк с использованием
XPath-выражений. Её имеет смысл применять в тех случаях, когда данные уже
загружены на клиента и выполнять серверный поиск нет необходимости.
Фильтрация поддерживается для данных секций (SectionData и SubSectionData), а
также для произвольных коллекций строк (RowDataCollection).
Выражения для поиска строятся стандартным для XPath способом (описание
синтаксиса XPath-запросов можно найти в оригинальном стандарте, в MSDN или в
специализированных изданиях).
В качестве элементов XPath-запроса могут выступать поля секции, по которой
осуществляется поиск (как собственные поля секции, так и связанные поля секций
других карточек). Полный перечень этих полей для стандартных типов карточек можно
посмотреть:
при помощи утилиты CardManager, открыв схему соответствующей карточки
(схемы всех базовых типов карточек входят в состав пакета разработчика);
в документе «Описание полей стандартных карточек» (входит в состав пакета
разработчика).
ПРИМЕЧАНИЕ
Другим простым способом, который может помочь в построении XPath-запроса,
является получение непосредственно данных секции в формате XML на примере
любой карточки интересующего типа (при помощи команды Экспорт и печать в
Навигаторе). Используя эти данные как образец, можно строить запросы
непосредственно на базе этого XML-документа.
Для поиска данных в секциях
используется метод FindRow(string filter)
(SectionData)
и
подсекциях
DocsVision 4.5: Руководство разработчика на платформе
(SubSectionData)
129
Метод принимает на вход единственный параметр – строку поиска в формате
XPath.
ПРИМЕЧАНИЕ
Клиентская фильтрация возвращает только один результат (строку). Это всегда
первая по порядку строка, удовлетворяющая условиям поиска (если таким
условиям удовлетворяет несколько строк).
Пример кода: поиск сотрудника в справочнике сотрудников по его фамилии:
const string ID_CARDTYPE = "{6710B92A-E148-4363-8A6F-1AA0EB18936C}";
const string ID_SECTION = "{DBC8AE9D-C1D2-4D5E-978B-339D22B32482}";
// Фамилия сотрудника
string name = "Иванов";
// Клиентская фильтрация
CardData card = session.CardManager.GetDictionaryData(new Guid(ID_CARDTYPE));
SectionData section = card.Sections[new Guid(ID_SECTION)];
RowData row = section.FindRow("@SurName=\"" + strName + "\"");
Для поиска строк в коллекции (RowDataCollection) параметры и способ
использования метода абсолютно аналогичны соответствующему методу для секций.
Единственное отличие заключается в том, что метод Filter может возвращать более чем
один результат (RowDataCollection).
4.9
РАБОТА С ФАЙЛАМИ
Платформа DocsVision позволяет загружать в базу данных и извлекать из базы
данных пользовательские файлы произвольного формата. Для работы с файлами в
системе существует специальная системная карточка — карточка файла, а также набор
интерфейсов менеджера объектов для манипуляций с файлами.
Для работы с файлами можно использовать несколько видов объектов:
системный объект — файл — реализует простейшую функциональность для
хранения файлов в базе данных DocsVision;
системный объект — версия файла — реализует дополнительные атрибуты для
нумерованной версии файла;
системная карточка файла — поддерживают функциональность по хранению
нескольких версий файла, комментариев к ним и дополнительных механизмов
работы с файлом;
карточка файла из решения «Делопроизводство» (в данном Руководстве не
рассматривается);
карточка — список файлов из решения
Руководстве не рассматривается).
«Делопроизводство»
DocsVision 4.5: Руководство разработчика на платформе
(в
данном
130
4.9.1 Системный объект — файл
Для работы с простыми файлами в системе предусмотрен объект FileData. Это
самый низкроуровневый объект для работы с двоичными данными файла – поэтому у
него нет таких понятий как “версия” или “свойства”.
Свойства и методы объекта FileData:
System.DateTime CreateDate — дата создания файла;
System.DateTime ChangeDate – дата последнего изменения файла
int ExtAttributes — дополнительные атрибуты файла (битовая маска)
System.Guid Id — идентификатор файла;
string Name — название файла;
System.Guid OwnerCardId — опциональное свойство. Идентификатор карточки, к
которой «привязан» данный файл (обычно это VersionedFileCard)
int Size — размер файла (в KB);
int StdAttributes — стандартные атрибуты файла (битовая маска);
System.Uri Url — URL-адрес для доступа к файлу по протоколу http;
bool Encrypted – признак того, что файл зашифрован;
bool Signed – признак того, что файл подписан;
DocsVision.Platform.ObjectManager.OfflineState OfflineState – статус вытесненного файла
DocsVision.Platform.ObjectManager.ArchiveState ArchiveState – статус архивного файла:
ArchiveState.NotArchived - файл не архивирован
ArchiveState.Archived - файл находится в архиве
ArchiveState.PreparedToArchive - файл подготовлен к архивации
ArchiveState.PreparedToDearchive - файл подготовлен к восстановлению из архива
(не доступен для обращений)
DocsVision.Platform.ObjectManager.FileData Copy() — создание копии файла на сервере;
Download(string fileName) — извлечение файла на файловую систему по указанному
пути;
Upload(string fileName) — загрузка файла из файловой системы на сервер;
System.IO.Stream OpenReadStream() — создание потока для чтения файла;
System.IO.Stream OpenWriteStream() — создание потока для записи файла;
Refresh() — обновляет информацию о файле;
BringOnline() - восстановление файла из offline хранилища;
TakeOffline(bool autoRestore) - перенос файла в offline хранилище. Параметр autoRestore
указывает на необходимость автоматического восстановления файла при первом
обращении к нему
Archive(bool delay) – перенос файла в архив (признак delay указывает на отложенную
архивацию);
Dearchive(bool delay) – восстановление файла из архива (признак delay указывает на
отложенную операцию).
DocsVision 4.5: Руководство разработчика на платформе
131
Работа со стандартными файлами осуществляется при помощи менеджера файлов,
который
может
быть
получен
из
интерфейса
менеджера
объектов
UserSession.FileManager
Менеджер файлов позволяет выполнять простейшие операции с файлами создавать, удалять, копировать и осуществлять поиск файлов в системе:
DocsVision.Platform.ObjectManager.FileData CopyFile(System.Guid fileId) – копирование файла
DocsVision.Platform.ObjectManager.FileData CreateFile(string fileName) – создание нового
файла с заданным именем (только что созданный файл будет пуст)
DeleteFile(System.Guid fileId) – удаление файла с указанным идентификатором
bool FileExists(System.Guid
идентификатором
DocsVision.Platform.ObjectManager.FileDataCollection
FindFiles(DocsVision.Platform.ObjectManager.FileSearchQuery searchQuery) – поиск файлов с
использованием полнотекстового поиска
DocsVision.Platform.ObjectManager.FileData GetFile(System.Guid fileId) – получение файла с
указанным идентификатором
fileId)
–
проверка
существования
файла
с
указанным
Пример создания файла при помощи менеджера файлов:
// создание нового файла
FileData file = session.FileManager.CreateFile("MyFile");
// загрузка содержимого с файловой системы
file.Upload("C:\\MyFile.doc");
4.9.2 Внешнее хранение файлов
При хранении большого количества файлов размер рабочей базы DocsVision
увеличивается, что замедляет скорость обработки информации (прежде всего построение полнотекстового каталога). При этом файлы, прикрепленные к документам,
не находящимся в процессе обработки, реально не используются. Следовательно,
разумно хранить такие файлы не в базе данных, а на внешнем (потенциально более
дешевом) носителе.
Начиная с версии DocsVision 3.6, реализована поддержка выгрузки файлов из
рабочей базы во внешнее файловое хранилище.
Поддерживается два типа хранилища:
Папка на локальном диске.
Сетевой ресурс, доступный по CIFS/SMB протоколу (сетевая папка).
Данные выгруженного файла недоступны. Перед тем, как снова включить файл в
обработку, необходимо вернуть его из внешнего хранилища. Тем не менее, наряду с
обычной выгрузкой файла во внешнее хранилище, реализован и прозрачный доступ к
выгруженным файлам, при котором данные автоматически возвращаются в базу при
первом обращении к ним пользователя.
Данные файлов, как и все остальные данные DocsVision, хранятся в одной из
таблиц оперативной базы данных. После выгрузки их во внешнее хранилище данные
файла удаляются (очищается соответствующее поле таблицы), и файл помечается
специальным атрибутом.
Внешнее хранилище организовано иерархически, файл выгружается в подпапку,
соответствующую его имени и идентификатору. Имя файла составляется по
следующему правилу:
<путь к файловому хранилищу>\<имя файла>\<идентификатор файла>\<имя файла>
DocsVision 4.5: Руководство разработчика на платформе
132
Таким образом, разные версии файла оказываются собранными в одной папке.
При этом файлы выгружаются из базы под своим именем, что позволяет осуществлять
поиск по маске.
Настройка внешнего хранилища осуществляется при помощи стандартной Консоли
настройки DocsVision, где указывается Папка для выгруженных файлов.
Файл
может
находиться
(DocsVision.Platform.ObjectManager.OfflineState):
в
следующих
состояниях
OfflineState.Online – данные файла находятся в базе, с ним можно работать как
обычно;
fflineState.Offline – данные файла выгружены во внешнее хранилище;
fflineState.OnlineAutoRestore – данные файла выгружена во внешнее хранилище,
однако будут возвращены в базу при первом же обращении, что для
пользователя гарантирует прозрачность работы с его данными.
Если попытаться читать или записывать данные файла, выгруженного из базы (и
если выключена автоматическая загрузка его обратно в базу), то клиенту будет
возвращена ошибка. Такая же ошибка будет возвращена, если попытаться выгрузить
уже выгруженный файл. Если попытаться загрузить файл, уже находящийся в базе,
клиенту также будет возвращена ошибка.
Функции для работы с выгруженными файлами доступны только программно.
ВНИМАНИЕ
Для выполнения операций вытеснения/восстановления файлов из внешнего
хранилища требуется наличие привилегии оператора архива (членство в группе
«DocsVision Archive Operators»).
4.9.3 Системный объект — версия файла
Версия файла (объект FileVersion) расширяет функциональность стандартного
файла и наследует его интерфейс. Свойства и методы версии файла повторяют
аналогичные свойства файла и добавляют к ним собственные. Объект версии файла не
может быть создан разработчиком напрямую и используется только в системной
карточке файла с версиями (VersionedFileCard).
Дополнительные свойства объекта FileVersion:
DocsVision.Platform.ObjectManager.SystemCards.FileAssociateCollection AssociatedFiles —
коллекция ассоциированных с версией файлов;
System.Guid AuthorId — автор версии файла (идентификатор пользователя из
системной таблицы dvsys_users)
DocsVision.Platform.ObjectManager.SystemCards.FileCommentCollection
Comments
коллекция комментариев к версии файла (FileCommentCollection);
—
System.Guid ExtCardId — идентификатор карточки расширения (в настоящее время не
используется)
int IncrementalNumbe — порядковый номер версии;
int Level — уровень версии файла;
System.Guid VersionId— уникаольный идентификатор версии;
int VersionNumber — номер версии на данном уровне;
DocsVision.Platform.ObjectManager.SystemCards.FileVersionCollection
коллекция подверсий файла (FileVersionCollection);
Versions—
string VersionString — строковое представление текущей версии.
DocsVision 4.5: Руководство разработчика на платформе
133
ПРИМЕЧАНИЕ
Например, для версий первого уровня номер уровня (Level) будет равнен 1,
номер версии на данном уровне будет храниться в свойстве VersionNumber
(например, 2). Тогда строковое представление (VersionString) будет выглядеть как
«1.2».
Дополнительные методы:
System.Guid[] GetHierarchy — получение иерархии версий и подверсий файла
(перечень идентфикаторов всех родительских объектов)
MakeCurrent() — пометка данной версии как текущей.
Для хранения комментариев к версии файла используется объект комментарий к
файлу (FileComment), обладающий следующими свойствами:
System.Guid AuthorId— автор комментария (идентификатор пользователя из системной
таблицы dvsys_users)
string Comment — текст комментария (строка);
System.DateTime CreationDate — дата создания комментария;
System.Guid Id — идентификатор комментария.
4.9.4 Системная карточка файла
Системная карточка файла используется для обеспечения удобства работы с
файлами и предоставляет дополнительные возможности, такие как:
поддержка неограниченного количества версий каждого файла;
возможность задания комментариев к версиям файла;
обеспечение безопасности при работе с файлом;
поддержка механизма единоличного владения файлом (CheckIn/CheckOut).
Для работы с системной карточкой файла в менеджере объектов предусмотрен
объект VersionedFileCard. Как и все системные карточки, он находится в пространстве
имен DocsVision.Platform.ObjectManager.SystemCards.
Свойства и методы объекта:
string Barcode— код файла в строчном формате (в настоящее время не используется)
bool CheckedOut— признак наличия постоянно блокировки
string CheckoutPath — путь в файловой системе, куда выгружен файл для единоличного
владения;
System.Guid CheckoutUser — пользователь, забравший файл в единоличное владение
(идентификатор пользователя из системной таблицы dvsys_users)
DocsVision.Platform.ObjectManager.SystemCards.FileCommentCollection Comments —
коллекция комментариев к файлу;
DocsVision.Platform.ObjectManager.SystemCards.FileVersion CurrentVersion — текущая версия
файла;
System.Guid ExtCardId — идентификатор карточки расширения (в настоящее время не
используется)
string Name— название карточки файла;
System.Guid ParentCardId — идентификатор родительской карточки;
DocsVision 4.5: Руководство разработчика на платформе
134
DocsVision.Platform.ObjectManager.SystemCards.FileVersionCollection Versions — коллекция
версий файла
Методы:
DocsVision.Platform.ObjectManager.SystemCards.FileVersion CheckIn(string filePath, int level,
bool remoteFile, bool copyRemote)— снятие постоянной блокировки и создание новой версии
файла;
DocsVision.Platform.ObjectManager.SystemCards.FileVersion CheckOut(string filePath,
System.Guid userId, bool download) — выгрузка файла на локальную файловую систему и
установка постоянной блокировки
DeleteVersion(System.Guid versionId) — удаление версии с указанным идентификатором;
string GetNextVersion(int level) - определение номера следующей версии файла на данном
уровне;
DocsVision.Platform.ObjectManager.SystemCards.FileVersion GetVersion(System.Guid versionId)
— получение конкретной версии по её идентификатору;
DocsVision.Platform.ObjectManager.SystemCards.FileVersion Initialize(string filePath,
System.Guid userId, bool remoteFile, bool copyRemote) — создание новой карточки на базе
содержмого файла, и создание первой версии
UndoCheckout() — отмена режима единоличного владения файлом.
ПРИМЕЧАНИЕ
Для создания первой версии файла используется метод Initialize, который
погружает файл в базу данных и инициализирует версию. Последующие версии
создаются автоматически при вызове CheckIn.
Поскольку карточка файла является обычной карточкой DocsVision, то для её
создания необходимо прибегнуть к помощи объекта — менеджера карточек
(CardManager).
Пример создания и первичной инициализации карточки файла:
// константа, идентификатор типа карточки-файла
const string FILE_CARD_TYPE = "6E39AD2B-E930-4D20-AAFA-C2ECF812C2B3";
// Создание карточки файла
VersionedFileCard fileCard =
(VersionedFileCard)session.CardManager.CreateCard(new Guid(FILE_CARD_TYPE));
// Первичная инициализация карточки файла
fileCard.Initialize("C:\\MyFile.doc", Guid.Empty, false, false);
// Получение первой версии файла
FileVersion fileVersion = fileCard.CurrentVersion;
MessageBox.Show(fileVersion.VersionString);
Таким образом, для работы с файлами:
при использовании системы в качестве хранилища файлов произвольного формата
для простоты следует использовать системный объект-файл;
при необходимости ведения сложной иерархии версий файла и реализации
механизмов CheckIn/CheckOut следует использовать системную карточку файла.
4.10 ИСПОЛЬЗОВАНИЕ НУМЕРАТОРОВ
Для упрощения автоматической нумерации документов в системе предусмотрены
специальные объекты — нумераторы. Нумераторы выполняют следующие функции:
выделение диапазонов номеров для документов;
ассоциация (закрепление) диапазонов номеров за пользователями системы;
DocsVision 4.5: Руководство разработчика на платформе
135
автоматическое выделение номеров новым документам;
резервирование номеров;
контроль и освобождение занятых и зарезервированных номеров.
В системе может одновременно существовать несколько нумераторов. Каждый
нумератор отвечает следующим принципам:
определяет непрерывное пространство номеров (например, 1…1000);
пространство номеров может содержать несколько диапазонов, закрепленных за
конкретными пользователями системы (например, 1..100, 500..800);
может содержать несколько именованных зон, номера в которых могут совпадать
(например, «2004 год», «2005 год»);
каждый номер может обладать собственным статусом:
свободен;
занят;
зарезервирован.
Для реализации работы с нумераторами в состав платформы входит специальная
системная карточка нумератора, а в менеджере объектов определен набор объектов
для выполнения операций с карточкой нумератора.
4.10.1 Карточка нумератора
Системная карточка нумератора (NumeratorCard) содержит свойства и методы для
работы с конкретным экземпляром нумератора. Для создания нового нумератора
требуется создать экземпляр этой карточки. Как и все системные карточки, она
находится в пространстве имен DocsVision.Platform.ObjectManager.SystemCards.
Свойства:
int StartNumber— начальный номер (свойство доступно только для чтения);
int EndNumber — конечный номер (свойство доступно только для чтения);
string Name— название нумератора;
bool Available — признак доступности нумератора для выдачи номеров;
DocsVision.Platform.ObjectManager.SystemCards.NumeratorRangeCollection Ranges —
коллекция диапазонов нумератора
DocsVision.Platform.ObjectManager.SystemCards.NumeratorZoneCollection Zones—
коллекция зон нумератора
Методы:
AllocateNumbers(System.Guid userId, string zoneName, int startNumber, int endNumber) резервирование группы номеров нумератора за определённым пользователем (userId идентификатор пользователя из системной таблицы dvsys_users)
ChangeEndNumber(int number, bool forceChange) - изменение конечного номера нумератора;
ChangeStartNumber(int number, bool forceChange) - изменение начального номера нумератора;
DocsVision.Platform.ObjectManager.InfoRowCollection GetNumbersStatus(string zoneName,
int startNumber, int endNumber) - получение статусов группы номеров нумератора;
ReleaseNumbers(string zoneName, int startNumber, int endNumber) - освобождение группы
номеров нумератора.
DocsVision 4.5: Руководство разработчика на платформе
136
4.10.2 Зона нумератора
Зона нумератора представляет собой именованную совокупность номеров. Внутри
одного нумератора может существовать несколько параллельных зон, номера в которых
совпадают. Вся работа, связанная с получением или освобождением номеров,
производится именно в конкретной зоне нумератора. Для работы с зонами в менеджере
объектов предусмотрен объект NumeratorZone.
Свойства:
System.Guid Id— идентификатор зоны;
string Name— название зоны;
DocsVision.Platform.ObjectManager.SystemCards.NumeratorCard Numerator — нумератор,
которому принадлежит зона
Методы:
System.Guid AllocateNumber(System.Guid userId, int number) - резервирование конкретного
номера из зоны для пользователя (userId - идентификатор пользователя из системной таблицы
dvsys_users)
int GetNumber(System.Guid userId, bool getMinimal, out System.Guid numberId) - получение
номера из зоны для пользователя;
System.Guid GetNumberId(int number) - получение идентификатора номера по его значению;
DocsVision.Platform.ObjectManager.SystemCards.NumberStatus GetNumberStatus(int number)
- получение статуса указанного номера:
NumberStatus.Free — номер свободен;
NumberStatus.InUse — номер занят;
NumberStatus.Reserved — номер зарезервирован;
NumberStatus.NotExists — номер не существует в нумераторе;
ReleaseNumber(int number) — освобождение указанного номера;
ReleaseNumber(System.Guid numberId) - освобождение номера по его идентификатору.
4.10.3 Диапазон нумератора
Диапазон нумератора представляет собой подмножество номеров, закрепленных
за определённым пользователем системы. Для работы с диапазонами в менеджере
объектов предусмотрен объект NumeratorRange.
Свойства:
int EndNumber — конечный номер диапазона;
System.Guid Id — идентификатор диапазона;
System.Guid OwnerId — идентификатор пользователя — владельца диапазона (userId идентификатор пользователя из системной таблицы dvsys_users)
int StartNumber — начальный номер диапазона.
Таким образом, для работы с нумератором следует выполнить следующие
действия:
Создать экземпляр карточки нумератора
Определить границы пространства номеров
Создать в нумераторе как минимум одну нумерованную зону.
При необходимости, добавить один или несколько диапазонов номеров.
DocsVision 4.5: Руководство разработчика на платформе
137
Пример работы с нумератором:
// константа, идентификатор типа карточки нумератора
const string NUMERATOR_CARD_TYPE = "959FF5E2-7E47-4F6F-9CF6-E1E477CD01CF";
// создание новой карточки нумератора
NumeratorCard numerator = (NumeratorCard)session.CardManager.CreateCard(new
Guid(NUMERATOR_CARD_TYPE));
// Первичная инициализация нумератора
numerator.ChangeStartNumber(1, true);
numerator.ChangeEndNumber(1000, true);
numerator.Name = "MyNumerator";
// Создание зоны
NumeratorZone zone = numerator.Zones.AddNew(DateTime.Now.Year.ToString());
// Получение номера
Guid outId;
int number = zone.GetNumber(Guid.Empty, true, out outId);
4.11 ЭКСПОРТ, ИМПОРТ И ПЕЧАТЬ
4.11.1 Экспорт
Платформа позволяет экспортировать любые данные (карточки, секции, наборы
строк и отдельные строки) в формат XML, а также импортировать их обратно. С этой
функциональностью неразрывно связана также и задача печати данных – так как
проще всего реализовать её через специальный формат экспорта.
Для получения XML-представления данных карточки можно использовать
соответствующие
методы
объектов
CardDataCollection,
CardData,
SectionData,
SubSectionData, RowData и RowDataCollection:
SaveXml(System.IO.Stream stream) – получает XML для записи в поток (в память или в
файл), содержащий данные самой карточки (по умолчанию)
SaveXml(System.IO.Stream stream, DocsVision.Platform.ObjectManager.ExportFlags exportFlags)
– этот метод предоставляет больше возможностей для управления форматом
экспорта при помощи параметра exportFlags:
ExportFlags.None - по умолчанию (аналогично предыдущему методу)
ExportFlags.Namespace - указывать ли пространство имен;
ExportFlags.LinkedCard - включать связанные карточки (RefCardID);
ExportFlags.LinkedFiles - включать данные файлов;
ExportFlags.LinkedRows - включать связанные строки (RefID);
ExportFlags.FilesNoData - включать атрибуты файлов (без данных);
ExportFlags.ChildRows - включать дочерние строки иерархии;
ExportFlags.LinkedSections - включать строки дочерних секций;
ExportFlags.Security - включать дескрипторы безопасности объектов
Пример:
FileStream file = new FileStream("C:\\MyCard.xml", FileMode.Create);
card.SaveXml(file, ExportFlags.LinkedCards & ExportFlags.LinkedRows);
SaveXml(System.IO.Stream stream, DocsVision.Platform.ObjectManager.ExportFlags exportFlags,
DocsVision.Platform.ObjectManager.ExportCardInspector inspector) – позволяет получить
XML с помощью специального вспомогательного объекта – инспектора, который
позволяет более гибко управлять логикой экспорта.
DocsVision 4.5: Руководство разработчика на платформе
138
Создать собственный инспектор для реализации сложного алогитма экспорта
можно на основе базового класса DocsVision.Platform.ObjectManager.ExportCardInspector.
При этом необходимо переопеределить реализацию одного или нескольких событий:
AfterExport() – инициируется после экспорта всех данных, и позволяет дополнить
итоговый XML собственными дополнительными данными
AfterExportCard(DocsVision.Platform.ObjectManager.CardData cardData) – инициируется
после экспорта данных очередной карточки, и позволяет дополнить ее XML
собственными данными
AfterExportField(DocsVision.Platform.ObjectManager.RowData rowData,
DocsVision.Platform.ObjectManager.Metadata.Field rowField) - инициируется после
экспорта данных поля, и позволяет дополнить ее XML собственными данными
AfterExportFile(DocsVision.Platform.ObjectManager.FileData fileData) - инициируется
после экспорта данных файла, и позволяет дополнить его XML собственными
данными
AfterExportRow(DocsVision.Platform.ObjectManager.RowData rowData) - инициируется
после экспорта данных строки, и позволяет дополнить ее XML собственными
данными
AfterExportSection(DocsVision.Platform.ObjectManager.SectionData sectionData,
System.Guid parentRowId) - инициируется после экспорта данных секции, и
позволяет дополнить ее XML собственными данными
BeforeExport(ref bool cancel) - инициируется перед началом экспорта, и позволяет
воспрепятствовать ему (cancel=true)
BeforeExportCard(DocsVision.Platform.ObjectManager.CardData cardData, ref bool cancel) инициируется перед началом экспорта данных карточки, и позволяет
воспрепятствовать ему (cancel=true)
BeforeExportField(DocsVision.Platform.ObjectManager.RowData rowData,
DocsVision.Platform.ObjectManager.Metadata.Field rowField, ref bool cancel) инициируется перед началом экспорта данных поля, и позволяет
воспрепятствовать ему (cancel=true)
BeforeExportFile(DocsVision.Platform.ObjectManager.FileData fileData, ref bool cancel) инициируется перед началом экспорта данных файла, и позволяет
воспрепятствовать ему (cancel=true)
BeforeExportRow(DocsVision.Platform.ObjectManager.RowData rowData, ref bool cancel) инициируется перед началом экспорта данных строки, и позволяет
воспрепятствовать ему (cancel=true)
BeforeExportSection(DocsVision.Platform.ObjectManager.SectionData sectionData,
System.Guid parentRowId, ref bool cancel) - инициируется перед началом экспорта
данных секции, и позволяет воспрепятствовать ему (cancel=true)
OnError(int errorCode, string errorMessage, ref bool cancel) – позволяет обработать ошибку
экспорта
4.11.2 Импорт
Обратное действие – импорт – позволяет загрузить в систему данные на основании
строки (или файла) в формате XML, ранее выгруженного из этой же (или другой) базы
данных DocsVision.
ПРИМЕЧАНИЕ
Корректность импорта не гарантируется, если версия базы данных, из которой
данные были экспортированы, отличается от версии базы, куда они
импортируются.
Для импорта предназначены следующие методы объекта CardManager:
DocsVision 4.5: Руководство разработчика на платформе
139
DocsVision.Platform.ObjectManager.CardDataCollection ImportCards(System.IO.Stream stream)
– импортирует одну или несколько карточек из XML-файла или потока
DocsVision.Platform.ObjectManager.CardDataCollection ImportCards(System.IO.Stream stream,
DocsVision.Platform.ObjectManager.ImportCardInspector cardInspector) – импортирует одну
или несколько карточек из XML-файла или потока, с использованием собственного
алгортма импорта
Загружаемый XML должен соответствовать стандартной схеме карточек DocsVision.
Проверка на соответствие этой схеме обязательно выполняется перед началом
собственно загрузки данных, и в случае несоответствия менеджер объектов вернет
ошибку. Таким образом, передавать на вход метода произвольный XML-документ
бессмысленно.
Для управления логикой работы импорта предназначен специальный тип объектов
– DocsVision.Platform.ObjectManager.ImportCardInspector. Этот объект полностью реализует
процесс импорта, осуществляет контроль целостности данных и выполняет разрешение
конфликтов.
ПРИМЕЧАНИЕ
Необходимость наличия сложного механизма разрешения конфликтов при
импорте обусловлена многообразием возможных конфигураций системы.
Например, даже при импорте одной отдельно взятой карточки может возникнуть
ситуация, когда такая карточка (с таким идентификатором) уже существует в
базе. Это сразу порождает несколько возможных вариантов дальнейшего
поведения импортера:
•
заменить полностью существующую в базе карточку на новую;
•
объединить данные существующей карточки с данными импортируемой;
•
создать новый экземпляр карточки
наполнить его импортируемыми данными;
•
прервать процесс импорта;
•
и т.д.
(с
другим
идентификатором)
и
Однако даже объект-инспектор не всегда может гарантировать корректность
импорта, так как некоторые ограничения активируются только при отправке уже
импортированных данных на сервер. К числу таких ограничений относятся:
•
права доступа к объектам;
•
ограничения ссылочной целостности (foreign key constraints);
•
ограничения уникальности (unique constraints).
Если импортируемые данные нарушают одно их этих ограничений, то ошибка
возникнет уже на сервере при попытке сохранить импортированные данные в БД.
В этом случае импорт будет отменен полностью в рамках одной транзакции.
По умолчанию, в менеджере объектов реализовано 2 типа объектов-инспекторов,
обладающих разным поведением:
ImportCardInspectorCopier – создаёт копию карточки (с другими идентификаторами
всех строк), используя данные из XML в качестве шаблона;
ImportCardInspectorReplacer – заменяет содержимое импортируемой карточки
(существующие строки будут заменены; отсутствующие строки буду добавлены в
существующий экземпляр);
Объект-инспектор нужно создавать явно, передав в его конструктор ссылку на
сессию:
FileStream file = new FileStream("C:\\MyCard.xml", FileMode.Open);
DocsVision 4.5: Руководство разработчика на платформе
140
ImportCardInspectorReplacer inspector = new
ImportCardInspectorReplacer(session);
CardDataCollection cards = session.CardManager.ImportCards(file);
Если
существующих
типов
инспекторов
недостаточно
для
реализации
необходимой логики импорта, то можно разработать собственный объект-инспектор.
Для
этого
нужно
создать
новый
класс,
унаследовав
его
от
базового
DocsVision.Platform.ObjectManager.ImportCardInspector; и переопределить методы этого
класса, отвечающие за импорт отдельных структур.
4.11.3 Печать
Печать данных карточки может быть выполнена как стандартными средствами
системы, так и любым другим способом — по усмотрению разработчика. При
использовании собственных методов печати целесообразно получить данные карточки
в формате XML, а затем преобразовать их в формат, удобный для печати (либо
экспортировать во внешнюю систему, осуществляющую печать).
Использование стандартных средств предполагает применение к данным карточки
XSLT- или InfoPath-преобразования, описание которого задается на этапе
проектирования схемы данных карточки в разделе «Преобразования». Получить
преобразования для конкретного типа карточки можно из мета-данных:
CardType type = session.CardManager.CardTypes[new Guid("идентфикатор_типа")];
CardTransformationCollection trans = type.Transformations;
После применения XSLT-преобразования данные карточки принимают формат XML
или HTML-документа, который впоследствии может быть распечатан. Для применения
XSLT-преобразования можно воспользоваться стандартными методами XML-парсера:
// получение XML карточки
CardData card = session.CardManager.GetCardData(new
System.Guid("идентификатор_карточки"));
MemoryStream stream = new MemoryStream();
card.SaveXml(stream);
stream.Position = 0;
XmlDocument cardXML = new XmlDocument();
cardXML.Load(stream);
// получение шаблона печати
CardType type = session.CardManager.CardTypes[new Guid("идентфикатор_типа")];
CardTransformation trans = type.Transformations[0];
// создание трансформации
XmlDocument transformXML = new XmlDocument();
transformXML.LoadXml(trans.Data.ToString());
XslCompiledTransform XSLTransform = new XslCompiledTransform();
XSLTransform.Load((IXPathNavigable)transformXML);
// применение преобразования
System.Text.StringBuilder builder = new System.Text.StringBuilder();
XmlWriter HTML = XmlWriter.Create(builder);
XSLTransform.Transform((IXPathNavigable)cardXML, HTML);
Собственно печать может быть выполнена при помощи любого внешнего
приложения (например, Microsoft Internet Explorer или Microsoft Word). В .NETприложении можно воспользоваться для этих целей стандартным элементом
управления WebBrowser.
DocsVision 4.5: Руководство разработчика на платформе
141
4.12 РАБОТА С ПРАВАМИ
4.12.1 Администрирование прав
Система позволяет назначать права на отдельные объекты, для чего используется
система безопасности Windows, основанная на пользователях и группах (доменных или
локальных) и описателях прав (дескрипторах).
Право дается или запрещается пользователю при помощи объекта ACE (access
control entry), который задает маску прав. Права могут быть даны (allowed) или
запрещены (denied) конкретному пользователю или группе (security principal). ACE
объединяются в список ACL (access control list). DACL (discretionary access control list)
хранится в описателе прав (security descriptor), в котором, кроме списка DACL, есть еще
информация о владельце объекта (owner), а также настройки аудита в виде списка
SACL (system access control list). Кроме того, начиная с версии 4.3, поддерживается
использование в дескрипторе метки уровня доступа (mandatory access control, MAC).
ПРИМЕЧАНИЕ
В текущей версии платформы аудит не поддерживается и будет реализован
в одной из ближайших версий.
Права, которые можно настраивать на объектах, делятся на общие (general),
которые отображаются в главном диалоге настройки безопасности; и специфические
(specific), которые появляются в списке в окне Advanced. Общие права используются
для упрощения администрирования. Специфические права дают администратору
возможность управлять поведением объектов на более тонком уровне.
Общие права (AccessGeneral) состоят из набора частных прав:
Чтение (R, RP);
Изменение (W, CC, DC);
Удаление (D);
Полный доступ (все права).
Специфические права (AccessSpecific):
Чтение данных объекта (R);
Изменение данных объекта (W);
Создание дочерних объектов (CC);
Удаление дочерних объектов (DC);
Удаление объекта (D);
Чтение разрешений (RP);
Изменение разрешений (SP);
Смена владельца (TO).
Система позволяет назначать права на все низкоуровневые объекты:
Типы карточек;
Карточки;
Секции;
Строки;
Файлы;
Хранимые процедуры;
Пользовательские объекты
Значения битовых флагов стандартных прав приведены в таблице:
DocsVision 4.5: Руководство разработчика на платформе
142
Описание прав
Маска
Расшифровка
Полный доступ
0x000F001F
Получена сложением прав доступа:
Чтение данных объекта, Изменение
данных объекта, Создание дочерних
объектов, Удаление дочерних
объектов, Копирование объекта,
Удаление объекта, Чтение
разрешений, Изменение разрешений,
Смена владельца
Чтение данных объекта
0x00000001
Изменение данных объекта
0x00000002
Создание дочерних
объектов
0x00000004
Удаление дочерних
объектов
0x00000008
Копирование объекта
0x00000010
Удаление объекта
0x00010000
Чтение разрешений
0x00020000
Изменение разрешений
0x00040000
Смена владельца
0x00080000
Чтение
0x 00020001
Получена сложением прав: Чтение
данных объекта, Чтение разрешений
Изменение
0x 0000001E
Получена сложением прав: Изменение
данных объекта, Создание дочерних
объектов, Удаление дочерних
объектов, Копирование объекта
Владение
0x 000C0000
Получена сложением прав: Изменение
разрешений, Смена владельца
В системе реализовано наследование прав от родительских к дочерним объектам
следующим образом:
карточка наследует права от других карточек, которые держат на данную карточку
сильные ссылки (физически от строки, в которой содержится ссылка). При
установке первой сильной ссылки на карточку её права меняются, чтобы отразить
включившееся наследование. При изменении прав на родительскую карточку права
на подчинённую карточку меняются соответственно;
секция карточки наследует от экземпляра карточки, которому он принадлежит, или
от родительской строки (если это подчинённая секция);
строка наследует права от своей секции;
файл наследует от карточки владельца, если она задана.
Частным, но важным случаем является наследование прав от папки на карточку.
Папка — это строка в карточке папок — от неё права наследуют все ярлыки в папке.
По сильным ярлыкам права переходят на карточки. Таким образом, права на карточки,
на которые существуют сильные ярлыки, наследуются от карточки папок. В Навигаторе
права на карточку папок могут быть отредактированы на узле «Папки».
Наследованием прав можно управлять
определяющих порядок наследования:
при
помощи
специальных
флагов,
ContainerInheritAce – права распространяются на дочерние контейнеры;
DocsVision 4.5: Руководство разработчика на платформе
143
ObjectInheritAce – права распространяются на дочерние объекты;
InheritOnlyAce – права распространяются только на потомков, но не на сам
объект.
Таким образом, возможные сочетания этих флагов определяют многообразие
типов наследования прав:
Кто наследует
Сочетание флагов
Этот объект, дочерние контейнеры и объекты
ContainerInheritAce
ObjectInheritAce
Этот объект и дочерние контейнеры
ContainerInheritAce
Этот объект и дочерние объекты (не контейнеры)
ObjectInheritAce
Только дочерние контейнеры и объекты
ContainerInheritAce
ObjectInheritAce
InheritOnlyAce
Только дочерние контейнеры
ContainerInheritAce
InheritOnlyAce
Только дочерние объекты (не контейнеры)
ObjectInheritAce
InheritOnlyAce
Только этот объект
ПРИМЕЧАНИЕ
ВСЕ стандартные объекты системы (карточки, секции, строки) являются
КОНТЕЙНЕРАМИ и именно в таком качестве рассматриваются при наследовании
прав.
4.12.2 Программное назначение прав
Как уже сказано выше, работу с правами поддерживают следующие объекты
системы:
CardType (тип карточки)
CardData (данные карточки)
SectionData (данные секции)
RowData (данные строки)
FileData (файл)
Report (хранимая процедура)
Для этого в каждом из этих объектов предусмотрено два специальных метода:
GetAccessControl() – получает описатель прав на объект
SetAccessControl(…) – устанавливает права на объект
Так как у этих объектов разные схемы прав, то в зависимости от типа объекта эти
методы оперируют соответствующими классами-обертками для работы с правами:
DocsVision.Platform.Security.AccessControl.CardDataSecurity
карточку, тип карточки, секцию, строку
DocsVision.Platform.Security.AccessControl.FileDataSecurity - права на файл
DocsVision 4.5: Руководство разработчика на платформе
–
права
на
144
DocsVision.Platform.Security.AccessControl.ReportSecurity - права на хранимую
процедуру
Все эти объекты расположены в специальном пространстве имен DocsVision.Platform.Security.AccessControl, которое реализовано в отдельной сборке DocsVision.Platform.dll. Поэтому для работы с безопасностью, эту сборку следует
предварительно подключить к своему проекту (references); а также задекларировать
использование пространства имен:
using DocsVision.Platform.Security.AccessControl;
Классы для работы с правами карточек, файлов, и хранимых процедур
унаследованы от базового класса
DocsVision.Platform.Security.AccessControl.DVObjectSecurity, который содержит основные
механизмы для работы с правами. Кроме этого, каждый из них содержит ряд
специфических свойств, характерных именно для данного объекта (схемы прав). Этот
класс по сути дела описывает дескриптор (SD), и включает в себя методы для работы с
разрешениями (ACE), аудитами, и другими свойствами дескриптора.
Рассмотрим основые свойства и методы объекта для работы с правами на примере
CardDataSecurity:
System.Type AccessRightType – тип объекта-описателя прав
System.Type AccessRuleType – тип объекта-разрешения
System.Type AuditRuleType – тип объекта аудита
System.Security.AccessControl.AccessRule
AccessRuleFactory(System.Security.Principal.IdentityReference identityReference, int
accessMask, bool isInherited, System.Security.AccessControl.InheritanceFlags inheritanceFlags,
System.Security.AccessControl.PropagationFlags propagationFlags,
System.Security.AccessControl.AccessControlType type) – создание нового разрешения на
объект:
o
identityReference – субъект, для которого создается разрешение
o
accessMask – маска прав
o
isInherited – признак унаследованного разрешения
o
inheritanceFlags – флаги дальнейшего наследования данноо разрешения
o
propagationFlags – флаги распространения данного разрешения
o
type – тип разрешения
AddAccessRule(DocsVision.Platform.Security.AccessControl.CardDataAccessRule
добавляет новое разрешение на объект
AddAuditRule(DocsVision.Platform.Security.AccessControl.CardDataAuditRule
добавляет аудит на объект
System.Security.AccessControl.AuditRule
AuditRuleFactory(System.Security.Principal.IdentityReference
identityReference,
int
accessMask, bool isInherited, System.Security.AccessControl.InheritanceFlags inheritanceFlags,
System.Security.AccessControl.PropagationFlags
propagationFlags,
System.Security.AccessControl.AuditFlags auditFlags) – создание нового аудита (параметры
аналогичны вышеописанному методу, за исключением auditFlags)
CardDataSecurity(DocsVision.Platform.Security.AccessControl.SecureObjectType objectType,
byte[] binaryForm) – инициализирует описатель прав из потока байт
CardDataSecurity(DocsVision.Platform.Security.AccessControl.SecureObjectType objectType)
– создает новый (пустой) описатель прав
DocsVision 4.5: Руководство разработчика на платформе
rule)
rule)
–
–
145
RemoveAccessRule(DocsVision.Platform.Security.AccessControl.CardDataAccessRule rule) –
удаляет разрешение из описателя прав
RemoveAccessRuleAll(DocsVision.Platform.Security.AccessControl.CardDataAccessRule rule)
– удаляет все разрешения для данного субъекта из описателя прав
RemoveAccessRuleSpecific(DocsVision.Platform.Security.AccessControl.CardDataAccessRul
e rule) – удаляет специфическое разрешение из описателя прав (учитываются все признаки
разрешения)
RemoveAuditRule(DocsVision.Platform.Security.AccessControl.CardDataAuditRule
удаляет конкретный аудит из описателя прав
RemoveAuditRuleAll(DocsVision.Platform.Security.AccessControl.CardDataAuditRule rule) –
удаляет все аудиты для данного субъекта из описателя прав
RemoveAuditRuleSpecific(DocsVision.Platform.Security.AccessControl.CardDataAuditRule
rule) – удаляет специфический аудит из описателя прав (учитываются все признаки аудита)
ResetAccessRule(System.Security.AccessControl.AccessRule
rule)
–
удаляет
все
НЕунаследованные разрешения объекта, и добавляет одно новое – переданное в качестве
параметра
SetAccessRule(System.Security.AccessControl.AccessRule rule) – удаляет из описателя прав
все разрешения для данного субъекта, и добавляет вместо них одно новое – переданное в
качестве параметра
SetAuditRule(System.Security.AccessControl.AuditRule rule) – удаляет из описателя прав все
аудиты для данного субъекта, и добавляет вместо них одно новое – переданное в качестве
параметра
rule)
-
Кроме вышеописанных, могут быть полезны некоторые свойства и методы,
унаследованные от базового класса System.Security.AccessControl.ObjectSecurity:
System.Security.Principal.IdentityReference
получает владельца прав на объект
GetOwner(System.Type
targetType)
–
SetOwner(System.Security.Principal.IdentityReference identity) – устанавливает нового
владельца прав
bool OwnerModified - признак что владелец изменен
ПРИМЕЧАНИЕ
Описания
остальных
свойств
и
методов
класса
System.Security.AccessControl.ObjectSecurity и способов работы с ним можно найти в
MSDN.
Отдельное разрешение (ACE) на объект описывается собственным классом:
DocsVision.Platform.Security.AccessControl.CardDataAccessRule – разрешение на карточку
DocsVision.Platform.Security.AccessControl.FileDataAccessRule – разрешение на файл
DocsVision.Platform.Security.AccessControl.ReporAccessRule – разрешение на хранимую
процедуру
Каждый из этих классов содержит одно значимое свойство AccessRights, которое
и определяет права на объект:
CardDataRights – права на карточку:
o
ChangePermissions – изменение разрешений
o
Copy – копирование
o
CreateChildObjects – создание дочерних объектов
DocsVision 4.5: Руководство разработчика на платформе
146
o
Delete – удаление объекта
o
DeleteChildObjects – удаление дочерних объектов
o
FullControl – полный доступ (совокупное право)
o
Modify – изменение (совокупное право)
o
Own –владение (совокупное право)
o
Read – чтение (совокупное право)
o
ReadData – чтение данных объекта
o
ReadPermissions – чтение разрешений
o
TakeOwnership – смена владельца
o
WriteData – изменение данных объекта
FileDataRights – права на файл:
o
ChangePermissions – изменение разрешений
o
Copy – копирование
o
Delete – удаление объекта
o
FullControl – полный доступ (совокупное право)
o
Modify – изменение (совокупное право)
o
Own –владение (совокупное право)
o
Read – чтение (совокупное право)
o
ReadData – чтение данных объекта
o
ReadPermissions – чтение разрешений
o
TakeOwnership – смена владельца
o
WriteData – изменение данных объекта
ReportRights – права на хранимую процедуру:
o
ChangePermissions – изменение разрешений
o
FullControl – полный доступ (совокупное право)
o
Own –владение (совокупное право)
o
Read – чтение (совокупное право)
o
ReadData – чтение данных объекта
o
ReadPermissions – чтение разрешений
o
TakeOwnership – смена владельца
Все классы для работы с разрешениями объектов DocsVision унаследованы от базового
System.Security.AccessControl.AuthorizationRule который имеет следующие важные свойства:
int AccessMask – битовая маска прав
System.Security.Principal.IdentityReference
(пользователь, группа)
System.Security.AccessControl.InheritanceFlags InheritanceFlags – флаги наследования
разрешения:
o
IdentityReference
–
субъект
прав
InheritanceFlags.None – не наследуюется
DocsVision 4.5: Руководство разработчика на платформе
147
o
InheritanceFlags.ObjectInherit – наследуют дочерние объекты
o
InheritanceFlags.ContainerInherit – наследуют дочерние контейнеры
bool IsInherited – признак, является ли разрешение унаследованным (только для чтения)
System.Security.AccessControl.PropagationFlags
распространения разрешений на дочерние объекты:
PropagationFlags
–
флаги
o
PropagationFlags.None – не указано
o
PropagationFlags. InheritOnly – распространять на дочерние объекты и контейнеры
o
PropagationFlags. NoPropagateInherit – не распространять на дочерние объекты и
контейнеры
Общий алгоритм работы с правами
сформулировать следующим образом:
в
рамках
данной
модели
можно
1) Для добавления нового разрешения на карточку (файл, процедуру):
a. Получить
объект
для
(CardData.GetAccessControl)
b. Создать новое
атрибутами
разрешение
c. Добавить
разрешение
SetAcccessRule)
к
работы
с
(CardDataAccessRule)
описателю
прав
разрешениями
с
необходимыми
(AddAccessRule
или
d. Сохранить измененный описатель прав (SetAccessControl)
// Получение с сервера данных карточки с известным идентификатором
CardData card = session.CardManager.GetCardData(new
System.Guid("идентификатор_карточки"));
// Получение описателя прав карточки
CardDataSecurity rights = card.GetAccessControl();
// Создание нового разрешения – совокупного права чтения
CardDataAccessRule rule = new CardDataAccessRule("DOMAIN\\Pupkin",
CardDataRights.Read, AccessControlType.Allow);
// Добавление нового разрешения к описателю прав
rights.SetAccessRule(rule);
// Сохранение измененного описателя прав
card.SetAccessControl(rights);
2) Для удаления разрешения на карточку (файл, процедуру):
a. Получить
объект
для
(CardData.GetAccessControl)
работы
с
разрешениями
b. Удалить разрешения для субъекта:
i. методом PurgeAccessRules, чтобы удалить ВСЕ разрешения для
субъекта
ii. методом RemoveAccessRuleSpecific
разрешение для субъекта
чтобы
iii. методом SetAccessRule чтобы удалить
субъекта и добавить вместо них новое
удалить
все
конкретное
разрешения
для
c. Сохранить измененный описатель прав (SetAccessControl)
// Получение с сервера данных карточки с известным идентификатором
DocsVision 4.5: Руководство разработчика на платформе
148
CardData card = session.CardManager.GetCardData(new
System.Guid("идентификатор_карточки"));
// Получение описателя прав карточки
CardDataSecurity rights = card.GetAccessControl();
// Удаление всех прав пользователя
rights.PurgeAccessRules(new NTAccount("DOMAIN\\Pupkin"));
// Сохранение измененного описателя прав
card.SetAccessControl(rights);
DocsVision 4.5: Руководство разработчика на платформе
149
4.13 ЭЦП И ШИФРОВАНИЕ
Платформа поддерживает базовые возможности наложения электронной
цифровой подписи (ЭЦП) и шифрования для загруженных в неё файлов, а также
произвольных пользовательских объектов.
ПРИМЕЧАНИЕ
Возможности наложить ЭЦП или зашифровать данные карточек (секций, строк) в
данный момент платформой не поддерживаются.
Реализация этой функциональности предоставляет возможности для создания,
чтения и удаления специального типа объектов – крипто-объектов. Выделяются два
типа крипто-объектов (DocsVision.Platform.ObjectManager.CryptObjectType):
CryptObjectType.Signature – подпись;
CryptObjectType.Key – публичный ключ шифрования.
Эти объекты сохраняются в специальной системной таблице (dvsys_crypto) и
привязаны к конкретному объекту системы (файлу), который собственно и был
подписан или зашифрован.
ВНИМАНИЕ
Для файлов, подпись и шифрование которых реализованы в самой платформе,
время жизни связанных крипто-объектов контролируется автоматически. То есть,
например, при удалении файла все наложенные на него подписи также будут
автоматически удалены. Однако, при создании крипто-объектов собственного
типа (не относящихся к файлам) разработчик должен сам контролировать время
их жизни и заботиться об удалении.
Для работы с крипто-объектами в объектой модели предусмотрен ряд методов,
предоставляемых объектом AccessManager:
System.Guid StoreCryptObject(System.Guid objectId,
DocsVision.Platform.ObjectManager.CryptObjectType cryptObjectType, byte[] cryptData, string
accountName, string certThumbprint, System.Guid userId, string description) – сохранение новой
подписи или ключа шифрования. Параметр objectId указывает идентификатор объекта (файла), к
которому относится подпись (ключ), cryptObjectType определяет тип сохранямого криптообъекта; параметр cryptData (поток байт) представляет собственно данные подписи (ключа
шифрования); параметр accountName позволяет дополнительно указать учетную запись
пользователя, который совершил операцию (с этим пользователем будет ассоциирована
наложенная подпись); userId – идентификатор пользователя, от имени которого выполняется
операция (например, если её выполняет заместитель); и description – поясняющий комментарий
(например, «Подпись наложена заместителем»)
DocsVision.Platform.ObjectManager.InfoRowCollection GetCryptObjects(System.Guid objectId,
DocsVision.Platform.ObjectManager.CryptObjectType cryptObjectType, string certThumbprint,
System.Guid userId) – получает список крипто-объектов (cryptObjectType) для конкретного
объекта (файла), идентификатор которого передан в параметре objectId. Метод возвращает
коллекцию нетипизированных данных (InfoRowCollection), по составу полей аналогичную
полям системной таблицы;
byte[] GetCryptObject(System.Guid cryptObjectId) – возвращает данные
подписи/зашифрованного объекта по его собственному идентификатору (полученному при
вызове GetCryptObjects);
DocsVision.Platform.ObjectManager.InfoRowCollection GetCryptObjectInfo(System.Guid
cryptObjectId) – получает дополнительную информацию о крипто-объекте с указанным
идентификатором. Метод возвращает коллекцию нетипизированных данных
(InfoRowCollection), по составу полей аналогичную полям системной таблицы;
DocsVision 4.5: Руководство разработчика на платформе
150
DeleteCryptObject(System.Guid cryptObjectId) – удаляет крипто-объект по его собственному
идентификатору;
DeleteCryptObjects(System.Guid objectId, DocsVision.Platform.ObjectManager.CryptObjectType
cryptObjectType) – удаляет все крипто-объекты типа cryptObjectType для конкретного файла
(objectId).
byte[] GetKey(System.Guid objectId) – получает ключ шифрования объекта
byte[] GetKey(System.Guid objectId, string accountName) - получает ключ шифрования объекта
для конкретного пользователя
System.Guid StoreKey(System.Guid objectId, byte[] keyData) – сохраняет ключ шифрования
объекта
System.Guid StoreKey(System.Guid objectId, byte[] keyData, string accountName) – сохраняет
ключ шифрования объекта для конкретного пользователя
System.Guid StoreSignature(System.Guid objectId, byte[] signatureData, string certThumbprint) –
сохраняет подпись объекта
System.Guid StoreSignature(System.Guid objectId, byte[] signatureData, string certThumbprint,
System.Guid userId, string description) – сохраняет подпись объекта с дополнительным
описанием
Пример: получение списка подписей файла
FileData file = session.FileManager.GetFile(new Guid("идентификатор_файла"));
InfoRowCollection coll = session.AccessManager.GetCryptObjects(file.Id,
CryptObjectType.Signature);
foreach (InfoRow cryptrow in coll)
{
MessageBox.Show("Файл подписан " + cryptrow["CreationDate"].ToString() + "
пользователем " + cryptrow["AccountName"].ToString());
}
Все эти методы позволяют оперировать уже готовыми крипто-объектами, а
выполнение самих операций подписи/шифрования при этом должно выполняться
другими средствами – например, при помощи библиотеки System.Security.Cryptography
для .NET Framework.
ПРИМЕЧАНИЕ
При выполнении операций подписи или шифрования можно использовать
текущие системные настройки криптографии, заданные в справочнике настроек
(к их числу относятся крипто-провайдер, алгоритм, длина ключа и т.д.).
DocsVision 4.5: Руководство разработчика на платформе
151
4.14 ЖУРНАЛИРОВАНИЕ
Функциональность журналирования обеспечивает единый механизм для фиксации
всех операций, производимых в системе, и возможность их последующего анализа.
Каждая запись в журнале может относиться к одному из следующих типов:
Информация;
Предупреждение;
Аудит;
Ошибка.
Весь журнал DocsVision разбит на три разных части:
Система – записи в этом журнале фиксирует сервер DocsVIsion. Сюда
могут попадать как ошибки, так и аудит низкоуровневых операций,
выполняемых сервером DocsVision
Безопасность – в этом журнале фиксируются результаты аудит операций
над объектами, для которых он явно настроен
Приложения – в этот журнал попадают операции, фиксируемые
конкртеными приложениями (Делопроизводство, Управление процессами, и
т.д.). Сюда же попадают все сообщения от решений стронних
разработчиков.
В системном журнале (Система)
низкоуровевые операции сервера:
автоматически
фиксируются
следующие
Операции с карточками:
o Создание карточки;
o Пометка карточки как удаленной;
o Пометка карточки как прочитанной;
o Удаление карточки;
o Копирование карточки;
o Изменение прав карточки;
o Добавление карточки к теме обработки;
o Архивирование карточки;
o Разархивирование карточки;
o Открытие карточки (если оно производилось из Навигатора);
o Экспорт карточки (если он производился из Навигатора);
Операции со строками:
o Добавление строки;
o Обновление строки;
o Удаление строки;
o Перемещение строки;
o Копирование строки;
o Изменение прав доступа к строке;
Безопасность:
o Изменение прав доступа к строке;
o Изменение прав доступа к карточке;
o Изменение прав доступа к файлу;
o Изменение прав доступа к элементу;
o Изменение прав доступа к отчету;
o Изменение прав доступа к типам карточек;
Операции с файлами:
o Создание файла;
o Открытие файла;
o Запись в файл;
o Закрытие файла;
DocsVision 4.5: Руководство разработчика на платформе
152
o Удаление файла;
o Изменение прав доступа к файлу;
o Копирование файла;
o Замена файла;
o Выгрузка файла из базы данных;
o Загрузка файла в базу данных;
o Архивирование файла;
o Разархивирование файла;
Операции с нумераторами:
o Изменение левой границы нумератора;
o Изменение правой границы нумератора;
o Выделение номера;
o Выделение диапазона номеров;
o Освобождение номера;
o Освобождение диапазона номеров;
Операции с ярлыками:
o Создание ярлыка;
o Удаление ярлыка;
o Перемещение ярлыка;
o Копирование ярлыка.
Разработчику на платформе доступны следующие возможности при работе с
журналом (все они требуют наличия административных привилегий для
выполнения):
получение определённого набора записей из журнала по фильтру;
поиск конкретной записи в журнале;
удаление записей из журнала;
изменение стратегии автоматической очистки журнала;
экспорт и импорт записей журнала в формат XML.
Кроме этого, программно доступна возможность фиксировать в журнале
собственные операции (для этого административные привилегии не требуются). Эти
записи могут быть любого типа (отладочные и информационные сообщения,
предупреждения); и их характер зависит от семантики конкретной ситуации.
Разработчики карточек могут расширять набор журналируемых операций, для
этого в редакторе библиотеки CardManager на вкладке Log необходимо определить
новые операции, указать их идентификатор, псевдоним и имя:
DocsVision 4.5: Руководство разработчика на платформе
153
Рис. 4.6. Определение операций журнала
Дополнительные атрибуты операций (Columns) определяются там же,
необходимо указать их псевдоним, тип данных и имя. Колонку можно ассоциировать с
какой-либо операций или указать, что она обязательна для всех операций данной
библиотеки.
При записи Custom-сообщения в журнал приложение должно сформировать xmlдокумент по схеме EventData.xsd и сохранить там все дополнительные атрибуты. В
следующих версиях платформы по этим атрибутам можно будет выводить в таблицу
сообщений, по ним появится возможность поиска.
Для работы с журналом предназначен специальный объект LogManager, доступ к
которому можно получить из объекта сессии (UserSession).
4.14.1 Стратегия журнала
Узнать общую стратегию ведения журнала
LogStrategy, которое может иметь одно из значений:
можно
при
помощи
свойства
LogStrategy.NoLogging – не вести журнал;
LogStrategy.Filtered – журналировать только определённые сообщения;
LogStrategy.Everything – журналировать всё.
Аналогичное
очистки журнала:
свойство
ClearLogStrategy
определяет
стратегию
DocsVision 4.5: Руководство разработчика на платформе
автоматической
154
ClearLogStrategy.Never – никогда не очищать журнал;
ClearLogStrategy.ByCount – очищать при превышении количества записей;
ClearLogStrategy.ByDate – очищать при превышении времени хранения.
Подробности стратегии очистки описывают свойства ClearLogCutCount (количество
записей, которое должно оставаться в журнале после очистки); ClearLogMaxCutCount
(максимальное количество записей в журнале при стратегии ClearLogStrategy.ByCount) и
ClearLogCutDays
(максимальное
время
хранения
в
журнале
при
стратегии
ClearLogStrategy.ByDate).
Все эти свойства доступны только для чтения, а изменить стратегии работы с
журналом можно только при помощи специального метода:
SetLogStrategy(Strategy As LogStrategyEnum, ClearStrategy As ClearLogStrategyEnum,
ClearLogMaxCount As Long, ClearLogCutCount As Long, ClearLogCutDays As Long).
В параметрах метода передаются новые значения стратегий и их настроек.
4.14.2 Запись в журнал
Для записи собственного сообщения в журнал, необходимо воспользоваться
методом:
LogMessage(DocsVision.Platform.ObjectManager.EventType eventType, int eventOperation, string
resourceName, System.Guid resourceId, System.Guid typeId, System.Guid parentId, string eventData)
Параметры метода:
eventType – тип записи:
EventType.Error – ошибка;
EventType.Information – информация;
EventType.Warning – предупреждение;
EventType.Audit – аудит;
eventOperation – код операции. Может быть либо одним из стандартных кодов
операций; либо собственной операцией (код 0).
resourceName – имя объекта, с которым произведена операция (формируется в
зависимости от контекста – например, при операциях с карточкой это может быть её
описание);
resourceId – идентификатор объекта, с которым производится операция (ID карточки,
строки, файла и т.д.);
typeId (необязательный параметр) – тип объекта (например, для карточки –
CardTypeID);
parentId (необязательный параметр) – идентификатор родительского объекта
(например, для операции со строкой – родительским объектом будет секция);
eventData (необязательный параметр) – любые дополнительные данные, связанные с
событием.
Пример кода записи собственного сообщения в журнал:
session.LogManager.LogMessage(EventType.Information,
0,
data.ID, Guid.Empty, Guid.Empty, "Добавлен исполнитель");
"Моя
карточка",
Вот как будет выглядеть такое сообщение в стандартном диалоге просмотра
журнала:
Тип сообщения: Информация.
Операция: Не определено.
Код: 0.
DocsVision 4.5: Руководство разработчика на платформе
155
Имя ресурса: Моя карточка.
Идентификатор ресурса: {1EA06712-EBB1-4E33-B2E2-6A4AD05991E5}.
Идентификатор типа ресурса: <Неизвестный идентификатор>.
Идентификатор родительского объекта: <Неизвестный идентификатор>.
Новый идентификатор: <Неизвестный идентификатор>.
Данные сообщения: Добавлен исполнитель.
Начиная с версии DocsVision 4.5, появился новый метод для записи в журнал
приложений:
void LogMessageEx(DocsVision.Platform.ObjectManager.EventType eventType, System.Guid
eventOperation, string resourceName, System.Guid resourceId, System.Guid typeId, System.Guid
parentId, string eventData)
Параметры метода аналогичны предыдущему, за исключением eventOperation – здесь это
идентификатор соответствующей операции из описания библиотеки карточек.
4.14.3 Получение сообщений
Для получения данных из журнала, обычно используется метод:
DocsVision.Platform.ObjectManager.InfoRowCollection
FindMessages(DocsVision.Platform.ObjectManager.LogSearchQuery searchQuery)
Параметр метода LogSearchQuery позволяет сформировать фильтр, по которому
будут выбираться сообщения.
ПРИМЕЧАНИЕ
Так как журнал часто содержит большое количество записей, получение данных
из него может занять длительное время. Поэтому рекомендуется максимально
специфицировать параметры фильтра, чтобы минимизировать число получаемых
сообщений.
Фильтр формируется из следующих параметров:
string AccountName – учетная запись пользователя, выполнявшего операцию;
System.Guid ObjectId
операция;
–
идентфикатор
объекта,
с
которым
была
совершена
System.Guid TypeId - тип объекта (например, для карточки – CardTypeID);
System.Guid ParentId - идентификатор родительского объекта (например, для
операции со строкой – родительским объектом будет секция);
DocsVision.Platform.ObjectManager.EventType EventType – тип сообщений
int OperationAfter, int OperationBefore – диапазон кодов операций. Так как коды
операция являются последовательными числами, то можно задать промежуток
OperationAfter < Код операции < OperationBefore;
System.DateTime CreatedAfter, System.DateTime CreatedBefore – границы временного
промежутка, в который должны попадать удаляемые записи DateAfter < Дата
операции < DateBefore.
На
выходе
метод
возвращает
коллекцию
InfoRowCollection со следующим составом полей:
нетипизированных
данных
ID – идентификатор сообщения в журнале;
ResourceID - идентификатор объекта;
TypeID – тип объекта;
ParentID – идентификатор родительского объекта;
DocsVision 4.5: Руководство разработчика на платформе
156
Date – дата операции;
Type – тип операции;
Operation – код операции;
Data – дополнительная информация.
Пример кода – получение всех сообщений об операциях с конкретной карточкой:
LogSearchQuery search = new LogSearchQuery();
search.ObjectId = new Guid("идентификатор_карточки");
InfoRowCollection messages = session.LogManager.FindMessages(search);
foreach(InfoRow row in messages)
{
System.Diagnostics.Debug.Print("Дата: " + row["Date"].ToString() + ";
сообщение:" + row["Data"].ToString());
}
Детали конкретного сообщения можно получить при помощи методов:
DocsVision.Platform.ObjectManager.InfoRowCollection GetMessage(int messageId)
string GetMessageDetails(int messageId)
Оба метода возвращают подробную информацию о конкретном сообщении из
журнала, идентификатор которого передан в качестве параметра. Разница между этими
методами заключается в типе возвращаемых данных – первый метод возвращает все
данные сообщения в виде набора полей (InfoRowCollection), а второй – только
информационную часть сообщения (Data).
Еще одним способом получить сообщения из журнала является поиск. Для этого
предназначен метод:
DocsVision.Platform.ObjectManager.InfoRowCollection FindMessages(string queryXml)
Параметром метода является поисковый запрос для фильтрации сообщений в
формате XML. Поисковый запрос можно построить при помощи стандартного объекта
SectionQuery (подробнее работа с ним описана в соответствующей главе). Нужно только
учитывать, что в качестве секции используется системная таблица dvsys_log; а в
качестве полей – имена её колонок. Условия на эти колонки можно накладывать
стандартным образом, с учетом типа.
В качестве результата метод возвращает коллекцию нетипизированных данных
InfoRowCollection, поля которой соответствуют полям системного журнала (dvsys_log).
Пример получения сообщений с использованием поиска:
// Построение запроса по условию "Данные сообщения содержат подстроку..."
SectionQuery query = session.CreateSectionQuery();
query.ConditionGroup.Conditions.AddNew("Data", FieldType.Unistring,
ConditionOperation.Contains, "исполнитель");
// Выполнение запроса
InfoRowCollection messages = session.LogManager.FindMessages(query.GetXml());
4.14.4 Удаление сообщений
Для удаления сообщений их журнала используется метод:
DeleteMessages(DocsVision.Platform.ObjectManager.LogSearchQuery searchQuery)
Параметр метода позволяют сформировать фильтр, по которому будут удаляться
сообщения. Состав и назначение параметров фильтра аналогично чтению сообщений
(GetMessages).
DocsVision 4.5: Руководство разработчика на платформе
157
Пример кода - удаление из журнала всех записей за текущий день:
LogSearchQuery search = new LogSearchQuery();
search.CreatedAfter = DateTime.Now.Subtract(new TimeSpan(1, 0, 0, 0));
session.LogManager.DeleteMessages(search);
4.14.5 Экспорт и импорт журнала
Записи журнала могут быть экспортированы в формат XML или загружены обратно
из XML-файла.
Для экспорта сообщений, используется метод string ExportMessages(string queryXml)
В качестве параметра метода указывается сформированная строка поискового
запроса для фильтрации сообщений (описана выше). Метод возвращает полученные
сообщения в виде строки XML, которую впоследствии можно сохранить в файл.
Обратный ему метод для импорта сообщений:
DocsVision.Platform.ObjectManager.InfoRowCollection ImportMessages(string xml)
На вход метода передается строка в формате XML, содержащая ранее
экспортированные записи журнала; на выходе метод возвращает коллекцию
нетипизированных данных InfoRowCollection, поля которой соответствуют полям
системного журнала (dvsys_log).
ВНИМАНИЕ
При импорте сообщения журнала загружаются только в память клиентского
приложения для последующей обработки и НЕ сохраняются в текущий журнал
сервера.
4.15 РАБОТА С ПРЕДСТАВЛЕНИЯМИ
Механизм представлений является частью функциональности платформы,
предназначенной для построения отчётов. Этот механизм предоставляет возможность
получать произвольные выборки данных, описывая их структуру при помощи
визуального редактора, и отображать полученные результаты в пользовательском
интерфейсе Навигатора, с возможностью их форматирования (подсветки, группировки
и так далее).
Можно выделить две основные задачи, которые разработчик на платформе может
решать с использованием представлений:
программное создание новых описаний представлений, которые затем будут
доступны пользователям в интерфейсе Навигатора;
получение данных конкретного представления, на основании уже имеющегося
описания; и их последующая обработка.
ПРИМЕЧАНИЕ
В частности, в ряде случаев использование представлений эффективно также для
повышения производительности работы решения. Например, если нужно
получить большую выборку данных (карточек) со сложной структурой
взаимосвязей, то вместо использования нескольких поисковых запросов, будет
более эффективно получить данные одним вызовом представления.
При работе с представлениями, имеет смысл оперировать такими понятиями, как
описание представления (это схема, которая определяет принципы выборки данных с
конкретной структурой) и данные представления (это результат применения запроса,
сгенерированного на основании описания, к конкретной базе данных в конкретный
момент времени). Очевидно, что на основании одного описания, можно произвольное
DocsVision 4.5: Руководство разработчика на платформе
158
количество раз получать данные, которые будут иметь одинаковую структуру (число и
состав столбцов), но разное содержание (число и состав строк).
В свою очередь, каждое описание представления разделено на две логические
части:
описание (схема) данных – эта часть определяет, какие именно данные и каким
способом необходимо выбрать из базы данных. Это описание в формате XML
физически хранится в специальной системной карточке сохраненных представлений
(SavedViewCard). При каждом изменении этой схемы происходит автоматическая
генерация хранимых процедур в БД, которые предназначены для получения
собственно
данных
(эти
процедуры
имеют
имена
dvview_get_data_{ID_представления});
описание форматирования – эта часть определяет, как именно полученные данные
нужно показать в пользовательском интерфейсе (имена и порядок колонок,
группировки, сортировки и т.д.). Это описание является частью другой системной
карточки – Навигатора (NavigatorCard) и хранится в специальной её секции
ViewSettings;
Такой принцип разграничения сущности данных от их визуализации потенциально
позволяет реализовать и другие формы отображения для одних и тех же данных. К
примеру, штатным способом данные представления можно просматривать в Навигаторе
(и поэтому он хранит собственное описание форматирования данных); однако
потенциально возможно реализовать другой клиент (например, для мобильных
устройств), который будет отображать те же данные в другом формате (с учетом
ограничений мобильных устройств).
4.15.1 Описание (схема) данных представления
Как уже было сказано выше, описание данных представления хранится в
специальной системной карточке и представляет собой XML-документ (также как схемы
карточек и библиотек).
Однако, работать с этим описанием, оперируя непосредственно узлами и
атрибутами XML-документа, было бы слишком сложно и неудобно. Поэтому в объектной
модели системы предусмотрен ряд специальных объектов, которые позволяют работать
с описанием представления уже на уровне семантических объектов (полей карточек,
операций с ними), что существенно упрощает взаимодействие с ними. Базовым
объектом в этой модели является объект View.
Этот объект является создаваемым (например, его можно создать при добавлении
в систему нового описания представления). Также он может быть проинициализирован
на основании существующего описания представления, сохраненного в карточке
ViewCard.
Для
загрузки
существующего
описания
представления
используется
вспомогательный объект SavedView (сохраненное описание представления), который
можно получить из карточки сохраненных представлений (ViewCard). Эта карточка (как
и все остальные системные карточки) имеет собственную объектную модель,
расположенную в пространстве имен DocsVision.Platform.ObjectManager.SystemCards.
Карточка сохраненных представлений
экземпляр всегда можно получить:
является
справочником,
DocsVision 4.5: Руководство разработчика на платформе
поэтому
ее
159
const string VIEW_CARD_ID = "17F8F0B3-7E93-45E9-B250-EED4E93F3FA3";
ViewCard vcard = (ViewCard)session.CardManager.GetDictionary(new
Guid(VIEW_CARD_ID));
Объектная модель карточки
следующие свойства и методы:
сохраненных
представлений
(ViewCard)
имеет
DocsVision.Platform.ObjectManager.SystemCards.SavedViewCollection Views – доступ к
коллекции сохраненных описаний представлений;
DocsVision.Platform.ObjectManager.SystemCards.SavedViewGroupCollection Groups – доступ к
коллекции групп представлений;
DocsVision.Platform.ObjectManager.SystemCards.SavedViewGroup CreateGroup(System.Guid
parentGroupId, string name) – создание новой подгруппы у родителя parentGroupId с именем
name
DocsVision.Platform.ObjectManager.SystemCards.SavedViewGroup GetGroup(System.Guid
groupId) – получение группы с идентификатором groupId
bool GroupExists(System.Guid groupId) – проверка существования группы с идентификатором
groupId
DeleteGroup(System.Guid groupId) – удаление группы с идентификатором groupId
DocsVision.Platform.ObjectManager.SystemCards.SavedView GetView(System.Guid viewId) получение представления с идентификатором viewed
bool ViewExists(System.Guid viewId) - проверка существования представления с
идентификатором viewId
DeleteView(System.Guid viewId) – удаление представления с идентификатором viewed
DocsVision.Platform.ObjectManager.SystemCards.SavedVirtualFieldCollection
GetVirtualFields(System.Guid sectionId) – получение коллекции сохраненных описаний
виртуальных полей для секции типа sectionId
Коллекция сохраненных представлений (ViewCard.Views) позволяет создавать
новые элементы (AddNew), удалять существующие (Remove) и получить конкретный
элемент по идентификатору (Item).
Элементами коллекции являются объекты SavedView, олицетворяющие собой XMLописания представлений. Свойства и методы объекта SavedView:
System.Guid Id – идентификатор представления;
string Name – название представления (его будут видеть пользователи);
string Comments – дополнительное описание (комментарий)
string Text – XML-описание представления в виде строки;
DocsVision.Platform.ObjectManager.ViewModel.View Export() – позволяет получить объект
View, для удобной работы с описание представления;
Import(DocsVision.Platform.ObjectManager.ViewModel.View view) – позволяет получить XMLописание на основании объекта View;
Publish() – этод метод инициирует безусловную генерацию хранимых процедур для получения
данных представления (их необходимо перегенерировать при каждом изменении описания
представления);
Revoke() – удаление хранимых процедур представления в БД.
Пример работы с сохраненным представлением и получение объекта View:
DocsVision 4.5: Руководство разработчика на платформе
160
const string VIEW_CARD_ID = "17F8F0B3-7E93-45E9-B250-EED4E93F3FA3";
ViewCard vcard = (ViewCard)session.CardManager.GetDictionary(new
Guid(VIEW_CARD_ID));
SavedView sview = vcard.Views[0];
DocsVision.Platform.ObjectManager.ViewModel.View view = sview.Export();
Наконец, объект View уже можно использовать для
редактирования описания представления. Объект View содержит:
непосредственного
коллекцию Columns — набор колонок, в который будут попадать данные от карточек;
коллекцию Elements — позволяет задать источники данных для колонок;
коллекцию Sorting — позволяет задать правила сортировок данных в колонках представления;
коллекцию Parameters — позволяет указать значения параметров представления;
методы GetXml()и ParseXml(string viewXml)– для загрузки или выгрузки описания
представления в формате XML.
метод DocsVision.Platform.ObjectManager.QueryParameterCollection
GetResolvedParameters(DocsVision.Platform.ObjectManager.UserSession session) для
разрешения значений поисковых слов (“Я”. “Руководитель”, ”Сегодня” и т.д.)
Объекты ViewColumn (колонка представления), ViewSorting (сортировка) и
QueryParameter (параметр представления) достаточно просты, и не требуют
дополнительных пояснений. Основной интерес вызывает объект ViewElement, который
описывает собственно источники данных для колонок. Представление может
объединять данные из нескольких разнородных источников (типов карточек) – в этом
случае их строки просто будут последовательно выводиться друг за другом при условии
совпадения количества и типов колонок.
Каждый элемент представления (ViewElement) содержит:
System.Guid SectionId – определяет идентификатор секции карточки, которая будет взята за
«основу» элемента (обычно это та секция, в которой в представлении фигурирует максимальное
число полей);
bool SkipInstanceLimit – позволяет отключить ограничение по экземплярам карточек (то есть в
представление будет выведено столько строк по каждой карточке, сколько строк её секции
попадает под условия);
DocsVision 4.5: Руководство разработчика на платформе
161
DocsVision.Platform.ObjectManager.ViewModel.SectionFieldCollection SectionFields —
позволяет задать набор физических полей секций, которые будут участвовать в представлении;
DocsVision.Platform.ObjectManager.ViewModel.ComputedFieldCollection ComputedFields —
позволяет задать набор правил для создания вычисляемых полей;
DocsVision.Platform.ObjectManager.ViewModel.JoinDefinitionCollection JoinDefinitions —
позволяет задать правила присоединения к представлению других секций и таблиц для
выборки данных;
DocsVision.Platform.ObjectManager.ViewModel.DataConditionGroup ConditionGroup —
позволяет задать условия для фильтрации результирующего набора данных;
RenameJoinDefinition(string oldAlias, string newAlias) – для переименования присоединенной
секции или таблицы;
DocsVision.Platform.ObjectManager.ViewModel.VirtualField ExtractVirtualField(string
columnAlias) – позволяет сохранить элемент представления в качестве виртуального поля;
MergeVirtualField(DocsVision.Platform.ObjectManager.ViewModel.VirtualField virtualField,
string targetSectionAlias, string columnAlias) – позволяет добавить в представление
существующее виртуальное поле.
DocsVision 4.5: Руководство разработчика на платформе
162
Отдельно стоит остановиться на использовании виртуальных полей. Виртуальные
поля представляют собой наборы правил, согласно которым можно извлечь данные из
физических таблиц базы данных – с использованием вычислений, агрегаций,
присоединений и т.д. Определения виртуальных полей привязаны к конкретному типу
секции, от которой начинается процесс вычислений.
Виртуальные поля могут быть определены разработчиком в процессе создания
схемы карточки (такие поля всегда будут доступны для использования во всех
представлениях). Доступ к определениям этих полей можно получить через объектную
модель метаданных (CardType.VirtualFields). Элементы этой коллекции доступны только
для чтения, так как они жестко определены в схеме карточки. Каждый объект
CardVirtualField содержит:
System.Guid Id – уникальный идентификатор виртуального поля;
string Alias – псевдоним виртуального поля, по которому оно доступно в коде;
DocsVision 4.5: Руководство разработчика на платформе
163
System.Guid SectionId – локализованное имя виртуального поля;
DocsVision.Platform.ObjectManager.ViewModel.VirtualField Export() – позволяет извлечь
определение виртуального поля для последующего добавления (импорта) в конкретное
описание представления.
Также виртуальные поля можно создать (выделить) в процессе построения
конкретного представления, и сохранить как отдельные объекты для дальнейшего
использования в других представлениях по аналогичной секции. Такие виртуальные
поля создаются на основе готовых элементов представлений (ViewElement) при помощи
метода ExtractVirtualField. Они сохраняются в той же системной карточке ViewCard, что и
описания представлений, и доступны для последующего повторного использования
через её объектную модель. Для работы с такими виртуальными полями используется
другой тип объектов – SavedVirtualField.
Пример добавления предварительно сохраненного виртуального поля к описанию
представления:
const string SECTION_TYPE_ID = "{8C77892A-21CC-4972-AD71-A9919BCA8187}";
// Получение сохраненных определений виртуальных полей для конкретного типа
секции
SavedVirtualFieldCollection savedColl = viewcard.GetVirtualFields(new
Guid(SECTION_TYPE_ID));
// Получение поля с псевдонимом "Performer"
SavedVirtualField savedField = savedColl["Performer"];
// Добавление поля к описанию представления
ViewElement element;
element.MergeVirtualField(savedField.Export(), "Performers", "Performers");
Типичный алгоритм создания нового описания представления может включать в
себя следующие шаги:
1) Определить количество и состав колонок будущего представления (View.Columns),
задать порядок сортировки данных в колонках (View.Sorting).
2) Сформировать
как
минимум
один
элемент
представления
(ViewElement),
определяющий источники данных для колонок:
a) Задать основную секцию карточки, из которой будут извлекаться данные
(SectionTypeID).
b) Физические
поля
секции,
которые
выводятся
в
представление
непосредственном виде, перечислить в коллекции SectionFields.
в
c) Если для данной секции ранее были определены виртуальные поля (в схеме
карточки или в конкретной базе данных), то загрузить их описание при помощи
метода MergeVirtualField.
d) Для вывода данных из полей другой секции или таблицы:
i)
Присоединить эту секцию (или таблицу) к основной секции в коллекции
JoinDefs.
ii) Выбрать поля присоединенной секции (или таблицы), добавив их
коллекцию SectionFields вместе с псевдонимом присоединенной секции.
в
e) Если представление должно содержать данные, не присутствующие в
физических полях секций, то такие данные нужно оформить в виде вычисляемых
полей (ComputationsFields). Для каждого вычисляемого поля (ComputedFileld)
необходимо:
DocsVision 4.5: Руководство разработчика на платформе
164
i)
Определить набор физических источников данных (ComputationParts), каждый
их которых может быть значением физического поля секции или результатом
выполнения арифметической фукнции.
ii) Определить агрегацию
источниками данных.
(Aggregation),
iii) Определить
операцию
источниками данных.
(Operation),
выполняемую
выполняемую
над
над
физическими
физическими
iv) Задать ожидаемый тип результата вычислений (Type).
v) При необходимости, можно сопоставить каждому из возможных результатов
вычислений конкретное значение, которое будет итоговым результатом
(ResultSwitch).
Пример кода создания нового представления:
//
//
//
//
//
//
Создание представления по документам с пятью колонками:
- Тема документа
- Номер документа
- Должность согласующего лица
- Количество файлов
- Количество свойств
DocsVision.Platform.ObjectManager.ViewModel.View view = session.CreateView();
// Добавление колонок
view.Columns.AddNew("Name").Caption = "Тема документа";
view.Columns.AddNew("Number").Caption = "Номер документа";
view.Columns.AddNew("ApproverPos").Caption = "Должность согласующего лица";
view.Columns.AddNew("FilesCount").Caption = "Количество файлов";
view.Columns.AddNew("PropertiesCount").Caption = "Количество свойств";
// Сортировка - по полю "Номер"
view.Sorting.AddNew("Number").Ascending = true;
// В представление будут выводиться данные только по Входящим документам
// Поэтому будет только один элемент данных (ViewElement)
// Его базовая секция – “Основная информация” Входящего документа
ViewElement element = view.Elements.AddNew(new Guid("8C77892A-21CC-4972-AD71A9919BCA8187"));
// Данные двух колонок - Тема и Номер
// выводятся непосредственно из физических полей секции
element.SectionFields.AddNew("Name").Name = "Name";
element.SectionFields.AddNew("Number").Name = "FullNumber";
// Формирование колонки Должность согласующего лица
// Базовой секцией представления является "Основная информация”
// А согласующее лицо хранится в секции "Сотрудники"
// Поэтому сначала нужно присоединить секцию "Сотрудники" к представлению
JoinDefinition join1 = element.JoinDefinitions.AddNew("Employees");
join1.SourceField = "InstanceID";
join1.DestinationField = "InstanceID";
join1.SectionId = new Guid("47C41171-9C64-450A-A3A6-102B3156AD79");
// Условие присоединения: в секции "Сотрудники" поле "Type"
// должно иметь значение "3" (согласующее лицо)
DataCondition cond = join1.ConditionGroup.Conditions.AddNew();
cond.Operation = ConditionOperation.Equals;
DataConditionItem item1 = cond.ConditionItems.AddNew();
item1.SectionAlias = "Employees";
item1.Value = "Type";
item1.DataType = DataType.Integer;
DocsVision 4.5: Руководство разработчика на платформе
165
DataConditionItem item2 = cond.ConditionItems.AddNew();
item2.DataType = DataType.Integer;
item2.Value = 3;
// Далее нужно присоединить секцию справочника сотрудников
JoinDefinition join2 = element.JoinDefinitions.AddNew("RefStaffEmployees");
join2.SourceField = "EmployeeID";
join2.DestinationField = "RowID";
join2.SectionId = new Guid("DBC8AE9D-C1D2-4D5E-978B-339D22B32482");
// Наконец, для получения названия должности, нужно присоединить секцию
должностей
JoinDefinition join3=element.JoinDefinitions.AddNew("RefStaffPositions");
join3.SourceField = "Position";
join3.DestinationField = "RowID";
join3.SectionId = new Guid("CFDFE60A-21A8-4010-84E9-9D2DF348508C");
// Добавляем в к элементу представления колонку - название должности
SectionField field = element.SectionFields.AddNew("ApproverPos");
field.SectionAlias = "RefStaffPositions";
field.Name = "Name";
// Четвертая колонка - Количество файлов - уже определена в описании карточки
// в виде виртуального поля. Нужно только добавить её к представлению
CardType type = session.CardManager.CardTypes[new Guid("C1FED883-08DE-420F8FB4-C16CEFFC1630")];
CardVirtualField virtfield = type.VirtualFields["FilesCount"];
element.MergeVirtualField(virtfield.Export(), "Main", "FilesCount");
// Последняя колонка - Количество свойств - это вычисляемое поле
// Представляет собой агрегацию (количество строк) по секции "Свойства"
// Присоединяем секцию Свойства
JoinDefinition join4 = element.JoinDefinitions.AddNew("Properties");
join4.SourceField = "InstanceID";
join4.DestinationField = "InstanceID";
join4.SectionId = new Guid("B822D7D1-2280-4B51-AE58-A1CF757C5672");
// Создание вычисляемого поля - количество строк в секции Свойства
ComputedField compfield = element.ComputedFields.AddNew("PropertiesCount");
ComputationPart comppart =
compfield.ComputationGroup.ComputationParts.AddNew();
comppart.DataItem.SectionAlias = "Properties";
comppart.DataItem.Value = "RowID";
ПРИМЕЧАНИЕ
При построении представления
предопределённых секций:
можно
использовать
псевдонимы
трех
- Main – базовая секция представления;
- Inst – строка из системной таблицы dvsys_instances, соответствующая текущей
карточке;
- Shortcuts – строка из секции ярлыков карточки папок, соответствующая
текущей карточке.
4.15.2 Описание (схема) форматирования
Другой важной частью представления, помимо получения данных, является их
форматирование (а также, возможно, дополнительная обработка) при отображении в
конечном клиентском приложении.
DocsVision 4.5: Руководство разработчика на платформе
166
Навигатор, который является базовым средством для работы с представлениями,
предлагает следующие возможности обработки и форматирования данных:
фильтрация данных (при помощи дополнительных фильтров);
агрегация (вычисление статистических величин);
группировка данных в таблице;
сортировка данных в таблице;
указание шрифта для таблицы;
разметка линий сетки в таблице;
указание ширины строк в таблице;
задание имен колонок.
Для работы с настройками представлений Навигатора в объектной модели
предусмотрен объект ViewSettings, доступный из карточки Навигатора (NavigatorCard).
Каждому конкретному представлению соответствуют индивидуальные настройки
отображения, поэтому общее число объектов ViewSettings соответствует количеству
настроенных в системе представлений.
Объект ViewSettings имеет следующие свойства:
DocsVision.Platform.ObjectManager.SystemCards.AggregationType
Aggregation
–
перечисление, которое определяет клиентскую операцию агрегации для табличных
данных:
AggregationType.None – агрегация отсутствует;
AggregationType.Count – количество строк;
AggregationType.Sum – арифметическая сумма значений;
AggregationType.Avg – срденее значение;
AggregationType.Min – минимальное значение;
AggregationType.Max – максимальное значение;
AggregationType.Dev – СКО;
AggregationType.ValueCount
string AggregationColumn – псевдоним колонки, по которой осуществляется агрегация
(в Навигаторе допускается агрегация только по одной колонке);
string AggregationText – текст строки, содержащей агрегацию;
DocsVision.Platform.ObjectManager.SystemCards.ViewColumnSettingsCollection
коллекция настроек колонок представления;
System.Guid FilterId – идентификатор дополнительного
представления (ID сохраненного поискового запроса);
DocsVision.Platform.ObjectManager.SystemCards.ViewFlags
Flags
–
дополнительные
атрибуты, регулирующие внешний вид представления (битовая маска):
фильтра
для
ViewFlags.None – флаги отсутствуют
ViewFlags.Preview – отображать область предварительного просмотра;
ViewFlags.Icon – отображать иконки карточек;
ViewFlags.GroupBox – отображать область группировки;
ViewFlags.AllowRowResize – разрешать изменять высоту строк;
ViewFlags.DoNotFitColumns – не выравнивать колонки по ширине;
DocsVision 4.5: Руководство разработчика на платформе
Columns
–
данных
167
ViewFlags.ShowGroupColumns – скрывать колонки, по которым производится
группировка;
int FolderLevel – глубина вложенности папок, из которых извлекаются данные в представление
DocsVision.Platform.ObjectManager.SystemCards.GridLineModes
отображения линий таблицы:
GridLineMode
GridLineModes.None – линии отсутствуют;
GridLineModes.Vertical – только вертикальные линии;
GridLineModes.Horizontal – только горизонтальные линии;
GridLineModes.Both – горизонтальные и вертикальные линии;
–
режим
DocsVision.Platform.ObjectManager.SystemCards.GridLineStyle GridLineStyle – стиль линий
таблицы:
GridLineStyle.Solid – сплошные;
GridLineStyle.Dashes – пунктирные;
GridLineStyle.SmallDots – точечные;
int LinkLevel – глубина раскрытия ссылок между карточками
string PreviewColumn
просмотра
int RowHeight – высота строк представления
System.Guid ViewId – идентификатор представления, к которому относятся эти
настройки.
- имя колонки, отображаемой в области предварительного
Методы:
DocsVision.Platform.ObjectManager.SystemCards.ViewSettings
viewId) – копирование настроек представления
Copy(System.Guid
DocsVision.Platform.ObjectManager.SystemCards.ViewFiltering GetFiltering(int index) –
получение настроек фильтрации представления
DocsVision.Platform.ObjectManager.SystemCards.ViewGrouping GetGrouping(int index)
– получение настроек группировки представления
DocsVision.Platform.ObjectManager.SystemCards.ViewSorting GetSorting(int index) получение настроек сортировки представления
System.Drawing.Font
GetFont(DocsVision.Platform.ObjectManager.SystemCards.ViewObjectType
– получение шрифта представления
SetFont(DocsVision.Platform.ObjectManager.SystemCards.ViewObjectType
System.Drawing.Font font) – установка шрифта представления
objectType)
objectType,
Пример кода работы с настройками представления:
// Получение первого попавшегося представления
SavedView view = viewcard.Views[0];
// Получение карточки Навигатора
const string NAVIGATOR_CARD_TYPE = "{A7F9784B-96A4-4B3E-B820-2E714A2A1463}";
NavigatorCard nav = (NavigatorCard)session.CardManager.GetDictionary(new
Guid(NAVIGATOR_CARD_TYPE));
// Получение настроек представления
ViewSettings settings = nav.ViewSettings[view.Id];
// Перебор всех колонок и вывод их названий
DocsVision 4.5: Руководство разработчика на платформе
168
foreach(ViewColumnSettings col in settings.Columns)
{
MessageBox.Show(col.Caption);
}
4.15.3 Получение данных представления
Другой важной задачей при работе с представлениями является получение
конкретной выборки данных на основании предварительно подготовленного
(программно или через пользовательский интерфейс) описания представления.
Для того, чтобы получить данные представления, необходимо воспользоваться
методом CardManager.GetViewData. Предусмотрено несколько вариантов реализации
данного метода, отличающихся набором параметров:
DocsVision.Platform.ObjectManager.InfoRowCollection
GetViewData(DocsVision.Platform.ObjectManager.ViewSource viewSource, string viewXml,
DocsVision.Platform.ObjectManager.QueryParameterCollection parameters) – получает данные
представления, описание которого передается напрямую в параметре viewXml. Также позволяет
указать значения параметров представления (parameters). Наибольший интерес представлеяет
первый параметр – viewSource, который пределяет источник данных представления. В качестве
источника может выступать вся база данных; конкретная папка, в которой хранятся карточки;
сохраненный или сформированный поисковый запрос. Конкретный источник данных можно
задать при помози объекта ViewSource, которые имеет следующие свойства и методы:
FromCardType(System.Guid cardTypeId) – все карточки указанного типа
FromFolder(System.Guid folderId) – физическая папка с указанным идентификатором
FromRecycleBin() – корзина
FromSearch(string searchQuery) – сформированный поисковый запрос (XML)
FromSearch(System.Guid searchQueryId) – сохраненный поисковый запрос
FromSearchFolder(System.Guid folderId) – виртуальная папка с указанным идентификатором
ShowArchived – признак выводить в представлении архивные карточки
ShowDeleted – признак выводить в представлении удаленные карточки
ShowHidden - признак выводить в представлении скрытые и системные карточки
Класс ViewSource является статическим, т.е. создавать этот объект нет необходимости.
DocsVision.Platform.ObjectManager.InfoRowCollection
GetViewData(DocsVision.Platform.ObjectManager.ViewSource viewSource, string viewXml) –
аналогично предыдущему, но без указания параметров
DocsVision.Platform.ObjectManager.InfoRowCollection
GetViewData(DocsVision.Platform.ObjectManager.ViewSource viewSource, System.Guid viewId,
DocsVision.Platform.ObjectManager.QueryParameterCollection parameters) – получает данные
сохраненного представления с указанным идентификатором
DocsVision.Platform.ObjectManager.InfoRowCollection
GetViewData(DocsVision.Platform.ObjectManager.ViewSource viewSource, System.Guid viewId) аналогично предыдущему, но без указания параметров
DocsVision.Platform.ObjectManager.InfoRowCollection
GetViewData(DocsVision.Platform.ObjectManager.ViewSource viewSource)
указанного источника данные стандартного представления - дайджеста
–
получает
для
Пример получения данных системного представления Дайджест, примененного к
конкретной папке:
const string FOLDER_ID = "{5929489F-3CC0-4B48-A032-9CCE7F9674CF}";
DocsVision 4.5: Руководство разработчика на платформе
169
InfoRowCollection viewdata =
session.CardManager.GetViewData(ViewSource.FromFolder(new Guid(FOLDER_ID)));
Другой пример: получение данных представления по XML-описанию на основании
результатов сформированного поискового запроса:
// Формирование поискового запроса
SearchQuery query = session.CreateSearchQuery();
//...
// Получение данных представления
ViewSource source = ViewSource.FromSearch(query.GetXml(true, null));
InfoRowCollection
viewData
=
session.CardManager.GetViewData(source,
view.GetXml());
Метод возвращает InfoRowCollection — набор строк, соответствующий результатам
запроса. Возможность его сортировки в объектной модели не предусмотрена, то есть
сортировать его можно только внешними средствами.
DocsVision 4.5: Руководство разработчика на платформе
170
4.16 ХРАНИМЫЕ ПРОЦЕДУРЫ
В ряде случаев при создании решения требуется прямой доступ к базе данных,
например:
для получения сложных выборок данных, которые не могут быть получены
штатными методами (например, статистических отчётов);
для повышения производительности работы решения (ускорения доступа к
данным);
для получения данных из сторонней базы или сервера и т.д.
Для реализации такой возможности в платформе предусмотрен механизм создания
и вызова хранимых процедур. Этот механизм предоставляет разработчику решения
возможность выполнить произвольную команду или запрос к базе данных, и получить
результат этого запроса на клиенте.
ВНИМАНИЕ
Следует помнить, что данный метод должен использоваться только в
исключительных случаях, когда разработчику решения не хватает встроенных
средств платформы! Написание подобных процедур потребует от разработчика
глубоких знаний внутреннего устройства базы данных DocsVision. Кроме того,
подобный механизм дает потенциальную возможность получения неправомочных
данных – так как запрос будет выполняться в обход системы безопасности
сервера.
Поэтому
следует
крайне
осторожно
использовать
данную
функциональность и, по возможности, защищать её от неправомерного
использования.
4.16.1 Создание хранимой процедуры
Хранимые процедуры описываются в схеме (XML-описании) библиотеки карточек
при помощи утилиты CardManager.
Для этого предназначена специальная вкладка Reports в свойствах библиотеки
(см. рис. 4.7).
Описание библиотеки может содержать в себе определения произвольного
количества процедур. Добавить новую процедуру можно нажатием кнопки Add в
списке процедур, а исключить процедуру из библиотеки – нажатием кнопки Remove.
Для каждой новой процедуры необходимо указать:
Alias - внутреннее имя, по которому к процедуре можно будет обращаться в коде;
Names – имя, под которым процедура будет видна пользователю;
ID – уникальный идентификатор процедуры (генерируется автоматически);
SQL file – здесь можно указать файл SQL-скрипта, содержащего собственно код
процедуры (описан ниже);
DocsVision 4.5: Руководство разработчика на платформе
171
Рис. 4.7. Описание хранимой процедуры
Parameters – список параметров процедуры. Если процедура содержит параметры,
то каждый из них нужно задекларировать здесь, указав:
Parameter name;
Parameter type:
– string – строка;
– integer – целое;
– double – дробное;
– datetime – дата/время;
– bool – признак;
– uniqueidentifier – GUID;
– text – блоб.
Файл SQL-сценария должен содержать только тело хранимой процедуры, начиная
с оператора BEGIN и заканчивая оперетором END. Заголовок хранимой процедуры и
описания параметров будут сгененированы автоматически.
Пример кода создания хранимой процедуры:
BEGIN
SELECT
tblMy.Info1, tblMy.Info2
FROM [dvtable_{SOME_DV_TABLE_GUID_HERE}] tblMy
DocsVision 4.5: Руководство разработчика на платформе
172
WHERE
tblMy.Param1 = @Param1 and tblMy.Param2 = @Param2
ORDER BY tblMy.Info2
END
4.16.2 Вызов хранимых процедур и получение данных
Для работы с процедурами в объектной модели ObjectManager существует
специальный объект - ReportManager. Его единственное свойство Reports позволяет
получить коллекцию всех процедур (из всех решений), доступных текущему
пользователю. Элементами коллекции являются объекты типа Report,
каждый из
которых предоставляет доступ к конкретной процедуре. Выбрав из коллекции
необходимый объект Report по его идентификатору, достаточно заполнить реальными
значениями набор параметров Parameters и вызвать метод получения данных GetData.
Данные отчёта возвращаются в виде стандартной коллекции InfoRowCollection.
Объект ReportManager (менеджер процедур) содержит:
коллекцию Reports — содержит список доступных процедур.
Объект Report (процедура) содержит:
свойство System.Guid Id — уникальный идентификатор процедуры;
свойство string Alias — псевдоним процедуры;
свойство string Name — локализованное название процедуры;
коллекция ReportParameterCollection Parameters— содержит список параметров
процедуры (перед получением данных необходимо подставить реальные
значения);
метод GetData() — запускает процедуру на исполнение и возвращает данные в
виде стандартной коллекции InfoRowCollection.
Объект ReportParameter (параметр процедуры):
string Name — название параметра;
DocsVision.Platform.ObjectManager.ParameterValueType ValueType — тип параметра;
object Value — значение параметра.
Пример кода получения данных хранимой процедуры:
const string REPORT_ID = "75AD4670-0DF3-43CD-A6FE-C34BC6E36E31";
// Получение объекта процедуры по идентификатору
Report report = session.ReportManager.Reports[new Guid(REPORT_ID));
// Задание значений параметров
report.Parameters["Param1"].Value = "Test";
report.Parameters["Param2"].Value = 0;
// Вызов процедуры и получение данных
InfoRowCollection results = report.GetData();
// Обработка полученных данных
ПРИМЕЧАНИЕ
Пользовательский интерфейс системы (Навигатор) не предусматривает штатного
способа для вызова хранимых процедур или отображения возвращаемых ими
данных (то есть, например, невозможно отобразить результаты вызова хранимой
процедуры в окне результатов представлений). Вместо этого, разработчик
решения должен сам полностью обеспечить возможность вызова хранимой
процедуры и отображения результатов её работы. Это может быть часть
функциональности конкретной карточки (например, карточки расширения) или
DocsVision 4.5: Руководство разработчика на платформе
173
дополнительного сервиса.
4.17 РАСШИРЕНИЯ НАВИГАТОРА
Платформа позволяет авторам решений реализовать собственные расширения
интерфейса
Навигатора
–
аналог
плагинов,
дополняющих
стандартную
функциональность Навигатора новыми возможностями, доступными пользователям.
Доступны следующие типы расширений Навигатора:
Расширение виртуальных папок – этот тип расширения позволяет
программно изменить поведение виртуальных папок. Например, «на лету»
сформировать новый текст поискового запроса для виртуальной папки; или
отобразить собственный диалог ввода параметров.
Расширение экспорта – этот тип расширения появляется в списке доступных
вариантов экспорта данных представления (по умолчанию в Навигаторе есть
только возможность выгрузки данных представления в Excel). При выборе
пользователем соответствующей команды экспорта управление получит код
расширения – которое и будет реализовывать собственно логику экспорта
данных (например, во внешнюю систему или базу данных).
Командное расширение – позволяет добавить собственные команды в панель
инструментов (тулбар) Навигатора или в контекстное меню карточек и папок.
Обработчик событий – такое расширение позволяет добавить собственную
обработку стандартных событий Навигатора: например, таких как запуск или
завершение работы.
Пикер – такой тип расширения позволяет разработчику реализовать
собственный интерфейс для выбора учетных записей пользователей (это может
быть полезно в случае разработки собственного, отличного от стандартного,
справочника сотрудников). Расширение такого типа будет вызвано, например,
при назначении прав на объекты системы – чтобы пользователь мог оперировать
не доменными учетными записями, а более полными сведениями из
справочника.
Контроль папки – это расширение позволяет динамически контролировать
поведение папок, например запретить отображать подпапки или не
подсвечивать количество непрочитанных карточек.
Страница свойств – расширение такого типа может добавлять собственные
страницы свойств к свойствам папок и карточек. На этих дополнительных
страницах можно расположить произвольную информацию и элементы
управления.
Расширение типов карточек – такое расширение предоставляет информацию
о пользовательских подтипах (видах) карточек. Это может быть полезно в
случае разработки собственного, отличного от стандартного, справочника типов.
Информация о подтипах, которую вернет расширение, будет доступна в
контекстном меню создания новой карточки, а также на странице свойств папки
с ограничением на типы карточек.
Расширение типов папок – такое расширение предоставляет информацию о
пользовательских подтипах папок. Это может быть полезно в случае разработки
собственного, отличного от стандартного, справочника типов папок.
4.17.1 Интерфейс карточки-расширения
Физически расширение Навигатора представляет собой обычную карточку
системы DocsVision, и разрабатывается по схожим принципам. Отличие заключается в
DocsVision 4.5: Руководство разработчика на платформе
174
том, что в схеме карточки-расширения необходимо выставить специальный признак
«Реализует расширения интерфейса хоста».
ПРИМЕЧАНИЕ
Дополнительно для карточки-расширения рекомендуется установить признак
«является справочником». В противном случае можно будет создать несколько
экземпляров карточки-расширения, что может привести к конфликтам при их
вызове.
Компонент карточки расширения, помимо стандартных, должен реализовывать
специальный
интерфейс,
который
реализован
в
классе
DocsVision.Platform.WinForms.NavExtension.
Поэтому
для
разработки
карточки
расширения, достаточно унаследовать ее основной класс от базового:
[ComVisible(true)]
[Guid("6A0676EE-1DAF-4A59-B5EB-E0B5B4C175EE")]
[ClassInterface(ClassInterfaceType.None)]
public sealed partial class TestExtension : NavExtension
Базовый класс предполагает реализацию следующих методов:
string
GetExtensionName(NavExtensionTypes
название этого расширения;
NavExtensionTypes
карточкой:
SupportedTypes
–
типы
extensionType)
расширений,
–
возвращает
реализуемые
o
NavExtensionTypes.All – все типы
o
NavExtensionTypes.CardTypes – расширение типов карточек
o
NavExtensionTypes.Command – командное расширение
o
NavExtensionTypes.Control – контроль папки
o
NavExtensionTypes.Event – расширение событий
o
NavExtensionTypes.FolderTypes – расширение типов папок
o
NavExtensionTypes.None – тип не указан
o
NavExtensionTypes.Picker – пикер
o
NavExtensionTypes.PropertyPages – страницы свойств
o
NavExtensionTypes.Report – расширение экспорта
o
NavExtensionTypes.VirtualFolder – расширение виртуальных папок
этой
ПРИМЕЧАНИЕ
Одна карточка расширения может реализовывать одновременно несколько
доступных типов расширений. Верно и обратное – допускается существование
нескольких карточек расширений, реализующих один и тот же тип.
Пример кода реализации интерфейса карточки расширения:
[ComVisible(true)]
[Guid("6A0676EE-1DAF-4A59-B5EB-E0B5B4C175EE")]
[ClassInterface(ClassInterfaceType.None)]
public sealed partial class TestExtension : NavExtension
{
public TestExtension()
{
}
DocsVision 4.5: Руководство разработчика на платформе
175
protected override NavExtensionTypes SupportedTypes
{
get
{
return NavExtensionTypes.All;
}
}
protected override string GetExtensionName(NavExtensionTypes
extensionType)
{
return "TextExtension";
}
Далее, в зависимости от типа расширения, в коде
реализовать один или несколько вспомогательных методов.
карточки
необходимо
4.17.2 Расширение виртуальных папок
Расширение виртуальных папок (NavExtensionTypes.VirtualFolder) не требует
реализации никаких специальных интерфейсов. Если для виртуальной папки назначена
в качестве фильтра карточка расширения (это нужно сделать явно, выбрав её в поле
«Тип фильтра» в свойствах папки), то при активации такой папки Навигатор вызывает
карточку расширения методом SelectFromCard. Соответственно, карточка расширения
может вернуть результат выбора (настроенный запрос) через FinishSelection.
protected override void OnCardClosed(EventArgs e)
{
if (this.DialogResult == DialogResult.OK)
{
this.CardFrame.FinishSelection(query.GetXML(true, null), false);
}
base.OnCardClosed(e);
}
4.17.3 Расширение экспорта
Расширение экспорта (NavExtensionTypes.Report) требует реализации в коде
карточки специального метода, который будет вызван в момент выбора пользователем
соответсвующей команды экспорта:
CreateReport(object
folderId)
grid,
InfoRowCollection
infoRowCollection,
Guid
На вход метода передаются следующие параметры:
grid – ссылка на элемент управления Janus Grid, используемый для отображения
данных представления в Навигаторе. Из этого элемента управления можно
прочитать текущие настройки и данные при помощи объектной модели,
описание которой можно найти у производителя);
ВНИМАНИЕ
Не рекомендуется записывать какие-либо данные непосредственно в JanusGrid
или изменять его настройки – это может привести к сбоям в работе Навигатора!
infoRowCollection
–
данные
нетипизированных данных);
текущего
представления
(коллекция
folderId – идентификатор текущей папки.
Используя эти параметры, код расширения может выгрузить данные текущего
представления во внешнюю систему (или приложение).
DocsVision 4.5: Руководство разработчика на платформе
176
4.17.4 Командное расширение
Командное расширение (NavExtensionTypes.Command) предполагает реализацию
следующих дополнительных методов:
IEnumerable<NavCommand> CreateCommands() – возвращает информацию о командах
расширения (NavCommand), для каждой из которых возвращается следующая
информация:
CommandType – тип команды (битовая маска значений):
NavCommandTypes.ContextMenuCard - команда контекстного меню карточки
NavCommandTypes.ContextMenuFolder - команда контекстного меню папки
NavCommandTypes.ContextMenuGrid - команда контекстного меню грида (вне
карточек и папок)
NavCommandTypes.Menu - команда меню
NavCommandTypes.None – тип не указан
NavCommandTypes.Picture - команда имеет иконку
NavCommandTypes.Separator – сепаратор в меню
NavCommandTypes.SubCommand – команда расположена в подменю
NavCommandTypes.Toolbar – команда панели инструментов
Name – имя команды
Description – описание команды (отображается в строке статуса)
Icon – иконка команды
ПРИМЕЧАНИЕ
Так как тип команды является битовой маской, то для реализации конкретной
команды нужно вернуть правильное сочетание флагов. Глобально команды
можно разделить на два типа: команды контекстого меню
(NavCommandTypes.Menu) и команды панели инструментов
(NavCommandTypes.Toolbar). Команды меню делятся на контекстное меню карточек
(NavCommandTypes.ContextMenuCard), папок (NavCommandTypes.ContextMenuFolder)
и просто команды грида (NavCommandTypes.ContextMenuGrid). Кроме того,
команда может опционально иметь иконку (NavCommandTypes.Picture), являться
сепаратором (NavCommandTypes.Separator) или входить в меню второго уровня
(NavCommandTypes.SubCommand). Таким образом, например, для команды
контекстного меню карточки, имеющей собственную иконку, нужно вернуть
следующее сочетание флагов:
NavCommandTypes.Menu | NavCommandTypes.ContextMenuCard |
NavCommandTypes.Picture
QueryCommandStatus(NavCommand command, NavCommandContext context) – текущий
статус команды для конкретного контекста (context), который включает в себя:
FolderType – тип текущей папки (NavFolderControlType):
NavFolderControlType.CardLibrary - папка библиотеки карточек в системной ветке
“Карточки”
NavFolderControlType.CardsRoot - системная папка ”Карточки”
NavFolderControlType.CardType - папка типа карточек в системной ветке ”Карточки”
NavFolderControlType.Folder - обычная папка
DocsVision 4.5: Руководство разработчика на платформе
177
NavFolderControlType.FoldersRoot - корневая папка ”Папки”
NavFolderControlType.RecycleBin - системная папка “Корзина”
NavFolderControlType.References - системная папка “Справочники”
NavFolderControlType.SearchResults - системная папка “Результаты поиска”
NavFolderControlType.Unknown - неизвестный тип папки
FolderId – идентификатор текущей папки;
Selection– массив идентификаторов выделенных объектов (карточек, ярлыков)
В качестве возвращаемого значения метод должен вернуть один из флагов:
NavCommandStatus.Enabled – команда активна
NavCommandStatus.HideStandard – спрятать стандартные команды
NavCommandStatus.Latched – кнопка нажата (пункт меню отмечен)
NavCommandStatus.Supported – команда применима к данному типу объектов
NavCommandStatus.None – статус неизвестен
InvokeCommand(NavCommand command, NavCommandContext context) – собственно
вызов команды (command) в конкретном окружении (context).
Логика работы Навигатора с командами расширения может быть отражена в
следующем алгоритме:
При первичной загрузке Навигатор опрашивает все доступные карточки расширения
на предмет наличия команд. Если расширение поддерживает команды – то
возвращает их массив (CreateCommands).
В процессе работы при выделении пользователем конкретных объектов (карточек,
папок), но ПЕРЕД тем как отобразить контекстное меню Навигатор опрашивает
расширение на предмет статуса каждой команды (QueryCommandStatus).
Наконец, при выборе пользователем конкретной команды, управление переходит в
код карточки расширения (InvokeCommand).
Пример кода реализации командного расширения:
protected override IEnumerable<NavCommand> CreateCommands()
{
Trace.WriteLine("TestExtension.InitializeCommands()");
return new NavCommand[] {
new NavCommand() {
CommandType = NavCommandTypes.ContextMenuCard |
NavCommandTypes.Picture,
Name = "ContextMenuCard Command",
Description = "NavCommandType.ContextMenuCard",
Icon = Resources.Icon_Command,
},
new NavCommand() {
CommandType = NavCommandTypes.ContextMenuFolder |
NavCommandTypes.Picture,
Name = "ContextMenuFolder Command",
Description = "NavCommandType.ContextMenuFolder",
Icon = Resources.Icon_Command,
},
new NavCommand() {
CommandType = NavCommandTypes.ContextMenuGrid |
NavCommandTypes.Picture,
Name = "ContextMenuGrid Command",
Description = "NavCommandType.ContextMenuGrid",
Icon = Resources.Icon_Command,
DocsVision 4.5: Руководство разработчика на платформе
178
},
new NavCommand() {
CommandType = NavCommandTypes.Menu | NavCommandTypes.Picture,
Name = "Menu Command",
Description = "NavCommandType.Menu",
Icon = Resources.Icon_Command,
},
new NavCommand() {
CommandType = NavCommandTypes.ToolBar |
NavCommandTypes.Picture,
Name = "ToolBar Command",
Description = "NavCommandType.ToolBar",
Icon = Resources.Icon_Command,
},
};
}
protected override NavCommandStatus QueryCommandStatus(NavCommand command,
NavCommandContext context)
{
Trace.WriteLine("TestExtension.QueryCommandStatus()");
return base.QueryCommandStatus(command, context);
}
protected override void InvokeCommand(NavCommand command, NavCommandContext
context)
{
Trace.WriteLine("TestExtension.InvokeCommand()");
MessageBox.Show(command.Description);
base.InvokeCommand(command, context);
}
4.17.5 Обработчик событий
Расширение событий (NavExtensionTypes.Event) — такая карточка вызывается при
загрузке
и
выгрузке
Навигатора.
Карточка
должна
реализовывать
два
специализированных метода:
OnStartup() – метод вызывается при загрузке Навигатора;
OnShutdown() - вызывается при завершении работы Навигатора.
ПРИМЕЧАНИЕ
Такой тип расширений может быть полезен в качестве вспомогательного для
других типов. Например, если расширение экспорта выгружает данные в какуюто внешнюю систему, то обработчик событий может при запуске Навигатора
пытаться заранее установить соединение с этой системой.
4.17.6 Пикер
Расширение-пикер (NavExtensionTypes.Picker) предполагает реализацию следующих
методов
LookupAccounts(string[]
accountNames,
SecurityIdentifier[]
accountSids,
string[] commonNames, NavPickerAccountTypes[] accountTypes) – этот метод
позволяет расширению преобразовать имена учетных записей в их идентификаторы
(SID’ы). На вход метода подается массив с именами учетных записей
(accountNames). На выходе должны быть заполнены массивы:
accountSids – SID’ы учетных записей;
commonNames - полные имена учетных записей;
DocsVision 4.5: Руководство разработчика на платформе
179
accountTypes – типы учетных записей;
LookupSids(SecurityIdentifier[]
accountSids,
string[]
accountNames,
string[] commonNames, NavPickerAccountTypes[] accountTypes) - этот метод,
обратный предыдущему, позволяет преобразовать SID’ы в доменные имена. На вход
метода подается массив с идентификаторами (accountSids). На выходе должны
быть заполнены массивы:
accountNames – доменные имена;
commonNames - полные имена учетных записей;
accountTypes – типы учетных записей;
LookupNames(NavPickerNameFormat
formatOffered,
NavPickerNameFormat
formatDesired, string[] accountNames, string[] resultNames) –универсальный
метод, объединяющий в себе преимущества LookupAccounts и LookupSids. На входе
метода указывается формат передаваемых параметров (formatOffered), формат
ожидаемого результата (formatDesired) и сами параметры, требующие перевода
(accountNames). На выходе метода – массив переведенных значений (resultNames).
Доступные форматы:
NavPickerNameFormat.Account – учетная запись
NavPickerNameFormat.Class – тип объекта (пользователь, группа)
NavPickerNameFormat.CommonName – короткое имя
NavPickerNameFormat.Default – по умолчанию
NavPickerNameFormat.Full – полное имя
NavPickerNameFormat.Locking – имя пользователя, заблокировавшего объект
NavPickerNameFormat.Sid – идентификатор (SID)
PickAccounts(NavPickerAccountTypes
accountTypes)
–
позволяет
карточке
расширения отобразить пользовательский интерфейс для выбора учетных записей
(например, этот режим реализует стандартный справочник сотрудников при выборе
пользователей). Параметр метода accountTypes указывает, какой класс объектов
необходимо выбрать:
NavPickerAccountTypes.None – неивестный тип;
NavPickerAccountTypes.Computer – компьютер
NavPickerAccountTypes.Group – группа
NavPickerAccountTypes.User – пользователь
4.17.7 Контроль папки
Расширение контроля
единственного метода:
папки
(NavExtensionTypes.Control)
требует
реализации
QueryFolderControl(NavFolderControlType folderType, Guid folderId)
На вход метода передается тип папки (NavFolderControlType) и её идентификатор. В
качестве результата, метод возвращает один из предопределённых флагов,
определяющих дальнейшие действия Навигатора:
NavFolderControlFlags.None – обычное поведение (по умолчанию)
NavFolderControlFlags.DoNotAskChildren – не показывать дочерние папки
NavFolderControlFlags.HideFolder – скрыть папку
DocsVision 4.5: Руководство разработчика на платформе
180
NavFolderControlFlags.HideUnreadCount
непрочитанных карточек
–
не
показывать
количество
Пример кода:
protected override NavFolderControlFlags
QueryFolderControl(NavFolderControlType folderType, Guid folderId)
{
if (folderType == NavFolderControlType.Folder)
{
return NavFolderControlFlags.DoNotAskChildren;
}
else
{
return base.QueryFolderControl(folderType, folderId);
}
}
4.17.8 Страницы свойств
Начиная с версии 4.0, доступен новый тип расширений Навигатора, позволяющий
добавлять
собственные
страницы
свойств
карточек
и
папок
(NavExtensionTypes.PropertyPages).
Для реализации дополнительных страниц свойств, карточка расширения должна
реализовывать специальный метод:
IEnumerable<NavPropertyPage> CreatePropertyPages()
Метод должен создавать коллекцию страниц свойств, каждая из которых
реализуется собствнным элементом управления (NavPropertyPage). Для создаваемых
страниц указываются следующие атрибуты:
PageType – тип страницы свойств:
NavPropertyPageTypes.Card – страница свойств карточки
NavPropertyPageTypes.CardType – страница свойств типа карточки
NavPropertyPageTypes.Folder – страница свойств папки
NavPropertyPageTypes.All – страница для всех типов объектов
NavPropertyPageTypes.None – страница не применима ни для каких объектов
Name – заголовок страницы свойств;
Clsid – идентификатор элемента управления, реализующего страницу
protected override IEnumerable<NavPropertyPage> CreatePropertyPages()
{
Trace.WriteLine("TestExtension.InitializePropertyPages()");
return new NavPropertyPage[] {
new NavPropertyPage() {
PageType = NavPropertyPageTypes.All,
Name = "TestPropertyPage",
Clsid = typeof(TestPropertyPage).GUID,
},
};
}
В свою очередь, элемент управления, реализующий собственно страницу свойств,
должен быть унаследован от специального класса – NavPropertyPageControl. И, так
же как и компоненты карточек, он должен иметь идентификатор COM-интерфейса:
[ComVisible(true)]
[Guid("572860E1-E4C6-4120-B3DC-78C0A03F7445")]
[ClassInterface(ClassInterfaceType.None)]
public sealed partial class TestPropertyPage : NavPropertyPageControl
DocsVision 4.5: Руководство разработчика на платформе
181
Базовый класс предполагает реализацию обработчиков следующих событий:
OnPageInitialized(EventArgs e) – вызывается при инициализации страницы свойств
OnPageActivated(EventArgs e)– вызывается при активации страницы (получении
фокуса);
OnPageDeactivated(EventArgs e)– вызывается при деактивации страницы (потере
фокуса);
OnPageApplied(EventArgs e)– вызывается при необходимости сохранить изменения
(при нажатии пользователем кнопки OK или Apply);
OnPageClosed(EventArgs e)– закрытие страницы свойств.
В коде страницы свойств можно получить доступ к свойствам базового класса:
Session – объект сессии
CardHost – ссылка на объект контейнера карточек
PageFrame – окно текущей страницы свойств
ActivateParams – параметры активации страницы. В зависимости от типа страницы,
в массиве параметров находятся следующие значения:
Тип страницы свойств
Параметры
NavPropertyPageTypes.Folder
ReadOnly – признак «только для чтения»
Folder – папка
NavPropertyPageTypes.Card
ReadOnly – признак «только для чтения»
CardData – данные карточки
CardID – идентификатор карточки
CardTypeID – идентификатор типа карточки
CardDesc – описание карточки
FolderID – идентфикатор папки, где лежит карточка
ShortcutID – идентификатор ярлыка
Archived – признак архивности
Template – является шаблоном
CreateDate – дата создания
ChangeDate – дата изменения
NavPropertyPageTypes.CardType
ReadOnly – признак «только для чтения;
CardType – тип карточки
4.17.9 Расширение типов карточек
Начиная с версии 4.0, доступен новый тип расширений Навигатора
(NavExtensionTypes.CardTypes), позволяющий расширить функциональность по работе с
подтипами (видами) карточек. Это может быть полезно разработчику при реализации
собственного справочника – аналога стандартного справочника типов.
Для реализации такого расширения предназначены следующие методы:
PopulateCardTypes(NavCardTypeCollection cardTypes) – позволяет сформировать и
и вернуть коллекцию всех доступных подтипов
LookupCardTypes(Guid[] cardIds, Guid[] cardTypeIds) – позволяет сопоставить
подтипы (cardTypeIds) для конкретных карточек (cardIds).
DocsVision 4.5: Руководство разработчика на платформе
182
Для каждого подтипа создается объект NavCardType и заполняются следующие
свойства:
string Alias – псевдоним подтипа;
DocsVision.Platform.WinForms.NavCardTypeFlags Flags – вспомогательные флаги подтипа;
System.Drawing.Icon Icon – иконка;
System.Guid Id – уникальный идентификатор;
string Name – отображаемое (локализованное) имя;
DocsVision.Platform.WinForms.NavCardTypeCollection CardTypes – дочерние подтипы.
4.17.10 Расширение типов папок
Начиная с версии 4.1, доступен новый тип расширений Навигатора
(NavExtensionTypes.FolderTypes), позволяющий реализовать функциональность по работе
с типами папок.
Для формирования типов папок используется единственыный метод:
PopulateFolderTypes(NavFolderTypeCollection folderTypes)
Метод должен сформировать и вернуть коллекцию объектов NavFolderType,
описывающих тип папки. Cвойства этого объекта практически полностью идентичны
соответствующим свойствам папки, за исключением следующих:
System.Guid FolderCardLocation – идентификатор карточки папок
DocsVision.Platform.WinForms.NavFolderTypeCollection FolderTypes – дочерние типы папок
4.18 СЕРВЕРНЫЕ РАСШИРЕНИЯ
Начиная с версии 4.0, у разработчиков появилась возможность разрабатывать
собственные расширения не только для Навигатора, но и для сервера DocsVision.
Это может быть востребовано при необходимости выполнения каких-то действий в
контексте основного процесса сервера (с его привилегиями), которые не могут быть
выполнены с использованием стандартных методов интерфейса сервера. Механизм
расширений позволяет интегрировать в контекст сервера дополнительные методы, а
также обеспечивает возможность их вызова с клиента через общую объектную модель
(ObjectManager).
Физически серверное расширение представляет собой .NET сборку (Class
Library), в которой должен быть реализован как минимум один класс, унаследованный
от DocsVision.Platform.StorageServer.Extensibility.StorageServerExtension.
Этот базовый класс уже содержит в себе всю необходимую инфраструктуру для
реализации модуля расширения. Разработчику остается только определить сигнатуру
методов, реализуемых данным модулем расширения. Такие методы необходимо
пометить специальным атрибутом: [ExtensionMethod].
ПРИМЕЧАНИЕ
Этот атрибут имеет дополнительное свойство AllowedUserRoles, которое можно
использовать для ограничения возможности вызова данного метода расширения
в зависимости от роли пользователя (членства в соответствующей группе
безопасности). Пример использования свойства (метод будет доступен только для
членов группы «DocsVision Administrators»):
[ExtensionMethod(UserRoles.Administrator)].
Пример кода реализации серверного расширения:
using System;
using System.IO;
DocsVision 4.5: Руководство разработчика на платформе
183
using DocsVision.Platform.StorageServer.Methods;
using DocsVision.Platform.StorageServer.Extensibility;
namespace DocsVision.Samples
{
public sealed class SampleExtension : StorageServerExtension
{
/// <summary>
/// Default constructor
/// </summary>
public SampleExtension()
{
}
/// <summary>
/// Пример метода: возвращает имя рабочей базы данных
/// </summary>
/// <returns param name="BaseName">Имя базы данных </returns>
[ExtensionMethod]
public string GetBaseName()
{
return this.Request.Base.Name;
}
}
}
В коде класса можно получить доступ к контексту исполнения (серверу) через
объекты базового класса:
public SessionRequest Request { get; } – данные о текщуей сессии и БД;
public IStorageServer StorageServer { get; } – доступ к другим методам сервера.
В качестве возвращаемого значения метод может вернуть либо скаляр, либо
набор данных (коллекцию). Во втором случае лучше воспользоваться специальным
типом возвращаемого значения - DocsVision.Platform.StorageServer.CursorInfo.
Этот объект позволяет создать серверный курсор, из которого потом можно читать
данные на клиенте.
Объект CursorInfo можно создать двумя способами:
с
помощью
метода
GetCursorBuilder,
который
возвращает
CursorBuilder и позволяет программно заполнять серверный курсор.
с помощью метода
команду, сохраняет
CursorInfo.
объект
ExecuteCursorCommand, который выполняет SQLеё результаты в курсоре, и возвращает готовый
Пример реализации серверного метода, возвращающего набор значений:
/// <summary>
/// Пример метода: возвращает сведения о размере таблиц БД
/// </summary>
[ExtensionMethod]
public DocsVision.Platform.StorageServer.CursorInfo GetSectionsSize()
{
using (DatabaseCommand Command =
base.Request.Connection.PrepareProcedure("dvsys_help_show_section_size"))
{
return ExecuteCursorCommand(Command);
}
}
Готовый модуль расширения необходимо зарегистрировать на сервере. Для этого
нужно создать новый ключ в реестре в ветке
DocsVision 4.5: Руководство разработчика на платформе
184
[HKEY_LOCAL_MACHINE\SOFTWARE\DocsVision\Platform\4.5\Server\Extensions].
В ней необходимо создать строковое значение с именем своего расширения и со
значением, представляющим полное имя сборки, реализующей интерфейс расширения.
Пример:
"SampleExtension"="DocsVision.Samples.SampleExtension,
DocsVision.Samples.StorageServerExtension, Version=4.5.0.0, Culture=neutral,
PublicKeyToken=7148afe997f90519".
Для вызова методов модуля расширения на клиенте необходимо воспользоваться
специальным объектом – менеджером расширений (ExtensionManager). Этот объект
очень прост в использовании – он содержит единственную функцию:
DocsVision.Platform.ObjectManager.ExtensionMethod
GetExtensionMethod(string
extensionName, string methodName) – получение объекта для вызова метода серверного
расширения. Назначение параметров:
extensionName – имя расширения (под которым оно зарегистрировано в реестре на
сервере);
methodName - имя метода, под которым он определен в коде расширения.
Если такого расширения или метода на сервере не зарегистрировано, фукнкция
вернет ошибку. В противном случае будет возвращен специальный объект –
ExtensionMethod, с помощью которого уже можно выполнять непосредственные вызовы
метода серверного расширения.
Объект ExtensionMethod имеет следующие свойства и методы:
string ExtensionName – свойство, возвращает название серверного расширения;
string MethodName – свойство, возвращает название метода;
DocsVision.Platform.ObjectManager.ExtensionMethodParameterCollection
свойство, возвращает коллекцию параметров метода;
Parameters
–
object Execute() – инициирует исполнение
возвращает скалярный результат;
расширения
и
DocsVision.Platform.ObjectManager.InfoRowCollection
ExecuteReader()
инициирует
исполнение метода серверного расширения и возвращает результат в виде набора
данных (курсора).
метода
серверного
Параметры вызова серверного метода задаются через коллекцию Parameters, в
которую их необходимо явно добавить в виде объектов ExtensionMethodParameter. Этот
объект очень прост – он описывает название, тип и значение параметра через
одноименные свойства.
Пример кода вызова метода серверного расширения:
// Получаем метод расширения
ExtensionMethod method =
session.ExtensionManager.GetExtensionMethod("SampleExtension",
"GetFileContent");
// Добавляем параметр метода
method.Parameters.AddNew("FilePath", ParameterValueType.String).Value =
"C:\\Test.txt";
// Вызов метода
string content = method.Execute().ToString();
DocsVision 4.5: Руководство разработчика на платформе
185
4.19 ПОЛЬЗОВАТЕЛЬСКИЕ СЦЕНАРИИ
Начиная с версии 3.6, появилась возможность разработки пользовательских
сценариев
для
обработки
событий
в
стандартных
карточках
документов
«Делопроизводства».
Возможных областей применения таких сценариев много, в том числе:
выполнение нестандартных действий на разных этапах жизненного цикла
карточки (при открытии, закрытии, сохранении карточки и т.д.);
создание специфических кнопок в панели инструментов карточки, при
активации которых будет срабатывать сценарий (например, кнопка панели
инструментов, при нажатии на которую инициируется запуск определённого
бизнес-процесса);
создание обработчиков событий для нестандартных полей (свойств);
другие задачи.
Сценарии первого типа привязываются
настраиваются в справочнике типов:
к
конкретным
видам
карточек
и
Рис. 4.8. Настройка сценариев для событий
Имеется возможность указать сценарии для пяти событий жизненного цикла
карточки:
открытие карточки – вызывается каждый раз при создании новой карточки,
или открытии существующей;
закрытие карточки – вызывается каждый раз при закрытии создаваемой или
редактируемой карточки; событие вызывается до появления вопроса о
сохранении изменений;
сохранение карточки – вызывается при каждом сохранении карточки
пользователем, либо при автоматическом сохранении карточки в момент её
закрытия;
DocsVision 4.5: Руководство разработчика на платформе
186
переход между вкладками — инициируется в момент смены активной
закладки в пользовательском интерфейсе карточки;
выделение номера – активируется в момент выделения номера карточки и
позволяет переопределить стандартный алгоритм выдачи номеров своим
собственным.
смена состояния задания – активируется в карточке Задания при любой
смене состоянии, инициируемой из пользовательского интерфейса карточки
(например, при нажатии стандартных кнопок ”В работу” или “Завершить”)
Кроме событий, имеется возможность разработки сценариев, инициируемых
пользовательской функцией в панели инструментов карточки:
Рис. 4.9. Сценарий для кнопки панели инструментов
Для каждой новой функции можно указать:
название новой кнопки панели инструментов;
её иконку;
строку подсказки;
код сценария.
Возможные опции:
сохранять изменения перед запуском сценария – установка данной опции означает,
что при нажатии данной кнопки (но перед вызовом собственно сценария), все
изменения из элементов управления карточки будут сохранены в объект CardData
(но не будут переданы на сервер);
проверять обязательные поля при сохранении (доступно только при установке
опции «Сохранять изменения перед запуском сценария»); указывает необходимость
проверки обязательных полей при сохранении (с выдачей соответствующих
предупреждений).
Третий тип сценариев позволяет создать обработчик события изменение значения
для нестандартного поля (свойства) карточки:
DocsVision 4.5: Руководство разработчика на платформе
187
Рис. 4.10. Сценарий обработки события изменения свойства
Такие сценарии создаются индивидуально для каждого свойства карточки (любого
типа) и активируются в момент изменения пользователем значения этого свойства.
Типичная область применения таких сценариев – это автоматизация каких-то действий
после выбора значения (например, при заполнении значения свойства «Проект» может
активироваться сценарий, который автоматически заполнит значения других свойств
«Дата начала» и «Дата окончания»).
ПРИМЕЧАНИЕ
При изменении значения свойства, перед вызовом соответствующего сценария, в
карточке автоматически сохраняются все изменения из элементов управления в
объект CardData. Поэтому такой сценарий всегда предваряется вызовом сценария
“Сохранение карточки”.
Для того, что бы значения из любого свойства сохранились в карточку
непосредственно после изменения, для этого свойства требуется создать
произвольный скрипт (можно пустой). Иначе для некоторых событий, не
требующих немедленного сохранения, н-р, переход на другую вкладку, значения
свойств не будут видны в данных карточки.
Код сценария (любого из вышеописанных типов) разрабатывается на языке
VBScript.
Этот код должен включать в себя следующий
автоматически при создании нового сценария):
заголовок
(формируется
Function DoEvent(UserSession, CardFrame, CardData, ActivateFlags, ModeID,
FolderID)
…
End Function
При активации сценария будет вызвана данная функция; и возвращаемое ею
значение будет считаться результатом работы сценария.
На вход функции передаются следующие параметры:
UserSession — ссылка на текущую сессию DocsVision;
CardFrame — ссылка на интерфейс текущего окна карточки;
CardData — ссылка на данные карточки;
ActivateFlags — флаги активации карточки, переданные ей при открытии;
DocsVision 4.5: Руководство разработчика на платформе
188
ModeID — идентификатор текущего режима работы карточки;
FolderID – идентификатор папки, из которой открыта карточка;
PropValue (только для сценариев изменения свойств) – старое значение
свойства;
TabIndex (только для сценариев перехода между вкладками) – номер
вкладки, на которую выполняется переход;
NumberRef (только для сценариев выдачи номера) – идентификатор нового
номера, сфорированного в сценарии;
NumberText (только для сценариев
сформированного в сценарии.
WorkMode (только для смены состояния задания) – режим открытия задания:
wmNormal = 0
wmPerformer = 1
wmController = 2
выдачи
номера)
–
текст
номера,
NewState (только для смены состояния задания) – новое состояние задания
(значение перечисления из поля карточки задания)
Содержание кода данной функции и его семантика находятся полностью на
усмотрении разработчика. Параметры функции доступны не по значению, а по ссылке
— что дает возможность не только чтения, но и записи их значений. В частности,
имеется возможность изменять данные текущей карточки (CardData) и других
карточек системы (через объект UserSession), инициировать открытие диалоговых
окон (CardFrame.Host), обращаться к любым внешним системам и т.д.
Возвращаемое функцией значение (числовое) определяет результат её работы и
может повлиять на дальнейшее поведение карточки. При этом, различные типы
сценариев имеют собственные наборы возвращаемых значений (значение представляет
собой битовую маску возможных действий):
Сценарий
Возможные возвращаемые значения
Открытие карточки
<0 — карточка не будет открыта
0 – карточка будет открыта в обычном режиме
1 – не используется
2 — обновить элементы управления карточки
4 — карточка будет открыта только для чтения (используется
совместно с предыдущим флагом)
8 – карточка не будет открыта
Закрытие карточки
<0 — карточка не будет закрыта
>=0 — карточка будет закрыта
Сохранение
карточки
<0 – отмена сохранения, содержимое элементов управления
карточки будет обновлено
0 – сохранение в обычном режиме, содержимое элементов
управления карточки НЕ будет обновлено
>0 - сохранение в обычном режиме, содержимое элементов
управления карточки будет обновлено
Переход между
вкладками
1 – не используется
2 – обновить только гриды в карточке
4 - установка режима “только чтение” для карточки
8 - закрытие карточки
16 — немедленное сохранение изменений из данных карточки на
DocsVision 4.5: Руководство разработчика на платформе
189
сервер
32 — установка флага изменения данных карточки
64 — установка флага сохранения изменений
128 – обновить ВСЕ элементы управления карточки (изменения
внесенные в поля и свойства карточки не сохраняются!)
1024 – при закрытии карточки не будет выбираться новое
состояние
4096 – загрузить номер в карточку (если он был изменен)
Выделение номера
0 – не выдавать номер вообще
1 – установить номер, который вернул скрипт в параметрах
NumberID и NumberText
Смена состояния
Задания
< 0 – смена состояния отменяется
> 0 – карточка задания обновляется
Начало задачи
< 0 - отменить немедленный запуск задачи.
>=0 – продолжить операцию
Кнопка тулбара
1 - кнопка становится недоступной
2 - обновить элементы управления карточки
4 - установка режима “только чтение” для карточки
8 - закрытие карточки
16 — немедленное сохранение изменений
32 — установка флага изменения данных карточки
64 — установка флага сохранения изменений
1024 – установка флага изменения состояния
4096 – загрузить номер в карточку (если он был изменен)
Изменение
свойства
1 – не используется
2 - обновить элементы управления карточки
4 - установка режима “только чтение” для карточки
8 - закрытие карточки
16 — немедленное сохранение изменений
32 — установка флага изменения данных карточки
64 — установка флага сохранения изменений
1024 – при закрытии карточки не будет выбираться новое
состояние
4096 – загрузить номер в карточку (если он был изменен)
ВНИМАНИЕ
Сценарий не имеет возможности непосредственно повлиять на элементы
управления карточки (например, обновить значение в конкретном элементе
управления). Поэтому все обновления данных необходимо выполнять в данных
карточки (CardData).
4.20 МЕТОДЫ КОНТЕЙНЕРА КАРТОЧЕК
При разработке визуального интерфейса карточек или приложений, работающих с
DocsVision, часто возникает необходимость взаимодействия с контейнером карточек
(Навигатором) для решения одной из следующих задач:
Выбор карточки
Выбор папки
DocsVision 4.5: Руководство разработчика на платформе
190
Отображение конкретной карточки
Навигация по дереву папок
И т.д.
Для решения этих задач можно использовать методы объекта – контейнера
карточек (DocsVision.Platform.WinForms.CardHost).
Ссылку на этот объект все карточки получают в момент инициализации, и
впоследствии она доступна в любой момент жизненного цикла карточки через
соответствующее свойство базового класса – CardControl.CardHost.
В случае разработки внешних приложений и утилит, которые работают вне
контекста Навигатора, этот объект необходимо создавать явно. Для этого предназначен
метод CreateInstance(DocsVision.Platform.ObjectManager.UserSession session). На вход метода
достаточно передать ссылку на текущую сессию (session). Пример создания объектаконтейнера карточек:
SessionManager manager = SessionManager.CreateInstance();
manager.Connect("http://localhost/DocsVision41/StorageServer/StorageServerSer
vice.asmx", string.Empty);
UserSession session = manager.CreateSession();
CardHost host = CardHost.CreateInstance(session);
Объект контейнера карточек предлагает следующие методы:
System.Guid SelectCard(string caption) – открытие на выбор экземпляра любой карточки. Окно
выбора будет иметь заголовок caption
System.Guid SelectCard(string caption, string filter) – открытие на выбор экземпляра карточки
по фильтру filter (XML поискового запроса) . Окно выбора будет иметь заголовок caption
System.Guid[] SelectCards(string caption) - открытие на выбор нескольких экземпляров любых
карточек. Окно выбора будет иметь заголовок caption
System.Guid[] SelectCards(string caption, string filter) - открытие на выбор нескольких
экземпляров карточек по фильтру filter (XML поискового запроса) . Окно выбора будет иметь
заголовок caption
System.Guid SelectFolder(string caption) – выбор папки
System.Guid SelectFolder(string caption, int allowedTypes) – выбор папки конкретного типа
(allowedTypes – битовая маска из значений
DocsVision.Platform.ObjectManager.SystemCards.FolderTypes)
System.Guid SelectFolder(string caption, int allowedTypes, System.Guid currentFolderId) - выбор
папки конкретного типа (allowedTypes), при этом изначальная позиция определяется папкой
currentFolderId
object SelectFromCard(System.Guid cardId, string caption) – отображение карточки (cardId) в
режиме выбора значений (строк). Для работы с этим методом, в описании карточки должен
быть установлен признак “Из этой карточки могут быть выбраны элементы”
object SelectFromCard(System.Guid cardId, string caption, object activateParams) - отображение
карточки (cardId) в режиме выбора значений (строк) с передачей дополнительных параметров
выбора (activateParams). Метод возвращает выбранне значения (строку) или несколько строк
ПРИМЕЧАНИЕ
Примеры параметров для выбора значений из справочников типового решения
Делопроизводство приведены в приложении 7.3
DocsVision 4.5: Руководство разработчика на платформе
191
object SelectFromCard(System.Guid cardId, string caption, object activateParams, out object
resultParams) - отображение карточки (cardId) в режиме выбора значений (строк) с передачей
дополнительных параметров выбора (activateParams). Метод возвращает выбранне значения
(строку) или несколько строк, а также дополнительные данные (resultParams)
ПРИМЕЧАНИЕ
5. Параметры активации (ActivateParams) указываются вызывающей
стороной и доступны в карточке через соответствующее свойство.
6. Результат открытия (SelectedValue) указывается в коде карточки при
помощи вызова FinishSelection или CloseAndCreateNew. Вызывающая
сторона получает его как возвращаемое значение метода SelectFromCard.
Если для открытия карточки используется другой метод – значение
теряется.
7. Возвращаемые параметры (ResultParams) также передаются при помощи
вызова FinishSelection или CloseAndCreateNew. Вызывающая сторона
получает их как Out-параметр метода SelectFromCard. Вы также можете
использовать вариант метода SelectFromCard без этого параметра – в этом
случае значение теряется.
8. Если для открытия карточки используется метод ShowCardModal, то
возвращаемое значение будет True в том случае, если в обработчике
события CardClosing карточка выставила флаг ActionFlags.CommittedData.
Во всех остальных случаях вернется False.
ShowCard(System.Guid cardId, DocsVision.Platform.WinForms.ActivateMode activateMode) –
отображает (немодально) пользовательский интерфейс карточки cardId в режиме контейнера
activateMode
ShowCard(System.Guid cardId, System.Guid modeId,
DocsVision.Platform.WinForms.ActivateMode activateMode) - отображает (немодально)
пользовательский интерфейс карточки cardId в режиме самой карточки modeid и режиме
контейнера activateMode
ShowCard(System.Guid cardId, System.Guid modeId,
DocsVision.Platform.WinForms.ActivateMode activateMode, object activateParams) - отображает
(немодально) пользовательский интерфейс карточки cardId в режиме самой карточки modeid и
режиме контейнера activateMode, с дополнительными параметрами activateParams
(вызываемая карточка трактует эти параметры по своему усмотрению)
bool ShowCardModal(System.Guid cardId, DocsVision.Platform.WinForms.ActivateMode
activateMode) - отображает модально пользовательский интерфейс карточки cardId в режиме
контейнера activateMode
bool ShowCardModal(System.Guid cardId, System.Guid modeId,
DocsVision.Platform.WinForms.ActivateMode activateMode) - отображает модально
пользовательский интерфейс карточки cardId в режиме самой карточки modeid и режиме
контейнера activateMode
bool ShowCardModal(System.Guid cardId, System.Guid modeId,
DocsVision.Platform.WinForms.ActivateMode activateMode, object activateParams) - отображает
модально пользовательский интерфейс карточки cardId в режиме самой карточки modeid и
режиме контейнера activateMode, с дополнительными параметрами activateParams
(вызываемая карточка трактует эти параметры по своему усмотрению)
DocsVision.Platform.WinForms.MessageResult ShowMessage(string caption, string text, string
details, DocsVision.Platform.WinForms.MessageType messageType,
DocsVision.Platform.WinForms.MessageButtons buttons, System.IntPtr hWnd) – отображение
контейнером сообщения:
o
Caption – заголовок сообщения
o
Text – текст сообщения
DocsVision 4.5: Руководство разработчика на платформе
192
o
Details – детали сообщения (отображаются по кнопке Подробно)
o
messageType – тип сообщения (Error, Information, Question, Warning)
o
buttons – кнопки сообщения
o
hWnd –хэндл текущего окна (для правильного определения модальности сообщения)
System.Uri GetCardUrl(System.Guid cardId, System.Guid modeId) – получение полного URLадреса карточки с идентификатором cardId в режиме modeId
System.Uri GetShortcutUrl(System.Guid folderId, System.Guid viewId, System.Guid shortcutId) –
получение полного URL-адреса ярлыка shortcutId лежащего в папке folderId и представлении
viewed
Помимо контейнера, в карточку также передается ссылка на другой объект –
текущее окно, в котором открыта карточка (CardFrame). Этот объект позволяет
выполнять действия с окном:
-
Закрыть окно
-
Задать заголовок окна
-
Открыть карточку в новом окне
-
И т.д.
ПРИМЕЧАНИЕ
При разработке внешних приложений и утилит получить ссылку на объект
CardFrame невозможно, т.к. они работают вне контекста контейнера
(Навигатора).
Основные свойства и методы объекта CardFrame:
string Caption – свойство позволяет прочитать или установить заголовок окна
bool Visible – свойство позволяет показать или скрыть текущее окно
System.IntPtr Handle – hWnd окна
Close() – немедленное закрытие текущего окна
CloseAndCreateNew(System.Guid modeId) – закрытие этого окна, и создание нового
экземпляра карточки в новом окне (аналог команды ”Сохранить и создать новую” в
карточку Делопроизводства)
CloseAndCreateNew(System.Guid modeId, object resultParams) – то же что и предыдущий,
но с передачей новой карточке дополнительных параметров
Commit(DocsVision.Platform.WinForms.ActionFlags flags) – завершает работу карточки с
сохранением изменений
FinishSelection(object selectedValue) – завершает выбор, если карточка была открыта на
выбор (SelectFromCard); параметр selectedValue – возвращаемое значение выбора
FinishSelection(object selectedValue, object resultParams) – то же что и предыдущий, но
позволяет вернуть несколько результатов выбора
Refresh() – обновление окна
DocsVision.Platform.WinForms.MessageResult ShowMessage(string caption, string text,
string details, DocsVision.Platform.WinForms.MessageType messageType,
DocsVision.Platform.WinForms.MessageButtons buttons) – отображение сообщения,
модального по отношению к текущему окну (остальные параматеры аналогичны
соответствующему методу CardHost)
Пример кода работы с окном:
DocsVision 4.5: Руководство разработчика на платформе
193
private void txtName_TextChanged(object sender, EventArgs e)
{
// при изменении названия карточки меняется заголовок окна
CardFrame.Caption = txtName.Text;
isChanged = true;
}
5
ОТЛАДКА И ТЕСТИРОВАНИЕ
При разработке карточек DocsVision перед разработчиками встает задача отладки
и тестирования разработанных компонент. Этот процесс включает в себя следующие
подзадачи:
проверка правильной погрузки библиотек и схем карточек в базу данных и
соответствия созданных структур данных их описаниям;
мониторинг состояния объектов системы;
проверка функционирования
режимах;
поиск и локализация ошибок в работе компонент карточек;
прямое воздействие на данные карточек в системе;
другие задачи.
клиентского
компонента
карточки
в
различных
Для решения подобных задач предназначено приложение DocsVision Explorer
(DVExplorer), входящее в состав пакета разработчика.
Приложение DVExplorer выполняет следующие функции:
Это самый «тонкий» клиент DocsVision, работающий непосредственно
ObjectManager и наиболее полно использующий все его возможности.
Это
приложение,
предназначенное
для
отладки
разрешения/локализации проблем в данных карточек.
Это единственное в своем роде средство, которое может применяться для того,
чтобы проникнуть вглубь платформы DocsVision
работы
через
карточек
и
Ниже описаны основные аспекты работы с приложением DVExplorer.
5.1
СОЕДИНЕНИЕ С СЕРВЕРОМ
В стартовом окне DVExplorer можно указать URL к WEB-сервису и базу, с которой
будет осуществляться работа, а также выбрать способ аутентификации. После нажатия
на кнопку Connect будет создана сессия и установлено соединение.
DocsVision 4.5: Руководство разработчика на платформе
194
Рис. 5.1. Параметры соединения
В случае успешного создания сессии будет отображен её идентификатор:
Рис. 5.2. Информация о соединении
5.2
СПИСОК СЕССИЙ
Если указать параметры соединения и нажать кнопку
стандартный диалог просмотра сессий (такой же диалог
использованием Навигатора):
DocsVision 4.5: Руководство разработчика на платформе
Sessions появится
можно вызвать с
195
Рис. 5.3. Список сессий
5.3
НАСТРОЙКИ СЕССИИ
Для обеспечения тонкой настройки поведения ObjectManager, а также для
хранения разной полезной информации в рамках конкретной сессии предназначена
коллекция настроек сессии. Команда Settings позволяет отобразить диалог для
просмотра/изменения этих настроек:
Рис. 5.4. Свойства сессии
5.4
СПИСОК БЛОКИРОВОК
Команда Locks предназначена для отображения стандартного диалога просмотра
блокировок (такой же диалог можно вызвать используя Навигатор):
DocsVision 4.5: Руководство разработчика на платформе
196
Рис. 5.5. Список блокировок
5.5
СИСТЕМНЫЙ ЖУРНАЛ
Команда Log позволяет отобразить стандартный диалог просмотра системного
журнала (такой же диалог можно вызвать используя Навигатор):
Рис. 5.6. Системный журнал
5.6
ПРАВА ДОСТУПА К ОБЪЕКТАМ
Доступ ко многим объектам DocsVision (строки, секции, файлы и т.д.) можно
защищать правами. В DVExplorer для этого служит кнопка Secuity, отображающая
DocsVision 4.5: Руководство разработчика на платформе
197
стандартный диалог настройки прав. Рядом расположена кнопка Clear security — она
сбрасывает дескриптор в состояние Everyone - Full access.
Рис. 5.7. Настройка прав доступа
5.7
РАБОТА С ФАЙЛАМИ
Команда Файлы… вызывает диалог работы с файлами в DocsVision. Это именно
файлы, а не всевозможные карточки файлов. Этот диалог работает непосредственно с
FileManager — низкоуровневым сервисом ObjectManager для работы с файлами.
Используя кнопки в этом диалоге можно создавать файлы, копировать их, удалять,
сохранять и т.д., и т.п. — всё, что может FileManager.
DocsVision 4.5: Руководство разработчика на платформе
198
Рис. 5.8. Диалог работы с файлами
5.8
ИНФОРМАЦИЯ О ФАЙЛЕ
Для просмотра информации о конкретном файле нужно дважды щелкнуть мышью
на его имени в списке файлов. Откроется диалог информации о файле:
Рис. 5.9. Информация о файле
5.9
ОПИСАНИЯ КАРТОЧЕК
Библиотека ObjectManager содержит средства для получения описаний карточек
(метаданных). Их в полной мере использует соответствующий диалог, вызываемый по
команде Card types.
DocsVision 4.5: Руководство разработчика на платформе
199
Рис. 5.10. Схемы данных карточек
5.9.1 Структура секций карточки
Используя кнопку Sections, можно просмотреть структуру секций карточки.
Рис. 5.11. Описание структуры секции карточки
5.9.2 Действия и режимы карточки
Для просмотра действий карточек и её режимов предназначены соответственно
кнопки Actions и Modes.
DocsVision 4.5: Руководство разработчика на платформе
200
Рис. 5.12. Действия карточки
Рис. 5.13. Режимы работы карточки
5.9.3 XML-описание карточки
С помощью кнопки XML можно просмотреть и сохранить в файл XML-описание
выбранной карточки. Это описание получается с использованием методов
ObjectManager, так что оно не обязательно будет получено с сервера (если
зарегистрирован компонент библиотеки — будет задействован он).
Рис. 5.14. XML-описание карточки
5.9.4 XSD-описание данных карточки
Нажав кнопку XSD, можно просмотреть XSD-схему
генерирует CardManager во время загрузки карточки в базу).
DocsVision 4.5: Руководство разработчика на платформе
данных
карточки
(её
201
Рис. 5.15. XSD-описание карточки
5.9.5 Трансформации карточки
Кнопка Transforms предназначена для просмотра преобразований карточки,
загруженных в базу (XSTL- или InfoPath-преобразований).
Рис. 5.16. Список преобразований карточки
Рис. 5.17. Просмотр XSLT-шаблона печати
5.9.6 Работа с экземплярами карточек
Нажав в стартовом окне кнопку Card, можно отобразить диалог для работы с
экземплярами карточек. Используя этот диалог, можно создавать, копировать и удалять
карточки.
DocsVision 4.5: Руководство разработчика на платформе
202
Рис. 5.18. Просмотр экземпляров карточек
5.9.7 Поиск карточек
Находить карточки можно по их типу, или используя поисковый запрос — для его
редактирования можно воспользоваться стандартным диалогом поиска (вызывается из
вкладки Расширенный поиск).
Рис. 5.19. Диалог поиска карточек
DocsVision 4.5: Руководство разработчика на платформе
203
5.9.8 Просмотр XML-представления данных карточки
Для просмотра XML-представления данных карточки надо выделить её в списке
карточек и нажать кнопку XML. При этом будет сформирован XML-документ с данными,
который можно просмотреть и сохранить в файл.
Рис. 5.20. Просмотр XML-представления данных карточки
5.9.9 Просмотр HTML-представления данных карточки
Если с карточкой ассоциировано XSLT-преобразование, то по команде HTML
можно посмотреть HTML-представление её данных:
Рис. 5.21. Просмотр HTML-представления данных карточки
DocsVision 4.5: Руководство разработчика на платформе
204
5.9.10 Просмотр ссылок на карточку
Используя кнопку Links можно отобразить диалог просмотра ссылок карточки и
на карточку:
Рис. 5.22. Просмотр ссылок на карточки
DocsVision 4.5: Руководство разработчика на платформе
205
5.9.11 Работа с данными карточки
Из списка карточек при нажатии кнопки Data можно перейти к диалогу работы с
данными
карточки.
Используя
этот
диалог
можно
перемещаться
по
секциям/подсекциям, создавать и удалять в них строки, изменять значения полей
строки.
Рис. 5.23. Работа с данными карточки
Слева отображается список дочерних секций на текущем уровне. Справа — строки
выбранной секции. Внизу — значения полей выбранной строки. Назначение кнопок
объяснено ниже:
BeginUpdate — включить режим отложенных изменений.
UpdateNow — записать изменения.
CancelUpdate — отменить несохраненные изменения и выключить режим отложенных
изменений.
EndUpdate - записать изменения и выключить режим отложенных изменений.
Refresh — обновить данные.
RefreshLinked — обновить только данные связанных полей.
Security — отобразить диалог настройки прав доступа на объект.
Add new — создать новую строку.
Copy — копировать выбранную строку.
Delete — удалить выбранную строку.
Enter section — опуститься вниз по иерархии секций.
Leave section — подняться вверх по иерархии секций.
DocsVision 4.5: Руководство разработчика на платформе
206
5.9.12 Работа с компонентом карточки
Приложение DVExplorer является простым контейнером карточек, и может быть
использовано для отладки компонент карточек. Для того, чтобы отобразить компонент
карточки, надо выбрать карточку в списке и нажать кнопку Component:
Рис. 5.24. Компонент карточки в DVExplorer
DocsVision 4.5: Руководство разработчика на платформе
207
6
РАСПРОСТРАНЕНИЕ РЕШЕНИЯ
После завершения разработки решения
распространении и развертывании на платформе.
необходимо
позаботиться
о
его
Установка готового решения включает в себя два этапа:
обновление серверной части платформы;
инсталляция на клиентские рабочие места.
6.1
ИНСТАЛЛЯЦИЯ СЕРВЕРНОЙ ЧАСТИ РЕШЕНИЯ
Если решение включает в себя какие-либо карточки (новые или модификацию
имеющихся), то первоочередным шагом при его распространении является загрузка
описаний этих карточек в базу данных (действие, аналогичное тому, что выполняется
по команде «Загрузить библиотеку в базу данных» в утилите CardManager) на
конкретном рабочем сервере.
Если решение предполагается установить на один конкретный сервер (разовая
операция), то это действие можно выполнить вручную при помощи приложения
CardManager (установив на этот сервер пакет DocsVision Resource Kit) или запуском
SQL-скрипта, предварительно сгенерированного CardManager для этой библиотеки
карточек (команда «Сгенерировать сценарий SQL для библиотеки карточек»). Оба этих
способа приведут к одинаковому результату – загрузке описаний карточек решения в
конкретную базу данных.
ВНИМАНИЕ
При каждом обновлении версии платформы на сервере все дополнительные
решения необходимо заново загружать в базу данных. В противном случае
карточки этих решений будут считаться устаревшими и станут недоступны для
использования (данные не будут потеряны, просто карточки решения не будут
видны в Навигаторе).
Если же решение планируется тиражировать (устанавливать более чем на одной
площадке), то выполнять обновление базы данных каждый раз вручную будет
нецелесообразно. В этом случае рекомендуется создание отдельной инсталляционной
программы для серверной части решения, с помощью которой обновление базы данных
будет выполняться в автоматическом режиме.
Такая инсталляционная программа может быть создана при помощи любых
специализированных средств (Install Shield, Visual Studio 2003 или 2005, WISE и т.п.),
предназначенных для создания инсталляций. В состав этой инсталляционной
программы можно будет включить специальный шаг, который будет исполнять SQLскрипт по загрузке карточек решения в базу данных (выбор конкретной базы данных
можно реализовать в диалоге в рамках этой же инсталляционной программы или
прочитать имя текущей рабочей базы данных из реестра). Содержание данного шага
зависит от конкретной среды создания инсталляционных программ (InstallShield,
например, предлагает встроенный инструмент для исполнения SQL-сценариев; в других
средах может понадобиться написать код для исполнения SQL самостоятельно и т.д).
Кроме этого, в число задач серверной установки входит размещение
инсталляционного пакета клиентской части решения (о создании этого пакета
рассказывается ниже) в определённой папке на сервере, откуда этот пакет может быть
загружен всеми клиентами. Пакет достаточно просто скопировать в заданную папку,
которая обычно расположена по пути:
\ProgramFiles\DocsVision\Platform\<Версия_платформы>\Server\Site\Setup\
<Имя_решения>.
Тогда этот инсталляционный пакет будет доступен с клиентских машин по URL:
http://<имя_сервера>/<вирт_папка>/Setup/<имя_решения>/<название_пакета>.
DocsVision 4.5: Руководство разработчика на платформе
208
Пример: http://localhost/DocsVision/Setup/TakeOfficeClient/TakeOfficeClient.msi
Возможны также какие-то дополнительные действия, которые должны быть
выполненны в процессе установки серверной части решения – это может быть
регистрация и запуск каких-то специализированных сервисов, установка прикладных
бизнес-процессов, создание виртуальных папок в IIS и т.п. В этом случае необходимые
файлы этих дополнительных компонент решения рекомендуется размещать по пути:
\ProgramFiles\DocsVision\<Имя_решения>\<Версия>\Server\.
А необходимые для работы решения дополнительные настройки рекомендуется
сохранять в реестре по пути:
HKEY_LOCAL_MACHINE\DocsVision\<Имя_решения>\<Версия>\.
6.2
МОДУЛЬ РАСШИРЕНИЯ КОНСОЛИ НАСТРОЙКИ
В ряде случаев задача установки серверной части решения может быть усложнена
необходимостью выполнения каких-то дополнительных действий, которые сложно (или
невозможно) выполнить в рамках ограниченных возможностей инсталляционной
программы. Такими действиями, в частности, могут являться:
работа с базой данных;
установка или конфигурирование NT-сервисов;
создание Web-сайтов или виртуальных папок в IIS;
взаимодействие с другими компонентами или решениями;
изменение параметров работы решения после окончания установки
и т.п.
Для упрощения решения этих задач предоставляется возможность разработки
специального программного компонента - модуля расширения (Snap-In) для Консоли
настройки DocsVision.
ПРИМЕЧАНИЕ
Консоль
настройки
DocsVision
–
универсальный
инструмент
для
конфигурирования и администрирования сервера DocsVision. Подробнее его
использование рассмотрено в «Руководстве администратора».
Механизм Snap-Ins (модулей расширения) является способом динамического
расширения функциональности Консоли настройки новыми возможностями, которые
могут появляться при установке в системе дополнительных модулей или решений.
Аналогами подобного механизма могут выступать оснастки консоли администрирования
(MMC) в Microsoft Windows или механизм плагинов (Plag-ins) в других программых
средах.
ПРИМЕЧАНИЕ
В частности, средства конфигурирования стандартных решений «Управление
процессами» и “Процессы WWF” также реализованы в виде модулей расширения
для Консоли настройки – их можно рассматривать в качестве примера
реализации.
Консоль настройки может работать в двух режимах:
Режим конфигурирования (Мастера) – этот режим активируется при
первичной установке или удалении конкретного решения (или сервера
DocsVision в целом);
Режим администрирования - этот режим активируется на рабочем сервере
для изменения конкретных параметров работы сервера и/или конкретных
решений.
DocsVision 4.5: Руководство разработчика на платформе
209
Соответсвенно, каждый Snap-In для Консоли настройки также имеет возможность
использовать один или оба этих режима. Например, можно реализовать Snap-In для
собственного решения, который будет активироваться как при его установке (для
выполнения каких-то сложных действий по регистрации компонент), так и позволит
администратору системы менять какие-то параметры в процессе его работы.
В качестве Snap-In Консоли настройки может выступать любой программный
компонент, реализующий ряд специальных интерфейсов (по аналогии с компонентами
карточек DocsVision).
В коде компонента Snap-In могут быть реализованы следующие интерфейсы (все
интерфейсы объявлены в сборке DocsVision.Tools.ServerConsole.Interfaces.dll, которую
необходимо подключить к проекту):
DocsVision.Tools.ServerConsole.ISnapIn – обязательный интерфейс для любого
модуля расширения. Предполагает реализацию следующих свойств и методов:
public string Name – свойство, которое должно возвращать отображаемое имя
модуля расширения
public void Initialize(IEnvironment environment) – метод, который вызывается
при первичной инициализации модуля расширения. На вход метода передается
объект, описывающий контекст исполнения (Консоль Настройки)
public object QueryInterface(SnapInInterfacesEnum itfType) – метод, который
вызывается при запросе конкретных функций модуля расширения. Модуль
расширения может выполнять следующие функции:
public enum SnapInInterfacesEnum
{
CONFIGURATOR = 0,
// Первичная инсталляция решения
WIZARD_CONTROL = 1,
// Инсталляция в режиме Мастера
CONSOLE_CONTROL = 2,
// Режим администрирования (настройки)
TOOLS = 3,
// Дополнительные инструменты
UNINSTALL_SNAP_IN = 4, // Режим деинсталляии (удаления) решения
DB_INFORMATION = 5
// Режим обновления базы данных
}
При запросе конкретной функции модуль расширения может либо вернуть ссылку
на объект, реализующий соответствующий интерфейс (если он выполняет эту
функцию), либо просто ничего не вернуть (если он не выполняет эту функцию);
DocsVision.Tools.ServerConsole.IDBInformation – данный интерфейс является
обязательным
для
модулей
расширения,
которые
выполняют
функции
конфигурации или удаления решения. Методы данного интерфейса предназначены
для загрузки каких-либо значений в базу данных (например, это необходимо при
установке новых библиотек карточек, или шлюзов Workflow). Интерфейс
предполагает реализацию следующих свойств и методов:
string GetScript(ScriptTypeEnum type) – Консоль настройки может запросить
данное свойство при выполнении каких-либо действий с базой данных. В
зависимости от типа действия (ScriptTypeEnum), модуль расширения должен
вернуть одно из следующих значений:
INSTALL_TABLES – путь к файлу SQL-скрипта создания таблиц (для библиотек
карточек);
INSTALL_ACTIONS – путь к файлу SQL-скрипта создания хранимых процедур (для
библиотек карточек);
INSTALL_FT_CATALOGS – путь к файлу SQL-скрипта создания полнотекстовых
каталогов;
UNINSTALL_FT_CATALOGS – путь к файлу SQL-скрипта удаления полнотекстовых
каталогов;
DocsVision 4.5: Руководство разработчика на платформе
210
UNREGISTER_CARD_LIBRARY – путь к файлу SQL-скрипта удаления библиотеки
карточек;
UNINSTALL_ALL – путь к файлу SQL-скрипта удаления других данных решения;
string GetCardPackage() – это свойство может вернуть путь к файлу – пакету
инсталлируемых XML-описаний карточек (это может потребоваться в случае, если
для корректной работы решения необходимо налиичие в базе данных каких-то
предопределённых значений – заполненных справочников, шаблонов карточек и
т.д.).
Файл с описанием пакета имеет следующий формат:
<?xml version="1.0" encoding="UTF-8"?>
<CardPackage>
<Card Path="<путь_к_файлу_XML" ID="ID_карточки" Replace="1 если карточка
должна заменить существующую; 0 – если дополнить"/>
…
</CardPackage>
bool ContainsCardLib { get; } – признак, содержит ли данное решение
библиотеку карточек (нужно ли запрашивать SQL-скрипты дял создания таблиц и
хранимых процедур).
DocsVision.Tools.ServerConsole.IConfigurator – необязательный интерфейс.
Может быть реализован в модуле расширения, выполняющем функции первичной
конфигурации решения (SnapInInterfacesEnum.CONFIGURATOR). Предполагает
реализацию следующего метода:
public bool Execute() – единственный метод, который должен выполнять все
задачи по корректной инсталляции решения. Возвращаемое значение
показывает успешность (true) или неудачу (false) установки;
DocsVision.Tools.ServerConsole.IUninstallSnapIn – необязательный интерфейс.
Может быть реализован в модуле расширения, выполняющем функции удаления
решения (SnapInInterfacesEnum.UNINSTALL_SNAP_IN). Предполагает реализацию
следующего метода:
public void Uninstall(bool removeSettings) – единственный метод, который должен
выполнять все задачи по корректному удалению решения. Входящий параметр
указывает на необходимость удалить (true) или сохранить (false) настройки
решения;
DocsVision.Tools.ServerConsole.ITools – необязательный интерфейс. Может быть
реализован
в
модуле
расширения,
дополняющим
Консоль
Настройки
специфическими Инструментами (SnapInInterfacesEnum.TOOLS). Предполагает
реализацию следующего метода:
public IControl[] Controls –
свойство, которое должно возвращать массив
элементов управления для конкретных инструментов. Элемент управления для
реализации каждого инструмента должен реализовывать интерфейс IControl
(IControl2);
DocsVision.Tools.ServerConsole.IConsoleControl – необязательный интерфейс.
Может быть реализован в элементе управления, который будет отображаться
пользователю
при
установке
в
режиме
Мастера
(SnapInInterfacesEnum.WIZARD_CONTROL), или в режиме администрирования
(SnapInInterfacesEnum.CONSOLE_CONTROL). Интерфейс предполагает реализацию
следующих свойств и методов:
public event ControlChangedDelegate ControlChanged – событие, которое элемент
управления должен инициировать при изменении данных;
public string Caption – свойство, возвращающее отображаемое имя элемента
управления;
DocsVision 4.5: Руководство разработчика на платформе
211
public UserControl Instance
управления WinForms;
–
свойство,
возвращающее
ссылку
на
элемент
public bool Changed – признак изменения настроек решения;
public bool Valid – признак корректности указанных настроек решения;
public void Initialize() – метод первичной инициализации элемента управления;
public bool Execute() – метод, вызываемый при завершении конфигурирования;
Пример кода модуля расширения с реализацией этих интерфейсов:
namespace DocsVision.Sample.SnapIn
{
public class SnapIn : ISnapIn, IConfigurator, IUninstallSnapIn
{
private IEnvironment _environment;
// Реализация интерфейса ISnapIn
public SnapIn()
{
}
public string Name
{
get
{
return "My Snap-In";
}
}
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;
}
// Реализация интерфейса IConfigurator
public bool Execute()
{
// Регистрация компонент решения
return true;
}
// Реализация интерфейса IUninstallSnapIn
public void Uninstall(bool removeSettings)
{
// Разрегистрация компонент решения
}
}
}
В коде модуля расширения, можно обращаться к различным вспомогательным
сервисам, предоставляемым Консолью настройки для упрощения решения типовых
задач. Для этого нужно воспользоваться ссылкой на объект контекста (IEnvironment),
которая передается модулю расширения при инициализации. Этот объект имеет
единственный метод:
DocsVision 4.5: Руководство разработчика на платформе
212
object
QueryService(EnvironmentServiceEnum
service)
– возвращающий
ссылку на конкретный вспомогательный сервис, запрошенный в параметре.
Доступны следующие сервисы:
EnvironmentServiceEnum.LOG – возвращает ссылку на сервис ILog, позволяющий
записывать сообщения в общий журнал работы Консоли настройки;
EnvironmentServiceEnum.COMMON_SETTINGS – возвращает ссылку на сервис
ICommonSettings(2), позволяющий прочитать и/или изменить основные
настройки сервера DocsVision;
EnvironmentServiceEnum.WORKER_PROCESS
– возвращает ссылку на сервис
IWorkerProcess,
позволяющий
модулю
расширения
корректно
функционировать
при
выполнении
длительных
операций
(например,
отображать индикатор прогресса выполнения). Для реализации таких
операций,
соответствующие
объекты
модуля
расширения
должны
реализовывать интерфейс ILengthyOperation(3);
EnvironmentServiceEnum.DB_INSTALLER
–
возвращает ссылку на сервис
IDbInstaller, позволяющий выполнять операции с базой данных (например,
исполнить сценарий SQL из строки или из файла);
EnvironmentServiceEnum.CARD_LIB_CONFIGURATOR – возвращает ссылку на сервис
ICardLibConfigurator(2), позволяющий корректно установить или удалить
описание библиотеки карточек;
EnvironmentServiceEnum.CARD_IMPORTER
–
возвращает ссылку на сервис
ICardImporter, позволяющий загрузить в базу данных предопределённые
значения (экспортированные в формат XML);
EnvironmentServiceEnum.MANAGEMENT
–
возвращает
ссылку
на
сервис
IManagement, позволяющий управлять работой других сервисов и решений.
Пример использования вспомогательного сервиса Консоли настройки в модуле
расширения для записи сообщения в журнал:
ILog log = (ILog)_environment.QueryService(EnvironmentServiceEnum.LOG);
log.WriteMessage(“Конфигурирование решения успешно завершено”);
Разработанный модуль расширения необходимо зарегистрировать на сервере в
процессе инсталляции серверной части решения. Для этого программа инсталляции
должна создать в реестре ключ в ветке HKLM\Software\DocsVision\<версия>\
Console\Snap-Ins.
Необходимо создать ключ с именем своего модуля расширения, в котором создать
два строковых значения:
Path – полный путь к сборке, в которой реализован модуль расширения;
TypeName – имя основного класса, реализующего интерфейс ISnapIn в
разработанном модуле расширения (например,
DocsVision.Sample.SnapIn.SnapIn).
Для того, чтобы запустить Консоль настройки в режиме конфигурирования нового
модуля расширения, необходимо запустить её исполняемый файл с ключами:
ServerConsole.exe /c /n <имя_решения>.
Вызов этой команды можно
серверной части решения.
6.3
сделать
последним
шагом
программы
инсталляции
ИНСТАЛЛЯЦИЯ КЛИЕНТСКОЙ ЧАСТИ РЕШЕНИЯ
Для корректной работы разработанного решения на клиентских компьютерах там
должны быть установлены и зарегистрированы компоненты карточек, библиотеки
карточек, а также всех вспомогательных библиотек, использованных при разработке.
DocsVision 4.5: Руководство разработчика на платформе
213
Платформа DocsVision предусматривает их автоматическую установку при первом
обращении к серверу DocsVision при помощи специализированной программы
инсталляции в формате Windows Installer (MSI), которую также должен создать
разработчик решения.
Создать инсталляционный MSI-файл можно при помощи специализированных
приложений, предназначенных для создания программ инсталляции. Например, это
может InstallShield (Windows Installer Edition), либо можно воспользоваться средствами
подготовки инсталляций в составе Microsoft Visual Studio (2003 или 2005). В процессе
создания MSI-файла в него нужно включить компонент библиотеки и компонент(ы)
карточек. Для всех COM-компонентов следует указать на необходимость их
регистрации (extract-at-build или self-register).
В процессе создания инсталляционного пакета необходимо указать следующие
его параметры:
название, описание, производитель;
версия (желательно, чтобы она совпадала с версией библиотеки карточек);
код продукта (ProductCode) – уникальный код инсталляционного пакета
(будет сгененрирован автоматически);
базовый путь для установки файлов.
Путь для установки файлов обычно зависит от выбранной области установки. При
установке «Только для текущего пользователя» это обычно путь:
$\Documents and Settings\<Название_профиля>\Local Settings\
DocsVision\ <Решение>\<Версия>\Client\,
а при установке в область «Для всех пользователей» - путь:
$\Program Files\DocsVision\<Решение>\<Версия>\Client\.
ВНИМАНИЕ
Особенность работы Windows Installer такова, что даже при установке в режиме
«только для текущего пользователя», ключи реестра для библиотек типов
(TypeLib) будут создаваться в общей ветке реестра (HKEY_LOCAL_MACHINE). В
случае отсутствия у пользователя административных привелегий на компьютере,
это может привести к ошибкам в процессе установки и некорректному
функционированию решения. Для избежания подобных ошибок желательно
отказаться от регистрации библиотек типов (если они не нужны) – для этого
нужно проследить, чтобы в таблице TypeLib инсталляционного пакета не было
никаких записей.
После создания инсталляционного пакета его необходимо сопоставить с
библиотекой карточек. Это делается при помощи утилиты CardManager - в описании
библиотеки на вкладке Installers:
DocsVision 4.5: Руководство разработчика на платформе
214
Рис. 6.1. Вкладка Инсталляционные программы
Поле PackageID (значение генерируется автоматически) содержит уникальный
идентификатор данной программы инсталляции (у библиотеки может быть несколько
инсталляционных программ). В поле ProductCode необходимо скопировать
идентификатор программы установки, сгенерированный при её создании, а в поле
Installer – имя файла с относительным путем, по которому на сервере будет
расположен инсталляционный пакет.
Готовый клиентский инсталляционный пакет необходимо расположить на сервере
(вручную или при помощи программы инсталляции серверной части решения), где он
будет доступен для скачивания и установки всем клиентам (см. выше).
При обновлении версии решения на сервере клиентские компоненты будут
обновлены на новую версию автоматически при первом обращении клиента к
обновленному серверу.
ВНИМАНИЕ
Для корректного обновления решения на клиентских машинах при изменении
версии на сервере в инсталляционном пакете новой версии решения необходимо
сгенерировать
новый
ProductCode,
но
оставить
прежнее
значение
UpgradeCode.
DocsVision 4.5: Руководство разработчика на платформе
215
7
ПРИЛОЖЕНИЯ
7.1
ПАРАМЕТРЫ СОЕДИНЕНИЯ
ConnectAddress – адрес сервера. В зависимости от используемого протокола,
может принимать одно из следующих значений (адрес однозначно определяет
протокол, и наоборот):
HTTP (SOAP):
http[s]://<server[:port]>/<Folder>/StorageServer/StorageServerService.asmx
HTTP (Remoting):
http[s]://<server[:port]>/<Folder>/StorageServer/StorageServerService.rem
Named Pipes (Remoting):
\\<server>\Pipe\DocsVision41\StorageServer или
net.pipe://<server>/DocsVision41/StorageServer
HTTP (WCF):
http[s]://<server[:port]>/<Folder>/StorageServer/StorageServerService.svc
Named Pipes (WCF):
net.pipe://<server>/StorageServer/StorageServerService.svc
TCP (WCF):
net.tcp://<server[:port]>/StorageServer/StorageServerService.svc
BaseName – псевдоним базы данных (имя, под которым она подключена к
серверу). Данный параметр является опциональным – если его значение не
указать, то будет использована база данных по умолчанию;
UserName – имя пользователя (при использовании базовой аутентификации)
Password – пароль (при использовании базовой аутентификации)
Proxy – адрес прокси-сервера (при использовании прокси). Если адрес проксисервера НЕ указан, то будут использованы настройки Internet Explorer.
ProxyBypass – список имен серверов, при соединении с которыми не будет
использован прокси-сервер (таким образом, если нужно соединяться с
сервером DocsVision в обход прокси, то его имеет смысл добавить сюда )
AllowAutoProxy – использовать скрипт автоматического определения прокси,
заданный в настройках Internet Explorer (используется для протокола HTTP);
Timeout – таймаут ожидания ответа сервера (при установке соединения, а
также при выполнении всех последующих операций). Задается в
миллисекундах. Значение 0 указывает на необходимость использования
значения по умолчанию, которое равно 3 минуты)
IgnoreInvalidCert – игнорировать неправильный сертификат сервера при
использовании SSL
ClientCertificate – клиентский сертификат (если используется SSL с
требованием клиентского сертификата)
DocsVision 4.5: Руководство разработчика на платформе
216
7.2
СВОЙСТВА СЕССИИ
Информация о пользователе:
AccountName (string) – имя учетной записи пользователя.
ComputerName (string) – имя компьютера пользователя.
ComputerAddress (string) – IP-адрес компьютера пользователя
ClientVersion (int) – версия клиентских компонент (версия ObjectManager.dll).
LocaleID (int) – числовой идентификатор текущего языка (на этом языке будут
возвращаться все строковые значения и описания ошибок)
AppID (string) – идентификатор приложения, из которого установлено
соединение. Например, идентификатор {8F47FCAF-6FC8-458E-910C5FCC4FFE6AF7} соответствует Навигатору DocsVision.
IsAdmin (bool) – является ли пользователь администратором (группа
DocsVision Administrators на сервере).
IsWFCreator (bool) – может ли пользователь создавать процессы WF (группа
DocsVision Workflow Creators на сервере).
IsSQCreator (bool) – может ли пользователь создавать новые поисковые
запросы (группа DocsVision Search Query Creators на сервере)
IsArchiveOperator (bool) – может ли пользователь работать с долговременным
архивом (группа DocsVision Archive Operators на сервере).
IsPowerUser (bool) – является ли пользователь привилегированным или
обычным (группа DocsVision Power Users на сервере).
Информация о сервере:
ConnectAddress (string) – адрес соединения с сервером.
ServerName (string) – имя компьютера сервера.
ServerUrl (string) – URL к корню WEB-сервера.
ServerTime (DateTime) – текущее время на сервере.
ServerVersion (int) – версия сервера (версия DocsVision.StorageServer.dll).
Logging (int) – уровень журналирования.
Информация о лицензии сервера:
Features (Guid[]) – список разрешенных дополнительных модулей
Languages (string[]) – список поддерживаемых языков пользовательского
интерфейса
ExpirationDate (DateTime) – дата окончания срока действия лицензии сервера
UpgradeLimit (DateTime) - дата окончания срока действия возможности
обновления сервера
License (string) – полный XML лицензионного ключа
Информация о базе:
BaseName (string) – псевдоним базы
BaseVersion (int) – версия базы (dvsys_global_info)
BaseReadOnly (bool) – работает ли база в режиме «только чтение»
ReplState(bool) – находится ли база под репликацией
FullTextSearchEnabled (bool) – включён ли на базе полнотекстовый поиск
Настройки соединения:
Compression (true) – использовать или нет сжатие при передаче данных по
сети
MinCompressSize (int) – минимальных блок данных (в kb) который нужно
сжимать
FileBlockSize (int) – размер блока данных (в kb) для пересылки файлов
(пересылаются кусками)
CardPoolSize (int) – количество карточек в кэше ObjectManager
DocsVision 4.5: Руководство разработчика на платформе
217
Timeout (int) – величина (в ms) максимального ожидания ответа сервера при
установке соединения или выполнении операций
PageSize (int) – размер блока данных (в kb) для пересылки данных карточек
7.3
ПАРАМЕТРЫ ВЫБОРА СПРАВОЧНИКОВ
В таблице приведены примеры параметров выбора значений из справочников
решения Делопроизводство.
Справочник
Параметры (activateParams)
Сотрудников
0 – ID секции, из которой выбираем (сотрудники, подразделения,
роли, группы, должности)
1 – ранее выбранный элемент
2 – подразделение в дереве, на которое надо
спозиционироваться, если не указан 1
3 – True, если режим поиска
4 – SectionFilter на дерево подразделений
5 – True, позволять выбор нескольких элементов
6 – True, специальный режим, который при выборе вернет не ID,
а учетные записи
7 – True, если требуется показ сертификатов сотрудников в гриде
при выборе
Контрагентов
0 – ID секции, из которой выбираем (сотрудники, подразделения,
роли, группы подразделений)
1 – ранее выбранный элемент
2 – подразделение в дереве, на которое надо
спозиционироваться, если не указан 1
3 – True, если режим поиска
4 – SectionFilter на дерево подразделений
5 – True, позволять выбор нескольких элементов
Универсальный
0 – ID секции, из которой выбираем (типы, записи)
1 – ранее выбранный элемент
2 – тип, которым ограничиваем выбор, при выборе записей
5 – True, позволять выбор нескольких элементов
Типов
0 – ID секции, из которой выбираем (только типы)
1 – ранее выбранный элемент
2 – категория
3 – True, позволять выбор нескольких элементов
5 – если число, то это Enum поля DocumentTypes, если GUID – ID
пользовательского типа карточек
Нумераторов
0 – ID секции, из которой выбираем (только нумераторы)
1 – ранее выбранный элемент
Ссылок
0 – ID секции, из которой выбираем (только типы ссылок)
DocsVision 4.5: Руководство разработчика на платформе
218
1 – ранее выбранный элемент
3 – True, позволять выбор нескольких элементов
Категорий
2 – True, позволять выбор нескольких элементов
Номенклатуры
дел
0 – ID секции, из которой выбираем (дела, папки)
1 – ранее выбранный элемент
DocsVision 4.5: Руководство разработчика на платформе
219