Cómo leer archivos Excel muy grandes en C# con transmisión solo hacia adelante

Ahmad Sohail
Ahmad Sohail
Actualizado: 17 de septiembre de 2026

Una hoja de cálculo con varios cientos de miles de filas rompe el enfoque usual. WorkBook.Load construye un modelo completo en memoria del libro de trabajo, lo que permite la edición, el estilo, las fórmulas y el acceso aleatorio, y también es por eso que una exportación de 400 MB puede tardar minutos y consumir varios gigabytes antes de que se lea el primer valor.

El lector de transmisión solo hacia adelante de IronXL, WorkBook.StreamRows, existe para los trabajos que solo necesitan los valores. Rinde una fila a la vez directamente desde el disco en lugar de materializar el libro de trabajo, lo que mantiene la memoria plana sin importar cuántas filas tenga la hoja.

Entender dónde cae la línea importa más que la propia API, porque malinterpretarla es la principal forma en que se usa incorrectamente la función. StreamRows es solo de lectura, solo XLSX y solo hacia adelante: un carril rápido para la extracción masiva de valores. La edición, el estilo, las fórmulas, los gráficos, el acceso aleatorio y los formatos no XLSX siguen siendo el trabajo de WorkBook.Load.

Por favor, tenga en cuenta: Requiere IronXL 2026.9.2 o posterior. Las versiones anteriores no exponen StreamRows y fallarán al compilar.
Inicio rápido: Transmitir un archivo XLSX grande fila por fila

Apunta StreamRows a una ruta de archivo y enumera el resultado. Detrás de escena, la sobrecarga del camino de cadena lee las partes del libro de trabajo de manera perezosa desde el disco, y solo se materializa una fila a la vez, lo que mantiene la memoria plana a través de una hoja arbitrariamente grande.

  1. 1Instalar IronXL con NuGet Package Manager

    PM > Install-Package IronXL.Excel

  2. 2Copie y ejecute este fragmento de código.

    foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx"))
        Console.WriteLine(row[0]?.Text);
  3. 3Despliegue para probar en su entorno real

    Empiece a usar IronXL en su proyecto hoy con una prueba gratuita
    arrow pointer


¿Cómo elijo entre StreamRows y WorkBook.Load?

La división es una cuestión de lo que el trabajo necesita, no solo del tamaño del archivo. Un archivo de 50 MB que necesita una celda restilizada pertenece a Load. Un archivo de 500 MB que necesita tres columnas empujadas a una base de datos pertenece a StreamRows.

Elegir entre el lector de transmisión y el modelo completo del libro de trabajo

RequisitosStreamRowsWorkBook.Load
Extracción masiva de valores, importaciones, ETL, validaciónSíSí (más lento)
Edición o guardadoNoSí
Estilo, objetos de formatoNoSí
Expresiones de fórmula y recálculoNo (solo resultados en caché)Sí
Acceso aleatorio a celdas arbitrariasNo (solo hacia adelante)Sí
XLS, CSV, TSV, libros de trabajo encriptadosNoSí
Gráficos e imágenesNoSí

La brecha es lo suficientemente amplia como para cambiar cómo se diseña un trabajo. Transmitir las 500,000 filas de un libro de trabajo de 23.4 MB tomó alrededor de seis segundos y mantuvo aproximadamente 75 MB, con la primera fila disponible en un cuarto de segundo; WorkBook.Load en el mismo archivo es dramáticamente más pesado en ambos aspectos. El hardware y la forma del libro de trabajo mueven estos números, y los libros de trabajo con filas inusualmente anchas o tablas de cadenas compartidas pesadas aterrizan de manera diferente nuevamente. La guía de rendimiento de carga de datos cubre las compensaciones equivalentes en el lado de escritura.


¿Cómo transmito filas de un libro de trabajo?

WorkBook.StreamRows es un método estático en WorkBook. Dale una fuente y una hoja de trabajo, y enumera lo que regresa.

Entrada

