DevExpress XtraReports — Core Runtime API

When to Use This Skill

CRITICAL — Do not bypass this skill. Whenever this skill is active, follow the patterns and constraints here. Do not substitute your own general knowledge of DevExpress APIs. If a scenario is not covered in the main skill body, read the relevant reference file or use MCP servers before writing code — do not guess API signatures.

Use for any task involving:

• Creating XtraReport instances and building report structure in code
• Adding bands (DetailBand, GroupHeaderBand, ReportHeaderBand, etc.)
• Adding controls (XRLabel, XRTable, XRChart, XRPictureBox, etc.) to bands
• Binding reports to data sources (IList, DataTable, SqlDataSource, ObjectDataSource)
• Defining report parameters, calculated fields, and expression bindings
• Exporting reports: ExportToPdf, ExportToXlsx, ExportToDocx, ExportToCsv, etc.
• Configuring PdfExportOptions, XlsxExportOptions, etc.
• Saving/loading report layouts with SaveLayoutToXml / LoadLayoutFromXml
• Report types: table, master-detail, cross-tab, label, subreport

Scope: This skill covers runtime API only — no viewer UI, no print preview, no designer embedding. For platform-specific viewer integration, see: devexpress-reports-aspnetcore, devexpress-reports-blazor, devexpress-reports-winforms, or devexpress-reports-wpf.

Before You Start

If the host agent has a structured question-asking tool available, use it to ask these questions one at a time with clear options — for example, Claude Code's AskUserQuestion tool or GitHub Copilot's askQuestions tool. If no such tool is available, ask the questions directly in the chat response before generating code.

Ask the developer:

1. Target framework: .NET 8+ or .NET Framework 4.x?
2. Platform: WinForms, WPF, ASP.NET Core, Blazor, console/service, or MAUI?
3. Operation: Create a new report in code? Load existing .repx layout? Modify an existing report class?
4. Data source: What data are you binding? (IList/collection, DataTable/DataSet, EF DbContext, SQL database, JSON, Excel, none)
5. Output: Export to file/stream? Which format(s)? Or display in a viewer?
6. Existing NuGet setup: Are DevExpress packages already installed, or starting fresh?

Prerequisites & Installation

Add the platform NuGet package from nuget.org:

Platform	NuGet Package
WinForms	DevExpress.Win.Reporting
WPF	DevExpress.Wpf.Reporting
ASP.NET Core	DevExpress.AspNetCore.Reporting
ASP.NET Web Forms and MVC	DevExpress.Web.Reporting
Console / server	DevExpress.Reporting.Core (core only)

All packages include the required namespaces (DevExpress.XtraReports.UI, DevExpress.XtraPrinting, DevExpress.Drawing) and export infrastructure.

Linux/macOS (non-Windows): Add DevExpress.Drawing.Skia for PDF rendering support.

Core Classes Overview

Class	Namespace	Role
XtraReport	DevExpress.XtraReports.UI	Root report object
DetailBand	DevExpress.XtraReports.UI	Repeating data rows (mandatory)
ReportHeaderBand	DevExpress.XtraReports.UI	Once at report start
ReportFooterBand	DevExpress.XtraReports.UI	Once at report end
GroupHeaderBand	DevExpress.XtraReports.UI	Group header
GroupFooterBand	DevExpress.XtraReports.UI	Group summary
PageHeaderBand	DevExpress.XtraReports.UI	Every page top
PageFooterBand	DevExpress.XtraReports.UI	Every page bottom
DetailReportBand	DevExpress.XtraReports.UI	Nested (master-detail) data
XRLabel	DevExpress.XtraReports.UI	Text / field display
XRTable / XRTableRow / XRTableCell	DevExpress.XtraReports.UI	Tabular layout
XRPictureBox	DevExpress.XtraReports.UI	Images
XRChart	DevExpress.XtraReports.UI	Charts
XRCrossTab	DevExpress.XtraReports.UI	Pivot tables
XRSubreport	DevExpress.XtraReports.UI	Embedded subreport
XRPageInfo	DevExpress.XtraReports.UI	Page number, date
Parameter	DevExpress.XtraReports.Parameters	Report parameter
CalculatedField	DevExpress.XtraReports.UI	Computed field

Quick Start — Report in Code

using DevExpress.XtraReports.UI;

var report = new XtraReport {
    DataSource = GetProducts(), // IList, DataTable, etc.
    Name = "ProductReport"
};

var detail = new DetailBand();
report.Bands.Add(detail);
detail.HeightF = 30;

var nameLabel = new XRLabel();
detail.Controls.Add(nameLabel);
nameLabel.BoundsF = new RectangleF(0, 0, 200, 25);
nameLabel.ExpressionBindings.Add(new ExpressionBinding("BeforePrint", "Text", "[ProductName]"));

