Xafari Reports. Deployment

Introduction

In order to implement the inbuilt system reports, deploy their templates in the target application. The success of the deployment procedure requires the following conditions to be met:

  • The report template is declared in the same module as the report.
  • The deployment procedure should be executed. This can be done in several ways. The developer of the target application decides which method is more appropriate.

This topic details each stage.

Declare Templates in XAF Module

The XAF module in which it is planned to declare the report should implement the IReportDeployerProvider interface; the only declared method is IEnumerable<IReportDeployer> GetReportDeployers(). This method returns a collection of the instances of the special classes; the framework contains the corresponding classes for each type of the report templates.

Each Deployer class provides several events allowing to implement additional operations. For instance, it may be a generation of the Parameters Objects that runs during the template's deployment.

The code snippet below demonstrates how various templates types are declared:

  • c#
  • VB

public sealed partial class XafariReportsSampleModule : ModuleBase, IReportDeployerProvider
{
  //...
  public IEnumerable<IReportDeployer> GetReportDeployers()
  {
    yield return new XtraTemplateDeployer<PersonsReport>("Xtra report", "XafariReportsSample.Module.Templates.PersonsBirthdayXtra.repx", this.GetType().Assembly);
    yield return new XtraTemplateDeployer<PersonsReport, PersonsBirthdayXtraPredefined>("Xtra report (predefined)");
    yield return new ExcelTemplateDeployer<PersonsReport>("Excel report", "XafariReportsSample.Module.Templates.PersonsBirthdayExcel.xlsx", this.GetType().Assembly);
    yield return new FileTemplateDeployer<PersonsReport, PersonsReportFileGenerator>("File report", XafariReportsModule.DefaultReportStorePath, FileReportResult.CreateSingleFile, "{0:ReportName}-{0:Parameters.Name}");
  }
  //...
}

Public Partial NotInheritable Class XafariReportsSampleModule
  Inherits ModuleBase
  Implements IReportDeployerProvider
  '...
  Public Function GetReportDeployers() As IEnumerable(Of IReportDeployer)
  End Function
  '...
End Class

Deployment by Administrator

This method is provided by the Xafari.Reports.Cfg module; thus, no coding is required. The administrator deploys the reports to the time when it's really required. This scenario is very useful in case the application supplies a large number of templates. For the reason the procedure of their deployment can be very long, it is not always desirable to deploy them when performing a DB update.

There is the Deploy Reports Action on the ReportDeployment_ListView, this Action starts a special Deploy Reports operation.

reports_21

The templates required to deploy are highlighted in red. It means that these templates have not been deployed yet; however, the deployment may also be required due to different versions. The Deploy Reports operation is applied to the entire list at once; therefore, no separate selection of the templates separately is required.

Deploy Reports is a context-agnostic Business Operation implemented in the Xafari.Reports.DeployReportsOperation class. Independence from context means that it is possible to call it in the application, without binding to ReportDeployment_ListView.

Deployment when Updating the Application Database

In the code of the ModuleUpdater class, the developer can specify that the reports should be deployed when updating the application's database. There is a static method Xafari.Reports.TemplatesDeploymentHelper.DeployReportsFromModule(IObjectSpace, ModuleBase) to implement this behavior. The method takes ObjectSpace and the reference to the module containing the templates needed to perform the deployment. By this method, all templates from the specified module are set up and prepared for work. If the version of the existing template is lower than the version of the module, then the template is considered outdated and will be updated automatically. If any templates were deleted from the module, then the framework removes them from the system. The whole procedure is fixed in the common application's log (eXpressAppFramework.log by default).

The code snippet below demonstrates the Updater class calling the DeployReportsFromModule(ObjectSpace, Module) method.

  • c#
  • VB

public class Updater : ModuleUpdater
{
  private readonly ModuleBase _module;
  public ModuleBase Module
  {
    get
    {
      return _module;
    }
  }
  public Updater(IObjectSpace objectSpace, Version currentDBVersion, ModuleBase module)
    : base(objectSpace, currentDBVersion)
  {
    _module = module;
  }
  public override void UpdateDatabaseAfterUpdateSchema()
  {
    base.UpdateDatabaseAfterUpdateSchema();
    TemplatesDeploymentHelper.DeployReportsFromModule(ObjectSpace, Module);
    //…
  }
}

Public Class Updater
  Inherits ModuleUpdater
  Private ReadOnly __module As ModuleBase
  Public ReadOnly Property [Module] As ModuleBase
    Get
      Return __module
    End Get
  End Property
  Public Sub New(ByVal objectSpace As IObjectSpace, ByVal currentDBVersion As Version, ByVal [module] As ModuleBase)
    MyBase.New(objectSpace, currentDBVersion)
    __module = [module]
  End Sub
  Public Overrides Sub UpdateDatabaseAfterUpdateSchema()
    MyBase.UpdateDatabaseAfterUpdateSchema()
    TemplatesDeploymentHelper.DeployReportsFromModule(ObjectSpace, [Module])
    '…
  End Sub
End Class

Note

You can view this deployment method in the complete sample project which is available at XafariReportSample.

Calling Deployment in Code Explicitly

In general, DeployReportsOperation can be started from code at any time via its Execute() method. For more information, see the How To Call Business Operation in Code topic. By default, this Business Operation deploys all the reports templates declared in the system. However, there is a DeployReportsOperation.DeploymentInfos parameter that allows to specify a specific template for the deployment. To get extra information about all the templates defined in the specified modules, use the ReportDeployment.CollectReportDeploymentInfo() static method.