Отладка формул, выражений N3, сценариев и C#-скриптов

Введение

Атрибуты, сценарии, вызов процессов, задачи, фильтры, кнопки и правила на форме можно настроить c помощью формул, выражений N3 и C#-скриптов. Однако при их составлении могут возникнуть различные проблемы, например:

• ошибки в именах функций, атрибутов, шаблонов и переменных;
• синтаксические ошибки;
• бесконечные циклы в процессах, сценариях, выражениях и скриптах;
• ошибки в логике построения формулы, выражения N3 или скрипта;
• неправильный тип данных вычисляемого атрибута, аргументов или возвращаемых значений.

Здесь представлены методы проверки и отладки, позволяющие обнаружить и исправить ошибки в формулах, выражениях N3 и скриптах.

Проверка с помощью редактора выражений

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

Порядок проверки

1. Откройте формулу, выражение N3 или скрипт в полном редакторе выражений и нажмите кнопку «Проверить».
2. На вкладке «Ошибки» отобразятся выявленные синтаксические ошибки и ошибки в именах функций, атрибутов, шаблонов или переменных. На вкладках «Предупреждения» и «Информация» отобразятся сведения, позволяющие оптимизировать выражение или скрипт.
3. Устраните ошибки и снова выполните проверку.
4. Сохраните формулу, выражение N3 или скрипт, если ошибки отсутствуют.

Отладка формул и N3 с помощью вспомогательного атрибута

Если редактор выражений не выявляет ошибки в формуле или выражении N3, а результат вычисления не соответствует ожидаемому, протестируйте формулу или выражение N3 посредством вспомогательного атрибута.

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

Порядок отладки

1. Создайте отладочный вычисляемый атрибут с типом данных, который соответствует результату вычисления проверяемой формулы или выражения N3.

   Совет

   Если вы не уверены, какой тип данных подходит, создайте текстовый атрибут. Это позволит в большинстве случаев увидеть на форме значение, возвращаемое формулой или выражением N3, и определить его фактический тип.

2. Введите формулу или выражение N3 в поле «Вычисляемое значение».

3. Поместите атрибут на форму.
4. Создайте запись или экземпляр процесса и посмотрите, какие данные отобразятся в поле атрибута.
5. Чтобы получить ожидаемое значение атрибута, скорректируйте формулу или выражение N3.
6. Чтобы удостовериться в работоспособности формулы или выражения N3, попробуйте заменить некоторые части выражения на литералы.
7. Чтобы быстрее найти ошибки, по возможности разбейте формулу или выражение N3 на самостоятельные части и протестируйте их по очереди. После отладки отдельных частей попробуйте снова объединить, внеся необходимые исправления.

8. Если самостоятельные части формулы или выражения N3 вычисляются правильно, но при объединении отрабатывают некорректно (например, из-за ошибок приведения типов данных, использовании конструкций с локальной областью действия переменных (if, or, for, assert и т. п.) или неожиданном поведении комбинированного выражения), можно воспользоваться следующим подходом:

   • создайте промежуточные атрибуты требуемых типов, вычисляемые по корректным частям формулы или выражения N3;
   • используйте значения промежуточных атрибутов в итоговой формуле или выражении N3.

   Это позволит не только декомпозировать сложные вычисления, но и комбинировать формулы и выражения N3 оптимальным образом.

Приведение типов данных

Для преобразования текстовых значений в логические и числовые в формулах можно использовать функции BOOL() и DECIMAL().

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

Пример

1. Создайте атрибут AmountText типа «Текст».

2. Создайте атрибут AmountNumber:

   • Тип данных: число
   • Вычислять автоматически: флажок установлен
   • Вычисляемое значение: формула

   DECIMAL($AmountText) 
   

3. Поместите атрибуты на форму.

