XtraReport.CreateDocument() Method
Creates a document from the report instance to display or print at a later time.
Namespace: DevExpress.XtraReports.UI
Assembly: DevExpress.XtraReports.v23.2.dll
NuGet Package: DevExpress.Reporting.Core
Declaration
Remarks
The CreateDocument method creates a report document that is ready to preview, print, and export. The created document is bound to the report instance from which it was created. When you view the report later, the preview component loads the already created document as long as no changes are made to the report instance.
The newly created document is accessible through the following notation:
report.PrintingSystem.Document
The page collection is accessible through the XtraReport.Pages property.
You can merge document pages to create a complex report. For more information, review the following help topic: Merge Reports.
Once the document creation process starts, it will continue until the document is complete. The process cannot be interrupted or canceled. To create a report document asynchronously in a separate task, use the CreateDocumentAsync(CancellationToken) method instead.
If you want to access document pages progressively as they are created, and to stop or cancel document creation, call the CreateDocument method overload with the buildForInstantPreview parameter set to true.
When a Method Call is Not Necessary
You do not need to call CreateDocument before calling one of the following methods, as they call the CreateDocument method internally:
- 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).
How to Invoke the Parameters Window
The CreateDocument method itself does not invoke the Parameters dialog that allows the user to enter parameter values.
If the report contains parameters and the XtraReport.RequestParameters is set to true, you should add the DevExpress.XtraPrinting.v23.2.dll to the project reference list and call the CreateDocument method after the report is assigned to the ReportPrintTool:
using DevExpress.XtraReports.UI;
// ...
XtraReport1 report = new XtraReport1();
ReportPrintTool tool = new ReportPrintTool(report);
report.CreateDocument();
The Parameters dialog is invoked:
Note
An attempt to call the CreateDocument method for a report that does not include a DetailBand results in an exception. This may happen when a report is created in code. You should add the DetailBand band to the report, even if it is not necessary for your task.
Web Specifics
Web components call the CreateDocument method internally before a report is previewed, printed, or exported. You do not have to call the CreateDocument method manually unless your task is to merge reports or modify document pages.
In distributed systems, calls to the CreateDocument method may be used to properly configure the preview.
Example
The following code snippet shows how to add all pages of one report to the end of another report, how to merge pages of two reports into a single report, and how to reorder report pages so that they can be printed as a booklet.
private void CombineTwoReports() {
// Create the 1st report and generate its document.
XtraReport1 report1 = new XtraReport1();
report1.CreateDocument();
// Create the 2nd report and generate its document.
XtraReport2 report2 = new XtraReport2();
report2.CreateDocument();
// Add all pages of the 2nd report to the end of the 1st report.
report1.Pages.AddRange(report2.Pages);
// Reset all page numbers in the resulting document.
report1.PrintingSystem.ContinuousPageNumbering = true;
// Show the Print Preview form.
report1.ShowPreviewDialog();
}
private void MergeTwoReports() {
// Create the 1st report and generate its document.
XtraReport1 report1 = new XtraReport1();
report1.CreateDocument();
// Create the 2nd report and generate its document.
XtraReport2 report2 = new XtraReport2();
report2.CreateDocument();
// Merge pages of two reports, page-by-page.
int minPageCount = Math.Min(report1.Pages.Count, report2.Pages.Count);
for (int i = 0; i < minPageCount; i++) {
report1.Pages.Insert(i * 2 + 1, report2.Pages[i]);
}
if (report2.Pages.Count != minPageCount) {
for (int i = minPageCount; i < report2.Pages.Count; i++) {
report1.Pages.Add(report2.Pages[i]);
}
}
// Reset all page numbers in the resulting document.
report1.PrintingSystem.ContinuousPageNumbering = true;
// Show the Print Preview form.
report1.ShowPreviewDialog();
}
private void CreateBooklet() {
// Create the 1st report and generate its document.
XtraReport1 report1 = new XtraReport1();
report1.CreateDocument();
// Preserve original page numbers on all pages.
report1.PrintingSystem.ContinuousPageNumbering = false;
// Create a booklet.
int centerPageIndex = Convert.ToInt32((report1.Pages.Count - 1) / 2);
for (int i = 0; i < centerPageIndex; i++) {
report1.Pages.Insert(i * 2 + 1, report1.Pages[report1.Pages.Count - 1]);
}
// Show the Print Preview form.
report1.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.