Правила разработки для лёгкого переноса и конвертации

Каждый знает, что процесс конвертации на новую версию DIRECTUM может быть не самым простым. Чаще всего он усложняется в системах с многочисленными доработками, интеграциями или при конвертации с большой разницей между текущей и новой версиями. Одной из причин такого усложнения является то, что большинство стандартных решений дорабатывается под конкретные нужды организации без учёта конвертации системы в будущем. Далее будут приведены рекомендации, следуя которым вы сможете упростить не только конвертацию, но и перенос разработки на другие системы.

Правильное наименование – первый шаг к успеху!

Как бы просто это ни звучало, но правильное наименование позволяет избежать ряда проблем в будущем. Основная суть данной рекомендации заключается в применении префиксов в названии элементов разработки. Такой подход позволяет сделать имя элемента/разработки уникальным.

Префиксы стоит использовать для вновь создаваемых элементов разработки.

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

1. Разработка новых модулей системы. В случае если ведётся разработка модуля для системы DIRECTUM с целью его распространения, то для всей прикладной разработки стоит придумать свой префикс.
   Например, в стандартной поставке DIRECTUM разработка, связанная с модулем «Интеграция с системами обмена документами», имеет префикс DISI (DIRECTUM Interchange Systems Integration).

2. Для модификаций внутри организации, дополняющих стандартную функциональность, также следует придумать и использовать уникальный префикс. В качестве префикса можно взять любое сочетание букв/цифр, главное, чтобы вся дополнительная разработка содержала его. Обычно, в качестве префикса предлагается использовать краткое наименование организации.
   Например, модификации для Very Fast Motor могут иметь логичный префикс VFM, а сценарий для отправки уведомлений, будет иметь наименование: VFMSendNotice.

Ниже приведён список элементов/компонент разработки, для которых данная рекомендация является актуальной:

• наименования блоков, групп блоков и реквизиты Код типовых маршрутов;
• названия (и имена полей) реквизитов электронных документов;
• наименования типов карточек документов;
• названия (и имена полей) реквизитов справочников;
• наименования типов справочников;
• наименования констант;
• наименования отчётов;
• наименования сценариев;
• наименования функций;
• наименования диалогов.

Используйте для идентификаторов объектов параметры и константы.

Очень часто разработчики стараются «вшить» в код конкретные ИД или Коды объектов. Для наглядности давайте рассмотрим процесс формирования комплекта договорных документов из макетов. В случае большого количества макетов, это может выглядеть так:

ListActsID = CreateList()
ListActsID.Add("Схема располсжения ЗУ"              ; 638051) 
ListActsID.Add("Технический план"                   ; 638056)
ListActsID.Add("Межевой план"                       ; 638048)
ListActsID.Add("Выбор трассы"                       ; 638048)
ListActsID.Add("Выкопи ровка"                       ; 637978)
ListActsID.Add("Вынос границ"                       ; 637985)
ListActsID.Add("Земляные работы"                    ; 638045)
ListActsID.Add("Акт обследования"                   ; 637855)
ListActsID.Add("ГКУ объекта кап. строительства"     ; 637897)
ListActsID.Add("ГКУ участка"                        ; 637910)
ListActsID.Add("Межевой план + ГКУ"                 ; 637916)
ListActsID.Add("Схема + МП"                         ; 637928)
ListActsID.Add("Технический план + ГКУ"             ; 637969)
ListActsID.Add("Схема + МП + ГКУ"                   ; 637930)
ListActsID.Add("Съемка"                             ; 637939)
ListActsID.Add("Съемка + МП"                        ; 637942)
ListActsID.Add("Съемка + схема"                     ; 637946)
ListActsID.Add("Съемка + схема + МП"                ; 637950)
ListActsID.Add("Съемка + схема + МП + ГКУ"          ; 637956)
ListActsID.Add("Изыскания"                          ; 638626)
ListActsID.Add("Схема на использование"             ; 699487)