4. Введите в поле AmountText значение 10500, в поле AmountNumber должно отобразиться значение 10 500.
5. Введите в поле AmountText значение 10,500, в поле AmountNumber должно отобразиться значение 10,5.
6. Введите в поле AmountText значение 10.500, в поле AmountNumber должно отобразиться -.

Отладка формул с помощью функции VALUE()

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

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

Пример

1. Создайте атрибут Amount типа «Число».

2. Создайте атрибут AmountValidation:

   • Тип данных: текст
   • Вычислять автоматически: флажок установлен
   • Вычисляемое значение: формула

   VALUE($Amount, "Не заполнено поле Amount") 
   

3. Поместите атрибуты на форму.

4. Если в поле Amount не ввести значение, то в поле AmountValidation отобразится текст «Не заполнено поле Amount».

Отладка выборок

Если в формуле или выражении N3 используется выборка, которая должна возвращать один элемент, используйте функции FIRST() (в формулах) или once{}. (в выражениях N3), чтобы предотвратить ошибки, когда выборка вернет несколько элементов.

Если после ограничения выборки выражение возвращает ожидаемый результат, попробуйте конкретизировать выборку с помощью условий, например, where (в запросах from...select).

Если конструкция from...select не возвращает ожидаемую выборку, её следует заключить в функцию LIST().

Отладка C#-скриптов

Для поиска ошибок в C#-скриптах можно воспользоваться конструкцией try..catch, которая позволяет перехватить исключения.

Отладка C#-скрипта для кнопки

1. Откройте кнопку с операцией «C#-скрипт».

2. Чтобы выводить определённое сообщение об ошибке, если возникло исключение при нажатии кнопки, воспользуйтесь следующим образцом кода:

   C#-скрипт с отладкой

   using System; 
   using System.Collections.Generic; 
   using System.Linq; 
   using Comindware.Data.Entity; 
   using Comindware.TeamNetwork.Api.Data.UserCommands; 
   using Comindware.TeamNetwork.Api.Data; 
    
   class Script 
   { 
       public static UserCommandResult Main(UserCommandContext userCommandContext, Comindware.Entities entities) 
       { 
           // Добавьте код, в котором не требуется обрабатывать исключения. 
           string ResultDescription = ""; 
           try 
           { 
               // Добавьте код, который должен отработать в штатном режиме. 
               ResultDescription = "Успех"; 
           } 
           catch 
           { 
               // Добавьте код, который должен отработать в случае ошибки. 
               ResultDescription = "Ошибка"; 
               var resultError = new UserCommandResult 
               { 
                   // Указываем, что скрипт завершился с ошибкой, 
                   // и формируем об этом уведомление 
                   Success = false, 
                   // Ставим флаг необходимости сохранения 
                   // результирующей записи в базу данных. 
                   Commited = true, 
                   // Указываем, что следует вывести уведомление. 
                   ResultType = UserCommandResultType.Notificate, 
                   // Формируем уведомление. 
                   Messages = new[] 
                   { 
                       new UserCommandMessage 
                       { 
                           // Указываем уровень важности уведомления: 
                           // Critical, Fatal, Low, Major, None, Normal 
                           Severity = SeverityLevel.Normal, 
                           // Этот текст будет выведен в уведомлении и 
                           // журнале действий и ошибок 
                           // в случае срабатывания исключения. 
                           Text = string.Format("Результат: {0}", ResultDescription) 
                       } 
                   } 
               }; 
               return resultError; 
           } 
    
           var result = new UserCommandResult 
               { 
                   // Указываем, что скрипт выполнен успешно, 
                   // и формируем об этом уведомление 
                   Success = true, 
                   Commited = true, 
                   ResultType = UserCommandResultType.Notificate, 
                   Messages = new[] 
                   { 
                       new UserCommandMessage 
                       { 
                           Severity = SeverityLevel.Normal, 
                           // Этот текст будет выведен в уведомлении и 
                           // журнале действий и ошибок 
                           // в случае штатного завершения работы скрипта. 
                           Text = string.Format("Результат: {0}", ResultDescription) 
                       } 
                   } 
               }; 
               return result;     
       } 
   } 
   

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

