Como Ler Arquivos Excel Muito Grandes em C# com Transmissão Somente para Frente

Ahmad Sohail
Ahmad Sohail
Atualizado: 17 de setembro de 2026

Uma planilha com várias centenas de milhares de linhas quebra a abordagem usual. WorkBook.Load constrói um modelo completo do workbook na memória, que é o que torna possível a edição, formatação, fórmulas e acesso aleatório, além de ser também por isso que uma exportação de 400 MB pode levar minutos e consumir vários gigabytes antes que o primeiro valor seja lido.

O leitor de transmissão somente para frente do IronXL, WorkBook.StreamRows, existe para os trabalhos que apenas precisam dos valores. Ele produz uma linha de cada vez diretamente do disco, em vez de materializar o workbook, o que mantém a memória estável, independentemente de quantas linhas a planilha contenha.

Entender onde a linha se explica ser mais importante do que a própria API, porque lê-la mal é o principal modo como o recurso é mal utilizado. StreamRows é somente leitura, somente XLSX e somente para frente: uma via rápida para extração em massa de valores. Edição, formatação, fórmulas, gráficos, acesso aleatório e formatos não XLSX continuam sendo trabalho de WorkBook.Load.

Por favor, note: Requer IronXL 2026.9.2 ou posterior. Versões anteriores não expõem StreamRows e falharão ao compilar.
Início rápido: Transmitir um grande arquivo XLSX linha por linha

Direcione StreamRows para um caminho de arquivo e enumere o resultado. Nos bastidores, a sobrecarga de caminho de string lê as partes do workbook de forma preguiçosa do disco e apenas uma linha é materializada de cada vez, o que mantém a memória estável em uma planilha arbitrariamente grande.

  1. 1Instale o IronXL com NuGet Package Manager

    PM > Install-Package IronXL.Excel

  2. 2Copie e execute este trecho de código.

    foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx"))
        Console.WriteLine(row[0]?.Text);
  3. 3Implante para testar em seu ambiente de produção.

    Comece a usar o IronXL em seu projeto hoje com uma avaliação gratuita
    arrow pointer


Como Escolho Entre StreamRows e WorkBook.Load?

A divisão é uma questão do que o trabalho precisa, não apenas do tamanho do arquivo. Um arquivo de 50 MB que precisa ter uma célula reformulada pertence a Load. Um arquivo de 500 MB que precisa de três colunas inseridas em um banco de dados pertence a StreamRows.

Escolhendo entre o leitor de streaming e o modelo completo do workbook

ExigênciaStreamRowsWorkBook.Load
Extração em massa de valores, importações, ETL, validaçãoSimSim (mais lento)
Editar ou salvarNãoSim
Formatação, objetos de formataçãoNãoSim
Expressões de fórmula e recalculaçãoNão (apenas resultados em cache)Sim
Acesso aleatório a células arbitráriasNão (somente para frente)Sim
XLS, CSV, TSV, workbooks criptografadosNãoSim
Gráficos e imagensNãoSim

A diferença é ampla o suficiente para mudar como um trabalho é projetado. Transmitir todas as 500.000 linhas de um workbook de 23,4 MB levou cerca de seis segundos e consumiu cerca de 75 MB, com a primeira linha disponível em um quarto de segundo; WorkBook.Load no mesmo arquivo é dramaticamente mais pesado em ambos os aspectos. Hardware e formato do workbook movem esses números, e workbooks com linhas excepcionalmente largas ou tabelas de strings compartilhadas pesadas aterram de forma diferente novamente. O guia de desempenho de carregamento de dados cobre os compromissos equivalentes na escrita.


Como Faço para Transmitir Linhas de um Workbook?

WorkBook.StreamRows é um método estático em WorkBook. Dê a ele uma fonte e uma planilha, e enumere o que retorna.

Entrada

Meio milhão de linhas de dados de transação, oito colunas de largura, 23,4 MB no disco. O Excel abre sem reclamar; o problema começa quando o código tenta puxar tudo para a memória.

