Comment lire des fichiers Excel très volumineux en C# avec le streaming en mode avancé

Ahmad Sohail
Ahmad Sohail
Mis à jour : 17 septembre 2026

Une feuille de calcul avec plusieurs centaines de milliers de lignes casse l'approche habituelle. WorkBook.Load construit un modèle complet en mémoire du classeur, ce qui permet l'édition, le style, les formules et l'accès aléatoire, et c'est aussi pourquoi une exportation de 400 MB peut prendre des minutes et consommer plusieurs gigaoctets avant que la première valeur ne soit lue.

Le lecteur de streaming en mode avancé de IronXL, WorkBook.StreamRows, existe pour les tâches qui ne nécessitent que les valeurs. Il produit une ligne à la fois directement depuis le disque plutôt que de matérialiser le classeur, ce qui maintient la mémoire constante quel que soit le nombre de lignes que contient la feuille.

Comprendre où se situe la limite est plus important que l'API elle-même, car mal la lire est la principale façon dont cette fonctionnalité est mal utilisée. StreamRows est en lecture seule, uniquement pour XLSX et en mode avancé uniquement : une voie rapide pour l'extraction en vrac de valeurs. L'édition, le style, les formules, les graphiques, l'accès aléatoire et les formats non-XLSX restent tous le travail de WorkBook.Load.

Veuillez noter: Nécessite IronXL 2026.9.2 ou version ultérieure. Les versions antérieures n'exposent pas StreamRows et échoueront à la compilation.
Démarrage rapide : Diffuser un fichier XLSX volumineux ligne par ligne

Pointez StreamRows vers un chemin de fichier et énumérez le résultat. En coulisses, la surcharge du chemin de la chaîne lit les parties du classeur par paresse depuis le disque, et seule une ligne est matérialisée à la fois, ce qui maintient la mémoire constante sur une feuille de taille arbitrairement grande.

  1. 1Installez IronXL avec NuGet Package Manager

    PM > Install-Package IronXL.Excel

  2. 2Copiez et exécutez cet extrait de code.

    foreach (StreamRow row in WorkBook.StreamRows("large-export.xlsx"))
        Console.WriteLine(row[0]?.Text);
  3. 3Déployez pour tester sur votre environnement de production.

    Commencez à utiliser IronXL dans votre projet dès aujourd'hui avec un essai gratuit
    arrow pointer


Comment choisir entre StreamRows et WorkBook.Load ?

La distinction concerne ce dont le travail a besoin, et non la taille du fichier à elle seule. Un fichier de 50 MB qui nécessite de redéfinir une cellule appartient à Load. Un fichier de 500 MB qui nécessite trois colonnes poussées dans une base de données appartient à StreamRows.

Choisir entre le lecteur de streaming et le modèle de classeur complet

ExigencesStreamRowsWorkBook.Load
Extraction massive de valeurs, importations, ETL, validationOuiOui (plus lent)
Édition ou sauvegardeNonOui
Style, objets de formatageNonOui
Expressions de formule et recalculNon (résultats mis en cache uniquement)Oui
Accès aléatoire aux cellules arbitrairesNon (lecture en séquence uniquement)Oui
XLS, CSV, TSV, classeurs chiffrésNonOui
Graphiques et imagesNonOui

La différence est assez grande pour changer la façon dont un travail est conçu. Lire en streaming les 500 000 lignes d’un classeur de 23,4 MB a pris environ six secondes et a tenu environ 75 MB, avec la première ligne disponible en un quart de seconde ; WorkBook.Load sur le même fichier est beaucoup plus lourd dans les deux cas. Le matériel et la forme du classeur déplacent ces chiffres, et les classeurs avec des lignes exceptionnellement larges ou des tables de chaînes partagées lourdes bénéficient à nouveau différemment. Le guide des performances de chargement des données couvre les compromis équivalents du côté de l'écriture.


Comment diffuser des lignes à partir d'un classeur ?

WorkBook.StreamRows est une méthode statique sur WorkBook. Donnez-lui une source et une feuille de calcul, et énumérez ce qui revient.

