Cómo leer archivos de Excel en C# usando IronXL

¿Cómo se instala IronXL para el procesamiento de Excel?

Abre la consola del Administrador de paquetes de NuGet en Visual Studio y ejecuta el siguiente comando para añadir IronXL a tu proyecto. Alternativamente, si prefieres trabajar desde un terminal, utiliza el comando de la CLI de .NET que se muestra en la segunda línea:

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

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

El paquete se instala en segundos y añade una única referencia de ensamblado administrado a tu proyecto. Sin necesidad de registro COM, sin ensamblados de interoperabilidad primaria de Office y sin dependencias de Excel específicas de cada versión que gestionar.

Tras la instalación, añada la directiva "using" al principio de cada archivo que trabaje con datos de hojas de cálculo:

using IronXL;

using IronXL;

Imports IronXL

Ese único espacio de nombres te da acceso a WorkBook, WorkSheet, rangos de celdas, propiedades de valores tipados, funciones de agregado y cualquier otro tipo de IronXL. La página de NuGet Gallery de IronXl.Excel enumera todas las versiones disponibles y su árbol de dependencias completo.

¿Qué formatos de archivo de Excel admite IronXL?

Comprender los formatos que debe gestionar su aplicación determina tanto las llamadas a la API que realiza como las decisiones de almacenamiento que adopta su proyecto.

XLSX —el formato predeterminado desde Excel 2007— es un archivo ZIP de archivos XML. Admite más de un millón de filas, formato avanzado, tablas dinámicas y rangos con nombre. La mayoría de los flujos de datos modernos generan archivos XLSX, por lo que este es el formato con el que te encontrarás con mayor frecuencia.

XLS es el formato binario heredado utilizado por Excel 2003 y versiones anteriores. Algunos sistemas Enterprise siguen exportando archivos XLS, por lo que es importante contar con una compatibilidad fiable con este formato a la hora de integrarse con infraestructuras más antiguas. IronXL lee archivos XLS sin necesidad de ninguna configuración especial por su parte.

XLSM amplía XLSX con compatibilidad con macros. IronXL lee los datos de las hojas de cálculo de los archivos XLSM incluso si no ejecuta el código VBA incrustado, lo cual es el comportamiento correcto para la extracción de datos del lado del servidor.

CSV y TSV son formatos tabulares de texto sin formato ampliamente utilizados para el intercambio de datos entre sistemas. WorkBook.LoadCSV gestiona archivos separados por comas, e IronXL devuelve el mismo objeto WorkBook que tu código ya sabe cómo manejar, manteniendo tu lógica de lectura de datos uniforme independientemente del formato de origen.

IronXL detecta el formato de archivo automáticamente a partir de la extensión del archivo cuando se llama a WorkBook.Load. En la mayoría de los casos, no es necesario especificar el formato explícitamente, lo que simplifica el código que debe gestionar entradas procedentes de múltiples fuentes.

¿Cómo cargar y leer un libro de Excel?

El método WorkBook.Load es el punto de entrada para todas las operaciones basadas en archivos. Pase la ruta del archivo e IronXL devolverá un objeto de libro de trabajo completamente rellenado que podrá consultar de inmediato:

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

Imports IronXL

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

' Access the first worksheet
Dim sheet As WorkSheet = workbook.DefaultWorkSheet

' Read a single cell by A1 address
Dim companyName As String = sheet("A1").StringValue
Console.WriteLine($"Company: {companyName}")

' Access sheets by name or by zero-based index
Dim byName As WorkSheet = workbook.GetWorkSheet("Sales")
Dim byIndex As WorkSheet = workbook.WorkSheets(1)

' Load a password-protected file
Dim secured As WorkBook = WorkBook.Load("Confidential.xlsx", "p@ssw0rd")

La propiedad DefaultWorkSheet devuelve la primera hoja, lo que cubre la mayoría de los archivos de una sola hoja. Cuando el archivo contiene varias hojas, GetWorkSheet recupera por nombre y WorkSheets[n] recupera por índice basado en cero. La referencia de la API de WorkBook documenta todas las sobrecargas y propiedades del objeto Workbook.

¿Cómo se leen los valores de las celdas escritas en Excel?

Cada celda de IronXL expone propiedades tipadas que devuelven valores en el tipo de datos exacto que necesitas, sin necesidad de análisis sintáctico ni conversión manual. Las propiedades tipadas gestionan automáticamente la conversión de la representación subyacente de la celda:

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

