В описании скрипта можно использовать:

• переменные отчета;
• колонки данных;
• функции, включая пользовательские;
• базовые конструкции C# – if, else, тернарный оператор, циклы.

Скрипты работают в:

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

Если в выражении есть оператор return, генератор отчетов обработает это выражение как скрипт; без оператора return – как простое выражение.

Script Language

Обработка скриптов в отчете зависит от выбранного значения для свойства Скриптовый язык (Script Language). Для работы C# скриптов на всех поддерживаемых платформах, необходимо свойство Скриптовый язык (Script Language) установить в значение C#. Это значение установлено по умолчанию для всех новых отчетов.

Однако, для обратной совместимости, для ранее сознанных отчетов свойство Скриптовый язык (Script Language) будет установлено в значение Платформа (Platform). В этом случае, скриптовый язык зависит от платформы, на котором выполняется построение отчета:

• платформа .NET - используются C# скрипты;
• платформа JS - используется JavaScript.

Если всегда необходимо использовать C# парсер, независимо от платформы, то следует установить свойство Скриптовый язык (Script Language) в значение C#. Это можно выполнить:

В дизайнере отчетов. Открыть отчет на редактирование, перейти к свойствам шаблона и установить значение C# для свойства Скриптовый язык (Script Language).

Из кода:
C#:

report.UsePlatformDependentScript = false;

JS:

report.usePlatformDependentScript = false;

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

Управление выполнением скриптов

Чтобы полностью отключить выполнение скриптов, следует установить свойство отчета Разрешить выполнение скриптов (Allow Scripts To Run) в значение Нет (False). Если же необходимо запретить скрипты только в выражениях, установите свойство отчета Разрешить скрипты в выражениях (Allow Scripts In Expressions) в значение Нет (False).
Информация

Обратите внимание, что выполнение скриптов в выражениях также зависит от свойства Разрешить выполнение скриптов. Если выполнение скриптов запрещено в свойствах отчетах или при помощи глобальной опции, то значение свойства Разрешить скрипты в выражениях не будет учитываться, так как скрипты не будут выполнятьсяКроме этого можно установить таймаут скрипта при помощи свойства Время ожидания выполнения скрипта (Script Timeout) в секундах. Для встраиваемых компонентов предусмотрена глобальная опция StiOptions.Engine.AllowScriptsToRun для включения или выключения возможности выполнения скриптов в режиме Интерпретации.

...
  StiOptions.Engine.AllowScriptsToRun = true;
...

Ниже рассмотрим некоторые примеры синтаксиса и основные конструкции.

Переменные и типы

В скриптах Stimulsoft можно объявлять переменные с помощью ключевого слова var или явно указывать тип. Поддерживаются все основные типы C#, включая числа, строки, даты, булевы значения, цвета, коллекции и объекты. Примеры объявления переменных:

...
var number = 10;
var text = "Hello, World!";
var isActive = true;
var price = 19.99m;
var date = DateTime.Today;
var color = Color.Red;
...

Массивы и коллекции

Доступны массивы и коллекции .NET:

...
var numbers = new int[3];
var list = new List<string>();
var dict = new Dictionary<string, int>();
...

Специальные типы

Можно использовать типы вроде GUID, Color, а также собственные бизнес-объекты, если они зарегистрированы в отчете.

...
var id = Guid.NewGuid();
var color = Color.FromArgb(255, 128, 64);
...

В скриптах Stimulsoft можно напрямую использовать переменные, определенные в отчёте, а также обращаться к их значениям и изменять их в коде. Для доступа к переменной достаточно указать ее имя, без дополнительных префиксов, например: var value = MyVariable;.

Если переменная объявлена в отчете, она автоматически становится доступна во всех скриптах отчета, включая события компонентов, выражения, пользовательские функции и глобальные скрипты. Также можно присваивать новые значения переменным: MyVariable = 42;. Это позволяет использовать переменные для хранения промежуточных результатов, передачи данных между различными частями отчета и управления логикой построения отчета на лету.

Преобразование типов

Поддерживается явное и неявное приведение типов:

...
var d = 5.5;
var i = (int)d; // 5
var s = (string)123; // "123"
...

Операторы в скриптах Stimulsoft

В скриптах Stimulsoft поддерживаются все стандартные операторы C#:

• включая арифметические (+, -, *, /, %);
• операторы сравнения (==, !=, <, >, <=, >=), логические (&&, ||, !);
• побитовые (&, |, ^, ~, <<, >>);
• операторы присваивания (=, +=, -=, *=, /=, %=, etc.);
• тернарный оператор (? :);
• инкремент и декремент (++, --);
• операторы проверки и приведения типа (is, as, typeof, GetType).

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

Циклы в скриптах Stimulsoft

В скриптах Stimulsoft можно использовать все основные виды циклов, которые есть в C#:

