Melhor maneira de ler arquivos do Excel em C# | Guia passo a passo da IronXL

Qual é a melhor maneira de ler arquivos Excel em C#?

A melhor abordagem é usar uma biblioteca dedicada, independente do Office, como o IronXL. Métodos tradicionais como Microsoft.Office.Interop.Excel funcionam em máquinas onde o Excel está instalado, mas são frágeis em ambientes de servidor ou container porque iniciam um processo COM nos bastidores. O SDK OpenXML é gratuito e seguro para servidores, mas expõe um modelo XML de baixo nível que requer muita codificação para tarefas cotidianas.

O IronXL se posiciona entre esses extremos. A API espelha como os desenvolvedores já pensam sobre planilhas -- workbooks contêm planilhas, planilhas contêm células, e células mantêm valores digitados. A biblioteca lida com a detecção de formato, avaliação de fórmulas e codificação internamente, então você se concentra na lógica de negócios em vez de detalhes de análise.

A documentação de leitura do Excel do IronXL cobre toda a superfície da API. Por enquanto, as seções abaixo mostram os padrões principais que você usará em cada projeto.

Como instalar o IronXL em um projeto .NET?

A instalação leva menos de um minuto usando o Gerenciador de Pacotes NuGet. Abra um terminal no diretório do seu projeto e execute:

dotnet add package IronXl.Excel

dotnet add package IronXl.Excel

Alternativamente, utilize o Console do Gerenciador de Pacotes do Visual Studio:

Install-Package IronXl.Excel

Install-Package IronXl.Excel

Após a instalação, adicione a diretiva using IronXL; a qualquer arquivo que necessite de acesso a planilhas. A biblioteca é compatível com .NET 10, .NET 8, .NET 6, .NET Framework 4.6.2 e .NET Standard 2.0, portanto, se encaixa em projetos existentes sem a necessidade de atualizar o runtime. Veja o guia de instalação do IronXL para notas específicas de plataforma e detalhes do pacote NuGet.

Não são necessários componentes de runtime adicionais, entradas no registro ou licenças do Office. O pacote NuGet inclui tudo que a biblioteca precisa.

Como Carregar e Ler um Workbook do Excel?

Carregar um workbook requer uma única chamada de método. WorkBook.Load aceita um caminho de arquivo e retorna um objeto WorkBook que representa o arquivo inteiro na memória.

using IronXL;

// Load any supported format -- XLSX, XLS, or CSV
WorkBook workbook = WorkBook.Load("financial_report.xlsx");

// Access the first worksheet by position
WorkSheet worksheet = workbook.WorkSheets[0];

// Or retrieve a named worksheet
WorkSheet expenses = workbook.GetWorkSheet("Expenses");

Console.WriteLine($"Sheets loaded: {workbook.WorkSheets.Count}");
Console.WriteLine($"Default sheet rows: {worksheet.RowCount}");

using IronXL;

// Load any supported format -- XLSX, XLS, or CSV
WorkBook workbook = WorkBook.Load("financial_report.xlsx");

// Access the first worksheet by position
WorkSheet worksheet = workbook.WorkSheets[0];

// Or retrieve a named worksheet
WorkSheet expenses = workbook.GetWorkSheet("Expenses");

Console.WriteLine($"Sheets loaded: {workbook.WorkSheets.Count}");
Console.WriteLine($"Default sheet rows: {worksheet.RowCount}");

O objeto WorkBook mantém todos os dados da planilha acessíveis. Cada instância WorkSheet mapeia para uma aba no arquivo. Acessar por índice (WorkSheets[0]) é confiável para arquivos de uma única planilha; acessar pelo nome é mais seguro quando o arquivo contém múltiplas abas com nomes conhecidos.

O IronXL avalia fórmulas automaticamente quando você lê uma célula. Se a célula B10 contiver =SUM(B2:B9), ler sheet["B10"].DecimalValue retorna o total calculado, não a string da fórmula. Para mais detalhes sobre opções de carregamento de workbook, veja o guia de como carregar planilhas.

Como Ler Valores de Célula de uma Planilha?

O IronXL fornece propriedades fortemente tipadas em cada célula, para que você possa ler valores diretamente no tipo .NET correto sem parsing manual.

using IronXL;

