Scripts Overview
- 6 minutes to read
You can write scripts within report elements’ event handlers to perform custom calculations over your report’s data. Scripts run when the corresponding event occurs (for instance, a mouse click).
Important
Report scripts are not secure. We recommend that you use expression bindings instead.
The scripts are initially disabled in Web applications and all ASP.NET Core applications. Review the following help topic for information on how to enable scripts: Scripts - Security Considerations. In ASP.NET Core and Blazor Server applications, you should also install the Microsoft.CodeAnalysis NuGet package to enable report script execution.
Note
Blazor WebAssembly Reporting applications do not support scripts.
Script Options
You can use the XtraReport.ScriptLanguage property to specify the language to write scripts in the report. Report Designers support the following script languages:
- C#
- Visual Basic .NET
- JScript .NET (not available in .NET applications)
Note that the script language does not depend on the language used to create the report.
Report scripts provide access to the following assemblies:
Core assemblies that all reporting applications reference:
- DevExpress.Charts.v24.1.Core
- DevExpress.Data.v24.1
- DevExpress.Office.v24.1.Core
- DevExpress.PivotGrid.v24.1.Core
- DevExpress.Printing.v24.1.Core
- DevExpress.RichEdit.v24.1.Core
- DevExpress.Sparkline.v24.1.Core
- DevExpress.XtraCharts.v24.1
Standard .NET framework assemblies that all reporting applications reference:
- Microsoft.CSharp.dll
- System.dll
- System.Data.dll
- System.Xml.dll
- System.Drawing.dll
- System.Windows.Forms.dll
- System.Core.dll
Other assemblies that are currently loaded into your application’s domain.
You can enable other assemblies in report scripts. List them in the XtraReport.ScriptReferences property at design time or in the XtraReport.ScriptReferencesString property at runtime. You can specify a path to an assembly as an absolute (full) path or a path relative to the directory where an application runs. All the listed assemblies are loaded into the application domain when report scripts are compiled.
If you modify specific classes in the loaded assemblies, these changes are not immediately applied to the Report Designer. You should reopen the Report Designer to reload assemblies. These changes are applied automatically only if you write scripts in the Visual Studio Report Designer and customize an assembly from the same solution.
Manage Scripts
A report and every report element has an individual set of script events. For instance, the XRChart control has the XRChartScripts.OnBoundDataChanged event that is specific to this control only, while the XRControl.BeforePrint event is declared at the base control’s level and is applicable to most report controls. The XRControl.Scripts collection provides access to all events that the selected report control supports.
At design time in Visual Studio, you can switch to the Properties window and expand the Scripts property. Select an event and choose (New) in the drop-down list. This opens the Scripts tab and adds the event handler’s template. This template uses the language that the XtraReport.ScriptLanguage property specifies.
The Scripts tab contains all scripts written for all report elements. You can choose a report element from the drop-down list on the left, and an event from the drop-down list on the right. This adds a new handler if it does not exist yet or navigates to the corresponding event handler if it is already specified.
You can write any syntactically correct code in scripts. You can declare new classes, variables, and methods.
Click the Validate button to check for errors in report scripts.
The Error List panel lists all found errors.
Click an error in the panel to navigate to the line that contains this error.
Refer to Debug Scripts in Visual Studio for information on how to debug report scripts.
Note
If you handle a report control’s event in code behind and write a script for the same event, the event in code behind is executed after the script event.
Intelligent Code Completion
Script editors support intelligent code completion for the C# and Visual Basic .NET script languages. Context-aware hints are displayed when you type a dot or press CTRL+spacebar.
Note
The WPF End-User Report Designer does not currently support this feature.
In the Visual Studio Report Designer, intelligent code completion always requires an Internet connection and supports only .NET Framework and DevExpress libraries deployed with the application.
For End-User Report Designers, you can either connect your machine to the Internet or register the local code completion engine (it also supports types defined in custom assemblies).
Do the following to activate the local code completion engine in your end-user reporting application:
Right-click the References node in the Solution Explorer and select Manage NuGet Packages in the invoked context menu.
Select DevExpress 24.1 Local in the Package source drop-down list and go to the Browse page. Find the DevExpress.Reporting.CodeCompletion NuGet package and install it.
Call the CodeCompletionRequestManager.UseLocalEngine method at application startup.
The local engine requires a storage for report layouts. You can use the predefined storage (the FileCodeCompletionContextStorage or InMemoryCodeCompletionContextStorage class) or provide your custom storage.
The UseLocalEngine() method without parameters activates an in-memory storage (InMemoryCodeCompletionContextStorage).
The UseLocalEngine(ICodeCompletionContextStorage) method accepts a storage object as a parameter.
The following code demonstrates how to pass the FileCodeCompletionContextStorage instance to store report layouts in the specified folder:
using DevExpress.XtraReports.CodeCompletion; using DevExpress.XtraReports.CodeCompletion.Storages; CodeCompletionRequestManager.UseLocalEngine(new FileCodeCompletionContextStorage("D:\\CodeCompletionContext"));You can also implement the ICodeCompletionContextStorage interface, create its instance and pass it to the method as the parameter.
To disable intelligent code completion, set the static SyntaxEditor.EnableCodeCompletion property to false.
Script Processing Mechanism
The reporting engine processes scripts as follows:
Generates a temporary class in memory.
Adds variables that correspond to the following items:
- report;
- report bands;
- report controls;
- calculated fields;
- parameters;
- styles;
- control appearance;
- data sources.
The item’s Name property value defines the variable name. An exception occurs while the script runs if you do not specify the Name property.
Note
If the script code already contains a variable with the same name as a report item, a variable for this item is not generated. This functionality requires the DevExpress.CodeParser.v24.1.dll assembly. If this assembly is not added to the project’s reference list, a compilation error is raised.
Cuts the using-like directives from the script code and adds them to the namespace that contains the temporary class.
Places all the report scripts into the temporary class as methods.
Compiles the resulting class in memory.
Calls this class’s methods to execute the corresponding report scripts.