Цикл for. Цикл с явным счетчиком. Обычно используется, когда известно, сколько раз нужно повторить действие.

...
var sum = 0;
for (var i = 0; i < 5; i++) {
sum += i;
}
// sum = 0 + 1 + 2 + 3 + 4 = 10
...

Цикл while. Цикл с предусловием. Выполняется, пока условие истинно.

...
var count = 0;
while (count < 3) {
count++;
}
// count = 3
...

Цикл do...while. Цикл с постусловием. Тело цикла выполнится хотя бы один раз.

...
var value = 0;
do {
value += 2;
} while (value < 6);
// value = 6
...

Цикл foreach. Цикл для перебора всех элементов коллекции (списка, массива и так далее).

...
var list = new List<int>();
list.Add(1);
list.Add(2);
list.Add(3);

var total = 0;
foreach (var item in list) {
total += item;
}
// total = 6
...

Внутри циклов можно использовать break (для выхода из цикла) и continue (для перехода к следующей итерации). Пример с break и continue:

...
for (var i = 0; i < 10; i++) {
if (i == 5) break;
if (i % 2 == 0) continue;
// This code will only execute for odd i values less than 5.
}
...

Функции в скриптах Stimulsoft

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

Встроенные функции Stimulsoft

Скрипты поддерживают большое количество встроенных функций Stimulsoft для работы с данными, строками, числами, датами, цветами и т.д. Их можно вызывать напрямую по имени.
Примеры:

...
var empty = IsNullOrEmpty("");
var max = Maximum(3, 5);
var color = RGB(255, 0, 0);
...

Полный список встроенных функций — в документации Stimulsoft.

Статические функции и методы .NET

Можно использовать статические методы стандартных .NET-классов, например, для преобразования типов, работы с числами, строками, датами.

...
var absValue = Math.Abs(-10);
var rounded = Math.Round(2.6);
var parsed = int.Parse("123");
var now = DateTime.Now;
var formatted = string.Format("Value: {0}", 42);
...

Функции типов (методы объектов)

Доступны методы стандартных типов .NET, например, для строк, чисел, дат, коллекций.

...
var text = "hello";
var upper = text.ToUpper();
var length = text.Length;
var tomorrow = now.AddDays(1);
var exists = list.Contains(2);
...

Пользовательские функции

Можно объявлять свои функции прямо в скрипте и вызывать их как обычно.

...
double square(double n) {
return n * n;
}
var result = square(5);
...

Функции из отчета

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

...
var value = MyReportFunction(10);
...

Приведение типов и проверки типа

В скриптах Stimulsoft поддерживаются стандартные C#-операторы для работы с типами: as, is, typeof, а также явное и неявное преобразование типов. Можно также использовать метод GetType для получения информации о типе объекта.

Оператор is. Позволяет проверить, относится ли объект к определенному типу. Возвращает true или false.

...
var result = "hello" is string; // true
var isInt = 123 is int; // true
var isBool = 123 is bool; // false
...

Оператор as. Выполняет попытку приведения типа. Если преобразование невозможно — возвращает null (а не выбрасывает исключение).

...
var obj = "hello";
var str = obj as string; // "hello"
var num = obj as int;    // null
...

Оператор typeof. Позволяет получить объект типа для дальнейших проверок или рефлексии.

...
var obj = "hello";
var str = obj as string; // "hello"
var num = obj as int;    // null
...

Оператор GetType. Метод возвращает реальный тип объекта во время выполнения. Это удобно для динамических проверок и отладки.

...
var value = 123;
var typeName = value.GetType().Name; // "Int32"
var typeFullName = value.GetType().FullName; // "System.Int32"

var text = "abc";
var isString = text.GetType() == typeof(string); // true
...

Парсер поддерживает стандартный синтаксис C# для приведения типов, в том числе между числами, строками, булевыми значениями и т.д. Если преобразование невозможно, будет выброшено исключение (как в обычном C#).

Использование источников данных и бизнес-объектов в скриптах Stimulsoft

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

...
Products.First();
var name = Products.ProductName;
...

Здесь происходит переход к первой строке источника данных Products и чтение значения столбца ProductName. Если между источниками данных настроены связи (relations), можно обращаться к связанным данным через точку:

...
var categoryName = Products.Categories.CategoryName;
...

Так можно получить имя категории для текущего продукта. Для работы с источниками данных доступны методы навигации, такие как First(), Next(), Previous().

Если в отчет добавлены бизнес-объекты через метод RegBusinessObject, к ним можно обращаться по имени, как к обычным объектам:

...
var id = Business.Id;
var name = Business.Name;
Business.Name = "NewName";
...

Для вложенных объектов используйте доступ через точку:

...
var subPrice = Business.Child.SubChild.Price;
...

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