Выше показан плохой подход к написанию кода. Представленный выше вариант не адаптирован для переноса между системами. Более правильным будет вынести ИД макетов из кода на уровень администрирования. Например, когда ИД документов не очень много, то для их хранения можно использовать константы или параметры ТМ, в зависимости от места использования данных значений. В данном примере было бы правильнее сделать ещё один справочник (т.к. макетов гораздо больше, чем показано тут) и уже в нем указать макеты документов и связываемый элемент. Такой подход обеспечил бы как лёгкость переноса разработки между системами, так и упрощение настройки данного решения, ведь её смог бы проводить администратор без участия разработчика.

Что стоит выносить в константы и параметры ТМ? Отдельно стоит выносить только идентификаторы объектов и данные, которые могут измениться при переносе на другую систему.
Пример данных, которые стоит выносить в параметры или константы:  

• настройки подключения (систем интеграции, сервисов и т.д.);
• ИД документов (макеты, шаблоны и т.д.);
• Коды или ИД записей справочников;
• списки групп пользователей;
• списки пользователей;
• пути для записи log-файлов и т.п.;
• данные, которые могут быть изменены при переносе на другой сервер или систему.

Особенности при разработке типовых маршрутов

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

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

Это повысит удобство при настройке и позволит избежать ошибок из-за невнимательности.

Пишем SQL запросы правильно!

При составлении и использовании запросов к базе данных, стоит придерживаться ряда правил:

1. Не указывать в запросе явное имя таблицы, если его можно получить с помощью объектной модели IS-Builder.

   Давайте рассмотрим два примера:

   // Пример 1
   AUTOTEXT = References.AUTOTEXT.GetComponent
   SQLText = Format('select count(*) from dbo.MBAnalit where Vid = %s'; AUTOTEXT.ComponentID)

   // Пример 2
   AUTOTEXT = References.AUTOTEXT.GetComponent
   SQLText = Format('select count(*) from dbo.%0:s where Vid = %1:s'; 
          ArrayOf(AUTOTEXT.SQLTableName; AUTOTEXT.ComponentID))

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

2. Microsoft предлагает указывать в запросе обращения к объектам четырехсоставными именами:

   [server_name].[database_name].[schema_name].[object_name]

   Но также поддерживаются более короткие записи:

   [database_name].[schema_name].[object_name]

   [schema_name].[object_name]

   [object_name]

   Где:

   • server_name - Указывает имя связанного или удалённого сервера.
   • database_name - Указывает имя базы данных SQL Server, если объект хранится на локальном экземпляре SQL Server. Когда объект находится на связанном сервере, аргумент database_name указывает каталог OLE DB.
   • schema_name - Если объект находится в базе данных SQL Server, указывает имя схемы, которая содержит объект. Когда объект находится на связанном сервере, аргумент schema_name указывает имя схемы OLE DB.
   • object_name - Ссылается на имя объекта.

   Чтобы избежать ошибок разрешения имён, при указании объекта области схемы рекомендуется всегда указывать имя схемы:

   [schema_name].[object_name]

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

   • без указания схемы, SQL сервер начинает искать таблицу в схеме по умолчанию для пользователя. В случае если таблица не найдена в схеме пользователя, поиск таблицы будет продолжен в схеме по умолчанию для сервера. У такого подхода есть минус. В результате выполнения запроса могут вернуться данные из таблицы, расположенной в другой схеме;
   • каждый запрос будет компилироваться, а значит SQL сервер будет тратить время на его выполнение. Но только тратой серверных ресурсов тут дело не ограничивается, в дополнение ко всему есть вероятность, что кэш планов запросов разрастётся, что в дальнейшем может сказаться на производительности всей системы в целом.

   Ситуация в связи с переносом разработки может усугубиться, если дополнительно указать название сервера. Вариант с указанием названия сервера стоит использовать только в межбазовых запросах. В основном это интеграции с другими системами, когда интегрируемая система прилинкована к SQL серверу. В таких ситуациях название прилинкованного сервера необходимо указывать в константе и подставлять в SQL запрос перед выполнением.

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

   Получать в таких случаях название базы данных следует через константы и объектную модель:

   // Получение наименования базы данных Directum
   Application.Connection.DatabaseName