WorkBook workbook = WorkBook.Load("Products.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Address-based access with typed properties
string productName = sheet["A2"].StringValue;
int quantity       = sheet["B2"].IntValue;
decimal price      = sheet["C2"].DecimalValue;
bool inStock       = sheet["D2"].BoolValue;

// Check for empty cells before processing
var statusCell = sheet["E2"];
if (statusCell.Value != null && statusCell.StringValue.Length > 0)
{
    Console.WriteLine($"Status: {statusCell.StringValue}");
}

// Row/column index access (zero-based)
var firstDataCell = sheet.Rows[1].Columns[0];
Console.WriteLine($"Product: {productName}, Qty: {quantity}, Price: {price:C}");

using IronXL;

WorkBook workbook = WorkBook.Load("Products.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Address-based access with typed properties
string productName = sheet["A2"].StringValue;
int quantity       = sheet["B2"].IntValue;
decimal price      = sheet["C2"].DecimalValue;
bool inStock       = sheet["D2"].BoolValue;

// Check for empty cells before processing
var statusCell = sheet["E2"];
if (statusCell.Value != null && statusCell.StringValue.Length > 0)
{
    Console.WriteLine($"Status: {statusCell.StringValue}");
}

// Row/column index access (zero-based)
var firstDataCell = sheet.Rows[1].Columns[0];
Console.WriteLine($"Product: {productName}, Qty: {quantity}, Price: {price:C}");

A sintaxe sheet["A2"] usa notação padrão do Excel. Letras de coluna não diferenciam maiúsculas de minúsculas, e números de linha começam em 1, coincidindo com a forma como o Excel rotula células. A documentação de leitura de valor de célula mostra accessorios digitados adicionais, incluindo DateTimeValue para células formatadas como datas.

Quando uma célula contém um número armazenado como texto (um problema comum de qualidade de dados em planilhas exportadas), StringValue retorna o texto como está, enquanto DecimalValue tenta uma análise e retorna 0 em caso de falha. Sempre valide dados inesperados antes de tratá-los como um valor digitado no código de produção.

Como Iterar Através de Linhas e Células?

Iterar através de um conjunto de dados requer um intervalo ou uma coleção de linhas. O IronXL suporta ambas as abordagens, e você pode combiná-las para corresponder ao formato dos dados.

using IronXL;

WorkBook workbook = WorkBook.Load("financial_report.xlsx");
WorkSheet sheet = workbook.WorkSheets[0];

// Iterate a cell range -- skips header row
foreach (var cell in sheet["A2:D100"])
{
    Console.WriteLine($"{cell.AddressString}: {cell.Text}");
}

// Row-by-row with column access
for (int rowIndex = 1; rowIndex < sheet.RowCount; rowIndex++)
{
    var row = sheet.Rows[rowIndex];
    var values = new System.Text.StringBuilder();

    foreach (var cell in row)
    {
        if (cell.Value != null)
            values.Append($"{cell.StringValue}\t");
    }

    Console.WriteLine(values.ToString().TrimEnd());
}

using IronXL;

WorkBook workbook = WorkBook.Load("financial_report.xlsx");
WorkSheet sheet = workbook.WorkSheets[0];

// Iterate a cell range -- skips header row
foreach (var cell in sheet["A2:D100"])
{
    Console.WriteLine($"{cell.AddressString}: {cell.Text}");
}

// Row-by-row with column access
for (int rowIndex = 1; rowIndex < sheet.RowCount; rowIndex++)
{
    var row = sheet.Rows[rowIndex];
    var values = new System.Text.StringBuilder();

    foreach (var cell in row)
    {
        if (cell.Value != null)
            values.Append($"{cell.StringValue}\t");
    }

    Console.WriteLine(values.ToString().TrimEnd());
}

A string de intervalo "A2:D100" cria uma coleção de células plana. Linhas dentro do intervalo são processadas de cima para baixo, da esquerda para a direita. Este padrão funciona bem para exportação para um List<t>, um DataTable ou um banco de dados.

A propriedade sheet.RowCount reflete a última linha usada na planilha, então o laço termina automaticamente quando os dados terminam. O guia de iteração de intervalo Excel cobre padrões de iteração adicionais, incluindo travessia por coluna.

Como Você Lida com Múltiplos Formatos Excel?

O IronXL detecta o formato do arquivo a partir da extensão e cabeçalho do arquivo automaticamente. A API é idêntica para arquivos XLSX, XLS e CSV, o que significa que o mesmo código de análise funciona em todos os três formatos sem lógica condicional.

using IronXL;

// Load different formats with identical API
WorkBook xlsxBook = WorkBook.Load("Modern.xlsx");
WorkBook xlsBook  = WorkBook.Load("Legacy.xls");
WorkBook csvBook  = WorkBook.Load("Export.csv");

// Access worksheets identically across formats
WorkSheet sheet1 = xlsxBook.DefaultWorkSheet;
WorkSheet sheet2 = xlsBook.DefaultWorkSheet;
WorkSheet sheet3 = csvBook.DefaultWorkSheet;

// Cross-format conversion -- save XLSX as CSV, or CSV as XLSX
xlsxBook.SaveAs("converted_output.csv");
csvBook.SaveAs("structured_output.xlsx");

Console.WriteLine($"XLSX rows: {sheet1.RowCount}");
Console.WriteLine($"XLS rows:  {sheet2.RowCount}");
Console.WriteLine($"CSV rows:  {sheet3.RowCount}");

using IronXL;

// Load different formats with identical API
WorkBook xlsxBook = WorkBook.Load("Modern.xlsx");
WorkBook xlsBook  = WorkBook.Load("Legacy.xls");
WorkBook csvBook  = WorkBook.Load("Export.csv");

// Access worksheets identically across formats
WorkSheet sheet1 = xlsxBook.DefaultWorkSheet;
WorkSheet sheet2 = xlsBook.DefaultWorkSheet;
WorkSheet sheet3 = csvBook.DefaultWorkSheet;

// Cross-format conversion -- save XLSX as CSV, or CSV as XLSX
xlsxBook.SaveAs("converted_output.csv");
csvBook.SaveAs("structured_output.xlsx");

Console.WriteLine($"XLSX rows: {sheet1.RowCount}");
Console.WriteLine($"XLS rows:  {sheet2.RowCount}");
Console.WriteLine($"CSV rows:  {sheet3.RowCount}");

Para arquivos CSV, o IronXL respeita as convenções RFC 4180, incluindo campos entre aspas que contêm vírgulas, novas linhas dentro de valores entre aspas e aspas duplas escapadas. O guia de conversão de CSV para XLSX cobre a customização de delimitadores para exportações CSV fora do padrão.

Quando sua aplicação deve aceitar arquivos de sistemas externos, é uma boa prática inspecionar a extensão do arquivo e validar o conteúdo antes de carregá-lo. O IronXL lança uma exceção descritiva se o arquivo estiver corrompido ou em um formato não suportado, o que você pode capturar e informar ao usuário.

Como Você Executa Consultas Avançadas em Dados Excel?

Além da leitura célula a célula, o IronXL expõe funções agregadas e compatibilidade com LINQ que transformam um intervalo de planilha em uma coleção consultável.

using IronXL;
using System.Linq;

WorkBook workbook = WorkBook.Load("Financials.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Built-in aggregates -- no manual looping needed
decimal totalSales = sheet["B2:B50"].Sum();
decimal maxRevenue = sheet["C2:C50"].Max(c => c.DecimalValue);
decimal avgMargin  = sheet["D2:D50"].Avg();

// LINQ filtering directly on a range
var highValueRows = sheet["C2:C50"]
    .Where(c => c.DecimalValue > 1000)
    .Select(c => new { c.AddressString, c.DecimalValue });

foreach (var row in highValueRows)
    Console.WriteLine($"Alto value at {row.AddressString}: {row.DecimalValue:C}");

// Write a calculated result back to the sheet
sheet["E2"].Value = totalSales;
workbook.SaveAs("Financials_Updated.xlsx");

Console.WriteLine($"Total: {totalSales:C}, Max: {maxRevenue:C}, Avg: {avgMargin:C}");

using IronXL;
using System.Linq;

WorkBook workbook = WorkBook.Load("Financials.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Built-in aggregates -- no manual looping needed
decimal totalSales = sheet["B2:B50"].Sum();
decimal maxRevenue = sheet["C2:C50"].Max(c => c.DecimalValue);
decimal avgMargin  = sheet["D2:D50"].Avg();

// LINQ filtering directly on a range
var highValueRows = sheet["C2:C50"]
    .Where(c => c.DecimalValue > 1000)
    .Select(c => new { c.AddressString, c.DecimalValue });

foreach (var row in highValueRows)
    Console.WriteLine($"Alto value at {row.AddressString}: {row.DecimalValue:C}");

// Write a calculated result back to the sheet
sheet["E2"].Value = totalSales;
workbook.SaveAs("Financials_Updated.xlsx");

Console.WriteLine($"Total: {totalSales:C}, Max: {maxRevenue:C}, Avg: {avgMargin:C}");

A compatibilidade com LINQ é útil quando você precisa filtrar linhas antes de importá-las para um banco de dados ou validar que todos os valores em uma coluna atingem um limite. A biblioteca avalia fórmulas antes de o LINQ ser executado, então consultas agregadas sempre operam sobre os valores finais computados em vez de strings de fórmulas.

O tutorial sobre LINQ com IronXL cobre junção de planilhas, agrupamento por coluna e projeção de resultados em objetos fortemente tipados -- padrões que eliminam muito código repetitivo em pipelines de dados.

Como Você Exporta Dados Excel para um DataTable?

Muitas aplicações .NET carregam dados de planilhas em um ADO.NET DataTable para processamento posterior ou inserção no banco de dados. O IronXL fornece um método de conversão direta que elimina a necessidade de mapeamento manual de colunas.

using IronXL;
using System.Data;

WorkBook workbook = WorkBook.Load("SalesData.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Convert worksheet to DataTable -- first row becomes column headers
DataTable dataTable = sheet.ToDataTable(true);

Console.WriteLine($"Columns: {dataTable.Columns.Count}");
Console.WriteLine($"Rows:    {dataTable.Rows.Count}");

// Iterate the DataTable normally
foreach (DataRow row in dataTable.Rows)
{
    Console.WriteLine($"{row["ProductName"]} -- {row["Quantity"]} -- {row["Price"]}");
}

using IronXL;
using System.Data;

WorkBook workbook = WorkBook.Load("SalesData.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Convert worksheet to DataTable -- first row becomes column headers
DataTable dataTable = sheet.ToDataTable(true);

Console.WriteLine($"Columns: {dataTable.Columns.Count}");
Console.WriteLine($"Rows:    {dataTable.Rows.Count}");

// Iterate the DataTable normally
foreach (DataRow row in dataTable.Rows)
{
    Console.WriteLine($"{row["ProductName"]} -- {row["Quantity"]} -- {row["Price"]}");
}

Passar true para ToDataTable trata a primeira linha da planilha como cabeçalhos de coluna. O DataTable resultante usa nomes de colunas como string que correspondem ao texto do cabeçalho, tornando as consultas LINQ-to-DataSet subsequentes legíveis. A documentação de exportação para DataTable cobre opções de tratamento de nulos e inferência de tipos.

Este padrão é particularmente útil quando o código a jusante já espera um DataTable -- por exemplo, ao chamar SqlBulkCopy para inserir linhas no SQL Server. Você pode carregar o arquivo XLSX, convertê-lo em um DataTable e inserir em massa sem escrever nenhum boilerplate de mapeamento de coluna.

Para uma lista completa da API, consulte a referência da API IronXL. A referência cobre todas as propriedades e métodos com descrições de parâmetros e detalhes do tipo de retorno.

Quais são os seus próximos passos?

Ler arquivos Excel em C# é simples uma vez que você tem a biblioteca certa. O IronXL remove a dependência do Office, simplifica a superfície da API e lida com formatos XLSX, XLS e CSV com o mesmo caminho de código. Os padrões cobertos aqui -- carregamento de um workbook, leitura de valores de células tipadas, iteração de intervalos, execução de agregações e exportação para um DataTable -- cobrem a maioria das necessidades reais de leitura de planilhas.

Para continuar desenvolvendo esses padrões:

• Leia a documentação de introdução do IronXL para orientação sobre configuração de projeto e requisitos de tempo de execução.
• Explore os guias de como fazer para escrita, formatação e geração de gráficos.
• Revise o guia de suporte a fórmulas do Excel para entender quais funções do Excel o IronXL avalia automaticamente.
• Verifique a página de licenciamento do IronXL para opções de implantação em produção.
• Navegue pelo blog do IronXL para exemplos que cobrem validação de dados, exportações de tabelas dinâmicas e manuseio de arquivos protegidos por senha.

Para equipes que estão avaliando o IronXL em comparação com outras bibliotecas, a comparação IronXL vs EPPlus e a comparação IronXL vs NPOI cobrem benchmarks de desempenho e diferenças de API. Ambas as comparações incluem exemplos de código para operações equivalentes em cada biblioteca.

A própria especificação de formato de arquivo Excel da Microsoft é uma referência útil se você encontrar estruturas de planilhas incomuns de sistemas legados. O padrão ECMA-376 define o formato OOXML que os arquivos XLSX seguem.

Comece com uma licença de teste gratuita do IronXL para testar a API completa em seu próprio projeto antes de se comprometer com uma licença de produção.