Reports Manager Concepts

  • 6 minutes to read

This topic describes the common concepts behind services that implement the IReportManagerService interface.

Reports Managing

Services implementing the IReportManagerService interface provide the same capabilities to manage reports.

public interface IReportManagerService {
    XtraReport GenerateReport(XtraReport initialReport = null);
    void AssignDataSource(XtraReport report);
    ReportInfo SaveReport(XtraReport report);
    void RemoveReport(ReportInfo info);
    XtraReport GetReport(ReportInfo info);
    void UpdateReport(ReportInfo info, XtraReport report);
    IEnumerable<ReportInfo> GetReports();
    bool HasPreview { get; }
    event EventHandler ReportsChanged;
}

Using the methods of the IReportManagerService within a ViewModel, you can perform the following actions under reports.

  • Create new or use existing reports
  • Save reports between the application's restarts
  • Edit and update reports stored within the service's storage
  • Remove specific reports from the storage

To learn how to obtain the service's methods depending on your ViewModel type, refer to one of the following topics: Services in POCO objects, Services in ViewModelBase descendants, Services in custom ViewModels.

The IReportManagerService.GenerateReport method provided by the IReportManagerService interface is used to create new reports. This method returns an instance of the XtraReport type

public void CreateNewReport() {
    XtraReport report = ReportManagerService.GenerateReport();
    //...
}

All XtraReport instances generated by the service are automatically populated with data from the control to which the service is attached. E.g., GridReportManagerService's reports use data from the associated GridControl, StandaloneReportManagerService's report load data from an arbitrary source.

If you have an existing report, you can also use it in the report manager service. But it is necessary to take into consideration that if you create a new report manually or load it from another place, you have to populate it with data by using the IReportManagerService.AssignDataSource method.

public void CreateNewReport() {
    XtraReport report = new XtraReport() { Name = "MyNewReport" };
    ReportManagerService.AssignDataSource(report);
    //...
}

Services implementing the IReportManagerService interface also provide the capability to declare predefined reports that are designed upfront and bundled with an application. The code snippet below demonstrates how to declare a predefined report by using the PredefinedReport class.

xmlns:dxrudex="http://schemas.devexpress.com/winfx/2008/xaml/reports/userdesignerextensions"
...
<dxg:GridControl Grid.Row="1" ItemsSource="{Binding Employees}">
    <dxg:GridControl.View>
        <dxg:TableView>
            <dxmvvm:Interaction.Behaviors>
                <dxrudex:GridReportManagerService x:Name="EmployeesReportService">
                    <dxrudex:PredefinedReport ReportName="Grouped by Department" Type="localReports:GroupedByDepartmentReport"/>
                </dxrudex:GridReportManagerService>
            </dxmvvm:Interaction.Behaviors>
        </dxg:TableView>
    </dxg:GridControl.View>
</dxg:GridControl>
TIP

It is necessary to specify the Name property when declaring a service. To save reports between application restarts, the service uses a folder of the same name which is located within the c:\Users[UserName]\AppData\Roaming[ApplicationName][ApplicationName]\1.0.0.0\ directory. If you specify the same Name for two or more report services, their reports will be shared between all report services.

The PredefinedReport entries reference the report types that had been created with the Report Wizard in Visual Studio. The capability to specify predefined reports is available to both the GridReportManagerService and StandaloneReportManagerService.

NOTE

Reports defined by using PredefinedReport are part of the application and cannot be removed or modified by the end-user.

To preserve your newly created reports between application restarts, save them to the service's storage by using the IReportManagerService.SaveReport method.

public void CreateNewReport() {
    XtraReport report = ... ;
    ReportInfo info = ReportManagerService.SaveReport(report);
    //...
}

The SaveReport method returns a new ReportInfo instance which contains the following information that is used to identify the report in the service store: the report's unique Key of type string; the report's Name that is displayed in the Report Designer; the boolean IsReadOnly flag that is used to prevent the Report Designer from overwriting the report at runtime.

A list of all saved reports can be retrieved by using the IReportManagerService.GetReports method. Note that only ReportInfo instances are returned. This prevents loading all available reports to memory when particular reports are required. To load the corresponding XtraReport from disk, use the IReportManagerService.GetReport method.

To modify an existing report and save your changes, call the IReportManagerService.UpdateReport method.

public void CreateNewReport() {
    XtraReport report = ...;
    ReportInfo info = ReportManagerService.SaveReport(report);
    info.Name = "Newly Added Report";
    ReportManagerService.UpdateReport(info);
}

The following ShowReport extension methods are used to show a report.

public static class IReportManagerServiceExtensions {
    public static void ShowReport(this IReportManagerService self, XtraReport report, bool forcePreview, bool forceEdit);
    public static void ShowReport(this IReportManagerService self, ReportInfo info, bool forcePreview, bool forceEdit);
    public static void ShowReportWizard(this IReportManagerService self);
}

Here is an example illustrating how to use these methods.

public void CreateNewReport() {
    XtraReport report = ...;
    ReportInfo info = ReportManagerService.SaveReport(report);
    info.Name = "Newly Added Report";
    ReportManagerService.UpdateReport(info);
    ReportManagerService.ShowReport(info, true, false);
}

Service's ViewModel

To simplify the use of the ReportManagerService in XAML, it contains an instance of a helper ReportManagerServiceViewModel class, which is accessible through the ReportManagerService.ViewModel property.

ReportManagerServiceViewModel provides a list of reports via the Reports collection property whose items are represented by ReportInfoViewModel and also provides several commands for common operations:

  • ShowReportWizardCommand - show a dialog to create a new report. The dialog allows end-users to specify a color theme for the resulting report, the paper size and paper orientation.
  • ShowReportPreviewCommand - show the ReportDesigner in a new window with its Preview tab open. The report to preview is specified via the command parameter which can be of type XtraReport or ReportInfo.
  • EditReportCommand - show the ReportDesigner in a new window. The report to preview is specified via the command parameter which can be of type XtraReport or ReportInfo.

Auxiliary ReportManagerBehavior

ReportManagerBehavior

This behavior is used to create a BarSplitButtonItem customized with common report operations. Below is an example of how to attach the behavior in XAML:

<dxr:RibbonControl>
    <dxr:RibbonDefaultPageCategory>
        <dxr:RibbonPage ... >
            <dxr:RibbonPageGroup>
                <dxb:BarSplitButtonItem ... >
                    <dxmvvm:Interaction.Behaviors>
                        <dxrudex:ReportManagerBehavior Service="{Binding ElementName=EmployeesReportService}" />
                    </dxmvvm:Interaction.Behaviors>
                </dxb:BarSplitButtonItem>
            </dxr:RibbonPageGroup>
        </dxr:RibbonPage>
    </dxr:RibbonDefaultPageCategory>
</dxr:RibbonControl>
TIP

Notice that the Service property is bound to a ReportManagerService by its ElementName.