Entrée

Une demi-million de lignes de données de transactions, huit colonnes de large, 23,4 MB sur disque. Excel l'ouvre sans se plaindre ; le problème commence quand le code essaie de tout charger en mémoire.

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

Sortie

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

Une ligne par cellule, car la boucle parcourt row.Cells plutôt qu'un ensemble fixe de colonnes. RowNumber est à base zéro, donc l'échantillon ajoute un pour aligner la sortie avec la numérotation d'Excel. Notez que l'en-tête arrive comme une ligne ordinaire ici : sans StreamReadOptions fourni, TxnId et Date passent en tant que valeurs de cellule sur la ligne 1 plutôt que de nommer les colonnes.

Le type de retour est IEnumerable<StreamRow>, et la distinction qui compte est que rien n'est lu tant que la séquence n'est pas itérée. Les lignes sont produites une à la fois au fur et à mesure que la boucle avance, donc un foreach sur une feuille de 500 000 lignes tient une seule ligne en mémoire plutôt qu'un demi-million. La conséquence est que la séquence est à passage unique et en mode avancé uniquement : il n'y a pas de retour en arrière à une ligne antérieure et pas d'indexation au milieu d'une. Les opérateurs LINQ se composent normalement contre elle, ce qui signifie que .Take(1000) lit mille lignes et s'arrête là.

Chaque StreamRow ne contient que les cellules qui ont du contenu, ce qui est couvert ci-dessous sous travailler avec un StreamRow.

Quelle surcharge devriez-vous utiliser ?

Neuf surcharges couvrent trois sources et trois manières de nommer la feuille. La source est la décision qui compte, car seules les surcharges string path lisent de manière paresseuse depuis le disque. Les surcharges Stream et byte[] doivent contenir les contenus décompressés du paquet en mémoire pendant toute la lecture.

Les neuf surcharges StreamRows, toutes retournant IEnumerable<StreamRow>

SurchargeMémoire faible
StreamRows(string path, int sheetIndex = 0)Oui
StreamRows(string path, string sheetName)Oui
StreamRows(string path, StreamReadOptions options)Oui
StreamRows(Stream stream, int sheetIndex = 0)Non
StreamRows(Stream stream, string sheetName)Non
StreamRows(Stream stream, StreamReadOptions options)Non
StreamRows(byte[] data, int sheetIndex = 0)Non
StreamRows(byte[] data, string sheetName)Non
StreamRows(byte[] data, StreamReadOptions options)Non

Les surcharges Stream et byte[] existent pour la commodité lorsqu'un fichier est déjà en mémoire, comme un téléchargement qui a été mis en tampon. Ils continuent à lire ligne par ligne, ils évitent donc de construire le modèle complet du classeur, mais les contenus décompressés restent en mémoire pendant toute la lecture. Attendez-vous à ce qu'il fonctionne environ dix fois la taille du fichier sur disque, donc un classeur de 23,4 MB contient un peu plus de 200 MB plutôt que le chiffre que sa taille suggère. Utilisez un chemin de fichier pour les plus gros fichiers.

Les trois retournent des lignes et des totaux identiques ; le coût est la mémoire, pas la vitesse ou la précision

Source de l'informationÉcouléMémoire de pointe
string path6.3 s75 MB
Stream6.2 s309 MB
byte[]6.3 s291 MB

Le temps écoulé est effectivement identique pour les trois, ce qui mérite d'être remarqué : choisir la mauvaise surcharge ne ralentit pas la lecture, cela la rend plus lourde. Un travail qui tient confortablement en mémoire ne ressentira pas du tout la différence jusqu'à ce que le fichier grossisse ou que la limite du conteneur soit abaissée.

Comment choisir une feuille de calcul ?

La sélection de la feuille a trois formes : un index à base zéro, un nom de feuille exact sans sensibilité à la casse, ou une instance StreamReadOptions. Un nom de feuille inconnu ou un index hors plage lance 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);
}

Ne pas passer d'argument de feuille diffuse la première feuille, car sheetIndex par défaut est 0. StreamReadOptions est la seule voie qui prend en charge les lignes d'en-tête, alors optez pour elle dès que des colonnes doivent être nommées.


