Scripting Overview

• Aug 03, 2020
• 6 minutes to read

Important

Report scripts are not secure. We recommend that you use expression bindings instead.

The End-User Report Designers enable you to handle script events of report elements. This document provides legacy information about the use of report scripts:

• Scripting Options
• Maintaining Scripts

Scripting Options

Scripting is supported in End-User Report Designers available for the following platforms:

• WinForms;
• WPF;
• ASP.NET.

To be able to modify report scripts, an end-user should be familiar with one of the scripting languages supported by XtraReports: C#, Visual Basic .NET and JScript .NET. The XtraReport.ScriptLanguage property specifies a common language that is used by all scripts in a report. The scripting language is independent from the language used to create the report.

Make sure that the specified scripting language is supported on the client side. For instance, JScript is not supported in the .NET 1.1 Framework by default, so it needs to be installed on an end-user machine.

The following assemblies are always accessible from report scripts.

• Core assemblies that are referenced by any reporting application:

  • DevExpress.Charts.v17.2.Core
  • DevExpress.Data.v17.2
  • DevExpress.Office.v17.2.Core
  • DevExpress.PivotGrid.v17.2.Core
  • DevExpress.Printing.v17.2.Core
  • DevExpress.RichEdit.v17.2.Core
  • DevExpress.Sparkline.v17.2.Core
  • DevExpress.XtraCharts.v17.2

• Several standard .NET framework assemblies that are always referenced by XtraReports:

  • 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 by listing them in the XtraReport.ScriptReferences property (or its runtime counterpart - XtraReport.ScriptReferencesString). To reference a specific assembly, specify its full file path along with the file name or use the relative path relative to the directory where an application runs. This loads all the necessary assemblies into the application domain when compiling report scripts.

However, this approach does not apply to the Preview tab in the Visual Studio report designer. In this case, the assemblies are loaded in the Visual Studio hosting environment, and there is no capability to manage their life cycle (i.e., reload them after modifying some of their classes) at that point. This is by design and it can only be suggested that you implement all necessary logic completely in report scripts. Otherwise, you have to restart Visual Studio after modifying classes that are used in the report scripts.

Maintaining Scripts

Scripts are custom event handlers that can be added for specific events of a report and any of its elements (e.g., for the XRControl.BeforePrint event). To do this in the End-User Designer, an end-user has access to the XRControl.Scripts collection, which contains strings for all events that are present in a report control. Note that a report and its elements may have a unique set of events available using its Scripts property. For example, an XRChart control has the XRChartScripts.OnBoundDataChanged event, which is specific only to this control.

To edit a report element’s script property at design time, expand the drop-down list of this property in the Properties window, and if there is no script defined for this property, click (New). This will show the Scripts tab containing a code template written in the language defined by the XtraReport.ScriptLanguage property.

This tab contains all scripts written for all report elements, and allows you to quickly navigate through them by choosing the required report element in the corresponding drop-down list, and specifying one of its available events in another menu.

Script editors support intelligent code completion that makes it easier and faster for end-users to write scripts. Context-aware hints are displayed on typing a dot or pressing CTRL+spacebar. This feature is only supported for the C# and Visual Basic .NET script languages.

Intelligent code completion is available only for .NET Framework and DevExpress libraries deployed with the application and cannot be provided for custom assemblies.

To be able to use this feature, an end-user machine must be connected to the Internet.

To disable intelligent code completion, set the static SyntaxEditor.EnableCodeCompletion property to false.

To check for errors in a report script, click the Validate button.

If errors are found, they are listed in the Error List panel.

To learn how to debug all report scripts at one time, refer to Debugging Scripts Using Visual Studio.

To proceed to the line that contains an error, click that error in the Error List panel.

The entered script will be used to handle the corresponding event of the control. Scripting events are raised in the same manner as ordinary event handlers. In XtraReports, scripting is carried out in the following order.

1. XtraReports generates a temporary class in memory and adds the variables corresponding to the report object, its bands and controls. The names of the variables are defined by the Name properties of the objects they represent.

   Before assigning the XtraReport.ScriptsSource in code, make sure to specify the XRControl.Name for each added report control. Otherwise, running the script will cause an exception, because the default control name is undefined.

   The following code illustrates the correct approach.

   C#

   XtraReport report = new XtraReport();
   report.Bands.Add(new DetailBand());
   
   XRLabel label1 = new XRLabel();
   label1.Name = "label1";
   report.Bands[0].Controls.Add(label1);
   
   XRLabel label2 = new XRLabel();
   label2.Name = "label2";
   report.Bands[0].Controls.Add(label2);
   
   this.ScriptsSource = "int i = 0;";
   
   ReportPrintTool pt = new ReportPrintTool(report);
   pt.ShowPreviewDialog();
   

   VB.NET

   Dim report As New XtraReport()
   report.Bands.Add(New DetailBand())
   
   Dim label1 As New XRLabel()
   label1.Name = "label1"
   report.Bands(0).Controls.Add(label1)
   
   Dim label2 As New XRLabel()
   label2.Name = "label2"
   report.Bands(0).Controls.Add(label2)
   
   Dim pt As New ReportPrintTool(report)
   pt.ShowPreviewDialog()
   

2. The scripts are preprocessed. While preprocessing, the using-like directives are cut from the script code and added to the namespace where the temporary class is defined.
3. After preprocessing, all the user scripts are placed in the code of the temporary class as plain text. Then, the resultant class is compiled in memory, and when required, its methods are called to execute user scripts.

Note

If a report control has a standard event-handling method, and a scripting method for the same event, both of them will be executed. Note that in this case, the element’s standard event-handling method has priority over the script’s method.

Since the scripting code placed into the temporary class can contain any code except for the using-like directives, this offers a lot of possibilities: you can declare classes (they will become inner classes), declare new variables, methods, classes, etc. The advantage of this approach is that a variable declared in one script can be accessed in another script as is, as a variable of the temporary class.