XtraReport.CreateDocument(Boolean) Method

Creates a document from the XtraReport object, so the report can be displayed or printed. Optionally, the document pages can be generated progressively and accessed as soon as they are created. Document creation is always synchronous and does not occur in a background thread.

Namespace: DevExpress.XtraReports.UI

Assembly: DevExpress.XtraReports.v24.1.dll

NuGet Package: DevExpress.Reporting.Core

Declaration

C#

public virtual void CreateDocument(
    bool buildForInstantPreview
)

VB.NET

Public Overridable Sub CreateDocument(
    buildForInstantPreview As Boolean
)

Parameters

Name	Type	Description
buildForInstantPreview	Boolean	true to enable accessing document pages progressively as they are created; otherwise false.

Remarks

Calling the CreateDocument method creates a report document that is ready to preview, print and export.

The created document can then be accessed via the PrintingSystemBase.Document property of a report’s XtraReport.PrintingSystem, and the page collection is available via the XtraReport.Pages property. For a code example, refer to Merging Reports.

Note

If the buildForInstantPreview parameter is set to true, document pages can be accessed progressively as they are created. In Print Preview, this enables you to start viewing the document as soon as its first page is ready. Remaining pages are progressively rendered in Print Preview.

Regardless of this parameter setting, a document will not be produced in a background thread. Document creation is not asynchronous, as parts of a document are rendered each time the Idle event is raised (in the WPF environment, a document is created using ticks from the DispatcherTimer class).

When this option is enabled, you can use the PrintingSystemBase.CreateDocumentException event to handle custom exceptions, which may occur during document creation. When an exception is handled (the ExceptionEventArgs.Handled property is set to true for it), the report creation process stops without displaying any errors in Print Preview.

When this option is enabled, document creation can be interrupted by calling the XtraReport.StopPageBuilding method.

The CreateDocument method is called internally from the following methods (i.e., it is not required to call it before calling one of the following methods).

• PrintTool.ShowPreview and PrintTool.ShowPreviewDialog;
• PrintTool.ShowRibbonPreview and PrintTool.ShowRibbonPreviewDialog;
• ReportPrintTool.Print and LinkPrintTool.Print;
• all the export methods (e.g., XtraReport.ExportToCsv or XtraReport.ExportToHtml);
• all static Write*To() methods (e.g., ReportViewer.WriteHtmlTo).

The CreateDocument method is not required when a report is assigned to the Web Document Viewer control.

An explicit call to the CreateDocument method is required only to refresh the document and after making changes to the report, prior to showing its preview, printing and/or exporting it.

If your report contains any parameters and the XtraReport.RequestParameters property is set to true, calling the CreateDocument method will not invoke the Parameters form that enables end-users to enter parameter values, until DevExpress.XtraPrinting.v24.1.dll is added to the project’s reference list and the following code is executed.

C#

using DevExpress.XtraReports.UI;
// ...

private void button1_Click(object sender, EventArgs e) {
    XtraReport1 report = new XtraReport1();
    ReportPrintTool tool = new ReportPrintTool(report);
    report.CreateDocument();
}

VB.NET

Imports DevExpress.XtraReports.UI
' ...

Private Sub button1_Click(sender As Object, e As EventArgs)
    Dim report As New XtraReport1()
    Dim tool As New ReportPrintTool(report)
    report.CreateDocument()
End Sub

After this code assigns a ReportPrintTool to the report, calling the CreateDocument method invokes the dialog requesting the report parameters’ values.

Note

An attempt to call the CreateDocument method for a report that does not contain the DetailBand raises an exception (in particular, when creating a report in code). Add this band to the report even if you do not need to display information in it.

Related GitHub Examples

The following code snippets (auto-collected from DevExpress Examples) contain references to the CreateDocument(Boolean) method.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

C#

reporting-winforms-export-reports-to-diff-sheets-in-xlsx-file-with-spreadsheet-document-server/CS/WindowsFormsApplication1/Form1.cs#L22

XtraReport2 report2 = new XtraReport2();
report.CreateDocument(false);
report2.CreateDocument(false);

asp-net-mvc-grid-create-report-based-on-grid-layout/CS/E4755/Models/ReportHelperMVC.cs#L192

public void WritePdfToResponse(HttpResponseBase Response, string fileName, string type) {
    report.CreateDocument(false);
    using (MemoryStream ms = new MemoryStream()) {

asp-net-web-forms-grid-create-report-based-on-grid-layout/CS/WebApplication1/ReportHelper.cs#L228

internal void WritePdfToResponse(HttpResponse Response, string fileName, string type) {
    report.CreateDocument(false);
    using(MemoryStream ms = new MemoryStream()) {

reporting-wpf-override-export-commands/CS/ReportingWpfOverrideExportCommand/MainWindow.xaml.cs#L18

var window = new DXWindow() { Content = preview };
report.CreateDocument(true);
window.ShowDialog();

reporting-wpf-override-print-commands/CS/MinimalisticReportPreviewDemo/MainWindow.xaml.cs#L16

var window = new Window() { Content = preview };
report.CreateDocument(true);
window.ShowDialog();

VB.NET

reporting-winforms-export-reports-to-diff-sheets-in-xlsx-file-with-spreadsheet-document-server/VB/WindowsFormsApplication1/Form1.vb#L21

Dim report2 As XtraReport2 = New XtraReport2()
report.CreateDocument(False)
report2.CreateDocument(False)

asp-net-mvc-grid-create-report-based-on-grid-layout/VB/E4755/Models/ReportHelperMVC.vb#L174

Public Sub WritePdfToResponse(ByVal Response As HttpResponseBase, ByVal fileName As String, ByVal type As String)
    report.CreateDocument(False)
    Using ms As New MemoryStream()

asp-net-web-forms-grid-create-report-based-on-grid-layout/VB/WebApplication1/ReportHelper.vb#L239

Friend Sub WritePdfToResponse(ByVal Response As HttpResponse, ByVal fileName As String, ByVal type As String)
    report.CreateDocument(False)
    Using ms As New MemoryStream()

reporting-wpf-override-export-commands/VB/ReportingWpfOverrideExportCommandVB/MainWindow.xaml.vb#L18

Dim window = New DXWindow() With {.Content = preview}
report.CreateDocument(True)
window.ShowDialog()

reporting-wpf-override-print-commands/VB/MinimalisticReportPreviewDemo/MainWindow.xaml.vb#L25

}
report.CreateDocument(True)
window.ShowDialog()