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

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

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

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

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

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

Чтобы полностью отключить выполнение скриптов, следует установить свойство отчета Разрешить выполнение скриптов (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(), а также свойства и индексаторы:

...
var price = Products["Price"];
var firstCustomer = Customers[0];
var count = Products.Count;
...

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

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

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

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

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

...
Pages[0].Components["Text1"].TextValue = Products.ProductName;
...