Medio millón de filas de datos de transacciones, ocho columnas de ancho, 23.4 MB en disco. Excel lo abre sin quejarse; el problema comienza cuando el código intenta cargar todo en la memoria.

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

Resultado

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

Una línea por celda, porque el bucle pasa por row.Cells en lugar de un conjunto fijo de columnas. RowNumber es de base cero, por lo que el ejemplo agrega uno para alinear la salida con la numeración de Excel. Tenga en cuenta que el encabezado llega como una fila ordinaria aquí: sin StreamReadOptions suministrado, TxnId y Date vienen como valores de celda en la fila 1 en lugar de nombrar las columnas.

El tipo de retorno es IEnumerable<StreamRow>, y la distinción que importa es que nada se lee hasta que se itera la secuencia. Las filas se producen una a la vez a medida que el ciclo avanza, por lo que un foreach sobre una hoja de 500,000 filas mantiene una sola fila en memoria en lugar de medio millón. La consecuencia es que la secuencia es de paso único y solo hacia adelante: no se puede volver a una fila anterior ni indexar en el medio de una. Los operadores LINQ se componen contra ella normalmente, lo que significa que .Take(1000) lee mil filas y se detiene ahí.

Cada StreamRow lleva solo las celdas que tienen contenido, lo cual cubre trabajando con un StreamRow a continuación.

¿Qué sobrecarga debo usar?

Nueve sobrecargas cubren tres fuentes y tres formas de nombrar la hoja de trabajo. La fuente es la decisión que importa, porque solo las sobrecargas string path leen perezosamente desde el disco. Las sobrecargas Stream y byte[] deben mantener el contenido descomprimido del paquete en memoria durante la lectura.

Las nueve sobrecargas StreamRows, todas devolviendo IEnumerable<StreamRow>

SobrecargaBajo-memoria
StreamRows(string path, int sheetIndex = 0)Sí
StreamRows(string path, string sheetName)Sí
StreamRows(string path, StreamReadOptions options)Sí
StreamRows(Stream stream, int sheetIndex = 0)No
StreamRows(Stream stream, string sheetName)No
StreamRows(Stream stream, StreamReadOptions options)No
StreamRows(byte[] data, int sheetIndex = 0)No
StreamRows(byte[] data, string sheetName)No
StreamRows(byte[] data, StreamReadOptions options)No

Las sobrecargas Stream y byte[] existen para conveniencia cuando un archivo ya está en memoria, como una subida que ha sido almacenada en búfer. Todavía transmiten fila por fila, por lo que evitan construir el modelo completo del libro de trabajo, pero el contenido desempacado permanece residente durante toda la lectura. Espere que funcione alrededor de diez veces el tamaño del archivo en disco, por lo que un libro de trabajo de 23.4 MB contiene un poco más de 200 MB en lugar de la cifra que sugiere su tamaño de archivo. Use una ruta de archivo para los archivos más grandes.

Los tres devuelven filas y totales idénticos; el costo es la memoria, no la velocidad o la precisión

FuenteTranscurridoMemoria máxima
string path6.3 s75 MB
Stream6.2 s309 MB
byte[]6.3 s291 MB

El tiempo transcurrido es efectivamente idéntico en los tres, lo cual vale la pena notar: elegir la sobrecarga incorrecta no hace que la lectura sea más lenta, la hace más pesada. Un trabajo que encaja cómodamente en la memoria no sentirá la diferencia hasta que el archivo crezca o se reduzca el límite del contenedor.

¿Cómo elijo una hoja de trabajo?

La selección de hojas tiene tres formas: un índice basado en cero, un nombre de hoja exacto que coincide sin sensibilidad a mayúsculas y minúsculas, o una instancia StreamReadOptions. Un nombre de hoja desconocido o un índice fuera de rango lanza 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);
}

Pasar ningún argumento de hoja transmite la primera hoja, porque sheetIndex se predetermina a 0. StreamReadOptions es la única ruta que admite filas de encabezado, por lo que acuda a ella tan pronto como las columnas necesiten nombres.


