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.v20.1.dll


public virtual void CreateDocument(
    bool buildForInstantPreview
Public Overridable Sub CreateDocument(
    buildForInstantPreview As Boolean


Name Type Description
buildForInstantPreview Boolean

true to enable accessing document pages progressively as they are created; otherwise false.


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.


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

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.v20.1.dll is added to the project's reference list and the following code is executed.

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

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

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



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.

See Also