C# Read Excel File Tutorial
This tutorial explains how to read an Excel file in C#, as well as perform everyday tasks like data validation, database conversion, Web API integrations, and formula modification. This article references code examples that utilize the IronXL .NET Excel library.
Overview
How to Read Excel File in C#
- Download the C# Library to read Excel files
- Load and read an Excel file (workbook)
- Create an Excel workbook in CSV or XLSX
- Edit cell values in a range of cells
- Validate spreadsheet data
- Export data using Entity Framework
IronXL facilitates reading and editing Microsoft Excel documents with C#. IronXL neither requires Microsoft Excel nor does it require Interop. In fact, IronXL provides a faster and more intuitive API than Microsoft.Office.Interop.Excel
.
IronXL Includes:
- Dedicated product support from our .NET engineers
- Easy installation via Microsoft Visual Studio
- Free trial test for development. Licenses from $749.
Reading and creating Excel files in C# and VB.NET is easy using the IronXL software library.
Reading .XLS and .XLSX Excel Files Using IronXL
Below is a summary of the overall workflow for reading Excel files using IronXL:
- Install the IronXL Excel Library. We can do this using our NuGet package or by downloading the .Net Excel DLL.
- Use the
WorkBook.Load
method to read any XLS, XLSX or CSV document. - Get Cell values using intuitive syntax:
sheet ["A11"].DecimalValue
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-1.cs
using IronXL;
using System;
using System.Linq;
// Supported spreadsheet formats for reading include: XLSX, XLS, CSV and TSV
WorkBook workBook = WorkBook.Load("test.xlsx");
WorkSheet workSheet = workBook.WorkSheets.First();
// Select cells easily in Excel notation and return the calculated value
int cellValue = workSheet["A2"].IntValue;
// Read from Ranges of cells elegantly.
foreach (var cell in workSheet["A2:A10"])
{
Console.WriteLine("Cell {0} has value '{1}'", cell.AddressString, cell.Text);
}
// Advanced Operations
// Calculate aggregate values such as Min, Max and Sum
decimal sum = workSheet["A2:A10"].Sum();
// Linq compatible
decimal max = workSheet["A2:A10"].Max(c => c.DecimalValue);
Imports IronXL
Imports System
Imports System.Linq
' Supported spreadsheet formats for reading include: XLSX, XLS, CSV and TSV
Private workBook As WorkBook = WorkBook.Load("test.xlsx")
Private workSheet As WorkSheet = workBook.WorkSheets.First()
' Select cells easily in Excel notation and return the calculated value
Private cellValue As Integer = workSheet("A2").IntValue
' Read from Ranges of cells elegantly.
For Each cell In workSheet("A2:A10")
Console.WriteLine("Cell {0} has value '{1}'", cell.AddressString, cell.Text)
Next cell
' Advanced Operations
' Calculate aggregate values such as Min, Max and Sum
Dim sum As Decimal = workSheet("A2:A10").Sum()
' Linq compatible
Dim max As Decimal = workSheet("A2:A10").Max(Function(c) c.DecimalValue)
The code examples used in the next sections of this tutorial (along with the sample project code) will work on three sample Excel spreadsheets (see below for a visual):
Tutorial
1. Download the IronXL C# Library for FREE
Start using IronXL in your project today with a free trial.
The first thing we need to do is install the IronXL.Excel
library, adding Excel functionality to the .NET framework.
Installing IronXL.Excel
, is most easily achieved using our NuGet package, although you may also choose to manually install the DLL to your project or to your global assembly cache.
Installing the IronXL NuGet Package
- In Visual Studio, right-click on the project select "Manage NuGet Packages ..."
Search for the IronXL.Excel package and click on the Install button to add it to the project
Another way to install the IronXL library is using the NuGet Package Manager Console:
- Enter the Package Manager Console
Type
> Install-Package IronXL.Excel
PM > Install-Package IronXL.Excel
Additionally, you can view the package on the NuGet website
Manual Installation
Alternatively, we can start by downloading the IronXL .NET Excel DLL and manually installing into Visual Studio.
2. Load an Excel Workbook
The WorkBook
class represents an Excel sheet. To open an Excel File using C#, we use WorkBook.Load
method, specifying the path of the Excel fil.
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-2.cs
WorkBook workBook = WorkBook.Load(@"Spreadsheets\\GDP.xlsx");
Dim workBook As WorkBook = WorkBook.Load("Spreadsheets\\GDP.xlsx")
Sample: ExcelToDBProcessor
Each WorkBook
can have multiple WorkSheet
objects. Each one represents a single Excel worksheet in the Excel document. Use the WorkBook.GetWorkSheet
method to retrieve a reference to a specific Excel worksheet.
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-3.cs
Sample: ExcelToDB
Creating new Excel Documents
To create a new Excel document, construct a new WorkBook
object with a valid file type.
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-4.cs
WorkBook workBook = new WorkBook(ExcelFileFormat.XLSX);
Dim workBook As New WorkBook(ExcelFileFormat.XLSX)
Sample: ApiToExcelProcessor
Note: Use ExcelFileFormat.XLS
to support legacy versions of Microsoft Excel (95 and earlier).
Add a Worksheet to an Excel Document
As explained previously, an IronXL WorkBook
contains a collection of one or more WorkSheet
s.
To create a new WorkSheet
call WorkBook.CreateWorkSheet
with the name of the worksheet.
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-5.cs
WorkSheet workSheet = workBook.GetWorkSheet("GDPByCountry");
Dim workSheet As WorkSheet = workBook.GetWorkSheet("GDPByCountry")
3. Access Cell Values
Read and Edit a Single Cell
Access to the values of individual spreadsheet cells is carried out by retrieving the desired cell from its WorkSheet
. as shown below:
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-16.cs
WorkBook workBook = WorkBook.Load("test.xlsx");
WorkSheet workSheet = workBook.DefaultWorkSheet;
IronXL.Cell cell = workSheet["B1"].First();
Dim workBook As WorkBook = WorkBook.Load("test.xlsx")
Dim workSheet As WorkSheet = workBook.DefaultWorkSheet
Dim cell As IronXL.Cell = workSheet("B1").First()
IronXL's Cell
class represents an invidual cell in an Excel spreadsheet. It contains properties and methods that enable users to access and modify the cell's value directly.
Each WorkSheet
object manages an index of Cell
objects corresponding to every cell value in an Excel worksheet. In the source code above, we reference the desired cell by its row and column index (cell B1 in this case) using standard array indexing syntax.
With a reference to Cell object, we can read and write data to and from a spreadsheet cell:
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-17.cs
IronXL.Cell cell = workSheet["B1"].First();
string value = cell.StringValue; // Read the value of the cell as a string
Console.WriteLine(value);
cell.Value = "10.3289"; // Write a new value to the cell
Console.WriteLine(cell.StringValue);
Dim cell As IronXL.Cell = workSheet("B1").First()
Dim value As String = cell.StringValue ' Read the value of the cell as a string
Console.WriteLine(value)
cell.Value = "10.3289" ' Write a new value to the cell
Console.WriteLine(cell.StringValue)
Read and Write a Range of Cell Values
The Range
class represents a two-dimensional collection of Cell
objects. This collection refers to a literal range of Excel cells. Obtain ranges by using the string indexer on a WorkSheet
object.
The argument text is either the coordinate of a cell (e.g. "A1", as shown previously) or a span of cells from left to right top to bottom (e.g. "B2:E5"). It is also possible to call GetRange
on a WorkSheet
.
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-6.cs
Range range = workSheet["D2:D101"];
Dim range As Range = workSheet("D2:D101")
Sample: DataValidation
There are several ways to read or edit the values of cells within a Range. If the count is known, use a For loop.
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-7.cs
// Iterate through the rows
for (var y = 2; y <= 101; y++)
{
var result = new PersonValidationResult { Row = y };
results.Add(result);
// Get all cells for the person
var cells = workSheet[$"A{y}:E{y}"].ToList();
// Validate the phone number (1 = B)
var phoneNumber = cells[1].Value;
result.PhoneNumberErrorMessage = ValidatePhoneNumber(phoneNumberUtil, (string)phoneNumber);
// Validate the email address (3 = D)
result.EmailErrorMessage = ValidateEmailAddress((string)cells[3].Value);
// Get the raw date in the format of Month Day[suffix], Year (4 = E)
var rawDate = (string)cells[4].Value;
result.DateErrorMessage = ValidateDate(rawDate);
}
' Iterate through the rows
For y = 2 To 101
Dim result = New PersonValidationResult With {.Row = y}
results.Add(result)
' Get all cells for the person
Dim cells = workSheet($"A{y}:E{y}").ToList()
' Validate the phone number (1 = B)
Dim phoneNumber = cells(1).Value
result.PhoneNumberErrorMessage = ValidatePhoneNumber(phoneNumberUtil, CStr(phoneNumber))
' Validate the email address (3 = D)
result.EmailErrorMessage = ValidateEmailAddress(CStr(cells(3).Value))
' Get the raw date in the format of Month Day[suffix], Year (4 = E)
Dim rawDate = CStr(cells(4).Value)
result.DateErrorMessage = ValidateDate(rawDate)
Next y
Sample: DataValidation
Add Formula to a Spreadsheet
Set formula of Cell
s with the Formula
property.
The code below iterates through each state and puts a percentage total in column C.
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-13.cs
// Iterate through all rows with a value
for (var y = 2 ; y < i ; y++)
{
// Get the C cell
Cell cell = workSheet[$"C{y}"].First();
// Set the formula for the Percentage of Total column
cell.Formula = $"=B{y}/B{i}";
}
' Iterate through all rows with a value
Dim y = 2
Do While y < i
' Get the C cell
Dim cell As Cell = workSheet($"C{y}").First()
' Set the formula for the Percentage of Total column
cell.Formula = $"=B{y}/B{i}"
y += 1
Loop
Sample: AddFormulaeProcessor
Validate Spreadsheet Data
Use IronXL to validate a sheet of data. The DataValidation
sample uses libphonenumber-csharp
to validate phone numbers and uses standard C# APIs to validate email addresses and dates.
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-8.cs
// Iterate through the rows
for (var i = 2; i <= 101; i++)
{
var result = new PersonValidationResult { Row = i };
results.Add(result);
// Get all cells for the person
var cells = worksheet[$"A{i}:E{i}"].ToList();
// Validate the phone number (1 = B)
var phoneNumber = cells[1].Value;
result.PhoneNumberErrorMessage = ValidatePhoneNumber(phoneNumberUtil, (string)phoneNumber);
// Validate the email address (3 = D)
result.EmailErrorMessage = ValidateEmailAddress((string)cells[3].Value);
// Get the raw date in the format of Month Day[suffix], Year (4 = E)
var rawDate = (string)cells[4].Value;
result.DateErrorMessage = ValidateDate(rawDate);
}
' Iterate through the rows
For i = 2 To 101
Dim result = New PersonValidationResult With {.Row = i}
results.Add(result)
' Get all cells for the person
Dim cells = worksheet($"A{i}:E{i}").ToList()
' Validate the phone number (1 = B)
Dim phoneNumber = cells(1).Value
result.PhoneNumberErrorMessage = ValidatePhoneNumber(phoneNumberUtil, CStr(phoneNumber))
' Validate the email address (3 = D)
result.EmailErrorMessage = ValidateEmailAddress(CStr(cells(3).Value))
' Get the raw date in the format of Month Day[suffix], Year (4 = E)
Dim rawDate = CStr(cells(4).Value)
result.DateErrorMessage = ValidateDate(rawDate)
Next i
The above code loops through each row in the spreadsheet and grabs the cells as a list. Each validates method checks the value of a cell and returns an error message if the value is invalid.
This code creates a new sheet, specifies headers, and outputs the error message results so that there is a log of invalid data.
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-9.cs
var resultsSheet = workBook.CreateWorkSheet("Results");
resultsSheet["A1"].Value = "Row";
resultsSheet["B1"].Value = "Valid";
resultsSheet["C1"].Value = "Phone Error";
resultsSheet["D1"].Value = "Email Error";
resultsSheet["E1"].Value = "Date Error";
for (var i = 0; i < results.Count; i++)
{
var result = results[i];
resultsSheet[$"A{i + 2}"].Value = result.Row;
resultsSheet[$"B{i + 2}"].Value = result.IsValid ? "Yes" : "No";
resultsSheet[$"C{i + 2}"].Value = result.PhoneNumberErrorMessage;
resultsSheet[$"D{i + 2}"].Value = result.EmailErrorMessage;
resultsSheet[$"E{i + 2}"].Value = result.DateErrorMessage;
}
workBook.SaveAs(@"Spreadsheets\\PeopleValidated.xlsx");
Dim resultsSheet = workBook.CreateWorkSheet("Results")
resultsSheet("A1").Value = "Row"
resultsSheet("B1").Value = "Valid"
resultsSheet("C1").Value = "Phone Error"
resultsSheet("D1").Value = "Email Error"
resultsSheet("E1").Value = "Date Error"
For i = 0 To results.Count - 1
Dim result = results(i)
resultsSheet($"A{i + 2}").Value = result.Row
resultsSheet($"B{i + 2}").Value = If(result.IsValid, "Yes", "No")
resultsSheet($"C{i + 2}").Value = result.PhoneNumberErrorMessage
resultsSheet($"D{i + 2}").Value = result.EmailErrorMessage
resultsSheet($"E{i + 2}").Value = result.DateErrorMessage
Next i
workBook.SaveAs("Spreadsheets\\PeopleValidated.xlsx")
4. Export Data using Entity Framework
Use IronXL to export data to a database or convert an Excel spreadsheet to a database. The ExcelToDB
sample reads a spreadsheet with GDP by country and then exports that data to an SQLite.
It uses EntityFramework
to build the database and then export the data line by line.
Add the SQLite Entity Framework NuGet packages.
EntityFramework
allows you to create a model object that can export data to the database.
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-10.cs
public class Country
{
[Key]
public Guid Key { get; set; }
public string Name { get; set; }
public decimal GDP { get; set; }
}
Public Class Country
<Key>
Public Property Key() As Guid
Public Property Name() As String
Public Property GDP() As Decimal
End Class
To use a different database, install the corresponding NuGet package and find the equivalent of UseSqLite()
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-11.cs
public class CountryContext : DbContext
{
public DbSet<Country> Countries { get; set; }
public CountryContext()
{
//TODO: Make async
Database.EnsureCreated();
}
/// <summary>
/// Configure context to use Sqlite
/// </summary>
/// <param name="optionsBuilder"></param>
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
var connection = new SqliteConnection($"Data Source=Country.db");
connection.Open();
var command = connection.CreateCommand();
//Create the database if it doesn't already exist
command.CommandText = $"PRAGMA foreign_keys = ON;";
command.ExecuteNonQuery();
optionsBuilder.UseSqlite(connection);
base.OnConfiguring(optionsBuilder);
}
}
Public Class CountryContext
Inherits DbContext
Public Property Countries() As DbSet(Of Country)
Public Sub New()
'TODO: Make async
Database.EnsureCreated()
End Sub
''' <summary>
''' Configure context to use Sqlite
''' </summary>
''' <param name="optionsBuilder"></param>
Protected Overrides Sub OnConfiguring(ByVal optionsBuilder As DbContextOptionsBuilder)
Dim connection = New SqliteConnection($"Data Source=Country.db")
connection.Open()
Dim command = connection.CreateCommand()
'Create the database if it doesn't already exist
command.CommandText = $"PRAGMA foreign_keys = ON;"
command.ExecuteNonQuery()
optionsBuilder.UseSqlite(connection)
MyBase.OnConfiguring(optionsBuilder)
End Sub
End Class
Create a CountryContext
, iterate through the range to create each record, and then SaveAsync
to commit data to the database
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-12.cs
public async Task ProcessAsync()
{
//Get the first worksheet
var workbook = WorkBook.Load(@"Spreadsheets\\GDP.xlsx");
var worksheet = workbook.GetWorkSheet("GDPByCountry");
//Create the database connection
using (var countryContext = new CountryContext())
{
//Iterate through all the cells
for (var i = 2; i <= 213; i++)
{
//Get the range from A-B
var range = worksheet[$"A{i}:B{i}"].ToList();
//Create a Country entity to be saved to the database
var country = new Country
{
Name = (string)range[0].Value,
GDP = (decimal)(double)range[1].Value
};
//Add the entity
await countryContext.Countries.AddAsync(country);
}
//Commit changes to the database
await countryContext.SaveChangesAsync();
}
}
Public Async Function ProcessAsync() As Task
'Get the first worksheet
Dim workbook = WorkBook.Load("Spreadsheets\\GDP.xlsx")
Dim worksheet = workbook.GetWorkSheet("GDPByCountry")
'Create the database connection
Using countryContext As New CountryContext()
'Iterate through all the cells
For i = 2 To 213
'Get the range from A-B
Dim range = worksheet($"A{i}:B{i}").ToList()
'Create a Country entity to be saved to the database
Dim country As New Country With {
.Name = CStr(range(0).Value),
.GDP = CDec(CDbl(range(1).Value))
}
'Add the entity
Await countryContext.Countries.AddAsync(country)
Next i
'Commit changes to the database
Await countryContext.SaveChangesAsync()
End Using
End Function
Sample: ExcelToDB
5. Download Data from an API to Spreadsheet
The following call makes a REST call with RestClient.Net. It downloads JSON and converts it into a "List" of the type RestCountry
. It is then easy to iterate through each country and save the data from the REST API to an Excel spreadsheet.
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-14.cs
var client = new Client(new Uri("https://restcountries.eu/rest/v2/"));
List<RestCountry> countries = await client.GetAsync<List<RestCountry>>();
Dim client As New Client(New Uri("https://restcountries.eu/rest/v2/"))
Dim countries As List(Of RestCountry) = Await client.GetAsync(Of List(Of RestCountry))()
Sample: ApiToExcel
This is what the API JSON data looks like.
The following code iterates through the countries and sets the Name, Population, Region, NumericCode, and Top 3 Languages in the spreadsheet.
:path=/static-assets/excel/content-code-examples/tutorials/how-to-read-excel-file-csharp-15.cs
for (var i = 2; i < countries.Count; i++)
{
var country = countries[i];
//Set the basic values
workSheet[$"A{i}"].Value = country.name;
workSheet[$"B{i}"].Value = country.population;
workSheet[$"G{i}"].Value = country.region;
workSheet[$"H{i}"].Value = country.numericCode;
//Iterate through languages
for (var x = 0; x < 3; x++)
{
if (x > (country.languages.Count - 1)) break;
var language = country.languages[x];
//Get the letter for the column
var columnLetter = GetColumnLetter(4 + x);
//Set the language name
workSheet[$"{columnLetter}{i}"].Value = language.name;
}
}
For i = 2 To countries.Count - 1
Dim country = countries(i)
'Set the basic values
workSheet($"A{i}").Value = country.name
workSheet($"B{i}").Value = country.population
workSheet($"G{i}").Value = country.region
workSheet($"H{i}").Value = country.numericCode
'Iterate through languages
For x = 0 To 2
If x > (country.languages.Count - 1) Then
Exit For
End If
Dim language = country.languages(x)
'Get the letter for the column
Dim columnLetter = GetColumnLetter(4 + x)
'Set the language name
workSheet($"{columnLetter}{i}").Value = language.name
Next x
Next i
Object Reference and Resources
You may also find the IronXL class documentation within the Object Reference of great value.
In addition, there are other tutorials which may shed light in other aspects of IronXL.Excel
including Creating, Opening, Writing, Editing, Saving and Exporting XLS, XLSX and CSV files without using Excel Interop.
Summary
IronXL.Excel is alone .NET software library for reading a wide variety of spreadsheet formats. It does not require Microsoft Excel to be installed, and is not dependant on Interop.
If you're finding the .NET library useful for modifying Excel files, you might also be interested in exploring Google Sheets API Client Library for .NET that allows you to modify Google Sheets.
Tutorial Quick Access
Download this Tutorial as C# Source Code
The full free C# for Excel Source Code for this tutorial is available to download as a zipped Visual Studio 2017 project file.
DownloadExplore this Tutorial on GitHub
The source code for this project is available in C# and VB.NET on GitHub.
Use this code as an easy way to get up and running in just a few minutes. The project is saved as a Microsoft Visual Studio 2017 project, but is compatible with any .NET IDE.
How to Read Excel File in C# on GitHubView the API Reference
Explore the API Reference for IronXL, outlining the details of all of IronXL’s features, namespaces, classes, methods fields and enums.
View the API Reference