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]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Collapse]Reporting
 [Expand]Product Information
 [Collapse]Creating Reports in Visual Studio
  [Expand]Adding a Report to Your .NET Application
  [Expand]Getting Started with DevExpress Reporting
  [Collapse]Detailed Guide to DevExpress Reporting
   [Expand]Storing and Distributing Reports
   [Expand]Providing Data to Reports
   [Expand]Shaping Report Data
   [Expand]Report Navigation, Interactivity and Appearance
   [Collapse]Reporting API
    [Expand]Creating Reports in Code
    [Collapse]Using Report Scripts
      Scripting Security
      Granting Script Security Permissions to Your End-Users
      Scripting Overview
      The Scripts Tab - Visual Studio Report Designer
      Debugging Scripts Using Visual Studio
      Calculating Custom Summaries via Scripts
      Handling Script Events of Report Elements
      Handling Script Events to Calculate Custom Summaries
      Handling Script Events at Runtime
  [Expand]Detailed Guide to Visual Studio Report Designer
 [Expand]Creating End-User Reporting Applications
 [Expand]API Reference
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Scripting Overview

This example illustrates a legacy approach to performing custom calculations over a report's data by handling script events for report elements.

Important

Report scripts can never be considered entirely safe, and their execution cannot be completely restricted.

In particular, assigning security permissions to report scripts does not restrict them from accessing the .NET framework's static variables and methods.

Consider using Data Binding Modes as the most convenient approach to performing custom calculations over your report's data.

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:

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

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?​​​​​​​