Store Report Layouts

• Oct 10, 2023
• 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).

Report definition files have an 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. However, forward compatibility is not guaranteed, which means that reports created in newer versions may not display correctly in older versions of components.

After a report’s definition is saved, you can open it in Visual Studio’s Report Designer or End-User Report Designer.

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

If you have not yet done so, be sure to review the following help topic: DevExpress Reporting - Security Considerations.

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

• Save Report Layouts
• 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 the report data sources.

When you use the following data sources, a report’s definition includes information about them:

• EFDataSource
• ExcelDataSource
• JsonDataSource
• ObjectDataSource
• SqlDataSource
• XPObjectSource
• FederationDataSource
• MongoDBDataSource

Important

A report definition contains only the data connection name - it does not include any sensitive information related to data connections. User credentials and connection strings are stored in the application configuration file.

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:

  C#

  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;
      }
  }
  

  VB.NET

  Imports DevExpress.DataAccess.ObjectBinding
  ' ...
  
  <HighlightedClass> _
  Public Class CustomObject
      <HighlightedMember> _
          Public Shared Function GetDataSet(methodParameter As System.Int32) As nwindDataSet
          Dim dataSet As New nwindDataSet()
  
          Dim dataAdapter As New nwindDataSetTableAdapters.CategoriesTableAdapter()
          dataAdapter.Fill(dataSet.Categories, methodParameter)
  
          Return dataSet
      End Function
  End Class
  

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.

Tip

Review the following examples for more information on how to serialize custom data sources to XML:

• Reporting for WinForms - How to Load and Restore a Report Using Custom XML Serialization

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:

C#

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");
}

VB.NET

Private Sub button1_Click(sender As Object, e As System.EventArgs) _
Handles button1.Click

   AppDomain.CurrentDomain.Load(GetType(CustomControNamespacel.MyCustomControl).Assembly.GetName())

   Dim Report As New XtraReport()
   Report.LoadLayout("layout.repx")
End Sub

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

Tip

See Use Custom Controls and Use 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.

View Example: Reporting for WinForms - How to Serialize Custom Type Parameters