Class ExcelPackage

Namespace

SheetStream

Assembly

SheetStream.dll

The .xlsx container. Owns the zip archive, streams each worksheet into it as the sheet is written, and on Save() emits the trailing parts (shared strings, styles, workbook, relationships and content types) that can only be known once every sheet is complete.

public sealed class ExcelPackage : IDisposable

Inheritance

object

ExcelPackage

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

using var package = ExcelPackage.Create("report.xlsx");
var sheet = package.Workbook.Worksheets.Add("Data");
sheet.Row().WriteCell("Hello").WriteCell(42);
package.Save();

Remarks

The package writes straight to the destination stream and never holds a sheet in memory. The price of that design is forward-only access: a ZipArchive in create mode can hold a single entry open at a time, so adding a worksheet seals the previous one, and rows must be written in ascending order. Column widths and frozen panes must be declared before the first row because the schema places them ahead of the sheet data.

Disposing the package without calling Save() saves it, so a plain using block always produces a complete file. Not thread-safe.

Constructors

ExcelPackage(Stream, bool, PackageOptions?)

Creates a package that writes to output.

public ExcelPackage(Stream output, bool leaveOpen = false, PackageOptions? options = null)

Parameters

output Stream

Destination stream. It only needs to support forward writes.

leaveOpen bool

true to leave output open after the package is saved, for example when writing into a MemoryStream you still need to read.

options PackageOptions

Optional tuning settings.

Properties

IsSaved

True once Save() has completed.

public bool IsSaved { get; }

Property Value

bool

Options

The options this package was created with.

public PackageOptions Options { get; }

Property Value

PackageOptions

Workbook

The single workbook of this package.

public Workbook Workbook { get; }

Property Value

Workbook

Methods

Create(string, PackageOptions?)

Creates a package that writes to a file, replacing any existing file at path.

public static ExcelPackage Create(string path, PackageOptions? options = null)

Parameters

path string

options PackageOptions

Returns

ExcelPackage

CreateBytes(Action<Workbook>, PackageOptions?)

Builds a complete workbook in memory and returns its bytes. Convenient for web endpoints that return a download, mirroring EPPlus' GetAsByteArray().

public static byte[] CreateBytes(Action<Workbook> build, PackageOptions? options = null)

Parameters

build Action<Workbook>

options PackageOptions

Returns

byte[]

CreateBytesAsync(Func<Workbook, Task>, PackageOptions?)

Like CreateBytes(Action<Workbook>, PackageOptions?), but the builder can await between sheets (a query per sheet, say). The workbook itself is still written synchronously into memory, so there is no I/O to await after the builder returns; this exists so callers need not run every query first and build afterwards.

public static Task<byte[]> CreateBytesAsync(Func<Workbook, Task> build, PackageOptions? options = null)

Parameters

build Func<Workbook, Task>

options PackageOptions

Returns

Task<byte[]>

Examples

var bytes = await ExcelPackage.CreateBytesAsync(async wb =>
{
    wb.Worksheets.Add("Orders").LoadFromCollection(await db.Orders.ToListAsync(ct));
    wb.Worksheets.Add("Customers").LoadFromCollection(await db.Customers.ToListAsync(ct));
});

Dispose()

Saves the package if it has not been saved yet, then releases the output stream unless it was left open.

public void Dispose()

Edit(Stream, Stream, bool, PackageOptions?)

Opens a workbook from a stream for editing and writes the edited copy to output. See Edit(string, string, PackageOptions?).

public static ExcelPackage Edit(Stream input, Stream output, bool leaveOpen = false, PackageOptions? options = null)

Parameters

input Stream

output Stream

leaveOpen bool

options PackageOptions

Returns

ExcelPackage

Edit(string, PackageOptions?)

Opens an existing workbook for editing in place. The edited copy is written to a temporary file next to path and replaces the original only when Save() (or the disposing using block) completes; if saving throws, the original is left untouched and the temporary file is removed. The whole workbook is re-written, see Edit(string, string, PackageOptions?).

public static ExcelPackage Edit(string path, PackageOptions? options = null)

Parameters

path string

options PackageOptions

Returns

ExcelPackage

Examples

using var package = ExcelPackage.Edit("budget.xlsx");
package.Workbook.Worksheets.Edit("Summary").Cells["B4"].Value = 1250;
package.Save();

Edit(string, string, PackageOptions?)

Opens an existing workbook for editing and writes the edited copy to outputPath. Open a sheet with Workbook.Worksheets.Edit(name), read and change cells through Cells, then Save(). The whole workbook is re-written: edited sheets from their cells, every other part (other sheets, charts, pictures, styles, names) copied as it was. Meant for small workbooks; see MaxEditableCells. When both paths name the same file the workbook is edited in place, see Edit(string, PackageOptions?).

public static ExcelPackage Edit(string inputPath, string outputPath, PackageOptions? options = null)

Parameters

inputPath string

outputPath string

options PackageOptions

Returns

ExcelPackage

Examples

using var package = ExcelPackage.Edit("budget.xlsx", "budget-2027.xlsx");
var sheet = package.Workbook.Worksheets.Edit("Summary");
var current = sheet.Cells["B4"].Value;
sheet.Cells["B4"].Value = 1250;
sheet.Cells[sheet.Cells.Dimension.LastRow + 1, 1].Value = "Added by code";
package.Save();

OpenTemplate(Stream, Stream, bool, PackageOptions?)

Opens a template from a stream and writes the filled copy to output.

public static ExcelPackage OpenTemplate(Stream template, Stream output, bool leaveOpen = false, PackageOptions? options = null)

Parameters

template Stream

output Stream

leaveOpen bool

options PackageOptions

Returns

ExcelPackage

OpenTemplate(string, string, PackageOptions?)

Opens a template workbook (designed in Excel: logo, styled headers, formulas, charts) and writes a filled copy to outputPath. Open sheets with Workbook.Worksheets.Open(name) and stream rows into them; everything you do not touch is copied unchanged.

public static ExcelPackage OpenTemplate(string templatePath, string outputPath, PackageOptions? options = null)

Parameters

templatePath string

outputPath string

options PackageOptions

Returns

ExcelPackage

Examples

using var package = ExcelPackage.OpenTemplate("invoice-template.xlsx", "invoice-42.xlsx");
var sheet = package.Workbook.Worksheets.Open("Lines");
var money = sheet.TemplateStyle("D5");
var row = 5;
foreach (var line in lines) sheet.Row(row++).WriteCell(line.Sku).WriteCell(line.Qty).Skip(1).WriteCell(line.Total, money);
package.Save();

Save()

Seals the current worksheet, writes the shared strings, styles, workbook, relationship and content-type parts, and closes the zip archive. Safe to call more than once; later calls do nothing. After saving, no further worksheets or rows can be written.

public void Save()