3. При составлении SQL запросов, ориентируйтесь на совместимость синтаксиса с последними версиями SQL серверов.
   В зависимости от уровня совместимости базы данных, появляется поддержка определённых команд или становится недоступной часть SQL синтаксиса.
   Вспомним о новом режиме Modern, который появился в DIRECTUM 5.4.
   О нем уже достаточно написано, однако не вся прикладная разработка без модификаций может работать в новом режиме. Данный режим появился ввиду отказа Microsoft от поддержки старых параметров соединения, что делает SQL ещё быстрее и стабильнее, однако требует модификаций текущей разработки.
   Рассмотрим два примера:

   -- Пример 1
   Select ValuePar from dbo.XIni where NamePar = "PlatformVersion"

   -- Пример 2
   Select ValuePar from dbo.XIni where NamePar = 'PlatformVersion'

   Запросы отличаются только кавычками, однако первый вариант не будет работать в новых редакциях MS SQL, а второй продолжит возвращать ожидаемые значения без доработок во всех редакциях MS SQL.

   Давайте ещё рассмотрим вариант запроса, который считается устаревшим:

   -- Устаревший вариант соединения таблиц
   select * from dbo.Orders o, dbo.Customers c where o.cnum *= c.cnum

   Операторы *= and =* для внешнего соединения перестали поддерживаться в базах с уровнем совместимости 90 (SQL Server 2005) и выше.

   Вариант для замены:

   -- Работающий вариант запроса
   select * from dbo.Orders o left join dbo.Customers c on c.cnum = o.cnum

4. Не рекомендуется вставлять и изменять данные в системе непосредственно через SQL запросы, т.к. эти манипуляции могут нарушить работу всей системы и вызвать проблемы.

   Правильным будет использовать объектную модель для вставки данных, через которую отработают все необходимые вычисления и зависимости. Также это исключит ряд проблем, которые могут быть вызваны изменением архитектуры платформы в будущем.

По возможности не вносите изменения в стандартную разработку

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

Пример наименования такой функции: VFMDayOfWeekName().

Изменение ISBL-кода в стандартной разработке необходимо выделять

Редко стандартное решение не дорабатывается под нужды организации. В таких случаях все свои доработки необходимо выделять и отмечать в коде. Хорошим правилом считается отмечать начало и конец изменений в коде хорошо видимым комментарием, а также единым обозначением.  Также не рекомендуется удалять стандартный код, для более понятного и лёгкого анализа в будущем.

Пример замены стандартной разработки:

// -----------------------------------------------
// Start Very Fast Motor 
// Мешало параллельно работать с задачами 
// -----------------------------------------------

// Object.Form.ShowModal
Object.Form.ShowNoModal

// -----------------------------------------------
// End Very Fast Motor 
// -----------------------------------------------

В данном примере в качестве контрольной метки используется название организации, что позволит в дальнейшем найти все внесённые изменения в разработку с помощью сценария «Поиск в текстах разработки».

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

Разберём ситуацию, когда Вам необходимо провести модернизацию стандартного модуля и добавить новый реквизит в разработку, ранее в ней не задействованный.

С одной стороны, это может показаться простым: берём незадействованный реквизит и используем его под свои нужды.
На самом деле беспорядочный подход способен вызвать проблемы при обновлении, т.к. в новой редакции модуля (разработки) данный реквизит может быть задействован. Для того чтобы избежать данных ситуаций, рекомендуется брать сгенерированный реквизит с максимально возможным порядковым номером или аналогичный сгенерированный реквизит с префиксом организации.

Пример: Вам необходимо добавить реквизит с типом Дата, в карточку документа. В списке незадействованных реквизитов существуют реквизиты от Дата3 до Дата7. Для уменьшения вероятности появления несовместимости в дальнейшем, более правильным будет выбрать реквизит с именем Дата7.

Использование реквизита с префиксом позволит избежать несовместимостей при обновлении, однако генерировать реквизиты стоит только тогда, когда в этом есть необходимость.

Данное правило не относится к полностью заказной разработке (например, к вновь созданному справочнику), т.к. при обновлении системы он не будет автоматически обновлён с помощью стандартного конвертера.

Документируйте как можно больше информации

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

Дополнительные материалы:

• Ошибки неуникальности имен при конвертации. Возможные проблемы и пути их решения
• Константы. Как и когда их использовать
• Обновление DIRECTUM на новую версию. Подготовительный этап. Первые вопросы и ответы на них
• Ошибка неуникальности реквизита при конвертации. Расследование.
• Общие соглашения об именовании (MSDN)