FastExcelWriterStream 2.0.1

FastExcelWriterStream

Lightweight, extremely fast and memory efficient Excel (.xlsx) writer for .NET 8.
Streams data directly to file — no XML serialization, no memory footprint.

✨ Features

• 🚀 Extremely fast — streams data directly to file
• 💾 Minimal RAM — no data accumulation in memory
• 📄 Multiple sheets — up to 10 sheets per file
• 🔀 Auto sheet split — automatically creates new sheets after 1M rows
• 🎨 Cell styles — bold, italic, colors, borders, alignment
• 🔢 Number formats — thousands separator, decimals, percent
• 📐 Auto column width — sample-based width detection
• 🔒 Freeze panes — freeze rows and columns
• ↔️ RTL support — right-to-left sheets
• 🔽 AutoFilter — column filters
• ↔️ Merge cells — merge cell ranges
• 📝 Formulas — custom and built-in (SUM, AVERAGE, etc.)

📊 Performance

📦 Installation

dotnet add package FastExcelWriterStream

🚀 Quick Start

using FastExcelWriterStream;

using var ew = new ExcelWriter("output.xlsx");

ew.Write("Name",  1, 1);
ew.Write("Amount", 2, 1);

ew.Write("Alice", 1, 2);
ew.WriteNumber(22954062, 2, 2);

📖 Usage

Basic Writing

using var ew = new ExcelWriter("output.xlsx", new SheetConfig
{
    Name        = "Report",
    FreezeRows  = 1,        // freeze header row
    RightToLeft = true      // RTL sheet
});

// Write text
ew.Write("Hello", col: 1, row: 1);

// Write number
ew.WriteNumber(1234567.89, col: 2, row: 1);

// Write formula
ew.WriteFormula("A1+B1", col: 3, row: 1);
ew.WriteFormula(FormulaType.Sum, col: 4, row: 1,
                dataCol: 2, dataRowStart: 1, dataRowEnd: 100);

Styles

using var ew = new ExcelWriter("output.xlsx");

// Register styles BEFORE any Write call
int headerStyle = ew.AddStyle(new StyleConfig
{
    Bold         = true,
    FillColor    = "1F4E79",   // dark blue background
    FontColor    = "FFFFFF",   // white text
    HAlign       = HAlign.Center,
    BorderBottom = true
});

int amountStyle = ew.AddStyle(new StyleConfig
{
    NumberFormat = NumberFormat.Thousands,   // 1,234,567
    HAlign       = HAlign.Right
});

int dollarStyle = ew.AddStyle(new StyleConfig
{
    NumberFormat  = NumberFormat.Thousands,
    DecimalPlaces = 2                        // 1,234,567.00
});

// Apply styles using named parameter
ew.Write("Revenue",    1, 1, styleIndex: headerStyle);
ew.WriteNumber(22954062,  1, 2, styleIndex: amountStyle);
ew.WriteNumber(1234.56,   1, 3, styleIndex: dollarStyle);

Multiple Sheets

using var ew = new ExcelWriter("report.xlsx", new SheetConfig { Name = "Summary" });

ew.Write("Summary data", 1, 1);

// Add second sheet
int sheet2 = ew.AddSheet(new SheetConfig { Name = "Details" });
ew.Write("Detail data", 1, 1, sheet2);

Auto Sheet Split (3M+ rows)

using var ew = new ExcelWriter("big_report.xlsx");

string[] headers = { "ID", "Name", "Amount", "Date" };

ew.EnableAutoSheetSplit(
    sheetNamePrefix: "Data",         // → "Data 1", "Data 2", "Data 3"
    headerRow:       headers,        // auto-repeat on each new sheet
    freezeRows:      1,
    rightToLeft:     true
);

// Write header on first sheet manually
for (int col = 1; col <= headers.Length; col++)
    ew.Write(headers[col - 1], col, 1);

// Write 3 million rows — sheet splitting is automatic
for (int row = 2; row <= 3_000_001; row++)
{
    ew.WriteNumber(row - 1,       1, row);
    ew.Write($"Name {row}",       2, row);
    ew.WriteNumber(row * 1000.0,  3, row);
    ew.Write("2026/01/01",        4, row);
}

Auto Column Width

using var ew = new ExcelWriter("output.xlsx");

// Must be called BEFORE any Write
ew.EnableAutoWidth(maxSampleRows: 1000);  // sample first 1000 rows

ew.Write("Transaction Description", 1, 1);
// ... rest of writes

Write to Stream (Azure Blob, etc.)

using var stream = await blobClient.OpenWriteAsync(overwrite: true);
using var ew = new ExcelWriter(stream, leaveOpen: false);

ew.Write("Hello", 1, 1);

SheetConfig Options

new SheetConfig
{
    Name         = "Sheet1",
    FreezeRows   = 1,                          // freeze top N rows
    FreezeCols   = 0,                          // freeze left N columns
    RightToLeft  = false,                      // RTL direction
    ColumnsWidth = new List<double>            // manual column widths
    {
        10, 25, 15, 12
    },
    MergeRanges  = new List<MergeRange>        // merge cells
    {
        new MergeRange(colStart: 1, rowStart: 1, colEnd: 4, rowEnd: 1)
    },
    FilterRange  = new FilterRange(            // AutoFilter
        colStart: 1, rowStart: 1,
        colEnd:   13, rowEnd:  1
    )
}

ExcelWriterOptions

new ExcelWriterOptions
{
    // StreamingZip: low RAM, streaming (default — recommended for large files)
    // SharpCompressZip: faster, higher RAM
    ZipMode = ZipMode.StreamingZip,

    // Optimal (default) / Fastest / NoCompression
    CompressionLevel = CompressionLevel.Fastest
}

📋 API Reference

ExcelWriter

StyleConfig Properties

Enumerations

enum DataType    { Text, Number, Formula }
enum FormulaType { Average, Count, Max, Min, Sum }
enum HAlign      { General, Left, Center, Right, Fill, Justify }
enum VAlign      { Top, Center, Bottom, Justify, Distributed }
enum NumberFormat { None, Thousands, ThousandsDecimal, Percent, Custom }
enum ZipMode     { StreamingZip, SharpCompressZip }

⚠️ Important Notes

1. Ascending row order — rows must be written from low to high
2. AddStyle before Write — register all styles before any Write call
3. Named parameter — always use styleIndex: myStyle, not positional
4. EnableAutoWidth before Write — must be called before any Write
5. using statement — always use using to ensure file is properly closed
6. StreamingZip + AddSheet — previous sheet must be fully written before adding new sheet

📄 License

MIT License — see LICENSE for details.