Excel showing a Transactions worksheet scrolled to row 250,000 of 500,000, with the frozen header row reading TxnId, Date, Sku, Description, Qty, UnitPrice, Region and Status
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);
    }
}

Saída

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
Text

Uma linha por célula, porque o loop percorre row.Cells em vez de um conjunto fixo de colunas. RowNumber é baseado em zero, então o exemplo adiciona um para alinhar a saída com a própria numeração do Excel. Observe que o cabeçalho chega como uma linha comum aqui: sem StreamReadOptions fornecido, TxnId e Date aparecem como valores de células na linha 1 em vez de nomear as colunas.

O tipo de retorno é IEnumerable<StreamRow>, e a distinção que importa é que nada é lido até que a sequência seja iterada. As linhas são produzidas uma de cada vez à medida que o loop avança, então um foreach sobre uma planilha de 500.000 linhas mantém uma única linha na memória em vez de meio milhão. A consequência é que a sequência é de passagem única e somente para frente: não há como voltar a uma linha anterior nem indexar no meio de uma. Operadores LINQ se compõem normalmente com ele, o que significa que .Take(1000) lê mil linhas e para ali.

Cada StreamRow carrega apenas as células que têm conteúdo, o que é abordado em trabalhando com um StreamRow abaixo.

Qual Sobrecarga Devo Usar?

Nove sobrecargas cobrem três fontes e três formas de nomear a planilha. A fonte é a decisão que importa, porque apenas as sobrecargas de string path leem preguiçosamente do disco. As sobrecargas Stream e byte[] devem manter o conteúdo descompactado do pacote na memória durante a leitura.

As nove sobrecargas StreamRows, todas retornando IEnumerable<StreamRow>

SobrecargaMemória baixa
StreamRows(string path, int sheetIndex = 0)Sim
StreamRows(string path, string sheetName)Sim
StreamRows(string path, StreamReadOptions options)Sim
StreamRows(Stream stream, int sheetIndex = 0)Não
StreamRows(Stream stream, string sheetName)Não
StreamRows(Stream stream, StreamReadOptions options)Não
StreamRows(byte[] data, int sheetIndex = 0)Não
StreamRows(byte[] data, string sheetName)Não
StreamRows(byte[] data, StreamReadOptions options)Não

As sobrecargas Stream e byte[] existem por conveniência quando um arquivo já está na memória, como um upload que foi armazenado em buffer. Elas ainda transmitem linha por linha, então evitam construir o modelo completo do workbook, mas o conteúdo descompactado permanece residente durante toda a leitura. Espere que corra cerca de dez vezes o tamanho do arquivo no disco, então um workbook de 23,4 MB segura um pouco mais de 200 MB em vez do tamanho que o arquivo sugere. Use um caminho de arquivo para os arquivos mais largos.

Todos os três retornam linhas e totais idênticos; o custo é de memória, não de velocidade ou correção

FonteDecursoMemória máxima
string path6,3 s75 MB
Stream6,2 s309 MB
byte[]6,3 s291 MB

O tempo decorrido é efetivamente idêntico nos três, o que vale a pena notar: escolher a sobrecarga errada não torna a leitura mais lenta, torna-a mais pesada. Um trabalho que cabe confortavelmente na memória não perceberá a diferença até que o arquivo cresça ou que o limite do contêiner seja reduzido.

Como Escolho uma Planilha?

A seleção da planilha tem três formas: um índice baseado em zero, um nome de planilha exato correspondido sem diferenciar maiúsculas de minúsculas, ou uma instância de StreamReadOptions. Um nome de planilha desconhecido ou um índice fora do intervalo lança ArgumentException.

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);
}

Não passar nenhum argumento de planilha transmite a primeira planilha, pois sheetIndex tem como padrão 0. StreamReadOptions é a única rota que suporta linhas de cabeçalho, então utilize-a assim que as colunas precisarem de nomes.


