Como ler arquivos do Excel em C# usando o IronXL

Como você instala o IronXL para processamento de Excel?

Abra o Console do Gerenciador de Pacotes NuGet no Visual Studio e execute o seguinte comando para adicionar o IronXL ao seu projeto. Alternativamente, se você preferir trabalhar a partir de um terminal, use o comando .NET CLI mostrado na segunda linha:

Install-Package IronXl.Excel
dotnet add package IronXl.Excel

Install-Package IronXl.Excel
dotnet add package IronXl.Excel

O pacote instala em segundos e adiciona uma referência de assembly gerenciado único ao seu projeto. Sem registro COM, sem Assemblies de Interoperabilidade Primária do Office, e sem dependências específicas de versão do Excel para gerenciar.

Após a instalação, adicione a diretiva 'using' no topo de cada arquivo que trabalha com dados de planilha:

using IronXL;

using IronXL;

Esse único namespace dá acesso a WorkBook, WorkSheet, intervalos de células, propriedades de valor tipadas, funções agregadas e todo outro tipo de IronXL. A página da Galeria NuGet para IronXl.Excel lista cada versão disponível e sua árvore completa de dependências.

Quais formatos de arquivo Excel o IronXL suporta?

Entender os formatos que sua aplicação deve lidar molda tanto as chamadas de API que você faz como as decisões de armazenamento que seu projeto adota.

XLSX -- o formato padrão desde o Excel 2007 -- é um arquivo ZIP de arquivos XML. Ele suporta mais de um milhão de linhas, formatação rica, tabelas dinâmicas e intervalos nomeados. A maioria dos pipelines de dados modernos produz saída em XLSX, então esse é o formato que você encontra com mais frequência.

XLS é o formato binário legado usado pelo Excel 2003 e anteriores. Alguns sistemas empresariais ainda exportam XLS, então o suporte confiável para esse formato é importante ao integrar com infraestrutura mais antiga. IronXL lê arquivos XLS sem qualquer configuração especial da sua parte.

XLSM estende o XLSX com suporte a macro. IronXL lê os dados da planilha de arquivos XLSM mesmo que não execute o código VBA incorporado, o que é o comportamento correto para extração de dados no lado do servidor.

CSV e TSV são formatos tabulares em texto simples amplamente usados para troca de dados entre sistemas. WorkBook.LoadCSV lida com arquivos separados por vírgulas, e IronXL retorna o mesmo objeto WorkBook que seu código já sabe como navegar, mantendo sua lógica de leitura de dados uniforme independentemente do formato da fonte.

IronXL detecta automaticamente o formato do arquivo a partir da extensão quando você chama WorkBook.Load. Você não precisa especificar o formato explicitamente na maioria dos casos, o que simplifica o código que deve lidar com entradas provenientes de múltiplas fontes.

Como Carregar e Ler um Workbook do Excel?

O método WorkBook.Load é o ponto de entrada para todas as operações baseadas em arquivos. Passe o caminho do arquivo e IronXL retorna um objeto de planilha totalmente preenchido que você pode consultar imediatamente:

using IronXL;

// Load the workbook; format is detected automatically
WorkBook workbook = WorkBook.Load("Employees.xlsx");

// Access the first worksheet
WorkSheet sheet = workbook.DefaultWorkSheet;

// Read a single cell by A1 address
string companyName = sheet["A1"].StringValue;
Console.WriteLine($"Company: {companyName}");

// Access sheets by name or by zero-based index
WorkSheet byName  = workbook.GetWorkSheet("Sales");
WorkSheet byIndex = workbook.WorkSheets[1];

// Load a password-protected file
WorkBook secured = WorkBook.Load("Confidential.xlsx", "p@ssw0rd");

using IronXL;

// Load the workbook; format is detected automatically
WorkBook workbook = WorkBook.Load("Employees.xlsx");

// Access the first worksheet
WorkSheet sheet = workbook.DefaultWorkSheet;

// Read a single cell by A1 address
string companyName = sheet["A1"].StringValue;
Console.WriteLine($"Company: {companyName}");

// Access sheets by name or by zero-based index
WorkSheet byName  = workbook.GetWorkSheet("Sales");
WorkSheet byIndex = workbook.WorkSheets[1];

// Load a password-protected file
WorkBook secured = WorkBook.Load("Confidential.xlsx", "p@ssw0rd");

A propriedade DefaultWorkSheet retorna a primeira planilha, cobrindo a maioria dos arquivos de uma única planilha. Quando o seu arquivo contém várias planilhas, GetWorkSheet recupera por nome e WorkSheets[n] recupera por índice baseado em zero. O referência API WorkBook documenta todas as sobrecargas e propriedades no objeto workbook.