¿Cómo descubro hojas antes de transmitir?

WorkBook.GetSheetNames enumera cada hoja en el orden del libro de trabajo sin cargar el contenido del libro de trabajo. Solo lee la lista de partes del libro de trabajo, por lo que se mantiene barato incluso en un archivo muy grande: alrededor de un cuarto de segundo en el libro de trabajo de 23.4 MB y 500,000 filas, que es el mismo tiempo que lleva en un archivo de unos pocos kilobytes. Eso lo hace la llamada natural primero para un archivo que llega de un sistema externo cuyo diseño no se conoce de antemano.

Las tres sobrecargas GetSheetNames, todas devolviendo IReadOnlyList<string>

SobrecargaFuente
GetSheetNames(string path)Un archivo en disco
GetSheetNames(Stream stream)Un flujo abierto
GetSheetNames(byte[] data)Un búfer en memoria

La posición en la lista devuelta equivale al índice de hoja que acepta StreamRows, por lo que las dos APIs se alinean directamente: el índice 2 en esta lista es la hoja que lee StreamRows(path, 2).

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

¿Cómo leo filas por nombre de columna?

Configurar HasHeaderRow nombra las columnas y permite que las filas se lean por nombre de encabezado. La fila de encabezado se consume para nombrar y no se rinde como datos, y cualquier fila antes de HeaderRowIndex se omite, lo que maneja el caso común de un título o preámbulo sentado por encima del verdadero encabezado.

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);
}
Advertencia: El acceso nombrado requiere HasHeaderRow. Sin ello, el indexador de cadenas y TryGetCell ambos lanzan InvalidOperationException.

El manejo de encabezados es deliberadamente estricto. Si la hoja no tiene fila en o antes del HeaderRowIndex configurado, la enumeración lanza InvalidOperationException con un mensaje de "fila de encabezado no encontrada", y lanza tan pronto como una fila de datos supera el índice de encabezado. Esto asegura que un consumidor utilizando Take o un temprano break vea la mala configuración inmediatamente en lugar de leer en silencio nada.

La coincidencia de nombres de columnas no distingue entre mayúsculas y minúsculas y recorta espacios en blanco circundantes. Los nombres de encabezado duplicados se resuelven en la primera, más a la izquierda, columna coincidente.

¿Qué configura StreamReadOptions?

Propiedades StreamReadOptions, establecidas a través del inicializador de objetos

PropiedadTipoDefaultComportamiento
SheetIndexint0Índice de hoja de trabajo basado en cero. Ignorado cuando se establece SheetName
SheetNamestringnullNombre de la hoja de trabajo, coincidencia sin sensibilidad a mayúsculas y minúsculas. Tiene prioridad sobre SheetIndex
HasHeaderRowboolfalseCuando está en true, la fila en HeaderRowIndex nombra las columnas y no se rinde como datos
HeaderRowIndexint0Fila de hoja de base cero que contiene el encabezado. Las filas antes de ella se omiten

¿Cómo manejo columnas opcionales?

Los dos accesores nombrados difieren en cómo tratan una columna que no está en el encabezado, y elegir el incorrecto es lo que convierte un archivo de origen tolerable en un accidente. El indexador de cadenas lanza ArgumentException; TryGetCell devuelve 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 una pregunta más estrecha de lo que parece al principio: informa si el encabezado contiene el nombre de la columna, no si esta fila particular tiene un valor allí. Una fila con una brecha dispersa en una columna conocida devuelve true con una celda null, por lo que todavía se necesita una verificación de nulo a la salida. Utilice TryGetCell para cualquier columna que pueda faltar en algunos archivos de origen, y el indexador de cadenas solo donde la columna está garantizada.


¿Cómo trabajo con un StreamRow?

Un StreamRow es una fila producida durante la enumeración. Expone su posición, las celdas que realmente contiene, y tanto búsqueda posicional como nombrada.

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

Miembros StreamRow, con acceso tanto posicional como nombrado