Отладка C#-скрипта для задачи-выполнения сценария

1. Откройте на диаграмме процесса задачу-выполнение сценария.

2. Чтобы выводить определённое сообщение об ошибке, если возникло исключение при выполнении задачи, воспользуйтесь следующим образцом кода:

   using System; 
   using System.Collections.Generic; 
   using System.Linq; 
   using Comindware.Data.Entity; 
   using Comindware.TeamNetwork.Api.Data.UserCommands; 
   using Comindware.TeamNetwork.Api.Data; 
    
   class Script 
   { 
       public static string Main(Comindware.Process.Api.Data.ScriptContext context, Comindware.Entities entities) 
       { 
           // Добавьте код, в котором не требуется обрабатывать исключения. 
           string ResultDescription = ""; 
           try 
           { 
               // Добавьте код, который должен работать в штатном режиме. 
               ResultDescription = "Успех"; 
           } 
           catch 
           { 
               // Добавьте код, который должен отработать в случае ошибки. 
               ResultDescription = "Ошибка"; 
           } 
           // Эта строка отобразится в поле «Выходные данные» 
           // для события «Скрипт выполнен» в цепочке событий 
           // для задачи-выполнения сценария. 
           return string.Format("Результат: {0}", ResultDescription); 
       } 
   } 
   

3. Опубликуйте диаграмму процесса.

4. Создайте экземпляр процесса и перейдите к его диаграмме.
5. Откройте журнал изменений.
6. Нажмите значок рядом с названием задачи-выполнения сценария.
7. Отобразится цепочка событий.
8. Выберите событие «Скрипт выполнен».

9. Справа отобразится информация о выполнении скрипта, в том числе:

   • Контекстные объекты — ID экземпляра процесса, в котором был запущен скрипт;
   • Код — скрипт задачи-выполнения сценария;
   • Входные данные — данные, которые использовались в скрипте;
   • Выходные данные — результат выполнения скрипта.

Отладка сценариев

Чтобы выявить проблемы и определить действия в сценарии, которые выполняются с ошибкой, можно воспользоваться действием «Проверить результат выражения».

Порядок отладки

1. После элемента сценария, работу которого требуется проверить, добавьте действие «Проверить результат выражения» и настройте его.

2. В поле «Выражение» введите формулу:

   false 
   

3. В поле «Сообщение об ошибке» введите отладочное сообщение, например:

   Сценарий отработал корректно до элемента «<название действия>» включительно. 
   

4. Запустите сценарий.

5. Если все элементы до действия «Проверить результат выражения» выполнены успешно, отобразится отладочное сообщение:

   • Для сценария по любым событиям, кроме входа и выхода токена, сообщение об ошибке отобразится во всплывающем уведомлении в браузере, в журнале действий и ошибок ‌ на информационной панели и в журналах событий на вкладке «Операции».
   • Для сценария на входе или выходе токена сообщение об ошибке отобразится в цепочке событий, которую можно просмотреть следующим образом:
     • Перейдите к диаграмме экземпляра процесса.
     • Откройте журнал изменений.
     • Нажмите значок ‌ рядом с названием сценария.
     • Отобразится цепочка событий.
     • Справа от цепочки событий в пункте «Уведомления» отобразится сообщение об ошибке.

6. Если какой-либо элемент до действия «Проверить результат выражения» не был выполнен, отладочное сообщение не отобразится.

   • Исправляйте ошибки в сценарии до тех пор, пока не отобразится отладочное сообщение.

7. Переместите действие «Проверить результат выражения» ниже по сценарию и укажите в отладочном сообщении название проверяемого элемента.

8. Снова запустите сценарий и проверьте его выполнение.
9. Проверьте весь сценарий, последовательно перемещая отладочное действие «Проверить результат выражения».