devexpress/agent-skills/devexpress-office-file-api-excel-export

DevExpress Excel Export Library

The Excel Export Library is a low-level, streaming .NET API for generating Excel files (.xlsx, .xls, .csv) with a minimal memory footprint. It writes rows sequentially to an output stream and cannot read or modify existing files. Use it when you need to produce large Excel reports from databases or data grids without loading the entire document into RAM. The primary namespace is DevExpress.Export.Xl.

Excel Export Library vs. Spreadsheet Document API

Rule: If the developer needs to read, modify, add charts, or create pivot tables → use the Spreadsheet Document API skill instead. If they need to stream-generate a large file from data → this skill is correct.

When to Use This Skill

Use this skill when you need to:

• Generate large Excel reports (.xlsx) with low memory consumption
• Write rows sequentially from a database reader or IEnumerable data source
• Export grid or report engine data to Excel in a streaming fashion
• Create Excel files in server-side or cloud environments where RAM is constrained
• Apply cell formatting (fonts, colors, borders, number formats) during export
• Add formulas, subtotals, or AutoFilter to generated files
• Create conditional formatting rules on streamed data
• Build Excel tables (IXlTable) with styles and calculated columns
• Insert sparklines or pictures into generated worksheets
• Configure print settings, headers/footers, and page breaks
• Add data validation rules to cell ranges

Prerequisites & Installation

NuGet Packages

String formulas (parsed from text) require an additional reference — see references/getting-started.md.

.NET (8/9/10+)

dotnet add package DevExpress.Document.Processor

.NET Framework (4.6.2+)

Add assembly references manually — see references/getting-started-dotnet-fw.md.

Important: All DevExpress packages in a project must share the same version number. A valid DevExpress license is required.

Package Versions

Unless the user explicitly requests a specific version, always target the latest DevExpress release (v26.1 at the time of writing). dotnet add package <PackageName> without --version installs the latest stable version — prefer this form. Never pin an older version in project files, Dockerfiles, or CI/CD pipelines unless the user asks for it. This is especially important in integration scenarios (Docker, cloud deployments). All DevExpress.* packages in a project must share the same version.

Before You Start — Ask the Developer

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.

Before generating code, ask these questions to avoid rework:

General Questions

1. Target framework: Are you using .NET 8+ or .NET Framework 4.x?
2. New or existing project?: Are you creating a new project or adding to an existing one?
3. Hosting model: Console app, ASP.NET Core, Blazor, MAUI, WinForms, WPF, or something else?

Excel Export-Specific Questions

1. Scenario check: Are you generating a new large report (this library is correct) or do you need to read/modify an existing file (use Spreadsheet Document API instead)?
2. Data source: IEnumerable / DataTable / direct row-by-row writing / database reader?
3. Excel features beyond basic cells: formulas / tables / conditional formatting / sparklines / pictures / printing?

Rule: If the developer's answer is ambiguous or missing, ask before generating code. Do not guess.

Component Overview

The Excel Export Library provides:

• Exporter factory: Create an exporter targeting XLSX, XLS, or CSV (XlExport, IXlExporter)
• Document and sheet management: Create documents and worksheets sequentially (IXlDocument, IXlSheet)
• Row and column writing: Stream rows and configure columns (IXlRow, IXlColumn)
• Cell authoring: Set values (string, number, bool, date, error), formulas, and formatting (IXlCell, XlCellFormatting)
• Advanced worksheet features: Conditional formatting, tables, sparklines, pictures, data validation, print settings

Core Entry Point

using DevExpress.Export.Xl;
using System.IO;
 
// Step 1: create an exporter for the target format
IXlExporter exporter = XlExport.CreateExporter(XlDocumentFormat.Xlsx);
 
// Step 2: open a stream and create the document
using (FileStream stream = new FileStream("output.xlsx", FileMode.Create, FileAccess.ReadWrite))
using (IXlDocument document = exporter.CreateDocument(stream))
{
    // Step 3: create a sheet
    using (IXlSheet sheet = document.CreateSheet())
    {
        sheet.Name = "Report";
 
        // Step 4: write rows top-to-bottom
        using (IXlRow row = sheet.CreateRow())
        using (IXlCell cell = row.CreateCell())
        {
            cell.Value = "Hello, World!";
        }
    }
} // document is finalized and flushed here

