Store Report Layouts

  • 6 minutes to read

You can save report layouts created in a Report Designer to a file or stream. This document describes the main aspects of report serialization.

Quick Guide to Report Serialization

A report's definition stores the name of the report class's type and information about the report layout (settings of the report and all its elements).

save-report-defintion-visual-studio-design-time

Report definition files have a REPX extension. This file extension is used to filter data in the Save File and Load File dialogs 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 a report's definition is saved, you can open it in Visual Studio's Report Designer or End-User Report Designer.

open-import-report-visual-studio-design-time

You can also use a text editor (for instance, Notepad) to open a report's REPX file if you want to know how to implement a particular feature.

TIP

Report definitions do not store information about events handled for a report or its elements. You should use report scripts to store custom code in a report's definition and execute it when you publish this report.

DevExpress Reports support the following serialization mechanisms to store reports and report style sheets:

  • XML Serialization

    The default serialization mechanism. We recommend that you use it for security reasons.

  • CodeDOM Serialization

    A legacy approach to saving reports. This approach can allow unauthorized code injections into a report's definition and execution of harmful code on a client machine when these reports are opened.

IMPORTANT

See Reporting Security for more information on security considerations related to storing and distributing DevExpress reports.

See the following documents for information on how to save and load report layouts:

TIP

You can use the Report Gallery to store reports and their parts and re-use them in other projects.

Implement a Custom Report Storage to store reports in a database or cloud and share them with multiple users.

Serialize Subreports

A report's definition does not include the layout and data bindings for any referenced subreports. Save them separately when you use the XRSubreport control.

As a possible workaround, consider using detail report bands instead.

Serialize 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 you use 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 users open 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 one of the following approaches to enable DataSet serialization and a custom data adapter that implements 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;
        }
    }
    

An entire BindingSource component cannot always be serialized. You can specify a data source schema for a report when the actual data is not required at design time.

Serialize Custom Controls

When a saved report contains custom controls or third-party controls, ensure that an application that creates the report's definition can create a control of this type. Declare this custom type in the assembly that creates the report or in a referenced assembly.

In some cases, the following unhandled exception can be thrown even if you reference the assembly and deploy 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 loaded into the application's domain, and the corresponding custom class is not found when the application loads the report's definition.

Visual Studio does not include a referenced assembly in the resulting assembly when your program does not use any types from it, even if you add this assembly to the list of your project's references.

To avoid this issue, load this assembly before the application loads any report definitions that reference 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");
}

Visual Studio Report Designer cannot load custom controls referenced in a report's definition.

TIP

See Using Custom and Third-Party Controls for more information on how to use custom and third-party controls in DevExpress Reports.

Serialize Custom Report Parameters

You can include custom parameter types when you serialize report definitions and save them as an XML file. Override the ReportStorageExtension class and register a custom ReportDesignExtension that serializes the data source.

To serialize custom objects and properties, set their XtraSerializeableProperty attribute to XtraSerializationVisibility.Reference.

See the following online exanoke for code that illustrates how to save a report and its parameters as an XML file: How to serialize parameters of custom types.

See Also