How to Read Very Large Excel Files in C# with Forward-Only Streaming

using IronXL;
using System;

// The string path overload reads the workbook's parts lazily from disk.
// Nothing is loaded up front, and only one row exists in memory at a time.
foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx"))
{
    // Cells holds only the columns that actually have content on this row.
    foreach (StreamCell cell in row.Cells)
    {
        Console.WriteLine("{0}{1} = {2}", cell.ColumnLetter, row.RowNumber + 1, cell.Text);
    }
}

using IronXL;
using System;

// The string path overload reads the workbook's parts lazily from disk.
// Nothing is loaded up front, and only one row exists in memory at a time.
foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx"))
{
    // Cells holds only the columns that actually have content on this row.
    foreach (StreamCell cell in row.Cells)
    {
        Console.WriteLine("{0}{1} = {2}", cell.ColumnLetter, row.RowNumber + 1, cell.Text);
    }
}

A1 = TxnId
B1 = Date
C1 = Sku
D1 = Description
E1 = Qty
F1 = UnitPrice
G1 = Region
H1 = Status
A2 = 1
B2 = 2026-01-01
C2 = SKU-079109
D2 = Item 0
E2 = 24
F2 = 8.62
G2 = North
H2 = OK
A3 = 2
B3 = 2026-02-02
C3 = SKU-011965
D3 = Item 1
E3 = 43
F3 = 460.94
G3 = South
H3 = PENDING

A1 = TxnId
B1 = Date
C1 = Sku
D1 = Description
E1 = Qty
F1 = UnitPrice
G1 = Region
H1 = Status
A2 = 1
B2 = 2026-01-01
C2 = SKU-079109
D2 = Item 0
E2 = 24
F2 = 8.62
G2 = North
H2 = OK
A3 = 2
B3 = 2026-02-02
C3 = SKU-011965
D3 = Item 1
E3 = 43
F3 = 460.94
G3 = South
H3 = PENDING

using IronXL;
using System;

// 1. By zero-based index. Omitting the argument streams the first sheet.
foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", 2))
{
    Console.WriteLine(row[0]?.Text);
}

// 2. By sheet name. Matching is case-insensitive, so "transactions" also works.
foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", "Transactions"))
{
    Console.WriteLine(row[0]?.Text);
}

// 3. By StreamReadOptions, which is the only route to header support.
// SheetName takes precedence over SheetIndex whenever it is set.
StreamReadOptions options = new StreamReadOptions
{
    SheetName = "Transactions",
    HasHeaderRow = true
};

foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", options))
{
    Console.WriteLine(row["Reference"]?.Text);
}

// An unknown sheet name or an out-of-range index throws ArgumentException.
try
{
    foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", "NoSuchSheet"))
    {
        Console.WriteLine(row.RowNumber);
    }
}
catch (ArgumentException ex)
{
    Console.WriteLine("Sheet selection failed: {0}", ex.Message);
}

using IronXL;
using System;

// 1. By zero-based index. Omitting the argument streams the first sheet.
foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", 2))
{
    Console.WriteLine(row[0]?.Text);
}

// 2. By sheet name. Matching is case-insensitive, so "transactions" also works.
foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", "Transactions"))
{
    Console.WriteLine(row[0]?.Text);
}

// 3. By StreamReadOptions, which is the only route to header support.
// SheetName takes precedence over SheetIndex whenever it is set.
StreamReadOptions options = new StreamReadOptions
{
    SheetName = "Transactions",
    HasHeaderRow = true
};

foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", options))
{
    Console.WriteLine(row["Reference"]?.Text);
}

// An unknown sheet name or an out-of-range index throws ArgumentException.
try
{
    foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", "NoSuchSheet"))
    {
        Console.WriteLine(row.RowNumber);
    }
}
catch (ArgumentException ex)
{
    Console.WriteLine("Sheet selection failed: {0}", ex.Message);
}

using IronXL;
using System;
using System.Collections.Generic;