Como Você Lê Valores de Células Tipadas do Excel?

Cada célula no IronXL expõe propriedades tipadas que retornam valores exatamente no tipo de dado que você precisa -- sem necessidade de análise ou conversão manual. As propriedades tipadas lidam com a coerção da representação da célula subjacente automaticamente:

using IronXL;

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

// Extract typed values from row 2
int      employeeId = sheet["A2"].IntValue;
string   name       = sheet["B2"].StringValue;
string   department = sheet["C2"].StringValue;
decimal  salary     = sheet["D2"].DecimalValue;
DateTime hireDate   = sheet["E2"].DateTimeValue;

Console.WriteLine($"ID:         {employeeId}");
Console.WriteLine($"Name:       {name}");
Console.WriteLine($"Department: {department}");
Console.WriteLine($"Salary:     {salary:C}");
Console.WriteLine($"Hired:      {hireDate:d}");

// Use the Text property for the formatted display value
string formattedSalary = sheet["D2"].Text;   // "$75,000.00"
string formattedDate   = sheet["E2"].Text;   // "28/02/2026"

// Guard against empty cells before reading
if (!sheet["B3"].IsEmpty)
{
    string value = sheet["B3"].StringValue;
}

using IronXL;

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

// Extract typed values from row 2
int      employeeId = sheet["A2"].IntValue;
string   name       = sheet["B2"].StringValue;
string   department = sheet["C2"].StringValue;
decimal  salary     = sheet["D2"].DecimalValue;
DateTime hireDate   = sheet["E2"].DateTimeValue;

Console.WriteLine($"ID:         {employeeId}");
Console.WriteLine($"Name:       {name}");
Console.WriteLine($"Department: {department}");
Console.WriteLine($"Salary:     {salary:C}");
Console.WriteLine($"Hired:      {hireDate:d}");

// Use the Text property for the formatted display value
string formattedSalary = sheet["D2"].Text;   // "$75,000.00"
string formattedDate   = sheet["E2"].Text;   // "28/02/2026"

// Guard against empty cells before reading
if (!sheet["B3"].IsEmpty)
{
    string value = sheet["B3"].StringValue;
}

A propriedade Text retorna o valor de exibição exatamente como formatado no Excel -- útil quando você precisa da cadeia numérica formatada em vez do número bruto. Para células que contêm fórmulas Excel, IronXL avalia a expressão e retorna o resultado computado através das mesmas propriedades tipadas. Propriedades de valor adicionais -- BoolValue, DoubleValue, FloatValue -- aparecem na referência de valor de célula.

Como Você Itera Através de Linhas e Colunas do Excel?

Processar cada registro em um conjunto de dados exige iterar pelas linhas e colunas. A sintaxe de intervalo do IronXL mapeia diretamente para a notação A1 do Excel, então selecionar um bloco de células é familiar para qualquer pessoa que já tenha escrito fórmulas de planilha:

using IronXL;

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

// Iterate a single column range
Console.WriteLine("Employee List:");
foreach (var cell in sheet["B2:B100"])
{
    if (!string.IsNullOrEmpty(cell.Text))
        Console.WriteLine($"  - {cell.Text}");
}

// Iterate all rows and all columns using the Rows property
foreach (var row in sheet.Rows)
{
    foreach (var cell in row)
        Console.Write(cell.Text.PadRight(15));
    Console.WriteLine();
}

using IronXL;

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

// Iterate a single column range
Console.WriteLine("Employee List:");
foreach (var cell in sheet["B2:B100"])
{
    if (!string.IsNullOrEmpty(cell.Text))
        Console.WriteLine($"  - {cell.Text}");
}

// Iterate all rows and all columns using the Rows property
foreach (var row in sheet.Rows)
{
    foreach (var cell in row)
        Console.Write(cell.Text.PadRight(15));
    Console.WriteLine();
}

O intervalo sheet["B2:B100"] retorna uma coleção enumerável de objetos de célula. Verificando string.IsNullOrEmpty pular linhas em branco de forma elegante. A propriedade Rows -- documentada no guia de intervalo de dados da planilha -- percorre a planilha uma linha por vez e expõe as células de cada linha sem exigir que você saiba o número de colunas com antecedência.

Como Você Executa Cálculos Agregados em Dados do Excel?

O IronXL inclui funções agregadas embutidas que calculam resultados diretamente em intervalos de células -- sem necessidade de loops de acumulação manual:

using IronXL;

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