Imports IronXL

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

' Extract typed values from row 2
Dim employeeId As Integer = sheet("A2").IntValue
Dim name As String = sheet("B2").StringValue
Dim department As String = sheet("C2").StringValue
Dim salary As Decimal = sheet("D2").DecimalValue
Dim hireDate As DateTime = 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
Dim formattedSalary As String = sheet("D2").Text   ' "$75,000.00"
Dim formattedDate As String = sheet("E2").Text     ' "28/02/2026"

' Guard against empty cells before reading
If Not sheet("B3").IsEmpty Then
    Dim value As String = sheet("B3").StringValue
End If

La propiedad Text devuelve el valor de visualización exactamente tal y como está formateado en Excel, lo cual resulta útil cuando se necesita la cadena numérica formateada en lugar del número sin formato. En el caso de las celdas que contienen fórmulas de Excel, IronXL evalúa la expresión y devuelve el resultado calculado a través de las mismas propiedades tipadas. Las propiedades de valor adicionales -- BoolValue, DoubleValue, FloatValue -- aparecen en la referencia del valor de la celda.

¿Cómo se recorre las filas y columnas de Excel?

El procesamiento de cada registro de un conjunto de datos requiere recorrer las filas y columnas. La sintaxis de rango de IronXL se corresponde directamente con la notación A1 de Excel, por lo que seleccionar un bloque de celdas resulta familiar para cualquiera que haya escrito fórmulas en hojas de cálculo:

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

Imports IronXL

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

' Iterate a single column range
Console.WriteLine("Employee List:")
For Each cell In sheet("B2:B100")
    If Not String.IsNullOrEmpty(cell.Text) Then
        Console.WriteLine($"  - {cell.Text}")
    End If
Next

' Iterate all rows and all columns using the Rows property
For Each row In sheet.Rows
    For Each cell In row
        Console.Write(cell.Text.PadRight(15))
    Next
    Console.WriteLine()
Next

El rango sheet["B2:B100"] devuelve una colección enumerable de objetos de celda. La comprobación de string.IsNullOrEmpty omite las filas en blanco de forma elegante. La propiedad Rows —documentada en la guía del rango de datos de la hoja de cálculo— recorre la hoja fila por fila y expone las celdas de cada fila sin necesidad de conocer de antemano el número de columnas.

¿Cómo se realizan cálculos agregados con datos de Excel?

IronXL incluye funciones de agregación integradas que calculan los resultados directamente en rangos de celdas, sin necesidad de bucles de acumulación manuales:

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

Imports IronXL

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

' Built-in aggregate methods work on any named range
Dim total As Decimal = sheet("D2:D200").Sum()
Dim highest As Decimal = sheet("D2:D200").Max()
Dim lowest As Decimal = sheet("D2:D200").Min()
Dim average As Decimal = 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
Dim itTotal As Decimal = sheet("D2:D200") _
    .Where(Function(c) sheet($"C{c.RowIndex}").StringValue = "IT") _
    .Sum(Function(c) c.DecimalValue)
Console.WriteLine($"IT Department Total: {itTotal:C}")

Sum, Min, Max y Avg omiten automáticamente las celdas vacías y gestionan la conversión numérica en segundo plano. Encadenar consultas LINQ en el rango le proporciona agregados filtrados —subtotales por departamento, sumas por rango de fechas y recuentos condicionales— todo ello sin salir de la API de IronXL.

¿Cómo se crea un lector completo de datos de empleados?

El siguiente ejemplo reúne todo lo visto hasta ahora en una aplicación de consola lista para producción que carga una hoja de cálculo de empleados, formatea cada registro, acumula los totales de salarios, gestiona la reescritura y captura los errores de forma elegante:

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

Imports IronXL