// GetSheetNames reads only the workbook's part list, not sheet data, so it is cheap
// even on a very large file. List position equals the sheet index StreamRows accepts.
IReadOnlyList<string> sheetNames = WorkBook.GetSheetNames("large-export.xlsx");

for (int i = 0; i < sheetNames.Count; i++)
{
    Console.WriteLine("[{0}] {1}", i, sheetNames[i]);
}

// Stream by exact sheet name. Matching is case-insensitive.
// An unknown name, or an out-of-range index, throws ArgumentException.
foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", "Transactions"))
{
    StreamCell reference = row[0];

    if (reference is not null)
    {
        Console.WriteLine(reference.Text);
    }
}

using IronXL;
using System;
using System.Collections.Generic;

// GetSheetNames reads only the workbook's part list, not sheet data, so it is cheap
// even on a very large file. List position equals the sheet index StreamRows accepts.
IReadOnlyList<string> sheetNames = WorkBook.GetSheetNames("large-export.xlsx");

for (int i = 0; i < sheetNames.Count; i++)
{
    Console.WriteLine("[{0}] {1}", i, sheetNames[i]);
}

// Stream by exact sheet name. Matching is case-insensitive.
// An unknown name, or an out-of-range index, throws ArgumentException.
foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", "Transactions"))
{
    StreamCell reference = row[0];

    if (reference is not null)
    {
        Console.WriteLine(reference.Text);
    }
}

using IronXL;
using System;

// This source file carries a title and a blank spacer above the real header,
// so the header sits on Excel row 3, which is HeaderRowIndex 2 (zero-based).
StreamReadOptions options = new StreamReadOptions
{
    SheetName = "Transactions",
    HasHeaderRow = true,
    HeaderRowIndex = 2
};

foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", options))
{
    // The header row is consumed to name columns and is never yielded as data.
    // Rows before HeaderRowIndex are skipped.
    // Named access requires HasHeaderRow; without it the string indexer throws
    // InvalidOperationException.
    StreamCell reference = row["Reference"];
    StreamCell amount = row["Amount"];

    // Both the sparse-row case and a blank cell produce null, so null-check before use.
    if (reference is null || amount is null)
    {
        continue;
    }

    Console.WriteLine("{0}: {1}", reference.Text, amount.Text);
}

using IronXL;
using System;

// This source file carries a title and a blank spacer above the real header,
// so the header sits on Excel row 3, which is HeaderRowIndex 2 (zero-based).
StreamReadOptions options = new StreamReadOptions
{
    SheetName = "Transactions",
    HasHeaderRow = true,
    HeaderRowIndex = 2
};

foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", options))
{
    // The header row is consumed to name columns and is never yielded as data.
    // Rows before HeaderRowIndex are skipped.
    // Named access requires HasHeaderRow; without it the string indexer throws
    // InvalidOperationException.
    StreamCell reference = row["Reference"];
    StreamCell amount = row["Amount"];

    // Both the sparse-row case and a blank cell produce null, so null-check before use.
    if (reference is null || amount is null)
    {
        continue;
    }

    Console.WriteLine("{0}: {1}", reference.Text, amount.Text);
}

using IronXL;
using System;

StreamReadOptions options = new StreamReadOptions
{
    SheetIndex = 0,
    HasHeaderRow = true
};

foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", options))
{
    // The string indexer throws ArgumentException when the column name is absent
    // from the header. TryGetCell returns false instead, which makes it the correct
    // choice for a column that may not exist in every source file.
    if (row.TryGetCell("CostCentre", out StreamCell costCentre) && costCentre is not null)
    {
        Console.WriteLine("Cost centre: {0}", costCentre.Text);
    }
    else
    {
        Console.WriteLine("Cost centre: not supplied");
    }

    // Header is positioned by column, so Header[i] lines up with column i.
    // A blank header column is null.
    for (int i = 0; i < row.Header.Count; i++)
    {
        string columnName = row.Header[i];

        if (string.IsNullOrEmpty(columnName))
        {
            continue;
        }

        StreamCell cell = row[i];
        Console.WriteLine("  {0} ({1}) = {2}", columnName, cell?.ColumnLetter, cell?.Text);
    }
}