Comment découvrir les feuilles avant la diffusion ?

WorkBook.GetSheetNames énumère chaque feuille dans l'ordre du classeur sans charger le contenu du classeur. Il lit seulement la liste des parties du classeur, donc il reste peu coûteux même avec un fichier très gros : environ un quart de seconde sur le classeur de 23,4 MB et de 500 000 lignes, ce qui est le même temps que pour un fichier de quelques kilooctets. Cela en fait l'appel naturel pour un fichier provenant d'un système externe dont la configuration n'est pas connue à l'avance.

Les trois surcharges GetSheetNames, toutes retournant IReadOnlyList<string>

SurchargeSource de l'information
GetSheetNames(string path)Un fichier sur disque
GetSheetNames(Stream stream)Un flux ouvert
GetSheetNames(byte[] data)Un tampon en mémoire

La position dans la liste retournée égale l'index de la feuille que StreamRows accepte, donc les deux API s'alignent directement : l'index 2 dans cette liste est la feuille que StreamRows(path, 2) lit.

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

Comment lire des lignes par nom de colonne ?

Définir HasHeaderRow nomme les colonnes et permet la lecture des lignes par nom d'en-tête. La ligne d'en-tête est utilisée pour le nommage et n'est pas produite en tant que données, et toutes les lignes avant HeaderRowIndex sont ignorées, ce qui gère le cas courant d'un titre ou d'un préambule situé au-dessus du véritable en-tête.

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);
}
Avertissement: L'accès nommé nécessite HasHeaderRow. Sans cela, l'indexeur de chaînes et TryGetCell lancent tous les deux InvalidOperationException.

Le traitement des en-têtes est délibérément strict. Si la feuille n'a pas de ligne à ou avant le HeaderRowIndex configuré, l'énumération lance InvalidOperationException avec un message "ligne d'en-tête non trouvée", et elle se déclenche dès qu'une ligne de données dépasse l'index de l'en-tête. Cela garantit qu'un consommateur utilisant Take ou un débutant break voit la mauvaise configuration immédiatement plutôt que de lire silencieusement rien.

Le nom des colonnes est insensible à la casse et élimine l'espace blanc environnant. Les noms d'en-tête en double résolvent en faveur de la première colonne correspondante la plus à gauche.

Qu'est-ce que StreamReadOptions configure ?

propriétés StreamReadOptions, définies par l'initialiseur d'objet

PropriétéTypeDefaultComportement
SheetIndexint0Index de feuille de calcul à base zéro. Ignoré lorsque SheetName est défini
SheetNamestringnullNom de la feuille de calcul, sans sensibilité à la casse correspondante. Prend le pas sur SheetIndex
HasHeaderRowboolfalseLorsqu'il est vrai, la ligne à HeaderRowIndex nomme les colonnes et n'est pas produite en tant que données
HeaderRowIndexint0Ligne de feuille de calcul à base zéro tenant l'en-tête. Les lignes avant sont ignorées

Comment gérer les colonnes facultatives ?

Les deux accesseurs nommés diffèrent sur la façon dont ils traitent une colonne qui n'est pas dans l'en-tête, et choisir le mauvais est ce qui transforme un fichier source tolérable en un crash. L'indexeur de chaîne lance ArgumentException; TryGetCell retourne 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 répond à une question plus étroite que ce qu'il semble d'abord : il indique si l'en-tête contient le nom de la colonne, pas si cette ligne particulière a une valeur. Une ligne avec un écart sparce dans une colonne connue retourne true avec une cellule null, donc une vérification nulle est nécessaire sur le chemin de sortie. Utilisez TryGetCell pour toute colonne qui peut manquer dans certains fichiers source, et l'indexeur de chaîne uniquement là où la colonne est garantie.


Comment travailler avec un StreamRow ?

Un StreamRow est une ligne produite lors de l'énumération. Il expose sa position, les cellules qu'il contient réellement, et à la fois une recherche positionnelle et nommée.

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

