With the XtraReports suite, end-users have the capability to write code for specific event handlers in the End-User Designer, to customize the appearance of report controls, bands, or a report itself. This document describes the basic principles of using scripts in XtraReports, lists the main properties required for using scripts, and gives an example on how scripting can be used in a report.

Scripting is a runtime feature of XtraReports that allows you or end-users to execute scripts at runtime when a report is generated. Note, that although it's possible to add scripts in both the Visual Studio IDE and in the End-User Designer, this feature is primarily intended to be used by advanced end-users who want to slightly customize a report in the End-User Designer. So, it is assumed that an end-user is familiar with one of the scripting languages supported by XtraReports: C#, Visual Basic .NET and JScript .NET. The scripting language must be the same for all scripts used in a report, and is specified by the XtraReport.ScriptLanguage property. This also means that the scripting language is independent from that of the language used to create the report.

To provide viable scripts for a report, another important property should be properly specified - XtraReport.ScriptReferences (or its runtime counterpart -XtraReport.ScriptReferencesString). This property contains a collection of strings that represent the paths to the assemblies used by the scripts in the report. Note that it is not required to add the following assemblies to the ScriptReferences collection:

• DevExpress assemblies required for the XtraReports functionality, and which are referenced in your project. You can find the detailed list of these assemblies in the Windows Forms Deployment document.
• Other assemblies currently loaded into your application's domain;
• Several standard .NET framework assemblies, which are always added by XtraReports: System.dll, System.Data.dll, System.Xml.dll, System.Drawing.dll, System.Windows.Forms.dll;

And the last important option which should be taken into account when enabling scripts for your end-users is XtraReport.ScriptSecurityPermissions. This property provides the capability to permit particular operations in end-user's scripts. To learn more on this, refer to Security Permissions in 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 via its Scripts property. For example, an XRChart control has theXRChartScripts.OnBoundDataChanged event, which is specific only for this control.

To edit a report element's script property at design time, expand the drop-down list of this property, and if there isn't any particular 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.

Another notable feature, is the availability of the built-in scripts validation mechanism, launched by clicking the Validate button.

If errors are detected in report scripts, they are listed in the Scripts Errors panel shown below the scripts editor. Click an error in this list, to focus cursor on the corresponding section of code.

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.
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's 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 the user's scripts.

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.

To enable script debugging, add the following lines enclosed in the <system.diagnostics> tags to the <configuration> section of the config file of your application (or the web.config file of your ASP.NET application).

<?xml version="1.0" encoding="utf-8"?> <configuration> <system.diagnostics> <switches> <add name="AllowDebugXtraReportScripts" value="true"/> </switches> </system.diagnostics> </configuration>

Then run your application and attach Microsoft Visual Studio to this process.

After calling the XtraReport.CreateDocument method for your report (e.g. when switching to the Preview tab in an End-User Designer), the corresponding script code is available at Visual Studio runtime, and it is possible to set a breakpoint on it.

After finishing debugging your scripts, you may wish to remove all temporary files that are created to provide this functionality. They are located in the following directory: C:\Users\User_Name\AppData\Local\Temp

This section contains other important notes on using scripts in XtraReports:

• If a report is created completely at runtime and it is necessary to use scripts in it, make sure that all report controls have names assigned to them. This is necessary because when controls are added out of a Report Designer, their names are undefined, and the following script or similar, will cause an exception:

  C# VB

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

  In this case, use the following code instead:

  C# VB

  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;"; report.ShowPreviewDialog();