Store Report Layouts
- 6 minutes to read
You can save report layouts created in Visual Studio or end-user Report Designers to a file, stream, database or cloud. This document describes the main aspects of report serialization.
Quick Guide to Report Serialization
A report’s definition stores the report class’s type name and complete information about the report layout (settings of the report and all its elements).
Report definition files have the REPX extension by default. This file extension is used to filter data in the Save File and Load File dialogs displayed in the Report Designer.
Note
DevExpress reports are backward compatible and do not need to be updated each time you upgrade your product version.
After saving a report’s definition, you can open it in Visual Studio Report Designer or any End-User Report Designer version (for WinForms, WPF, or ASP.NET).
Tip
Report definitions do not store any information about events being handled for a report or its elements. You need to utilize report scripts to store custom code in a report’s definition and execute it when publishing this report.
DevExpress Reports support the following serialization mechanisms for storing reports and report style sheets:
-
The default serialization mechanism. We recommend using it for security reasons.
-
A legacy approach to saving reports. Avoid using it to prevent unauthorized code injections into a report’s definition and execution of harmful code on a client machine when opening these reports.
Important
See Reporting Security for more information on security considerations related to storing and distributing DevExpress reports.
See the following documents to learn how to save and load report layouts:
Tip
You can use Report Gallery to store reports and their parts for re-use in other projects.
Implementing a Custom Report Storage allows you to store reports in a database or cloud and share them with multiple users.
Serialization of Subreports
A report’s definition does not include the layout and data bindings of any associated subreports. You need to save them separately when using the XRSubreport control.
As a possible work around, consider using detail report bands instead of subreports.
Serialization of Data Sources
Unlike published report documents, a report definition does not store the actual values from a report’s data sources. It can only include general information about a report’s data sources and report elements’ data bindings.
When using any of the following data sources, a report’s definition includes information about them:
Important
A report definition only stores the data connection name by default. It does not include any sensitive information related to data connections (both the user’s credentials and connection string is saved to your application’s configuration file by default).
A report definition can contain information about the data source schema (as Base64-encoded text), which includes names of selected data source tables, views, and columns.
Information about a data source assigned to a report’s XtraReportBase.DataSource property is serialized along with the report’s layout. After opening the report, its data source settings are restored.
A data source’s information is not saved to a report’s definition when it is not assigned to the XtraReportBase.DataSource property.
Tip
You can handle the XtraReport.SaveComponents event to access and manage the list of serialized components.
Use any of the following approaches to enable DataSet serialization and a custom data adapter implementing the IDataAdapter interface:
- Specify a report’s XtraReportBase.DataSource and XtraReportBase.DataAdapter properties.
- Add these objects to the XtraReport.ComponentStorage collection.
Use the ObjectDataSource:
using DevExpress.DataAccess.ObjectBinding; // ... [HighlightedClass] public class CustomObject { [HighlightedMember] public static nwindDataSet GetDataSet(System.Int32 methodParameter) { nwindDataSet dataSet = new nwindDataSet(); nwindDataSetTableAdapters.CategoriesTableAdapter dataAdapter = new nwindDataSetTableAdapters.CategoriesTableAdapter(); dataAdapter.Fill(dataSet.Categories, methodParameter); return dataSet; } }
Complete BindingSource component serialization cannot be guaranteed. You can specify a data source schema for a report when the actual data is not required at design time.
Tip
See the following examples to learn how to serialize custom data sources to XML:
Serialization of Custom Controls
When a saved report contains custom controls or third-party controls, an application creating the report’s definition should be able to create a control of this type. This custom type should be declared either in the current assembly that creates the report or in the assembly the current assembly references.
In some cases, the following unhandled exception can be thrown even if you have referenced the required assembly and deployed it with the main application file: “The type or namespace name ‘MyCustomControl’ could not be found (are you missing a using directive or an assembly reference?)”
This happens because a referenced assembly is not always automatically loaded into the application’s domain, and the corresponding custom class could not be found when loading the report’s definition.
Visual Studio does not include a referenced assembly into the resulting assembly by default when your program does not use any types from it, even if you added this assembly to the list of your project’s references.
To avoid this issue, you need to manually load this assembly before opening any report definitions that have a reference to this custom type:
private void button1_Click(object sender, System.EventArgs e) {
AppDomain.CurrentDomain.Load(typeof(CustomControNamespacel.MyCustomControl).Assembly.GetName());
XtraReport report = new XtraReport();
report.LoadLayout("layout.repx");
}
Custom controls referenced in a report’s definition cannot be loaded in the Visual Studio Report Designer.
Tip
See Using Custom and Third-Party Controls to learn more about using custom and third-party controls in DevExpress Reports.
Serialization of Custom Report Parameters
You can serialize custom parameter types along with report definitions to an XML file by overriding the ReportStorageExtension class and registering a custom ReportDesignExtension, which implements the data source serialization functionality.
To serialize custom objects and properties, specify the XtraSerializeableProperty attribute with the XtraSerializationVisibility.Reference parameter (this parameter defines whether or not an object should be serialized by a reference).
See the following example online for a sample code illustrating how to save a report, along with its parameters of the Enum type to an XML file: How to serialize parameters of custom types.