using IronXL;
using System;

StreamReadOptions options = new StreamReadOptions
{
    SheetIndex = 0,
    HasHeaderRow = true
};

foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", options))
{
    // The string indexer throws ArgumentException when the column name is absent
    // from the header. TryGetCell returns false instead, which makes it the correct
    // choice for a column that may not exist in every source file.
    if (row.TryGetCell("CostCentre", out StreamCell costCentre) && costCentre is not null)
    {
        Console.WriteLine("Cost centre: {0}", costCentre.Text);
    }
    else
    {
        Console.WriteLine("Cost centre: not supplied");
    }

    // Header is positioned by column, so Header[i] lines up with column i.
    // A blank header column is null.
    for (int i = 0; i < row.Header.Count; i++)
    {
        string columnName = row.Header[i];

        if (string.IsNullOrEmpty(columnName))
        {
            continue;
        }

        StreamCell cell = row[i];
        Console.WriteLine("  {0} ({1}) = {2}", columnName, cell?.ColumnLetter, cell?.Text);
    }
}

using IronXL;
using System;

StreamReadOptions options = new StreamReadOptions
{
    SheetName = "Transactions",
    HasHeaderRow = true
};

foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", options))
{
    // RowNumber is zero-based, so Excel row 1 is RowNumber 0.
    // With a header consumed, the first data row keeps its real sheet position.
    Console.WriteLine("Sheet row {0}, {1} populated cells", row.RowNumber, row.Cells.Count);

    // Index access. Rows are sparse, so a column with no content returns null
    // rather than a blank cell object.
    StreamCell firstColumn = row[0];
    Console.WriteLine("  column A: {0}", firstColumn?.Text ?? "(empty)");

    // Name access. Requires HasHeaderRow, and throws ArgumentException if the
    // header has no such column. Matching is case-insensitive and trims whitespace.
    StreamCell reference = row["Reference"];
    Console.WriteLine("  Reference: {0}", reference?.Text ?? "(empty)");

    // Header is positioned by column: Header[i] names column i.
    // A column with a blank header cell is null.
    for (int i = 0; i < row.Header.Count; i++)
    {
        string name = row.Header[i];
        Console.WriteLine("  column {0} is named {1}", i, name ?? "(unnamed)");
    }
}

using IronXL;
using System;

StreamReadOptions options = new StreamReadOptions
{
    SheetName = "Transactions",
    HasHeaderRow = true
};

foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", options))
{
    // RowNumber is zero-based, so Excel row 1 is RowNumber 0.
    // With a header consumed, the first data row keeps its real sheet position.
    Console.WriteLine("Sheet row {0}, {1} populated cells", row.RowNumber, row.Cells.Count);

    // Index access. Rows are sparse, so a column with no content returns null
    // rather than a blank cell object.
    StreamCell firstColumn = row[0];
    Console.WriteLine("  column A: {0}", firstColumn?.Text ?? "(empty)");

    // Name access. Requires HasHeaderRow, and throws ArgumentException if the
    // header has no such column. Matching is case-insensitive and trims whitespace.
    StreamCell reference = row["Reference"];
    Console.WriteLine("  Reference: {0}", reference?.Text ?? "(empty)");

    // Header is positioned by column: Header[i] names column i.
    // A column with a blank header cell is null.
    for (int i = 0; i < row.Header.Count; i++)
    {
        string name = row.Header[i];
        Console.WriteLine("  column {0} is named {1}", i, name ?? "(unnamed)");
    }
}

using IronXL;
using System;

foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", "Transactions"))
{
    StreamCell cell = row[1];

    // Sparse gap: no cell at this column on this row.
    if (cell is null)
    {
        continue;
    }

    // Position: zero-based index, plus the spreadsheet column letter.
    Console.WriteLine("Column {0} (letter {1})", cell.ColumnIndex, cell.ColumnLetter);

    // Type classifies the value. For a formula cell it reports the type of the
    // cached result, never a "formula" type.
    Console.WriteLine("  Type:      {0}", cell.Type);

    // IsFormula is how formula-ness is exposed. The expression itself is not
    // available from the streaming reader, only the cached result.
    Console.WriteLine("  IsFormula: {0}", cell.IsFormula);

    // Value is the raw typed value, and is null for a blank cell.
    Console.WriteLine("  Value:     {0}", cell.Value ?? "(null)");

    // Text is the formatted display text, which is what Excel shows in the cell.
    Console.WriteLine("  Text:      {0}", cell.Text);
}

using IronXL;
using System;

foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", "Transactions"))
{
    StreamCell cell = row[1];

    // Sparse gap: no cell at this column on this row.
    if (cell is null)
    {
        continue;
    }

    // Position: zero-based index, plus the spreadsheet column letter.
    Console.WriteLine("Column {0} (letter {1})", cell.ColumnIndex, cell.ColumnLetter);

    // Type classifies the value. For a formula cell it reports the type of the
    // cached result, never a "formula" type.
    Console.WriteLine("  Type:      {0}", cell.Type);

    // IsFormula is how formula-ness is exposed. The expression itself is not
    // available from the streaming reader, only the cached result.
    Console.WriteLine("  IsFormula: {0}", cell.IsFormula);

    // Value is the raw typed value, and is null for a blank cell.
    Console.WriteLine("  Value:     {0}", cell.Value ?? "(null)");

    // Text is the formatted display text, which is what Excel shows in the cell.
    Console.WriteLine("  Text:      {0}", cell.Text);
}

using IronXL;
using System;
using System.Globalization;

StreamReadOptions options = new StreamReadOptions
{
    SheetName = "Transactions",
    HasHeaderRow = true
};

foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", options))
{
    StreamCell amount = row["Amount"];

    // Sparse rows and blank cells both yield null. Check before touching Type or Value.
    if (amount is null || amount.Type == StreamCellType.Blank)
    {
        continue;
    }

    // A formula cell reports IsFormula true, and Type reports the real type of the
    // cached result. The formula expression itself is not exposed, and nothing is
    // recalculated, which is why StreamCellType has no Formula member.
    if (amount.IsFormula)
    {
        Console.WriteLine("Row {0} column {1} is a cached formula result.",
            row.RowNumber, amount.ColumnLetter);
    }

    switch (amount.Type)
    {
        case StreamCellType.Number:
            // Convert rather than casting directly: the boxed numeric type is not
            // guaranteed to be the one you expect.
            decimal value = Convert.ToDecimal(amount.Value, CultureInfo.InvariantCulture);
            Console.WriteLine("Amount: {0}", value);
            break;

        case StreamCellType.Date:
            // Date cells honour the workbook's date system, including 1904-based
            // workbooks produced by Excel for Mac.
            if (amount.Value is DateTime date)
            {
                Console.WriteLine("Date: {0:yyyy-MM-dd}", date);
            }
            break;

        case StreamCellType.Boolean:
            Console.WriteLine("Flag: {0}", Convert.ToBoolean(amount.Value));
            break;

        case StreamCellType.Error:
            Console.WriteLine("Row {0} contains an error value.", row.RowNumber);
            break;

        default:
            // Falls through to the formatted display text for String and anything else.
            Console.WriteLine("Text: {0}", amount.Text);
            break;
    }
}

using IronXL;
using System;
using System.Globalization;

StreamReadOptions options = new StreamReadOptions
{
    SheetName = "Transactions",
    HasHeaderRow = true
};

foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", options))
{
    StreamCell amount = row["Amount"];

    // Sparse rows and blank cells both yield null. Check before touching Type or Value.
    if (amount is null || amount.Type == StreamCellType.Blank)
    {
        continue;
    }

    // A formula cell reports IsFormula true, and Type reports the real type of the
    // cached result. The formula expression itself is not exposed, and nothing is
    // recalculated, which is why StreamCellType has no Formula member.
    if (amount.IsFormula)
    {
        Console.WriteLine("Row {0} column {1} is a cached formula result.",
            row.RowNumber, amount.ColumnLetter);
    }

    switch (amount.Type)
    {
        case StreamCellType.Number:
            // Convert rather than casting directly: the boxed numeric type is not
            // guaranteed to be the one you expect.
            decimal value = Convert.ToDecimal(amount.Value, CultureInfo.InvariantCulture);
            Console.WriteLine("Amount: {0}", value);
            break;

        case StreamCellType.Date:
            // Date cells honour the workbook's date system, including 1904-based
            // workbooks produced by Excel for Mac.
            if (amount.Value is DateTime date)
            {
                Console.WriteLine("Date: {0:yyyy-MM-dd}", date);
            }
            break;

        case StreamCellType.Boolean:
            Console.WriteLine("Flag: {0}", Convert.ToBoolean(amount.Value));
            break;

        case StreamCellType.Error:
            Console.WriteLine("Row {0} contains an error value.", row.RowNumber);
            break;

        default:
            // Falls through to the formatted display text for String and anything else.
            Console.WriteLine("Text: {0}", amount.Text);
            break;
    }
}

using IronXL;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Threading.Tasks;

public class TransactionImporter
{
    private const int BatchSize = 5000;

    public async Task<int> ImportAsync(string path, ITransactionSink sink)
    {
        StreamReadOptions options = new StreamReadOptions
        {
            SheetName = "Transactions",
            HasHeaderRow = true,
            HeaderRowIndex = 0
        };

        List<TransactionRecord> batch = new List<TransactionRecord>(BatchSize);
        int imported = 0;

        // Enumeration is lazy: only one row is materialised at a time, so peak memory
        // stays flat regardless of how many rows the sheet holds.
        foreach (StreamRow row in WorkBook.StreamRows(path, options))
        {
            TransactionRecord record = MapRow(row);

            if (record is null)
            {
                continue;
            }

            batch.Add(record);

            if (batch.Count == BatchSize)
            {
                await sink.WriteAsync(batch);
                imported += batch.Count;
                batch.Clear();
            }
        }

        if (batch.Count > 0)
        {
            await sink.WriteAsync(batch);
            imported += batch.Count;
        }

        return imported;
    }

    private static TransactionRecord MapRow(StreamRow row)
    {
        StreamCell reference = row["Reference"];
        StreamCell amount = row["Amount"];
        StreamCell posted = row["PostedOn"];

        // Required columns missing on this row: skip rather than throw, so one bad
        // row does not abort an import of several hundred thousand.
        if (reference is null || amount is null)
        {
            return null;
        }

        if (amount.Type != StreamCellType.Number)
        {
            return null;
        }

        DateTime? postedOn = posted?.Value as DateTime?;

        // Optional column that only some source files carry.
        string costCentre = row.TryGetCell("CostCentre", out StreamCell centre)
            ? centre?.Text
            : null;

        return new TransactionRecord
        {
            SourceRow = row.RowNumber,
            Reference = reference.Text,
            Amount = Convert.ToDecimal(amount.Value, CultureInfo.InvariantCulture),
            PostedOn = postedOn,
            CostCentre = costCentre
        };
    }
}

public class TransactionRecord
{
    public int SourceRow { get; set; }
    public string Reference { get; set; }
    public decimal Amount { get; set; }
    public DateTime? PostedOn { get; set; }
    public string CostCentre { get; set; }
}

public interface ITransactionSink
{
    Task WriteAsync(IReadOnlyList<TransactionRecord> batch);
}

using IronXL;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Threading.Tasks;

public class TransactionImporter
{
    private const int BatchSize = 5000;