MiembroTipoComportamiento
RowNumberintBasado en cero. La fila 1 de Excel es RowNumber 0
CellsIReadOnlyList<StreamCell>Disperso. Solo las columnas con contenido están presentes
HeaderIReadOnlyList<string>Los nombres de las columnas están posicionados por columna, por lo que Header[i] nombra la columna i. Una columna de encabezado en blanco es null, y Header en sí misma es null cuando no se configuró un encabezado
this[int columnIndex]StreamCellCelda en un índice de columna basado en cero, o null para una brecha dispersa
this[string columnName]StreamCellCelda bajo una columna de encabezado nombrada. Lanza ArgumentException cuando el nombre está ausente
TryGetCell(string, out StreamCell)booltrue cuando el encabezado contiene el nombre, false cuando no lo hace
Advertencia: Header es null a menos que StreamReadOptions.HasHeaderRow se haya establecido. Protégelo antes de iterar, o el bucle desreferenciará una lista nula.

La dispersión es la propiedad que da forma al código de llamada. Una fila no es un registro de ancho fijo: una hoja con columnas A a F produce filas que contienen tres celdas donde se llenaron tres columnas, y el indexador posicional devuelve null para las brechas. RowNumber siendo de base cero es consistente con el resto de IronXL, donde los indexadores numéricos son de base cero mientras que las direcciones de cadena estilo A1 no lo son.


¿Cómo leo valores tipados de un StreamCell?

Un StreamCell es una instantánea inmutable de una celda. A diferencia de un Cell normal, no está respaldado por el libro de trabajo y no se puede usar para escribir un valor de vuelta.

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

Miembros StreamCell, cubriendo posición, tipo y valor

MiembroTipoComportamiento
ColumnIndexintÍndice de columna basado en cero
ColumnLetterstringLetra de columna de hoja de cálculo, por ejemplo "A", "C" o "AA"
TypeStreamCellTypeEl tipo de valor que se mantiene. Para una celda de fórmula, el tipo del resultado en caché
ValueobjectEl valor tipado bruto. null para una celda en blanco
TextstringEl texto de visualización formateado, tal como lo muestra Excel
IsFormulabooltrue cuando la celda contiene una fórmula

Value está empaquetado, por lo que lo que conviertes sigue de Type:

  • Number da un double
  • String da un string
  • Boolean da un bool
  • Date da un DateTime
  • Blank da null

Verificar Type antes de tocar Value es la diferencia entre una importación que sobrevive a los datos reales y una que falla en la fila 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;
    }
}

Dos hábitos importan aquí. El primero es verificar null en cada acceso al indexador, porque las filas son dispersas y Value es null para una celda en blanco, por lo que ambos casos convergen en la misma verificación. El segundo es convertir en lugar de castear: Value contiene el valor tipado bruto, y el código que hace una conversión directa de él enseña un error que solo aparece en el único archivo donde una columna resulta estar almacenada de manera diferente. Leer Text en su lugar es completamente razonable cuando el destino es una columna de cadena.

¿Qué informa StreamCellType?

Valores StreamCellType, informados por StreamCell.Type

ValorInformado cuando
BlankLa celda no contiene valor. Value es null
NumberLa celda contiene un valor numérico
StringLa celda contiene texto
BooleanLa celda contiene TRUE o FALSE
DateLa celda contiene una fecha, respetando el sistema de fechas del libro de trabajo
ErrorLa celda contiene un valor de error de Excel

Deliberadamente no hay un miembro Formula. Una celda de fórmula informa el tipo real de su resultado en caché aquí, por ejemplo Number, y la fórmula-se expone por separado a través de IsFormula. Cualquier persona que busque en el enumerador un caso de fórmula no encontrará uno, y eso es por diseño en lugar de una omisión.


¿Cuáles son las limitaciones del lector de transmisión?

Conocer estas de antemano previene los diagnósticos erróneos más comunes.

