Excel Workbooks

The OfficeIMO.Excel package provides a higher-level API for creating, reading, and modifying Excel workbooks (.xlsx) without requiring Microsoft Office. It uses the Open XML SDK, an editable object model, a report builder, and a streaming writer for large exports.

Key Classes

Class	Description
`ExcelDocument`	Root class for creating and loading workbooks. Implements `IDisposable` and `IAsyncDisposable`.
`ExcelSheet`	Represents a single worksheet with cells, rows, columns, tables, and conditional formatting.
`ExcelTable`	An editable structured table with filters and styles.
`ExcelReportBuilder`	Sections, KPI rows, tables, and other report elements, reached through `sheet.Report()`.
`ExcelWorkbookWriter`	A bounded writer for forward-only exports, created by `ExcelDocument.CreateWriter()`.

Creating a Workbook

using OfficeIMO.Excel;

// Create with a file path
using var workbook = ExcelDocument.Create("report.xlsx");
var sheet = workbook.AddSheet("Sales");

sheet.Cell("A1").SetValue("Product");
sheet.Cell("B1").SetValue("Revenue");
sheet.Cell("A2").SetValue("Widget A");
sheet.Cell("B2").SetValue(15000);

workbook.Save();

Create with a named worksheet in one call:

using var workbook = ExcelDocument.Create("report.xlsx", new ExcelCreateOptions { FirstSheetName = "Sales" });
var sheet = workbook.Sheets[0]; // "Sales" sheet

Creating a Workbook in Memory

using var stream = new MemoryStream();
using var workbook = ExcelDocument.Create(stream);
var sheet = workbook.AddSheet("Data");
// ... populate ...
workbook.Save();

Loading an Existing Workbook

using var workbook = ExcelDocument.Load("existing.xlsx");

foreach (var sheet in workbook.Sheets) {
    Console.WriteLine($"Sheet: {sheet.Name}");
}

Add typed data

using OfficeIMO.Excel;

using var workbook = ExcelDocument.Create("monthly.xlsx");
workbook.Properties.Title = "Monthly Report";
workbook.Properties.Creator = "OfficeIMO";
var summary = workbook.AddSheet("Summary");
summary.AddTable(new[] {
    new { Metric = "Users", Value = 1250 },
    new { Metric = "Revenue", Value = 45000 }
}, new ExcelTableOptions { Name = "Metrics" });
var details = workbook.AddSheet("Details");
details.AddTable(new[] { new { Item = "Widget A", Quantity = 100, Price = 15.99m } });
workbook.Save();

Document Properties

using var workbook = ExcelDocument.Create("props.xlsx");

workbook.Properties.Title = "Financial Report";
workbook.Properties.Creator = "Finance Team";
workbook.ApplicationProperties.Company = "Evotec";

workbook.Save();

Execution Policy

Control parallel vs sequential operations for large workbooks:

var workbook = ExcelDocument.Create("large.xlsx");
workbook.Execution.Mode = ExcelExecutionMode.Parallel;
workbook.Execution.MaxDegreeOfParallelism = 4;

Sheet Caching

For very large workbooks, you can disable sheet wrapper caching to reduce memory:

workbook.SheetCachingEnabled = false;

CSV interoperability

Install the optional OfficeIMO.Excel.Csv adapter when a workflow needs to move data between CSV and Excel. The adapter keeps parsing and writing in OfficeIMO.CSV, workbook operations in OfficeIMO.Excel, and avoids adding CSV dependencies to Excel-only or Reader workloads.

dotnet add package OfficeIMO.Excel.Csv

using OfficeIMO.Excel;
using OfficeIMO.Excel.Csv;

using var workbook = ExcelDocument.Create();
ExcelCsvImportResult imported = workbook.ImportCsvFile("sales.csv");
workbook[imported.SheetName].SaveAsCsv("sales-roundtrip.csv");
workbook.Save("sales.xlsx");

imported.Delimiter reports the delimiter that was actually used, including one selected automatically by delimiter detection. imported.TableName reports the sanitized, unique table name that was actually created.

Use OfficeIMO.Reader.Excel instead when the job is normalized extraction of workbook content for search, indexing, or AI ingestion; it does not own CSV conversion.

Search OfficeIMO