// Export
report.ExportToPdf("output.pdf");

See examples/quickstart.cs for a full working example with grouping, a page header, and PDF export.

Single-field display only: The pattern above uses XRLabel for one field. For reports with multiple side-by-side columns, group subtotals, images, or charts — read references/report-controls.md (control types) and references/report-bands.md (band types) before writing code.

For designer-backed reports (with InitializeComponent()): do not add a second DetailBand. See Antipatterns (AP7) and Constraint 9.

Export API

All export methods have sync and async variants:

// To file path
report.ExportToPdf("report.pdf");
report.ExportToXlsx("report.xlsx");
report.ExportToDocx("report.docx");
report.ExportToCsv("report.csv");
report.ExportToHtml("report.html");
report.ExportToImage("report.png");
report.ExportToRtf("report.rtf");
report.ExportToText("report.txt");
report.ExportToXls("report.xls");
report.ExportToMht("report.mht");

// To stream (preferred for web/API scenarios)
using var ms = new MemoryStream();
report.ExportToPdf(ms);

// Async (required in web apps)
await report.ExportToPdfAsync(ms);

With options:

var pdfOptions = new DevExpress.XtraPrinting.PdfExportOptions {
    PageRange = "1-3",
    PdfACompatibility = DevExpress.XtraPrinting.PdfACompatibility.PdfA2b
};
report.ExportToPdf("report.pdf", pdfOptions);

📄 See references/export.md for all ExportOptions classes and their properties.

Common Patterns

Pattern 1 — Data-bound report:

report.DataSource = myList;       // IList, DataTable, or DevExpress data source
report.DataMember = "Orders";     // Table name (for DataSet) or empty for simple list

Pattern 2 — Expression binding:

Do not use DataBindings.Add — this is the legacy binding mode. See Antipatterns (AP1).

// Specify an expression that calculates total value from UnitPrice and UnitsInStock fields.
label.ExpressionBindings.Add(new ExpressionBinding("BeforePrint", "Text", "[UnitPrice]*[UnitsInStock]"));
// Specify an expression that is rendered within the PrintOnPage event.
label.ExpressionBindings.Add(new ExpressionBinding("PrintOnPage", "Text", "'Printed'"));

Expression function names are NOT .NET method names — see Antipatterns (AP2) and references/expressions.md for the complete catalogue.

Pattern 3 — Report parameter:

// Create a date report parameter.
// Use an expression to specify the parameter's default value.
var dateParameter = new Parameter() {
    Name = "date",
    Description = "Date:",
    Type = typeof(System.DateTime),
    ExpressionBindings = { new BasicExpressionBinding("Value", "Now()") }
};
// Add the parameter to the report's Parameters collection.
report.Parameters.Add(dateParameter);
// Create a label and bind the label's Text property to the parameter value.
// Use the parameter's name to reference the parameter in the label's expression.
var dateLabel = new XRLabel();
report.Bands[BandKind.Detail].Controls.Add(dateLabel);
dateLabel.BoundsF = new RectangleF(0, 0, 200, 50);
dateLabel.ExpressionBindings.Add(new ExpressionBinding("BeforePrint", "Text", "?date"));
// Use the parameter in the report filter if needed:
report.FilterString = "[OrderDate] >= ?date";

Pattern 4 — Save/Load layout:

report.SaveLayoutToXml("layout.repx");  // .repx = XML serialization

var loaded = XtraReport.FromXmlFile("layout.repx");

Pattern 5 — CreateDocument before export (optional, ensures data is prepared):

report.CreateDocument();           // sync — OK in desktop apps
// OR in web:
await report.CreateDocumentAsync();
report.ExportToPdf(outputStream);

Pattern 6 — Tabular column layout with XRTable:

Use XRTable / XRTableRow / XRTableCell for every multi-column layout — data rows, header rows, and summary rows. See Antipatterns (AP3).

var table = new XRTable();
detail.Controls.Add(table);
table.BeginInit();
var row = new XRTableRow();
table.Rows.Add(row);
var nameCell = new XRTableCell { WidthF = 450 };  // absolute column width in pixels
var priceCell = new XRTableCell { WidthF = 200 };  // 450 + 200 = 650 (equals table SizeF.Width)
row.Cells.Add(nameCell);
row.Cells.Add(priceCell);
nameCell.ExpressionBindings.Add(new ExpressionBinding("BeforePrint", "Text", "[ProductName]"));
priceCell.ExpressionBindings.Add(new ExpressionBinding("BeforePrint", "Text", "[UnitPrice]"));
table.SizeF = new SizeF(650, 25);  // total width = sum of cell WidthF values
table.EndInit();
// See references/report-controls.md for the full XRTable reference.

Pattern 7 — Group or report summary using XRSummary:

Summary labels require XRSummary. See Antipatterns (AP5, AP6).

// Pattern A — XRSummary.Func + FormatString (simplest for standard aggregates):
var countLabel = new XRLabel();
groupFooter.Controls.Add(countLabel);
countLabel.BoundsF = new RectangleF(0, 0, 200, 25);
countLabel.Summary = new XRSummary {
    Func = SummaryFunc.Count,        // .Sum, .Avg, .Max, .Min, .Count, etc.
    Running = SummaryRunning.Group,  // .Page / .Report
    FormatString = "Count: {0}"      // {0} is replaced by the calculated value
};

// Pattern B — XRSummary.Running + ExpressionBinding with sum*() for computed expressions:
var totalLabel = new XRLabel();
groupFooter.Controls.Add(totalLabel);
totalLabel.BoundsF = new RectangleF(0, 0, 200, 25);
totalLabel.Summary = new XRSummary { Running = SummaryRunning.Group };
totalLabel.ExpressionBindings.Add(new ExpressionBinding("BeforePrint", "Text", "sumSum([Price])"));
// Other sum*() functions: sumAvg([Field]), sumCount(), sumSum([Field]), sumMin([Field])
// See references/expressions.md for the full Summary Functions reference.

Pattern 8 — Calculate available control width from page dimensions:

// Set Margins first, then compute availableWidth once and reuse it across all bands.
Margins = new DevExpress.Drawing.DXMargins(50, 50, 50, 50); // Left, Right, Top, Bottom
var availableWidth = PageWidthF - Margins.Left - Margins.Right;

// Single control filling the full band width:
label.BoundsF = new RectangleF(0, 0, availableWidth, 25);
table.SizeF   = new SizeF(availableWidth, 25);

// Multi-column table — proportional fractions of availableWidth:
cell1.WidthF = availableWidth * 0.67f;
cell2.WidthF = availableWidth * 0.33f;
// Rule: cell1.WidthF + cell2.WidthF must equal table.SizeF.Width exactly.

Set full-band controls to availableWidth. See Antipatterns (AP9).

Key Properties — XtraReport

Property	Type	Description
DataSource	object	Data source (IList, DataTable, DevExpress source)
DataMember	string	Table/collection path within the data source
Bands	BandCollection	All bands in the report
Parameters	ParameterCollection	Report parameters
CalculatedFields	CalculatedFieldCollection	Calculated fields
FilterString	string	Report-level data filter
ExportOptions	ExportOptions	Default export settings
StyleSheet	XRControlStyleCollection	Named styles
ReportUnit	ReportUnit	HundredthsOfAnInch or TenthsOfAMillimeter
Margins	DXMargins	Page margins (DevExpress.Drawing)
PaperKind	DXPaperKind	Paper size (DevExpress.Drawing.Printing)
Landscape	bool	Page orientation

Troubleshooting

Symptom	Cause	Fix
DetailBand required exception at render	No DetailBand added	Always add a DetailBand to report.Bands
Export file is empty / 0 bytes	DataSource null or no records	Verify data source returns data before export
ko is not defined at runtime (web)	Not relevant to core API	See devexpress-reports-aspnetcore skill
PDF export fails on Linux	Missing Skia package	Add DevExpress.Drawing.Skia NuGet package
ExpressionBinding has no effect	Binding added to wrong property name	Check property name is "Text", "Visible", etc. — case-sensitive
LoadLayoutFromXml loses data source	.repx does not store data	Re-assign DataSource after LoadLayoutFromXml
Build error: namespace not found	Missing using directive	Add using DevExpress.XtraReports.UI; and using DevExpress.XtraReports.Parameters;
CreateDocument() hangs in web app	Blocking call on async context	Use await report.CreateDocumentAsync() in web/API
Code uses DataBindings.Add("Text", null, "Field")	Legacy binding API	Replace with ExpressionBindings.Add(new ExpressionBinding("BeforePrint", "Text", "[Field]")). See Constraint 13.
Group footer label shows last value, or error XRE093 "no summary functions"	Expression uses Sum([Field]) — not a valid DevExpress reporting function	Replace with sumSum([Field]); ensure label.Summary.Running is set. See Pattern 7 and references/expressions.md
Summary label displays expression literally or shows 0 / nothing	XRSummary not set on the label — sumCount(), sumSum() etc. were used in ExpressionBinding without label.Summary	Assign label.Summary = new XRSummary { Running = SummaryRunning.Group } (Pattern A or B). XRSummary is always required. See Pattern 7.
Expression binding silently ignored or runtime error with unrecognized function	Expression function name guessed from C# knowledge (e.g., Format(), String.Format(), ToString()) — no such function in DevExpress expression language	Use FormatString(format, value) for formatting; check references/expressions.md for the full function list. See Pattern 2.
System.Exception: Incorrect band type at report constructor	A second instance of a singleton band (DetailBand, TopMarginBand, BottomMarginBand) was added via Bands.Add() after the singleton band was already created previously	Remove the Bands.Add() call; get the existing band from the designer field (e.g., detailBand1) and configure it directly. See Constraint 9.