membres StreamRow, avec un accès à la fois positionnel et par nom

MembreTypeComportement
RowNumberintZero-based. La ligne Excel 1 est RowNumber 0
CellsIReadOnlyList<StreamCell>Sparse. Seules les colonnes avec du contenu sont présentes
HeaderIReadOnlyList<string>Les noms de colonnes positionnés par colonne, donc Header[i] nomme la colonne i. Une colonne d'en-tête vide est null, et Header est en lui-même null quand aucun en-tête n'a été configuré.
this[int columnIndex]StreamCellCellule à un index de colonne à base zéro, ou null pour un écart sparce
this[string columnName]StreamCellCellule sous un nom d'en-tête colonne. Lance ArgumentException lorsque le nom est absent
TryGetCell(string, out StreamCell)booltrue quand l'en-tête contient le nom, false quand il ne le fait pas
Avertissement: Header est null sauf si StreamReadOptions.HasHeaderRow était défini. Protégez-le avant de faire une itération, sinon la boucle déréférencera une liste nulle.

La rareté est la propriété qui façonne le code d'appel. Une ligne n'est pas un enregistrement de largeur fixe : une feuille avec des colonnes A à F produit des lignes contenant trois cellules là où trois colonnes ont été remplies, et l'indexeur positionnel retourne null pour les écarts. RowNumber étant à base zéro est conforme au reste de IronXL, où les indexeurs numériques sont à base zéro alors que les adresses de chaîne de style A1 ne le sont pas.


Comment lire des valeurs typées d'un StreamCell ?

Un StreamCell est un instantané immuable d'une cellule. Contrairement à une Cell normale, elle n'est pas supportée par le classeur et ne peut pas être utilisée pour réécrire une valeur.

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

membres StreamCell, couvrant la position, le type et la valeur

MembreTypeComportement
ColumnIndexintIndex de colonne à base zéro
ColumnLetterstringLettre de colonne de feuille de calcul, par exemple "A", "C" ou "AA"
TypeStreamCellTypeLe type de valeur détenue. Pour une cellule de formule, le type du résultat mis en cache
ValueobjectLa valeur typée brute. null pour une cellule vide
TextstringLe texte d'affichage formaté, tel que l'affiche Excel
IsFormulabooltrue quand la cellule contient une formule

Value est encadré, donc ce à quoi vous le convertissez découle de Type :

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

Vérifier Type avant de toucher Value fait la différence entre un import qui résiste aux données réelles et un qui échoue à la ligne 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;
    }
}

Deux habitudes comptent ici. La première consiste à vérifier la nullité pour chaque accès à l'indexeur, car les lignes sont éparses et Value est null pour une cellule vide, donc les deux cas convergent vers la même vérification. La seconde consiste à convertir plutôt qu'à caster : Value contient la valeur typée brute, et le code qui fait un cast directement d'elle apprend un bug qui ne se manifeste que sur le fichier où une colonne se trouve stockée différemment. Lire Text à la place est tout à fait raisonnable lorsque la destination est une colonne de chaînes.

Que rapporte StreamCellType ?

Valeurs de StreamCellType, rapportées par StreamCell.Type

ValeurRapporté quand
BlankLa cellule ne contient pas de valeur. Value est null
NumberLa cellule contient une valeur numérique
StringLa cellule contient du texte
BooleanLa cellule contient TRUE ou FALSE
DateLa cellule contient une date, conforme au système de date du classeur
ErrorLa cellule contient une valeur d'erreur d'Excel

Il n'y a délibérément pas de membre Formula. Une cellule de formule rapporte ici le type réel de son résultat mis en cache, par exemple Number, et la nature de la formule est exposée séparément via IsFormula. Quiconque scanne l'énumération pour un cas de formule n'en trouvera pas, et cela est volontaire plutôt qu'une omission.


Quelles sont les limites du lecteur de streaming ?

Savoir cela à l'avance empêche les diagnostics erronés les plus courants.