Solo las sobrecargas de ruta son genuinamente de baja memoria. Esta es la advertencia más importante en la página. Un desarrollador que pasa una subida de 400 MB como byte[], observa el aumento de la memoria y concluye que la función está rota ha topado precisamente con esto.

Los límites restantes están fijados por el diseño:

  • Solo lectura: El lector de transmisión no puede modificar ni guardar. Editar significa WorkBook.Load.
  • Solo XLSX: Sin .xls, sin libros de trabajo encriptados y sin escritura de ningún tipo.
  • Solo hacia adelante y de paso único: No hay acceso aleatorio ni rebobinado. El código que necesita saltar en una hoja quiere Load.
  • Sin estilo ni objetos de formato: No se expone el aspecto de las celdas.
  • Solo resultados de fórmulas en caché: No se expone la expresión de la fórmula y nada se recalcula.
Por favor, tenga en cuenta: Tanto StreamRows como GetSheetNames requieren una licencia válida de IronXL, aplicada cuando se llama al método, exactamente como con WorkBook.Load.

Una advertencia adicional se encuentra entre la limitación y el comportamiento: la lectura de baja memoria desde una ruta es de mejor esfuerzo. Un libro de trabajo cuyo directorio central zip no se pueda leer puede recurrir a cargar el paquete en memoria.


¿Cómo construyo una tubería de importación de transmisión?

El patrón que lleva el trabajo de producción es una lectura de transmisión que alimenta escrituras por lotes, por lo que ni la fuente ni el destino se mantienen en memoria en tamaño 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);
}

El loteo es lo que lo sostiene. Las filas llegan una a la vez, se acumulan en un búfer de tamaño fijo y se envían a la base de datos o cola cuando el búfer se llena. La memoria máxima está limitada por el tamaño del lote en lugar de por el conteo de filas, lo que significa que el mismo código maneja un archivo de 5,000 filas y un archivo de 5,000,000 filas idénticamente.

Saltar filas malformadas en lugar de lanzar es una elección deliberada para importaciones masivas. Una fila que no se puede analizar entre varios cientos de miles no debería abortar la ejecución, y registrar RowNumber junto a cada registro da a los operadores una forma de rastrear un valor malo a su celda en el archivo de origen.


¿Qué casos extremos debo manejar?

GetSheetNames devuelve cada hoja en el libro de trabajo, incluidas las hojas de gráficos. Una hoja de gráficos no tiene filas, por lo que pasar su índice a StreamRows da una secuencia vacía en lugar de arrojar un error. El código que recorre cada índice de hoja encontrará esto, y un resultado vacío ahí es 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);
    }
}

Las celdas de fecha respetan el sistema de fechas del libro de trabajo, incluidas las obra de libros basados en 1904 que Excel para Mac produce. No se necesita ningún ajuste en el código de llamada.

¿Dónde voy después?

StreamRows cubre un trabajo bien: obtener valores de un archivo XLSX grande rápidamente, con memoria que se mantiene plana. Cualquier cosa más allá de leer valores pertenece al modelo completo del libro de trabajo, y mezclar los dos en una sola tubería es normal. Transmita para validar o importar, luego Load el archivo de trabajo más pequeño cuando se necesiten ediciones.

Para la funcionalidad circundante, el Cómo leer un archivo XLSX en C# cubre la lectura estándar, el Cómo importar archivos de Excel cubre los patrones de importación de datos, y el Tutorial de lectura de archivos de Excel en C# trabaja en los conceptos básicos. La página de solución de problemas de límites de tamaño de archivo cubre los techos de filas y columnas a nivel de formato, y la referencia de la API de WorkBook documenta la clase completa.

Ahmad es un desarrollador full-stack con una sólida base en C#, Python y tecnologías web. Tiene un profundo interés en construir soluciones de software escalables y disfruta explorando cómo el diseño y la funcionalidad se encuentran en aplicaciones del mundo real.

Leer más

¿Listo para empezar?

Descargas de NuGet 2,393,101Versión:2026.11recién lanzado