1. O que é e para que serve

A biblioteca CsvHelper é uma ferramenta poderosa e flexível para ler e escrever arquivos CSV no ecossistema .NET. Ela oferece aos desenvolvedores uma API de alto nível que abstrai a complexidade do formato CSV, permitindo que você se concentre na lógica de negócios da sua aplicação. Diferente de métodos primitivos, como String.Split(','), o CsvHelper lida corretamente com caracteres escapados, aspas, campos multilinha e diferentes configurações culturais (separadores, formatos de data e número).

Para que serve? No desenvolvimento moderno, o CSV continua sendo um dos formatos mais comuns para troca de dados: exportação de relatórios, importação do Excel, carregamento de configurações, integração com sistemas legados e migração de dados. O CsvHelper transforma a tarefa rotineira de parsing em código limpo e declarativo, usando mapeamento de classes (atributos ou Fluent API), conversão automática de tipos e validação integrada. Isso economiza horas de desenvolvimento e reduz a quantidade de erros relacionados à análise manual de linhas.

Principais recursos: suporte ao .NET Standard 2.0+ (funciona em qualquer lugar: .NET Framework, .NET Core, .NET 5+), processamento em streaming (não carrega o arquivo inteiro na memória), conversores de tipo personalizados, detecção de delimitadores, trabalho com cabeçalhos e índices, além de suporte completo a operações assíncronas (ReadAsync/WriteAsync).

2. Instalação

A instalação é feita através do gerenciador de pacotes NuGet. Execute um dos seguintes comandos no console do gerenciador de pacotes ou no terminal do .NET CLI:

dotnet add package CsvHelper

ou via Package Manager Console:

Install-Package CsvHelper

Para a versão 31.0.2 (atual no momento da escrita), é necessário .NET Standard 2.0 ou superior. Após a instalação, adicione as diretivas using no seu código:

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

3. Início rápido — exemplo mínimo funcional

Vamos criar um modelo simples e escrever/ler um arquivo CSV.

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

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public string Email { get; set; }
}

// Escrita
var people = new List<Person>
{
    new Person { Name = "Ana", Age = 30, Email = "ana@exemplo.com" },
    new Person { Name = "Bruno", Age = 25, Email = "bruno@exemplo.com" }
};

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

// Leitura
using (var reader = new StreamReader("pessoas.csv"))
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
    var records = csv.GetRecords<Person>().ToList();
    foreach (var p in records)
        Console.WriteLine($"{p.Name}, {p.Age}, {p.Email}");
}

Este exemplo demonstra o ciclo básico: criar um objeto CsvWriter ou CsvReader, passar o stream e a cultura, e chamar o método de escrita/leitura. Observe o uso de CultureInfo.InvariantCulture — isso garante que separadores decimais e datas sejam gravados em um formato uniforme (ponto para números, ISO para datas).

4. Principais métodos/funções/classes

Vamos explorar as principais classes e métodos da biblioteca. Cada método é acompanhado por sua assinatura, descrição e um exemplo prático.

4.1. CsvReader.GetRecords<T>()

Assinatura: public IEnumerable<T