// Built-in aggregate methods work on any named range
decimal total   = sheet["D2:D200"].Sum();
decimal highest = sheet["D2:D200"].Max();
decimal lowest  = sheet["D2:D200"].Min();
decimal average = sheet["D2:D200"].Avg();

Console.WriteLine($"Total Payroll:  {total:C}");
Console.WriteLine($"Highest Salary: {highest:C}");
Console.WriteLine($"Lowest Salary:  {lowest:C}");
Console.WriteLine($"Average Salary: {average:C}");

// Combine with LINQ for filtered aggregation
decimal itTotal = sheet["D2:D200"]
    .Where(c => sheet[$"C{c.RowIndex}"].StringValue == "IT")
    .Sum(c => c.DecimalValue);
Console.WriteLine($"IT Department Total: {itTotal:C}");

using IronXL;

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

// Built-in aggregate methods work on any named range
decimal total   = sheet["D2:D200"].Sum();
decimal highest = sheet["D2:D200"].Max();
decimal lowest  = sheet["D2:D200"].Min();
decimal average = sheet["D2:D200"].Avg();

Console.WriteLine($"Total Payroll:  {total:C}");
Console.WriteLine($"Highest Salary: {highest:C}");
Console.WriteLine($"Lowest Salary:  {lowest:C}");
Console.WriteLine($"Average Salary: {average:C}");

// Combine with LINQ for filtered aggregation
decimal itTotal = sheet["D2:D200"]
    .Where(c => sheet[$"C{c.RowIndex}"].StringValue == "IT")
    .Sum(c => c.DecimalValue);
Console.WriteLine($"IT Department Total: {itTotal:C}");

Sum, Min, Max, e Avg automaticamente pulam células vazias e lidam com a conversão numérica nos bastidores. Encadear consultas LINQ no intervalo fornece agregados filtrados -- subtotais de departamento, somas por intervalo de datas e contagens condicionais -- tudo sem sair da API do IronXL.

Como Você Constrói um Leitor de Dados de Funcionários Completo?

O exemplo a seguir reúne tudo o que foi abordado até agora em uma aplicação console pronta para produção que carrega uma planilha de funcionários, formata cada registro, acumula totais salariais, lida com retorno de escrita e captura erros de forma graciosa:

using IronXL;

try
{
    WorkBook workbook = WorkBook.Load("Employees.xlsx");
    WorkSheet sheet   = workbook.DefaultWorkSheet;

    Console.WriteLine("=== Employee Data Report ===\n");

    int     rowNumber     = 2;
    decimal totalSalary   = 0m;
    int     employeeCount = 0;

    while (!string.IsNullOrEmpty(sheet[$"A{rowNumber}"].StringValue))
    {
        int      id         = sheet[$"A{rowNumber}"].IntValue;
        string   name       = sheet[$"B{rowNumber}"].StringValue;
        string   department = sheet[$"C{rowNumber}"].StringValue;
        decimal  salary     = sheet[$"D{rowNumber}"].DecimalValue;

        Console.WriteLine($"{id,4}  {name,-20}  {department,-15}  {salary,10:C}");

        totalSalary   += salary;
        employeeCount += 1;
        rowNumber     += 1;
    }

    Console.WriteLine($"\nTotal Employees: {employeeCount}");
    Console.WriteLine($"Total Payroll:   {totalSalary:C}");

    // Write a new record back to the sheet and save
    sheet["A10"].Value = 1010;
    sheet["B10"].Value = "Jane Doe";
    sheet["C10"].Value = "Finance";
    sheet["D10"].Value = 75000;
    workbook.SaveAs("Employees-Updated.xlsx");
}
catch (Exception ex)
{
    Console.WriteLine($"Error reading Excel file: {ex.Message}");
}

using IronXL;

try
{
    WorkBook workbook = WorkBook.Load("Employees.xlsx");
    WorkSheet sheet   = workbook.DefaultWorkSheet;

    Console.WriteLine("=== Employee Data Report ===\n");

    int     rowNumber     = 2;
    decimal totalSalary   = 0m;
    int     employeeCount = 0;

    while (!string.IsNullOrEmpty(sheet[$"A{rowNumber}"].StringValue))
    {
        int      id         = sheet[$"A{rowNumber}"].IntValue;
        string   name       = sheet[$"B{rowNumber}"].StringValue;
        string   department = sheet[$"C{rowNumber}"].StringValue;
        decimal  salary     = sheet[$"D{rowNumber}"].DecimalValue;

        Console.WriteLine($"{id,4}  {name,-20}  {department,-15}  {salary,10:C}");

        totalSalary   += salary;
        employeeCount += 1;
        rowNumber     += 1;
    }

    Console.WriteLine($"\nTotal Employees: {employeeCount}");
    Console.WriteLine($"Total Payroll:   {totalSalary:C}");

    // Write a new record back to the sheet and save
    sheet["A10"].Value = 1010;
    sheet["B10"].Value = "Jane Doe";
    sheet["C10"].Value = "Finance";
    sheet["D10"].Value = 75000;
    workbook.SaveAs("Employees-Updated.xlsx");
}
catch (Exception ex)
{
    Console.WriteLine($"Error reading Excel file: {ex.Message}");
}

