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.v18.2.dll

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).

Calling the CreateDocument method is not required after assigning a report to the ASPxDocumentViewer or ASPxWebDocumentViewer 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.v18.2.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_how-to-export-reports-to-different-sheets-in-an-xlsx-file-by-using-spreadsheet-e4892/CS/WindowsFormsApplication1/Form1.cs#L22

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

Reporting_how-to-add-an-empty-page-if-a-group-in-the-report-ends-on-an-even-page-e4990/CS/WindowsFormsApplication1/Form1.cs#L20

XtraReport1 report = new XtraReport1();
report.CreateDocument(false);

Reporting_how-to-sort-a-report-in-documentpreviewcontrol-t329474/CS/WpfApplication1/MainWindow.xaml.cs#L32

XtraReport1 rep = new XtraReport1();
rep.CreateDocument(false);

Reporting_how-to-build-report-pages-progressively-to-be-able-to-access-them-as-soon-as-they-are-e960/CS/Form1.cs#L30

private void btnStart_Click(object sender, EventArgs e) {
    report.CreateDocument(true);
}

Reporting_how-to-implement-editing-in-the-preview-form-e26/CS/XtraReport1.cs#L21

    ((DataRowView)e.Brick.Value)[fieldName] = frm.str;
    this.CreateDocument(false);
}

VB.NET

Reporting_how-to-export-reports-to-different-sheets-in-an-xlsx-file-by-using-spreadsheet-e4892/VB/WindowsFormsApplication1/Form1.vb#L24

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

Reporting_how-to-add-an-empty-page-if-a-group-in-the-report-ends-on-an-even-page-e4990/VB/WindowsFormsApplication1/Form1.vb#L22

Dim report As New XtraReport1()
report.CreateDocument(False)

Reporting_how-to-sort-a-report-in-documentpreviewcontrol-t329474/VB/WpfApplication1/MainWindow.xaml.vb#L31

Dim rep As New XtraReport1()
rep.CreateDocument(False)

Reporting_how-to-build-report-pages-progressively-to-be-able-to-access-them-as-soon-as-they-are-e960/VB/Form1.vb#L32

Private Sub btnStart_Click(ByVal sender As Object, ByVal e As EventArgs) Handles btnStart.Click
    report.CreateDocument(True)
End Sub

Reporting_how-to-implement-editing-in-the-preview-form-e26/VB/XtraReport1.vb#L23

    CType(e.Brick.Value, DataRowView)(fieldName) = frm.str
    Me.CreateDocument(False)
End Sub

Implements

CreateDocument(Boolean)