CsvHelper para C# (.NET): guía completa con ejemplos

1. ¿Qué es y para qué sirve?

La librería CsvHelper es una herramienta potente y flexible para leer y escribir archivos CSV en el ecosistema .NET. Proporciona a los desarrolladores una API de alto nivel que abstrae la complejidad de trabajar con el formato CSV, permitiéndoles centrarse en la lógica de negocio de la aplicación. A diferencia de métodos primitivos como String.Split(','), CsvHelper maneja correctamente caracteres escapados, comillas, campos multilínea y diferentes configuraciones culturales (separadores, formatos de fecha y número).

¿Para qué sirve? En el desarrollo moderno, CSV sigue siendo uno de los formatos más comunes para el intercambio de datos: exportación de informes, importación desde Excel, carga de configuraciones, intercambio con sistemas heredados y migración de datos. CsvHelper convierte la tediosa tarea de analizar CSV en código limpio y declarativo, utilizando mapeo de clases (atributos o Fluent API), conversión automática de tipos y validación integrada. Esto ahorra horas de desarrollo y reduce la cantidad de errores relacionados con el análisis manual de cadenas.

Características clave: soporte para .NET Standard 2.0+ (funciona en todas partes: .NET Framework, .NET Core, .NET 5+), procesamiento por streaming (no carga todo el archivo en memoria), convertidores de tipos personalizados, detección de delimitadores, trabajo con encabezados e índices, y soporte completo para operaciones asíncronas (ReadAsync/WriteAsync).

2. Instalación

La instalación se realiza a través del administrador de paquetes NuGet. Ejecuta uno de los siguientes comandos en la consola del administrador de paquetes o en la terminal de .NET CLI:

dotnet add package CsvHelper

o a través de la Package Manager Console:

Install-Package CsvHelper

Para la versión 31.0.2 (actual en el momento de escribir esto) se requiere .NET Standard 2.0 o superior. Después de la instalación, agrega la directiva using en tu código:

using CsvHelper;
using CsvHelper.Configuration;
using System.Globalization;

3. Inicio rápido — ejemplo mínimo funcional

Vamos a crear un modelo simple y escribir/leer un archivo CSV.

using System.Globalization;
using CsvHelper;
using CsvHelper.Configuration;

public class Persona
{
    public string Nombre { get; set; }
    public int Edad { get; set; }
    public string Email { get; set; }
}

// Escritura
var personas = new List<Persona>
{
    new Persona { Nombre = "Ana", Edad = 30, Email = "ana@ejemplo.com" },
    new Persona { Nombre = "Carlos", Edad = 25, Email = "carlos@ejemplo.com" }
};

using (var writer = new StreamWriter("personas.csv"))
using (var csv = new CsvWriter(writer, CultureInfo.InvariantCulture))
{
    csv.WriteRecords(personas);
}

// Lectura
using (var reader = new StreamReader("personas.csv"))
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
    var registros = csv.GetRecords<Persona>().ToList();
    foreach (var p in registros)
        Console.WriteLine($"{p.Nombre}, {p.Edad}, {p.Email}");
}

Este ejemplo muestra el ciclo básico: crear un objeto CsvWriter o CsvReader, pasar el flujo y la cultura, y llamar al método de escritura/lectura. Observa el uso de CultureInfo.InvariantCulture — esto garantiza que los separadores decimales y las fechas se escriban en un formato uniforme (punto para números, ISO para fechas).