Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Collapse]Reporting
 [Expand]Product Information
 [Expand]Getting Started
 [Expand]Fundamental Concepts
 [Collapse]Concepts
  [Expand]Report Types
  [Expand]Report Controls
  [Expand]Platform-Specific Reporting
  [Collapse]Creating Reports
   [Expand]Providing Data to Reports
   [Expand]Providing Data To Report Controls
   [Expand]Shaping Data
   [Expand]Using Report Parameters
   [Expand]Appearance Customization
   [Expand]Navigation and Interaction
   [Collapse]Scripting
     Scripting Overview
     Scripting Security
     Debugging Scripts Using Visual Studio
     Calculating Custom Summaries via Scripts
  [Expand]Storing Reports
  [Expand]Publishing Reports
  [Expand]End-User Reporting
  [Expand]Application Appearance
  [Expand]Migration to XtraReports
 [Expand]Design-Time Features
 [Expand]Examples
  End-User Capabilities
 [Expand]Localization
 [Expand]Redistribution and Deployment
 [Expand]API Reference
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Scripting Overview

The End-User Report Designer provides the capability to write code for specific event handlers 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.

Important

When your application is enabled to execute report scripts, it is important that you properly implement all necessary restrictions to prevent any possibility of executing malicious code. For example, a script is allowed to access the file system of a machine on which it is being executed without restrictions. To learn more, refer to the Scripting Security topic.

This document consists of the following sections.

Expanded Scripting Options

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

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.1.Core
    • DevExpress.Data.v17.1
    • DevExpress.Office.v17.1.Core
    • DevExpress.PivotGrid.v17.1.Core
    • DevExpress.Printing.v17.1.Core
    • DevExpress.RichEdit.v17.1.Core
    • DevExpress.Sparkline.v17.1.Core
    • DevExpress.XtraCharts.v17.1
  • 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.

To enable other assemblies in report scripts, they should be listed in the XtraReport.ScriptReferences property (or its runtime counterpart - XtraReport.ScriptReferencesString). After this, all necessary assemblies will be loaded into the application domain when compiling report scripts.

  • To reference .NET framework assemblies in the ScriptReferences property, specify only their file name (a report will always locate them in the "C:\Windows\Microsoft.NET\Framework" directory).
  • To reference any other assembly, specify its file path (either full or relative) along with the file name.

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.

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

  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.

Expanded See Also

How would you rate this topic?​​​​​​​