OfficeIMO.Excel 3.6.0

OfficeIMO.Excel

Create, edit, read and save Excel workbooks (.xlsx, and the supported subsets of .xlsb and Excel 97–2003 .xls) in .NET, without Microsoft Excel or COM. Tables, charts and cell styles follow the workbook's theme; very large exports stream rows with bounded memory.

Returned authoring objects

range.ConditionalFormat() adds rules; each call returns the attached ExcelConditionalFormattingInfo, the same editable model used by AddConditionalFormattingRule. Edit the returned model and call sheet.UpdateConditionalFormattingRule(rule) to apply it, or pass it to RemoveConditionalFormattingRule to remove that exact rule. Pivot conditional formats use the pivot's output range: sheet.Range(sheet.GetPivotTableRange(name)).ConditionalFormat().

range.AutoFilter() returns the ExcelAutoFilter on that range. Column(header) or Column(offset) sets criteria, Clear() removes the filter and Inspect() reads current criteria and table ownership. Creating the handle preserves deferred workbook exports. AddTableOfContents returns the sheet it creates, and AddPivotManualGrouping returns the created ExcelPivotGroupingInfo.

CustomProperties.Add returns the attached ExcelCustomProperty, so edits to the returned value are saved with the workbook. The collection also implements IDictionary<string, ExcelCustomProperty> and ICollection<KeyValuePair<string, ExcelCustomProperty>>.

AddManualRowPageBreak and AddManualColumnPageBreak return an attached ExcelPageBreak with its worksheet, index, orientation and Remove() method. AddMacro returns the attached ExcelMacroProject, which can read, save or remove the VBA payload. Removed or replaced handles reject further operations. AddIgnoredErrorRegion returns the created ExcelIgnoredErrorRegionInfo. AddBackLinksToToc returns hyperlink metadata keyed by the worksheets receiving links. Use AddImage to create an image and receive its ExcelImage. Image dimensions and anchor offsets use OfficeLength: image.Width, image.Height, image.OffsetX and image.OffsetY retain whole EMUs. Two-cell ending offsets use ToOffsetX and ToOffsetY. For example, replace widthPixels: 96 with new ExcelImageOptions { Width = OfficeLength.Pixels(96) }. SetSize, MoveTo, SetTwoCellEndingMarker and TryGetAbsoluteAnchorBounds use the same length contract. Cell and ending-marker offsets on existing XML remain inspectable when signed; SetTwoCellEndingMarker requires non-negative ending offsets; the absolute-position AddImage(x, y, ...) overload requires non-negative authored positions. HTML round trips preserve signed positions and offsets read from existing native drawings. Omitted byte-image sizes remain 96 by 32 pixels at 96 DPI, while file/scaled placement retains its source-dimension defaults. Remote insertion also uses detected source dimensions when width, height and scale are omitted; use explicit lengths to request a fixed 96 by 32 pixel image. Raster export applies its pixel rounding and safety limits when rendering. GetRangeSize returns Width and Height as lengths; worksheet reports insert images through sheet.Report().AddImage(...).

Use AddImage with a path, stream or native byte array. AddImageAsync reads files and streams asynchronously or loads an HTTP or HTTPS Uri. Geometry, metadata, network policy and stream ownership belong to ExcelImageOptions:

ExcelImage logo = sheet.AddImage(2, 3, "logo.png", new ExcelImageOptions {
    ScalePercent = 20,
    Description = "Company logo",
    Title = "Logo"
});
sheet.AddImage("A1:C15", File.ReadAllBytes("header.png"), new ExcelImageOptions {
    Placement = ExcelImagePlacement.MoveAndSize
});
await sheet.AddImageAsync(4, 2, new Uri("https://example.org/logo.png"));

A single A1 reference uses a one-cell anchor; a colon-delimited range, including A1:A1, uses a two-cell anchor. AddImage(x, y, source, options) uses an absolute anchor. Range anchors determine their own size and reject explicit dimensions or scale. LockAspectRatio sets Excel's picture lock; it does not calculate an omitted dimension. Streams stay open by default and retain their seekable position; LeaveOpen = false closes them on success, failure or cancellation. Image bytes are embedded without re-encoding. Deduplicate = true shares identical native payloads within the worksheet drawing while each picture keeps its own metadata; the default creates separate image parts. sheet.Report() uses the same options and returns the worksheet's attached image.

Install

