In the script description you can use:

• report variables;
• data columns;
• functions, including user-defined ones;
• basic C# constructs - if, else, ternary operator, loops.

Scripts work in:

• events;
• user functions;
• report expressions;
• expressions of components, variables, calculated columns.

If the expression contains the return operator, the report engine will process it as a script; if it does not, it will be processed as a simple expression.

Script execution control

To completely disable script execution, set the Allow Scripts To Run report property to False. If you only want to disable scripts in expressions, set the Allow Scripts In Expressions report property to False. Information

Note! Script execution in expressions also depends on the Allow Scripts To Run property. If script execution is disabled either in the report properties or via a global option, the Allow Scripts In Expressions property will be ignored, because scripts will not be executed. In addition, you can set the script timeout (in seconds) using the Script Timeout property. For embedded components, there is a global option - StiOptions.Engine.AllowScriptsToRun - which enables or disables script execution in Interpretation mode.

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

Below are some samples of syntax and basic constructions.

Variables and types

In scripts, you can declare variables using the var keyword or by explicitly specifying the type. All basic C# types are supported, including numbers, strings, dates, Booleans, colors, collections, and objects. Below are examples of variable usage:

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

Arrays and collections

.NET arrays and collections are available (see examples below):

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

Special types

You can use types like GUID, Color, and your own business objects if they are registered in reports.

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

In scripts, you can directly use variables defined in the report and access or modify their values in code. To reference a variable, simply use its name - no prefixes required. For example: var value = MyVariable;.

If a variable is declared in a report, it automatically becomes available in all report scripts, including component events, expressions, user functions, and global scripts. You can also assign new values to variables, for example: MyVariable = 42;. This allows you to use variables to store intermediate results, transfer data between different parts of the report, and manage the logic of report building on the fly.

Type conversion

Explicit and implicit type conversion is supported:

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

Operators in Stimulsoft scripts

Stimulsoft scripts support all standard C# operators:

• including arithmetic (+, -, *, /, %);
• comparison operators (==, !=, <, >, <=, >=), logical (&&, ||, !);
• bit (&, |, ^, ~, <<, >>);
• assignment operators (=, +=, -=, *=, /=, %=, etc.);
• ternary operator (? :);
• increment and decrement (++, --);
• type checking and casting operators (is, as, typeof, GetType).

This allows using familiar constructs and expressions for calculations, conditions, and working with variables and types, just as in regular C#. All operators follow the same associativity rules as in C#. Complex expressions, operator combinations, and all standard scenarios - such as using operators in conditions, loops, functions, and when working with collections - are supported.

Loops in Stimulsoft scripts

In scripts, you can use all the primary loop constructs available in C#:

The loop for: a loop with a counter. It is usually used when you know in advance how many times an action needs to be repeated.

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

The loop while: a loop with a precondition that runs as long as the condition is true.

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

The loop do...while: a loop with a postcondition that executes the loop body at least once.

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

The loop foreach: a loop for iterating over each element of a collection (e.g., a list, array, etc.).

...
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
...

Inside loops, you can use break to exit the loop and continue to move to the next iteration. Here are some examples with break and 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.
}
...

Functions in Stimulsoft scripts

You can use different types of functions in scripts: built-in functions, static functions, type functions, and custom (user) functions, which can be defined directly in the code or accessed from the report.

Built-in Stimulsoft functions

Scripts support a large number of built-in Stimulsoft functions for working with data, strings, numbers, dates, colors, etc. These functions can be called directly by name.
Examples:

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

The full list of built-in functions you may find here.

.NET static functions and methods

You can use static methods of standard .NET classes - for example, to convert types or to work with numbers, strings, and dates.

...
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);
...

Type functions (object methods)

Methods of standard .NET types are available including those for strings, numbers, dates, and collections.

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

Custom functions

You can declare your functions directly in the script and call them as usual.

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

Functions from a report

If custom functions are defined in a report, they can be called by name if they are available in the script context.

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

Casting and type checking

Stimulsoft scripts support standard C# operators for working with types: as, is, and typeof, as well as explicit and implicit type conversion. You can also use the GetType method to get information about an object’s type.

Operator is: the operator allows you to check whether an object belongs to a certain type. Returns true or false.

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

Operator as: the operator attempts a type conversion. If the conversion is not possible, it returns null (rather than throwing an exception).

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

Operator typeof: the operator allows you to obtain a type object for further checking or reflection.

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

Operator GetType: the method returns the actual type of the object at runtime. This is useful for dynamic testing and debugging.

...
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
...

The parser supports the standard C# syntax for type casting, including casting between numbers, strings, booleans, and more. If a conversion is not possible, an exception is thrown, as in regular C#.

Using data sources and business objects in Stimulsoft scripts

In scripts, you can directly access data sources registered in the report, as well as their related data and business objects. To access a data source, simply use its name, for example:

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

Here we move to the first row of the Products data source and read the value of its ProductName column. If relationships are set up between data sources, we can access related data using a dot:

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

This is how you can get the category name for the current product. Navigation methods such as First(), Next(), Previous(), as well as properties and indexers are available for working with data sources:

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

If business objects are added to a report via the RegBusinessObject method, they can be accessed by name like regular objects:

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

For nested objects, use dot:

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

All business object properties and fields are readable and writable, provided their type allows it. For more complex scenarios, you can combine access to data, collections, report components, and business objects in a single statement:

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