Documentation & Navigation Guide

Getting Started (.NET)

Refer to references/getting-started.md

When you need to:

• Install NuGet packages and set up a .NET project
• Understand the streaming document model
• Create your first XLSX file end-to-end
• Use string formulas (requires XlFormulaParser)
• See a complete working example with headers and data rows

Getting Started (.NET Framework)

Refer to references/getting-started-dotnet-fw.md

When you need to:

• Set up a .NET Framework 4.6.2+ project with assembly references
• Understand which DLLs are required
• Handle framework-specific API differences

Cells and Formatting

Refer to references/cells-and-formatting.md

When you need to:

• Create cells and set values (string, numeric, bool, date, error)
• Apply fonts, colors, background fills, and borders
• Set number formats (currency, date, percentage, custom)
• Align cell content (horizontal, vertical, wrap, indent)
• Apply predefined or theme-based cell styles
• Create rich text (mixed fonts within a single cell)
• Merge cells or add hyperlinks
• Apply conditional formatting rules

Advanced Features

Refer to references/advanced-features.md

When you need to:

• Create Excel tables (IXlTable) with styles and calculated columns
• Add string, expression, or token-based cell formulas
• Create shared formulas or SUBTOTAL aggregations
• Add sparklines (line, column, win/loss) and customize them
• Insert pictures and add hyperlinks to pictures
• Configure print settings, page margins, headers/footers, page breaks, print titles
• Group rows or columns
• Enable AutoFilter on a data range
• Add data validation rules

Quick Start Example

using DevExpress.Export.Xl;
using System.IO;
 
IXlExporter exporter = XlExport.CreateExporter(XlDocumentFormat.Xlsx);
 
using (FileStream stream = new FileStream("SalesReport.xlsx", FileMode.Create, FileAccess.ReadWrite))
using (IXlDocument document = exporter.CreateDocument(stream))
{
    using (IXlSheet sheet = document.CreateSheet())
    {
        sheet.Name = "Sales";
 
        // Freeze header row
        sheet.SplitPosition = new XlCellPosition(0, 1);
 
        // Header formatting
        XlCellFormatting headerFmt = new XlCellFormatting();
        headerFmt.Font = new XlFont { Bold = true };
        headerFmt.Font.Color = XlColor.FromTheme(XlThemeColor.Light1, 0.0);
        headerFmt.Fill = XlFill.SolidFill(XlColor.FromTheme(XlThemeColor.Accent1, 0.0));
 
        // Write header row
        string[] headers = { "Product", "Q1", "Q2", "Total" };
        using (IXlRow row = sheet.CreateRow())
        {
            foreach (string h in headers)
            {
                using (IXlCell cell = row.CreateCell())
                {
                    cell.Value = h;
                    cell.ApplyFormatting(headerFmt);
                }
            }
        }
 
        // Write 3 data rows
        string[] products = { "Widget A", "Widget B", "Widget C" };
        int[] q1 = { 12000, 8500, 15000 };
        int[] q2 = { 14500, 9200, 11000 };
 
        for (int i = 0; i < 3; i++)
        {
            using (IXlRow row = sheet.CreateRow())
            {
                using (IXlCell cell = row.CreateCell()) { cell.Value = products[i]; }
                using (IXlCell cell = row.CreateCell()) { cell.Value = q1[i]; }
                using (IXlCell cell = row.CreateCell()) { cell.Value = q2[i]; }
                using (IXlCell cell = row.CreateCell())
                {
                    // Formula: =B{row}+C{row}
                    int rowNum = i + 2;
                    cell.SetFormula($"=B{rowNum}+C{rowNum}");
                }
            }
        }
 
        // Enable AutoFilter
        sheet.AutoFilterRange = sheet.DataRange;
    }
}

What This Does

Creates SalesReport.xlsx with a styled header row (bold, theme-colored), three data rows with numeric Q1/Q2 values, a formula-driven Total column, a frozen header row, and AutoFilter enabled. No Microsoft Office is required.

Key Properties & API Surface

XlExport (static entry point)

IXlExporter

IXlDocument

IXlSheet

IXlRow