Como Descubro Planilhas Antes de Transmitir?

WorkBook.GetSheetNames lista todas as planilhas na ordem do workbook sem carregar o conteúdo do workbook. Ela lê apenas a lista de partes do workbook, então permanece barata mesmo em um arquivo muito grande: cerca de um quarto de segundo no workbook de 23,4 MB e 500.000 linhas, que é o mesmo tempo que leva em um arquivo de alguns kilobytes. Isso faz dela a primeira chamada natural para um arquivo que chega de um sistema externo cujo layout não é conhecido com antecedência.

As três sobrecargas GetSheetNames, todas retornando IReadOnlyList<string>

SobrecargaFonte
GetSheetNames(string path)Um arquivo no disco
GetSheetNames(Stream stream)Um fluxo aberto
GetSheetNames(byte[] data)Um buffer na memória

A posição na lista retornada é igual ao índice da planilha que StreamRows aceita, então as duas APIs se alinham diretamente: o índice 2 nesta lista é a planilha que StreamRows(path, 2) lê.

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);
    }
}

Como Leio Linhas pelo Nome da Coluna?

Configurar HasHeaderRow nomeia as colunas e permite que as linhas sejam lidas pelo nome do cabeçalho. A linha de cabeçalho é consumida para nomeação e não é gerada como dado, e quaisquer linhas antes de HeaderRowIndex são puladas, o que lida com o caso comum de um título ou preâmbulo sentado acima do cabeçalho real.

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);
}
Aviso: O acesso nomeado requer HasHeaderRow. Sem isso, o indexador de strings e TryGetCell ambos lançam InvalidOperationException.

O manuseio do cabeçalho é deliberadamente rigoroso. Se a planilha não tiver linha na ou antes da configurada HeaderRowIndex, a enumeração lança InvalidOperationException com uma mensagem "linha de cabeçalho não encontrada", e ela é lançada assim que uma linha de dados ultrapassa o índice do cabeçalho. Isso garante que um consumidor usando Take ou uma break cedo veja a configuração incorreta imediatamente em vez de ler silenciosamente nada.

A correspondência de nomes de colunas não diferencia maiúsculas de minúsculas e remove espaços em branco ao redor. Nomes de cabeçalho duplicados se resolvem para a primeira, coluna mais à esquerda correspondente.

O Que o StreamReadOptions Configura?

Propriedades StreamReadOptions, definidas através do inicializador de objeto

PropriedadeTipoDefaultComportamento
SheetIndexint0Índice de planilha baseado em zero. Ignorado quando SheetName está definido
SheetNamestringnullNome da planilha, comparado sem diferenciar maiúsculas de minúsculas. Toma precedência sobre SheetIndex
HasHeaderRowboolfalseQuando verdadeiro, a linha em HeaderRowIndex nomeia as colunas e não é gerada como dado
HeaderRowIndexint0Linha de planilha baseada em zero que mantém o cabeçalho. Linhas antes dela são puladas

Como Lido com Colunas Opcionais?

Os dois acessadores nomeados diferem em como tratam uma coluna que não está no cabeçalho, e escolher o errado é o que transforma um arquivo fonte tolerável em um erro. O indexador de string lança ArgumentException; TryGetCell retorna false.

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);
    }
}

TryGetCell responde a uma pergunta mais restrita do que parece à primeira vista: ele relata se o cabeçalho contém o nome da coluna, não se esta linha em particular tem um valor ali. Uma linha com um espaço escasso em uma coluna conhecida retorna true com uma célula null, então uma verificação de nulo ainda é necessária na saída. Use TryGetCell para qualquer coluna que possa estar ausente em alguns arquivos fonte, e o indexador de string apenas onde a coluna é garantida.


Como Trabalho com um StreamRow?

StreamRow é uma linha produzida durante a enumeração. Ele expõe sua posição, as células que realmente contém, e tanto a busca posicional quanto por nome.

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)");
    }
}