Constraints & Rules

1. Always add DetailBand for newly created reports: XtraReport requires at least one DetailBand in Bands to render.
2. Never mix package versions: All DevExpress NuGet packages in a project must be the same version (e.g., all 26.1.*).
3. Namespace imports: Always include using DevExpress.XtraReports.UI;. Never assume it exists.
4. ExpressionBinding property names are case-sensitive: "Text" not "text".
5. DataSource is not serialized: .repx files store layout only. When loading with LoadLayoutFromXml, re-assign DataSource explicitly. When using XtraReport.FromXmlStream(), the concrete subclass is restored so constructor-assigned data sources are preserved — but any runtime-assigned data must still be re-assigned.
6. Async in web: Use await report.CreateDocumentAsync() and await report.ExportToPdfAsync() in ASP.NET Core and Blazor.
7. No destructive changes: When modifying existing report classes, preserve existing band/control structure; only add or modify what is required.
8. Verify build: Always run dotnet build and confirm 0 errors before reporting task complete.
9. Singleton bands in designer-backed reports: XtraReport enforces exactly one DetailBand, one TopMarginBand, and one BottomMarginBand. In a designer-backed partial class (one with InitializeComponent()), these bands already exist. Calling Bands.Add(new DetailBand()) will throw System.Exception: Incorrect band type at runtime. Rule: Reuse the existing singleton bands declared in the designer file (e.g., detailBand1). Only call Bands.Add(...) for band types that may appear multiple times (e.g., GroupHeaderBand, PageFooterBand) and that InitializeComponent() did not already add.
10. Project structure — designer file class ordering: When adding helper or model classes alongside a report class, never place them before the XtraReport subclass in the same .cs file. Visual Studio requires the designed class to be the first class in its file. Place model/helper classes in a dedicated separate file (e.g., Model/Product.cs).
11. Project structure — respect existing folders: Before creating a new folder for model or helper classes, inspect the existing project structure. If a folder already exists for models (e.g., Model, Models, Data) or reports (e.g., Reports, PredefinedReports), place new files inside it and match its name and namespace exactly. Never create a parallel folder with a similar name.
12. Tabular layout must use XRTable: Any multi-column layout — data rows in DetailBand, static column header rows in GroupHeaderBand or PageHeaderBand, summary rows in GroupFooterBand — must use XRTable / XRTableRow / XRTableCell. Never build a helper that positions XRLabel controls at calculated x offsets. Never simulate a table with multiple XRLabel controls at absolute X positions. This constraint applies to header rows and static text rows equally, not only to data-bound rows. See Pattern 6.
13. Never use DataBindings: DataBindings is the legacy binding mode. For new reports, always use ExpressionBindings with new ExpressionBinding(eventName, propertyName, expression). Generating DataBindings.Add(...) is not recommended unless maintaining legacy reports.
14. Set size/position properties AFTER adding to parent — never in object initializers: Always call Bands.Add(band) before setting band.HeightF, and always call Controls.Add(control) before setting control.BoundsF, control.LocationF, or control.SizeF. Report objects inherit the parent's measure unit when added to a parent; sizes assigned before this point will be silently recalculated and produce incorrect layout. Other properties (Text, Font, TextAlignment, ForeColor, ExpressionBindings, GroupFields, etc.) may be set at any time, including in object initializers. ✅ Correct: var label = new XRLabel { Text = "X", Font = … }; band.Controls.Add(label); label.BoundsF = …; ❌ Wrong: var label = new XRLabel { BoundsF = …, Text = "X" }; band.Controls.Add(label);
15. Content properties are mandatory — never omit them: Some controls have one or more essential content properties that hold the actual data to be displayed. XRLabel requires Text, XRPictureBox requires ImageSource or ImageUrl, XRBarCode requires Text or BinaryData, XRCheckBox requires CheckBoxState, XRGauge requires ActualValue, XRRichText requires Rtf or Html, etc. These are not optional styling tweaks — without them the control will be invisible or non-functional. Always bind content properties via ExpressionBindings or assign values directly. See references/report-controls.md for each control's content property requirements.
16. Adding assembly references (.NET Framework): Resolve the required assemblies via the DevExpress Docs MCP, add the corresponding NuGet package, or — if a visual designer is available — have the developer drag the control from the Toolbox so references are added automatically. Avoid manually editing the .csproj references node to add new assembly references.

Antipatterns

The following patterns produce incorrect output, runtime errors, or layout bugs. Never generate code matching these shapes.