---
title: "Read an Excel file in C#"
url: https://recursiveai.org/onedocument/cookbook/read-excel-file/
description: "Read an Excel file in C# with OneDocument for .NET 10. Free, open-source code with a runnable download, self-made inputs and real output."
version: "1.0.0"
---

# Read an Excel file in C#

**OneDocument** is a free, open-source Word, Excel and PowerPoint document library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneDocument.Spreadsheets) · [GitHub](https://github.com/recursive-ai-oss/onedocument-csharp) · [Docs](https://recursiveai.org/onedocument/docs/)

```shell
dotnet add package \
    RecursiveAI.OneDocument.Spreadsheets
```

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

```csharp
using RecursiveAI.OneDocument.Spreadsheets;
using var wb = Workbook.Open("budget.xlsx");
Console.WriteLine(wb.Sheets[0]["B2"].Text);
```

Prints B2 as 189.5 for the sample.

**[Download this example (.zip)](https://recursiveai.org/onedocument/cookbook/read-excel-file/read-excel-file.zip)**: unzip, then `dotnet run`.

## The full program

The download first makes budget.xlsx, including a SUM formula and currency formats. It then opens the file and reads each row, followed by the formula text.

```csharp
using RecursiveAI.OneDocument.Spreadsheets;

using (Workbook made = Workbook.Create())
{
    Worksheet sheet = made.Sheets[0];
    sheet.Rename("Budget");
    sheet.Range("A1:B3").Values = new object?[,]
    {
        { "Item", "Cost" },
        { "Ladder", 189.5 },
        { "Bulbs", 42 }
    };
    sheet["A4"].SetString("Total");
    sheet["B4"].Formula = "SUM(B2:B3)";
    sheet.Range("B2:B4").NumberFormat = "$#,##0.00";
    made.Recalculate();
    made.SaveAs("budget.xlsx");
}

using Workbook book = Workbook.Open("budget.xlsx");
Worksheet budget = book.Sheets["Budget"];
for (int row = 1; row <= 4; row++)
    Console.WriteLine($"{budget[$"A{row}"].Text}: {budget[$"B{row}"].FormattedText}");
Console.WriteLine($"B4 formula: {budget["B4"].Formula}");
```

`dotnet run` prints:

```text
Item: Cost
Ladder: $189.50
Bulbs: $42.00
Total: $231.50
B4 formula: SUM(B2:B3)
```

Opening a workbook does not recalculate formulas. A malformed worksheet raises `OfficeFormatException` when that sheet is first touched; it is not silently read as an empty sheet.

## Variations

**Read the formatted text instead of the raw number.**

```csharp
using RecursiveAI.OneDocument.Spreadsheets;

using var book = Workbook.Open("budget.xlsx");
Console.WriteLine(book.Sheets["Budget"]["B2"].FormattedText);
```

```text
$189.50
```

**Read rows into a list.** This example’s data rows are 2 and 3:

```csharp
using RecursiveAI.OneDocument.Spreadsheets;

using var book = Workbook.Open("budget.xlsx");
var sheet = book.Sheets["Budget"];
var items = new List<string>();
for (int row = 2; row <= 3; row++)
    items.Add(sheet[$"A{row}"].Text);
Console.WriteLine(string.Join(", ", items));
```

```text
Ladder, Bulbs
```

## Related recipes

- [Convert DOCX to PDF in C#](https://recursiveai.org/onedocument/cookbook/convert-docx-to-pdf/)
- [Create an Excel XLSX file in C#](https://recursiveai.org/onedocument/cookbook/create-excel-file/)
- [Read a Word DOCX document in C#](https://recursiveai.org/onedocument/cookbook/read-word-document/)
- [Convert Excel to PDF in C#](https://recursiveai.org/onedocument/cookbook/convert-excel-to-pdf/)

---

## The short answer

To read an Excel file in C#, install OneDocument’s Spreadsheets package, open the file with `Workbook.Open`, select a worksheet, and address cells by their Excel coordinates. `Sheets[0]` selects the first sheet; `Sheets["Budget"]` selects it by name. Dispose the workbook with `using` when you are done reading.

Choose the cell property for the job. `Value` holds the typed cell value, `Text` exposes its text, `FormattedText` applies the number format, and `Formula` exposes its formula text. The difference is visible in this example: B2 is the number 189.5, while its formatted text is `$189.50`. Do not parse a display string back into a number when you need the stored numeric value.

## How do I read data from Excel in C#?

The full program is a small, reproducible example: it makes a workbook, closes it, then opens it for reading. Replace budget.xlsx with your own path and Budget with your sheet’s name. The first row is a header, rows 2 and 3 contain items, and row 4 holds the total. Those row numbers describe this sample, not a requirement of the API.

[Workbook opening](https://recursiveai.org/onedocument/docs/spreadsheets/) identifies the content rather than trusting the extension. Worksheet data is read lazily when you first access its cells. Reading a sheet does not edit it, and opening a workbook does not run the calculation engine. If you only want to inspect the saved values, there is no need to save or recalculate the file.

For numeric reports, use the workbook model rather than general text extraction. The [text extraction documentation](https://recursiveai.org/onedocument/docs/text-extraction/) says workbook extraction emits string cells, not numbers, booleans or errors. A plain-text search API is therefore not a substitute for reading a budget’s cells.

## How do I read an Excel file line by line in C#?

Think in worksheet rows, not physical text lines. The loop in the full program builds A and B cell addresses for each row and reads the values in a known rectangular table. That is a useful approach when the table’s structure is part of your input contract. Blank cells do not mean the file has ended, and a total row is not another item.

For a file too large for the editable workbook model, the library also has a [streaming reader, `XlsxStreamReader.Open`](https://recursiveai.org/onedocument/docs/spreadsheets-streaming/). It exposes rows as they are read rather than constructing the whole worksheet’s cell store. Choose that API for sequential import; choose `Workbook` when you need random cell access or edits. Do not assume that calling `Workbook.Open` turns every subsequent operation into a streaming operation.

For a shorter row-import API over those cursors, use `Spreadsheet.ReadRows`. This one-line call, after the namespace import, counts the sample’s four rows without building the editable workbook model:

```csharp
using RecursiveAI.OneDocument.Spreadsheets;
Console.WriteLine(Spreadsheet.ReadRows("budget.xlsx").Count());
```

```text
4
```

## How do I read an Excel file into a List in C#?

The list variation reads just the item names and produces `Ladder, Bulbs`. It deliberately skips the header and total. In an importer, define which columns and rows form records before adding them to a list. Preserve numeric values as numbers if later code will sum or compare them; formatted text is for display.

Formula cells have two distinct pieces of information: the formula and its stored result. This file stores `SUM(B2:B3)` and a calculated total because the creation step explicitly calls `Recalculate`. A file saved by another producer may have stale cached results. Call `Recalculate` when you want OneDocument to calculate after changes, not merely to read the file as saved. The [README](https://recursiveai.org/onedocument/docs/overview/) states: “Formula text is en-US and invariant only; localized function names are not supported.” This applies when you supply formula text too: use `SUM`, not a translated function name.