Membros StreamRow, com acesso tanto posicional quanto nomeado

MembroTipoComportamento
RowNumberintBaseado em zero. A linha 1 do Excel é RowNumber 0
CellsIReadOnlyList<StreamCell>Escasso. Apenas colunas com conteúdo estão presentes
HeaderIReadOnlyList<string>Nomes de colunas posicionadas por coluna, então Header[i] nomes coluna i. Uma coluna de cabeçalho em branco é null, e Header em si é null quando nenhum cabeçalho foi configurado
this[int columnIndex]StreamCellCélula em um índice de coluna baseado em zero, ou null para um espaço escasso
this[string columnName]StreamCellCélula sob uma coluna de cabeçalho nomeada. Lança ArgumentException quando o nome está ausente
TryGetCell(string, out StreamCell)booltrue quando o cabeçalho contém o nome, false quando não.
Aviso: Header é null, a menos que StreamReadOptions.HasHeaderRow tenha sido definido. Proteja-o antes de iterar, ou o loop fará referência a uma lista nula.

Escassez é a propriedade que molda o código de chamada. Uma linha não é um registro de largura fixa: uma planilha com as colunas de A a F produz linhas que contêm três células onde três colunas foram preenchidas, e o indexador posicional retorna null para as lacunas. RowNumber sendo baseado em zero é consistente com o resto do IronXL, onde indexadores numéricos são baseados em zero enquanto endereços de string no estilo A1 não são.


Como Leio Valores Tipados de um StreamCell?

StreamCell é uma instantâneo imutável de uma célula. Ao contrário de um Cell normal, ele não é respaldado pelo workbook e não pode ser usado para escrever um valor de volta.

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);
}

Membros StreamCell, cobrindo posição, tipo e valor

MembroTipoComportamento
ColumnIndexintÍndice de coluna baseado em zero
ColumnLetterstringLetra da coluna da planilha, por exemplo "A", "C" ou "AA"
TypeStreamCellTypeO tipo de valor mantido. Para uma célula de fórmula, o tipo do resultado em cache
ValueobjectO valor tipado bruto. null para uma célula em branco
TextstringO texto de exibição formatado, como o Excel mostra
IsFormulabooltrue quando a célula contém uma fórmula

Value é combinado, então o que você o converte para segue de Type:

  • Number dá um double
  • String dá um string
  • Boolean dá um bool
  • Date dá um DateTime
  • Blank dá null

Verificar Type antes de tocar em Value é a diferença entre uma importação que sobrevive a dados reais e uma que dá erro na linha 40.000.

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;
    }
}

Dois hábitos importam aqui. O primeiro é verificar nulos em cada acesso de indexador, porque as linhas são escassas e Value é null para uma célula em branco, então ambos os casos convergem na mesma verificação. O segundo é converter em vez de fazer casting: Value mantém o valor tipado bruto, e o código que faz casting direto dele ensina um bug que aparece apenas naquele arquivo onde uma coluna é armazenada de forma diferente. Ler Text em vez disso é completamente razoável quando o destino é uma coluna de string.

O Que o StreamCellType Reporta?

Valores StreamCellType, relatados por StreamCell.Type

ValorReportado quando
BlankA célula não contém valor. Value é null
NumberA célula contém um valor numérico
StringA célula contém texto
BooleanA célula contém TRUE ou FALSE
DateA célula contém uma data, respeitando o sistema de datas do workbook
ErrorA célula contém um valor de erro do Excel

Não há deliberadamente nenhum membro Formula. Uma célula de fórmula relata o tipo real de seu resultado em cache aqui, por exemplo Number, e a fórmula em si é exposta separadamente através de IsFormula. Qualquer um que escaneie o enum para um caso de fórmula não encontrará nenhum, e isso é por design ao invés de uma omissão.


Quais São as Limitações do Leitor de Streaming?

Conhecer essas limitações antecipadamente evita os diagnósticos errados mais comuns.