    public async Task<int> ImportAsync(string path, ITransactionSink sink)
    {
        StreamReadOptions options = new StreamReadOptions
        {
            SheetName = "Transactions",
            HasHeaderRow = true,
            HeaderRowIndex = 0
        };

        List<TransactionRecord> batch = new List<TransactionRecord>(BatchSize);
        int imported = 0;

        // Enumeration is lazy: only one row is materialised at a time, so peak memory
        // stays flat regardless of how many rows the sheet holds.
        foreach (StreamRow row in WorkBook.StreamRows(path, options))
        {
            TransactionRecord record = MapRow(row);

            if (record is null)
            {
                continue;
            }

            batch.Add(record);

            if (batch.Count == BatchSize)
            {
                await sink.WriteAsync(batch);
                imported += batch.Count;
                batch.Clear();
            }
        }

        if (batch.Count > 0)
        {
            await sink.WriteAsync(batch);
            imported += batch.Count;
        }

        return imported;
    }

    private static TransactionRecord MapRow(StreamRow row)
    {
        StreamCell reference = row["Reference"];
        StreamCell amount = row["Amount"];
        StreamCell posted = row["PostedOn"];

        // Required columns missing on this row: skip rather than throw, so one bad
        // row does not abort an import of several hundred thousand.
        if (reference is null || amount is null)
        {
            return null;
        }

        if (amount.Type != StreamCellType.Number)
        {
            return null;
        }

        DateTime? postedOn = posted?.Value as DateTime?;

        // Optional column that only some source files carry.
        string costCentre = row.TryGetCell("CostCentre", out StreamCell centre)
            ? centre?.Text
            : null;

        return new TransactionRecord
        {
            SourceRow = row.RowNumber,
            Reference = reference.Text,
            Amount = Convert.ToDecimal(amount.Value, CultureInfo.InvariantCulture),
            PostedOn = postedOn,
            CostCentre = costCentre
        };
    }
}

public class TransactionRecord
{
    public int SourceRow { get; set; }
    public string Reference { get; set; }
    public decimal Amount { get; set; }
    public DateTime? PostedOn { get; set; }
    public string CostCentre { get; set; }
}

public interface ITransactionSink
{
    Task WriteAsync(IReadOnlyList<TransactionRecord> batch);
}

using IronXL;
using System;
using System.Collections.Generic;

// GetSheetNames returns every sheet in workbook order, including chartsheets.
// List position equals the index that StreamRows accepts.
IReadOnlyList<string> sheetNames = WorkBook.GetSheetNames("large-export.xlsx");

for (int i = 0; i < sheetNames.Count; i++)
{
    int rowCount = 0;

    foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", i))
    {
        rowCount++;
    }

    // A chartsheet holds no rows, so it streams as an empty sequence rather than
    // raising an error. Zero rows here is expected, not a failure to investigate.
    if (rowCount == 0)
    {
        Console.WriteLine("[{0}] {1}: no rows (chartsheet or empty worksheet)", i, sheetNames[i]);
    }
    else
    {
        Console.WriteLine("[{0}] {1}: {2} rows", i, sheetNames[i], rowCount);
    }
}

using IronXL;
using System;
using System.Collections.Generic;

// GetSheetNames returns every sheet in workbook order, including chartsheets.
// List position equals the index that StreamRows accepts.
IReadOnlyList<string> sheetNames = WorkBook.GetSheetNames("large-export.xlsx");

for (int i = 0; i < sheetNames.Count; i++)
{
    int rowCount = 0;

    foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx", i))
    {
        rowCount++;
    }

    // A chartsheet holds no rows, so it streams as an empty sequence rather than
    // raising an error. Zero rows here is expected, not a failure to investigate.
    if (rowCount == 0)
    {
        Console.WriteLine("[{0}] {1}: no rows (chartsheet or empty worksheet)", i, sheetNames[i]);
    }
    else
    {
        Console.WriteLine("[{0}] {1}: {2} rows", i, sheetNames[i], rowCount);
    }
}