XtraReport.CreateDocument() Method
Creates a document from the XtraReport object, so it can be displayed or printed.
Namespace: DevExpress.XtraReports.UI
Assembly: DevExpress.XtraReports.v20.1.dll
NuGet Packages: DevExpress.Reporting.Core, DevExpress.WindowsDesktop.Reporting.Core
Declaration
Remarks
Calling the CreateDocument method creates a report document that is ready to preview, print and export.
The newly 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. To see a code example, refer to the following help topic: Merging Reports.
Note
Once the document creation process has started, it will run until the document is complete. It cannot be interrupted or canceled during this process. To create a report document asynchronously in a separate task, use the CreateDocumentAsync(CancellationToken) method instead.
To be able to access document pages progressively as they are created, as well as interrupt or cancel the document creation, call the CreateDocument method overload with the buildForInstantPreview parameter set to true.
The CreateDocument method is called internally from the following methods (i.e., you do not need to call CreateDocument before calling one of these methods).
- PrintTool.ShowPreview and PrintTool.ShowPreviewDialog;
- PrintTool.ShowRibbonPreview and PrintTool.ShowRibbonPreviewDialog;
- ReportPrintTool.Print and LinkPrintTool.Print;
- all 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, or before printing and/or exporting.
If a report contains 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, unless 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);
report.CreateDocument();
}
If you call the CreateDocument method after this code assigns a ReportPrintTool to the report, it invokes a dialog that requests report parameter values.
Note
An attempt to call the CreateDocument method for a report that does not contain a DetailBand raises an exception (specifically, when creating a report in code). Add this band to the report even if you do not need to display information within it.
Example
This example illustrates the use of the XtraReport.CreateDocument method. The report’s Print Preview is shown by using ReportPrintTool.
In this example, an XRLabel object contained in the XtraReport1 class has its Modifiers property set to public.
using System;
using System.Drawing;
using System.Windows.Forms;
using DevExpress.XtraReports.UI;
// ...
private void button1_Click(object sender, EventArgs e) {
// Create a report and assign to a Print Tool.
XtraReport1 report = new XtraReport1();
ReportPrintTool printTool = new ReportPrintTool(report);
// Show the report's preview for the first time.
printTool.ShowPreviewDialog();
// Change the report's contents.
((XtraReport1)printTool.Report).xrLabel1.BackColor = Color.Blue;
// Create the report's document.
printTool.Report.CreateDocument();
// Show the report's preview for the second time.
printTool.ShowPreviewDialog();
}
Related GitHub Examples
The following code snippets (auto-collected from DevExpress Examples) contain references to the CreateDocument() 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.