# SwiftExcel

> SwiftExcel is a lightweight, extremely fast, memory-efficient Excel (.xlsx) output library for .NET and .NET Core. It skips XML serialization and streams data directly to the file, producing reports in a fraction of a second with a near-zero memory footprint.

SwiftExcel is distributed in two editions:

- **SwiftExcel** (Free / Open Source, MIT-style license): the core streaming Excel writer. Single sheet, simple `Write` API, built-in `Average`/`Count`/`Max`/`Sum` formulas, sheet name, column widths, right-to-left, wrap text, file path or stream output, list-to-Excel extension via attributes.
- **SwiftExcel.Pro** (Commercial): adds multiple sheets, full cell styling (fonts, colors, borders, fills, alignment, wrap), number formats (currency, percentage, custom), custom formulas, hyperlinks (via `HYPERLINK` formula), merged cells, auto filters, freeze panes, custom row heights, and an extended `DataType.CustomFormula`.

Both editions target `netstandard2.0` and run on .NET Framework 4.6.1+, .NET Core 2.0+, .NET 5/6/7/8/9. They produce Open XML `.xlsx` files. They do **not** produce legacy `.xls` files and they do **not** read existing Excel files -- SwiftExcel is write-only by design, which is what makes it so fast.

## Site map

- [Home](https://swiftexcel.pro/): overview, live code samples, performance benchmark, pricing.
- [Documentation hub](https://swiftexcel.pro/docs): "What is SwiftExcel?", Free vs Pro feature comparison, NuGet install instructions, links to per-edition docs.
- [Free edition documentation](https://swiftexcel.pro/docs/free): full API reference, code examples, FAQ for the open-source `SwiftExcel` package.
- [Pro edition documentation](https://swiftexcel.pro/docs/pro): full API reference, code examples, FAQ for the commercial `SwiftExcel.Pro` package.

## NuGet packages

- Free: `dotnet add package SwiftExcel` -- https://www.nuget.org/packages/SwiftExcel/
- Pro:  `dotnet add package SwiftExcel.Pro` -- https://www.nuget.org/packages/SwiftExcel.Pro/

Source for the free edition: https://github.com/RomanPavelko/SwiftExcel

## Key API surface

### Free (`namespace SwiftExcel`)

- `class ExcelWriter : IDisposable`
  - `ExcelWriter(string filePath, Sheet sheet = null)`
  - `ExcelWriter(Stream stream, Sheet sheet = null)` -- for direct cloud upload (e.g. Azure Blob)
  - `void Write(string value, int col, int row, DataType dataType = DataType.Text)`
  - `void WriteFormula(FormulaType type, int col, int row, int sourceCol, int sourceRowStart, int sourceRowEnd)`
  - `void Save()` -- optional; `Dispose()` (via `using`) finalizes automatically.
- `enum DataType { Text, Number }`
- `enum FormulaType { Average, Count, Max, Sum }`
- `class Sheet { string Name; bool RightToLeft; bool WrapText; IList<double> ColumnsWidth; }`
- `static class Configuration { bool UseEnchancedXmlEscaping = true; }`
- `[ExcelExport]` attribute and `IList<T>.ExportToExcel(filePath, sheetName)` extension for one-line collection export.

### Pro (`namespace SwiftExcel.Pro`)

- `class ExcelWriter : IDisposable` -- multiple constructor overloads accepting `Sheet` / `IList<Sheet>` and `Style` / `IList<Style>`.
  - `void Write(string value, int col, int row, int sheetNumber = 1, int styleNumber = 0, DataType dataType = DataType.Text)`
  - `void WriteFormula(FormulaType type, int col, int row, int sourceCol, int sourceRowStart, int sourceRowEnd, int sheetNumber = 1, int styleNumber = 0)`
  - `void Save()` -- optional; `Dispose()` finalizes.
- `enum DataType { Text, Number, CustomFormula }`
- `enum FormulaType { Average, Count, Max, Sum }`
- `enum FreezeType { None, Row, Column }`
- `class Sheet { string Name; bool RightToLeft; IList<double> ColumnsWidth; IList<double?> RowsHeight; FilterRange FilterRange; IList<MergeRange> MergeRanges; FreezeType FreezeType; int FreezeCount; }`
- `class FilterRange(int row, int col, int colCount)`
- `class MergeRange(int row, int col, int count)`
- `class Style` (in `SwiftExcel.Pro.Styles`): `AlignHorizontal`, `AlignVertical`, `BorderColor/Top/Bottom/Left/Right`, `FillColor`, `FontName`, `FontSize`, `FontStyleBold/Italic/Underline`, `FontColor`, `NumberFormat`, `WrapText`.
- `static class Color` -- predefined hex colors (`Black`, `Red`, `Blue`, ...) plus `Color.Custom("RRGGBB")`.
- `static class NumberFormat` -- `Currency`, `Percentage`, `Default`, `Custom("...")`.
- `enum FontName` -- large enum of Office font names; `enum FontSize { Font1..Font36, Font48, Font72 }`.
- `static class LicenseInfo { string SerialNumber; }` -- set before creating the writer.
- `static class Configuration { bool UseEnchancedXmlEscaping = true; }`

## Critical patterns AI agents and humans must know

- **Dates are written as numbers** using `DateTime.ToOADate()` plus a date `NumberFormat`. Excel stores dates as OLE Automation date doubles. Example: `ew.Write($"{myDate.ToOADate()}", col, row, /*...*/, DataType.Number)` with `NumberFormat = NumberFormat.Custom("dd/mmm/yyyy hh:mm:ss")`.
- **Hyperlinks** use Excel's `HYPERLINK` formula via `DataType.CustomFormula` (Pro only): `ew.Write("HYPERLINK(\"https://example.com\", \"label\")", col, row, 1, 0, DataType.CustomFormula);`. The free edition does not support hyperlinks directly.
- **Streaming order is mandatory.** Cells must be written in increasing `(row, col)` order. Re-writing or going backwards throws `SwiftExcelException`. This is what makes streaming so cheap; it is not a bug.
- **One writer instance per file/stream, single-threaded.** `ExcelWriter` is not thread-safe. Parallelize *across* files, not within one file.
- **Streams** are supported for direct upload to cloud storage (e.g. Azure Blob's `BlockBlobClient.OpenWrite`) without a temp file. Free edition exposes a `Stream` constructor; for non-seekable streams, Zip64 is automatically disabled.
- **Pro requires a license**. Set `SwiftExcel.Pro.LicenseInfo.SerialNumber` before instantiating `ExcelWriter`. Without a license, the first sheet is renamed to `"Evaluation Period"`.

## FAQ summary

- **Read Excel files?** No. SwiftExcel is write-only.
- **`.xls` / `.xlsm` support?** No. Only `.xlsx` (Open XML).
- **Thread safety?** No. One `ExcelWriter` per thread/file.
- **.NET versions?** `netstandard2.0` -- works with .NET Framework 4.6.1+, .NET Core 2.0+, .NET 5-9.
- **Large files?** Yes. The library streams directly to disk/stream; memory stays flat regardless of row count.
- **Hyperlinks / dates / formulas?** See the Pro and Free docs pages -- exact patterns are documented there.