Apenas as sobrecargas de caminho são genuinamente de baixa memória. Este é o aviso mais importante na página. Um desenvolvedor que passa um upload de 400 MB como um byte[], vê a memória subir, e conclui que a funcionalidade está quebrada, encontrou exatamente isso.

Os limites remanescentes são fixados pelo design:

  • Somente leitura: O leitor de streaming não pode modificar ou salvar. Editar significa WorkBook.Load.
  • Somente XLSX: Nenhum .xls, nenhum workbook criptografado, e nenhuma escrita de qualquer tipo.
  • Somente para frente e de passagem única: Não há acesso aleatório nem rebobinamento. O código que precisa pular ao redor de uma planilha requer Load.
  • Sem formatação ou objetos de formatação: A aparência da célula não é exposta.
  • Apenas resultados de fórmula em cache: A expressão da fórmula não é exposta e nada é recalculado.
Por favor, note: Ambos StreamRows e GetSheetNames requerem uma licença válida do IronXL, aplicada quando o método é chamado, exatamente como com WorkBook.Load.

Outro aviso adicional está entre a limitação e o comportamento: a leitura de baixa memória de um caminho é o melhor esforço. Um workbook cujo diretório central de zip não pode ser lido pode recair para carregar o pacote na memória.


Como Construo um Pipeline de Importação de Streaming?

O padrão que carrega o trabalho de produção é uma leitura de streaming alimentando gravações em lotes, então nem a fonte nem o destino são mantidos na memória em tamanho completo.

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);
}

A coisa que faz isso aguentar são os lotes. Linhas chegam uma de cada vez, acumulam-se em um buffer de tamanho fixo, e esvaziam-se no banco de dados ou fila quando o buffer se enche. A memória de pico é limitada pelo tamanho do lote em vez da contagem de linhas, o que significa que o mesmo código lida com um arquivo de 5.000 linhas e um arquivo de 5.000.000 de linhas de forma idêntica.

Ignorar linhas malformadas em vez de lançar uma exceção é uma escolha deliberada para importações em massa. Uma linha não analisável em várias centenas de milhares não deve abortar a execução, e gravando RowNumber ao lado de cada registro dá aos operadores uma maneira de rastrear um valor ruim de volta para sua célula no arquivo fonte.


Quais Casos de Borda Devo Manipular?

GetSheetNames retorna todas as planilhas no workbook, incluindo planilhas de gráficos. Uma planilha de gráfico não contém linhas, então passar seu índice para StreamRows gera uma sequência vazia em vez de levantar um erro. O código que percorre cada índice de planilha encontrará isso, e um resultado vazio ali é esperado.

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);
    }
}

Células de data honram o sistema de datas do workbook, incluindo os workbooks baseados em 1904 que o Excel para Mac produz. Nenhum ajuste é necessário no código de chamada.

Para Onde Devo Ir a Seguir?

StreamRows cobre bem um trabalho: obter valores de um arquivo XLSX grande rapidamente, com memória que permanece estável. Qualquer coisa além de ler valores pertence ao modelo completo do workbook, e misturar os dois em um pipeline é normal. Transmita para validar ou importar, então Load o arquivo de trabalho menor quando forem necessárias edições.

Para a funcionalidade circundante, o Como Ler Arquivo XLSX em C# cobre leitura padrão, o Como Importar Arquivos Excel cobre padrões de importação de dados, e o Tutorial de Como Ler Arquivos Excel em C# trabalha através dos fundamentos. A página de solução de problemas de limites de tamanho de arquivo cobre os limites de linha e coluna no nível de formato, e a referência da API do WorkBook documenta a classe completa.

Ahmad é um desenvolvedor full-stack com uma sólida base em C#, Python e tecnologias web. Ele tem um grande interesse em construir soluções de software escaláveis e gosta de explorar como design e funcionalidade se encontram em aplicações do mundo real.

Leia Mais

Pronto para começar?

Downloads no NuGet 2,393,101Versão:2026.11recém-lançado