dotnet add package OfficeIMO.Excel
dotnet add package OfficeIMO.Excel.Pdf   # only for SaveAsPdf

Targets netstandard2.0, net8.0 and net10.0, plus net472 on Windows.

A table and a chart from your data

using OfficeIMO;
using OfficeIMO.Excel;

Order[] orders = [
    new("Contoso", "North", 12_400m, 0.21),
    new("Fabrikam", "South", 8_900m, 0.17),
    new("Northwind", "North", 15_100m, 0.24),
    new("Tailspin", "West", 6_300m, 0.12)
];

using var book = ExcelDocument.Create("Orders.xlsx", new ExcelCreateOptions { Theme = OfficeTheme.Modern });
ExcelSheet sheet = book.AddSheet("Orders");

ExcelTable table = sheet.AddTable(orders, new OfficeTableOptions { Name = "Orders" });
sheet.AddChart(OfficeChartType.Column, orders, nameof(Order.Customer),
    new ExcelChartOptions { Title = "Revenue by customer", Row = 2, Column = 7 }, nameof(Order.Total));

book.Save();

record Order(string Customer, string Region, decimal Total, double Margin);

AddTable writes a native Excel table: a header row from the property names, typed cells and the theme's table style. It returns the ExcelTable, and AddChart returns the ExcelChart, for further changes. ExcelChartOptions.Row and Column anchor the chart; Width and Height take an OfficeLength.

Cells, formulas and formatting

using OfficeIMO;
using OfficeIMO.Excel;

using var book = ExcelDocument.Create("Budget.xlsx");
ExcelSheet sheet = book.AddSheet("Budget");

sheet.Range("A1:B3").SetValues(new object?[,] {
    { "Item", "Cost" },
    { "Laptops", 18_500m },
    { "Licenses", 7_250m },
});
sheet.Cell("A4").SetValue("Total").SetBold();
sheet.Cell("B4").SetFormula("SUM(B2:B3)");

sheet.Range("A1:B1").SetBold().SetFillColor(OfficeColor.Parse("D9EAF7"));
sheet.Range("B2:B4").SetNumberFormat("#,##0.00");
sheet.Range("B2:B3").ConditionalFormat().DataBar(OfficeColor.Accent1);
sheet.View.Freeze(topRows: 1);
sheet.AutoFitColumns();

book.Save();

Rows and columns are 1-based, as in Excel. sheet.Cell(row, column) and sheet.Cell("B4") return a lightweight ExcelCell handle (a struct, so a loop over cells allocates nothing); sheet.Range("A1:V1") returns an ExcelRange. Format a block through its range rather than cell by cell: one range call applies the style under one lock and saves the stylesheet once. sheet.UsedRange returns the range in use, and book.GetNamedRange("Total")?.FirstCell writes through a defined name without parsing its address.

Cells created in a formatted row or column start with that row's or column's style, so values written into a template keep its number formats and fonts. A date written into a cell that already has a date format keeps it.

Native roles such as OfficeColor.Accent1 stay linked to the workbook theme. Success, Warning and Danger use the shared palette selected at creation or through book.ApplyTheme(theme). Loading a file or replacing raw theme XML does not infer these status roles, because Excel's native theme has no slots for them. In that case, pass color.Resolve(theme) as a literal color, or call book.ApplyTheme(theme) before authoring with status roles.

Read rows back as objects

using OfficeIMO.Excel;

using var book = ExcelDocument.Load("Orders.xlsx");
foreach (Order order in book["Orders"].RowsAs<Order>()) {
    Console.WriteLine($"{order.Customer}: {order.Total:N0}");
}

record Order(string Customer, string Region, decimal Total, double Margin);

Columns map to properties or constructor parameters by header name. RowsAs also accepts a factory or an explicit column mapping. For files from outside your organization, load with ExcelLoadOptions.UntrustedDefaults.

For a forward-only read, OpenReader(pathOrStream, options) returns an ExcelWorkbookDataReader derived from DbDataReader. The shared OfficeIMO.Data mappings also work on loaded documents:

using OfficeIMO.Data;
using OfficeIMO.Excel;

using ExcelWorkbookDataReader reader = ExcelDocument.OpenReader("Orders.xlsx",
    new ExcelReaderOptions { SheetName = "Orders" });
List<Order> streamed = reader.RowsAs<Order>().ToList();

using var book = ExcelDocument.Load("Orders.xlsx");
List<Order> loaded = book.RowsAs<Order>(
    options: new ExcelReaderOptions { SheetName = "Orders" }).ToList();

