Использование "общих справочников" в разработке

Функциональная возможность "общие справочники" включает режим использования данных из справочников только в режиме чтения и призвана сократить потребление памяти и повысить производительность любого приложения, реализованного с применением клиентского API Docsvision. Функциональность доступна для Web-клиента, начиная с версии 17, данная статья описывает взаимодействие с режимом при разработке собственных решений.

Если при разработке кода решения для работы со справочниками используется сборка DocsVision.Platform.ObjectModel.dll (или DocsVision.BackOffice.ObjectModel.dll) решение будет автоматически работать и с общими справочниками. Стандартная логика Docsvision реализует автоматическое переключение режима работы со справочниками в зависимости от того читаются данные или изменяются.

Функциональность доступна только при использовании DocsVision.Platform.ObjectManager.Rest.dll в качестве API для работы с системой.

Если код решения взаимодействует со справочниками через DocsVision.Platform.ObjectManager.dll разработчику доступны два варианта:

  • При работе на стороне Web-клиента для доступа к общим справочникам необходимо использовать методы класса CardManager — GetDictionaryAsReadonly и GetDictionaryDataAsReadonly. Эти методы передают доступные только для чтения CardData запрошенных справочников.

  • Если код работает вне Web-клиента, необходимо до использования методов GetDictionaryAsReadonly и GetDictionaryDataAsReadonly создать сессию, через которую будет осуществляться чтение данных справочников и установить эту сессию как общую путём вызова SessionManager.SetCommonSession. Для создания сессии следует использовать УЗ, обладающую правами чтения всех данных справочников, например, состоящую в группе DocsVision Administrators.

Основные особенности использования функциональности общих справочников

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

  2. Вызов RowData.Refresh у строчек справочников в режиме чтения приведёт к ошибке для данных, полученных таким образом.

  3. Для сохранения совместимости не рекомендуется возвращать справочники в режиме чтения в старых публичных методах, где возвращались справочники не в режиме чтения.

  4. Рекомендуется использовать интерфейс IReadOnly<T> при работе со справочниками в режиме чтения через классы ObjectManager, см. ниже.

  5. При работе со справочниками через API ObjectModel дополнительных действий не требуется.

  6. Справочники в режиме чтения не повышают производительность в однопользовательских приложениях как, например, Конструктор Web-разметок или Панель управления Web-клиентом.

Использование интерфейса IReadOnly<T>

При вызове методов с параметрами, которые имеют типы справочников или строчек справочников из ObjectManager (CardData, RowData, FolderCard, Folder и т.д.) во время компиляции отсутствует проверка того, что в качестве аргументов были переданы справочники или строки в режиме чтения. В результате разработчик может случайно изменить вызываемый метод, добавив в него код модификации для передаваемых в качестве аргументов справочников, не зная, что в этот метод могут быть переданы справочники в режиме чтения. Если аргументы попадут в метод по цепочке вызовов, отследить такие операции, определить, в каком режиме они используются, будет сложно.

Рекомендуется использовать в объявлении аргументов интерфейс-обертку IReadOnly<T>, чтобы не забывать, что метод работает со справочниками в режиме чтения.

Интерфейс служит напоминанием о том, что обертываемый объект (справочник или строка) может быть в режиме чтения. Обычный справочник или строка справочника могут быть приведены к IReadOnly<T> с помощью метода расширения AsReadOnly(), что является безопасным, т.к. с обычным справочником можно делать то же, что со справочником в режиме чтения плюс модификация и обновление.

Интерфейс IReadOnly<T> содержит метод Apply, который используется, например, следующим образом:

IReadOnly<FolderCard> folderCard = …
IReadOnly<Folder> folder = folderCard.Apply((FolderCard f)=>f.GetFolder(folderId));

Если типы не проставлены явно:

Var folder = folderCard.Apply( f => f.GetFolder(folderId));

Метод-расширение Unwrap() возвращает обертываемое значение. Его использование является небезопасным, но необходимым. Использовать Unwrap желательно как можно позже, в противном случае использование маркерного интерфейса теряет своё значение. Метод реализован как расширение, чтобы не вызывать ошибку при вызове, когда объект типа IReadOnly<T> null.