Seules les surcharges de chemin sont vraiment à mémoire faible. C'est la mise en garde la plus importante de la page. Un développeur qui passe un téléchargement de 400 Mo en tant que byte[], observe l'augmentation de la mémoire et conclut que la fonctionnalité est cassée a frappé exactement cela.

Les limites restantes sont fixées par le design :

  • Lecture seule : Le lecteur de streaming ne peut pas modifier ou enregistrer. Éditer signifie WorkBook.Load.
  • XLSX uniquement : Pas de .xls, pas de carnets de travail chiffrés, et aucune écriture de quelque sorte que ce soit.
  • En mode avancé uniquement et à passage unique : Il n'y a pas d'accès aléatoire et pas de retour en arrière. Le code qui doit sauter autour d'une feuille veut Load.
  • Aucun objet de style ou de formatage : L'apparence des cellules n'est pas exposée.
  • Résultats de formules mis en cache uniquement : L'expression de formule n'est pas exposée et rien n'est recalculé.
Veuillez noter: Les deux StreamRows et GetSheetNames nécessitent une licence IronXL valide, appliquée lorsque la méthode est appelée, exactement comme pour WorkBook.Load.

Une autre mise en garde est à mi-chemin entre limitation et comportement : la lecture à mémoire faible depuis un chemin est un meilleur effort. Un classeur dont le répertoire central zip ne peut être lu peut rebondir à charger le paquet en mémoire.


Comment construire un pipeline d'importation en streaming ?

Le modèle qui porte le travail de production est une lecture en streaming alimentant des écritures par lots, donc ni la source ni la destination ne sont conservées en mémoire à pleine taille.

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

Le lotissement est ce qui permet à cela de tenir. Les lignes arrivent une à la fois, s'accumulent dans un tampon de taille fixe et se déchargent vers la base de données ou la file d'attente lorsque le tampon est plein. La mémoire maximale est délimitée par la taille du lot plutôt que par le nombre de lignes, ce qui signifie que le même code traite un fichier de 5 000 lignes et un fichier de 5 000 000 de lignes de manière identique.

Ignorer les lignes mal formées plutôt que d'échouer est un choix délibéré pour les importations en vrac. Une ligne non analysable parmi plusieurs centaines de milliers ne devrait pas interrompre l'exécution, et enregistrer RowNumber aux côtés de chaque enregistrement offre aux opérateurs un moyen de retracer une mauvaise valeur jusqu'à sa cellule dans le fichier source.


Quels cas limites devrais-je gérer ?

GetSheetNames retourne chaque feuille du classeur, y compris les chartsheets. Un chartsheet ne contient pas de lignes, donc passer son index à StreamRows renvoie une séquence vide plutôt que de soulever une erreur. Le code qui boucle chaque index de feuille rencontrera cela, et un résultat vide là-bas est attendu.

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

Les cellules de date respectent le système de date du classeur, y compris les classeurs basés sur 1904 que produit Excel pour Mac. Aucun ajustement n'est nécessaire dans le code d'appel.

Où aller ensuite ?

StreamRows couvre bien un travail : extraire rapidement des valeurs d'un fichier XLSX volumineux, avec une mémoire qui reste stable. Tout ce qui dépasse la lecture des valeurs appartient au modèle de classeur complet, et mélanger les deux dans un pipeline est normal. Diffusez pour valider ou importer, puis Load le petit fichier de travail lorsque des modifications sont nécessaires.

Pour les fonctionnalités environnantes, le guide C# Lire un fichier XLSX couvre la lecture standard, le guide Importer des fichiers Excel couvre les modèles d'importation de données, et le tutoriel Lire des fichiers Excel en C# aborde les fondamentaux. La page de dépannage sur les limites de taille des fichiers couvre les plafonds de lignes et de colonnes au niveau du format, et la référence API de WorkBook documente la classe complète.

Ahmad est un développeur full-stack avec une solide fondation en C#, Python et technologies web. Il a un profond intérêt pour la construction de solutions logicielles évolutives et aime explorer comment le design et la fonctionnalité se rencontrent dans des applications du monde réel.

Lire la suite

Prêt à commencer ?

Téléchargements NuGet 2,393,101Version :2026.11tout juste publié