Try
    Dim workbook As WorkBook = WorkBook.Load("Employees.xlsx")
    Dim sheet As WorkSheet = workbook.DefaultWorkSheet

    Console.WriteLine("=== Employee Data Report ===" & vbCrLf)

    Dim rowNumber As Integer = 2
    Dim totalSalary As Decimal = 0D
    Dim employeeCount As Integer = 0

    While Not String.IsNullOrEmpty(sheet($"A{rowNumber}").StringValue)
        Dim id As Integer = sheet($"A{rowNumber}").IntValue
        Dim name As String = sheet($"B{rowNumber}").StringValue
        Dim department As String = sheet($"C{rowNumber}").StringValue
        Dim salary As Decimal = sheet($"D{rowNumber}").DecimalValue

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

        totalSalary += salary
        employeeCount += 1
        rowNumber += 1
    End While

    Console.WriteLine(vbCrLf & $"Total 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 ex As Exception
    Console.WriteLine($"Error reading Excel file: {ex.Message}")
End Try

El bucle while finaliza cuando la columna A queda vacía, lo que permite que el lector se adapte a hojas de cálculo de cualquier longitud sin necesidad de un recuento de filas codificado de forma fija. La reescritura de valores sigue la misma sintaxis de direcciones de celda que la lectura, y SaveAs guarda los cambios en un nuevo archivo para que el original permanezca intacto. El bloque try/catch gestiona archivos que faltan, libros de trabajo bloqueados y datos dañados, todos ellos escenarios que se producen en entornos de producción en los que los archivos de entrada proceden de fuentes externas.

¿Cómo gestionas los escenarios de lectura avanzados?

En los proyectos reales surgen varios escenarios menos habituales, pero importantes. Los rangos con nombre, la detección de hojas de cálculo y la carga de CSV cuentan cada uno con soporte API específico.

Los rangos con nombre te permiten hacer referencia a datos mediante una etiqueta lógica en lugar de una dirección de celda. Si el autor del libro definió un rango con nombre llamado SalaryTable, se accede a él directamente a travé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}");

Dim range = workbook.GetRangeByName("SalaryTable")
Dim total As Decimal = range.Sum()
Console.WriteLine($"Named range total: {total:C}")

La función "Discovery" de hojas de cálculo enumera todas las hojas del libro, lo cual resulta útil al procesar archivos con un número variable de pestañas:

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

For Each ws As WorkSheet In workbook.WorkSheets
    Console.WriteLine($"Sheet: {ws.Name}, Rows: {ws.RowCount}")
Next

La carga de CSV utiliza un método específico optimizado para archivos de texto sin formato, que devuelve un WorkSheet al navegar con la misma API de rango:

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

Dim csv As WorkBook = WorkBook.LoadCSV("data.csv")
Dim first As WorkSheet = csv.DefaultWorkSheet
Console.WriteLine(first("A1").StringValue)

Estos patrones abarcan los escenarios de lectura avanzados que aparecen en proyectos de migración de datos, procesos ETL y sistemas de generación de informes automatizados. Para ver la superficie completa de la API, consulte la referencia de objetos de IronXL.

Referencias adicionales de referencia:

• Página principal de la documentación de IronXL
• Cómo editar fórmulas de Excel
• Cómo trabajar con funciones matemáticas
• Cómo seleccionar rangos
• Especificación ECMA-376 Open XML: el estándar de referencia que define el formato XLSX
• Documentación de Microsoft Open XML SDK: material de referencia sobre la estructura de archivos subyacente
• NuGet Gallery -- IronXl.Excel -- página del paquete con historial de versiones y estadísticas de descargas

¿Cuales son tus próximos pasos?

IronXL convierte la lectura de archivos Excel, que antes era un reto de interoperabilidad cargado de dependencias, en unas pocas líneas de código C# sencillo. Cargar libros de trabajo, extraer valores introducidos, iterar fila por fila, ejecutar cálculos de agregados y gestionar casos extremos: todo ello sigue el mismo patrón API coherente, sin necesidad de tener Microsoft Office instalado en ningún lugar de su entorno de implementación.

Para pasar del tutorial a la producción:

1. Inicie una prueba gratuita para desbloquear todas las funciones de IronXL y compruebe su funcionamiento con sus propios archivos de Excel antes de adquirir una licencia.
2. Consulte la documentación completa de IronXL para obtener guías sobre cómo escribir, dar formato, aplicar estilos y convertir hojas de cálculo.
3. Explora la referencia de objetos y la API completa para descubrir todas las clases, métodos y propiedades disponibles en la biblioteca.
4. Consulte la guía práctica para crear hojas de cálculo cuando su flujo de trabajo requiera generar archivos de salida, además de leer archivos de entrada.
5. Consulte el índice de entradas del blog de IronXL para encontrar tutoriales adicionales que abordan situaciones reales, como la generación de informes, la validación de datos y la consolidación de varias hojas.