Loaded-document RowsAs overloads support automatic, configured RowMapper<T> and factory mapping, with ExcelReaderOptions and cancellation. Their RowsAsParallel counterparts take parallelOptions, format options, then cancellationToken and preserve source order. OpenReaderAsync returns Task<ExcelWorkbookDataReader> on .NET 8 and later.

XML Spreadsheet import also limits defined names (10,000 by default). Set ExcelSpreadsheetXmlOptions.MaxNames for a larger trusted workbook.

Large exports

The object model keeps the whole workbook editable until Save(). For hundreds of thousands of rows, the XLSX and XLSB streaming writers write each row as it arrives with bounded row memory:

using OfficeIMO;
using OfficeIMO.Excel;

IEnumerable<LogEvent> events = Enumerable.Range(1, 200_000)
    .Select(i => new LogEvent(DateTime.UtcNow.AddSeconds(-i), i % 7 == 0 ? "Warning" : "Info", $"Event {i}"));

using (ExcelWorkbookWriter writer = ExcelDocument.CreateWriter("Events.xlsx", theme: OfficeTheme.Modern)) {
    writer.WriteTable("Events", events);
}

record LogEvent(DateTime Time, string Level, string Message);

WriteTable also takes an IAsyncEnumerable<T>, a DataTable or an IDataReader. The file is published when the writer is disposed.

The same writer supports binary formats with an explicit format argument. A typed callback writes scalar values directly to native records:

using (var writer = ExcelDocument.CreateWriter(ExcelFileFormat.Xlsb, "Events.xlsb")) {
    writer.WriteTable("Events", events, new[] { "Time", "Level", "Message" },
        static (row, item) => row.Write(item.Time).Write(item.Level).Write(item.Message));
}

Use ExcelFileFormat.Xls for BIFF8 output, within its limit of 65,536 rows (including headers) and 256 columns. XLS stages native records and its required shared-string table; RequireStreaming=true rejects that format. Binary row writers create plain worksheets and reject tables, AutoFit, freeze panes and declared styles. Existing CreateWriter(path) and CreateWriter(stream) calls select XLSX. WriteData retains its selector and buffering behavior.

XLS and XLSB numeric cells use IEEE-754 double precision, including when a callback supplies a decimal, long or ulong. Large integers and high-precision decimals may lose digits. Write identifiers or exact decimal text as strings when every digit matters.

Report sheets

sheet.Report() lays out titled sections, KPI rows, paragraphs and tables on a sheet, for workbooks that people read rather than filter:

using OfficeIMO;
using OfficeIMO.Excel;

using var book = ExcelDocument.Create("Summary.xlsx");
book.AddSheet("Summary").Report()
    .Title("Service review", "October")
    .KpiRow([("Availability", "99.95%"), ("Incidents", 3), ("Changes", 41)])
    .Section("Highlights")
    .BulletedList(["No priority 1 incidents", "Patch compliance at 98%"]);
book.Save();

Save as PDF

using OfficeIMO;
using OfficeIMO.Excel;
using OfficeIMO.Excel.Pdf;

using var book = ExcelDocument.Load("Orders.xlsx");
OfficeConversionReport report = book.SaveAsPdf("Orders.pdf");
Console.WriteLine($"{report.ItemsWritten} pages, loss: {report.HasLoss}");

More

• Excel guide: styles, validation, conditional formats, pivot tables, slicers, sparklines, templates, formulas and calculation, protection, links, images, printing, legacy .xls and image export.
• Formula calculation: typed errors and lookup modes, reference-valued INDEX and XLOOKUP, and named scalar and array expressions.
• Compatibility matrix and the generated operation contract: exactly what is supported, preserved or rejected.
• Large-workbook guidance, remote loading and legacy XLS compatibility.
• Examples and the migration guide.
• Adapters: OfficeIMO.Excel.Pdf, Html, Csv, OpenDocument, GoogleSheets and IWork. PDF tables back to Excel live in OfficeIMO.Pdf.Excel.
• PowerShell: PSWriteOffice (Export-OfficeExcel, New-OfficeExcel).

Dependencies: the Open XML SDK and OfficeIMO.Core. MIT licensed.

Generated capability summary

This table is generated from the package-neutral OfficeIMO operation catalog. The detailed source contracts remain authoritative for feature-level behavior and limitations.

The complete rows for OfficeIMO.Excel are published in the generated operation contract.