O loop while termina quando a coluna A fica vazia, tornando o leitor adaptável a planilhas de qualquer comprimento sem exigir uma contagem de linhas fixa. Escrever valores de volta segue a mesma sintaxe de endereço de célula da leitura, e SaveAs persiste as alterações em um novo arquivo para que o original permaneça intacto. O bloco try/catch lida com arquivos ausentes, pastas de trabalho bloqueadas e dados corrompidos -- todos os cenários que ocorrem em ambientes de produção onde os arquivos de entrada chegam de fontes externas.

Como lidar com cenários de leitura avançada?

Vários cenários menos comuns, mas importantes, surgem em projetos reais. Intervalos nomeados, descoberta de planilhas e carregamento de CSV possuem suporte dedicado de API.

Intervalos nomeados permitem que você referencie dados por um rótulo lógico em vez de um endereço de célula. Se o autor da planilha definiu um intervalo nomeado chamado SalaryTable, você o acessa diretamente através de GetRangeByName:

var range = workbook.GetRangeByName("SalaryTable");
decimal total = range.Sum();
Console.WriteLine($"Named range total: {total:C}");

var range = workbook.GetRangeByName("SalaryTable");
decimal total = range.Sum();
Console.WriteLine($"Named range total: {total:C}");

Descoberta de planilhas enumera cada folha na pasta de trabalho, o que é útil ao processar arquivos com um número variável de abas:

foreach (WorkSheet ws in workbook.WorkSheets)
    Console.WriteLine($"Sheet: {ws.Name}, Rows: {ws.RowCount}");

foreach (WorkSheet ws in workbook.WorkSheets)
    Console.WriteLine($"Sheet: {ws.Name}, Rows: {ws.RowCount}");

Carregamento de CSV usa um método dedicado otimizado para arquivos de texto simples, retornando um WorkSheet que você navega com a mesma API de intervalo:

WorkBook csv    = WorkBook.LoadCSV("data.csv");
WorkSheet first = csv.DefaultWorkSheet;
Console.WriteLine(first["A1"].StringValue);

WorkBook csv    = WorkBook.LoadCSV("data.csv");
WorkSheet first = csv.DefaultWorkSheet;
Console.WriteLine(first["A1"].StringValue);

Esses padrões cobrem os cenários de leitura avançada que aparecem em projetos de migração de dados, pipelines de ETL e sistemas de relatórios automatizados. Para a superfície completa da API, consulte a referência de objetos do IronXL.

Referências autoritativas adicionais:

• Documentação principal do IronXL
• Como editar fórmulas do Excel
• Como trabalhar com funções matemáticas
• Como selecionar intervalos
• Especificação Open XML ECMA-376 -- o padrão autoritativo que define o formato XLSX
• Documentação Microsoft Open XML SDK -- material de referência para a estrutura subjacente do arquivo
• Galeria NuGet -- IronXl.Excel -- página do pacote com histórico de versões e estatísticas de download

Quais são os seus próximos passos?

O IronXL transforma a leitura de arquivos Excel de um desafio dependente de Interop em algumas linhas de código C# direto. Carregar pastas de trabalho, extrair valores tipados, iterar linha por linha, executar cálculos agregados e lidar com casos extremos seguem todos o mesmo padrão de API consistente -- sem o Microsoft Office instalado em nenhum lugar do seu ambiente de implantação.

Para passar do tutorial para a produção:

1. Inicie uma avaliação gratuita para desbloquear o conjunto completo de recursos do IronXL e validá-lo contra seus próprios arquivos Excel antes de se comprometer com uma licença.
2. Navegue pela documentação completa do IronXL para guias sobre escrita, formatação, estilização e conversão de planilhas.
3. Explore a referência de objetos e a API completa para descobrir todas as classes, métodos e propriedades disponíveis na biblioteca.
4. Revise o guia de como criar planilhas quando seu fluxo de trabalho exigir a geração de arquivos de saída, bem como a leitura de arquivos de entrada.
5. Confira o índice de postagens do blog do IronXL para tutoriais adicionais cobrindo cenários do mundo real, como geração de relatórios, validação de dados e consolidação de várias planilhas.