Leitor e gravador de CSV em C#: Crie, exporte e converta arquivos CSV com o IronXL

O que é o formato CSV e por que isso importa?

Um arquivo de Valores Separados por Vírgula (CSV) é um dos formatos mais amplamente utilizados para armazenar e trocar dados tabulares entre diferentes aplicativos. Na sua forma mais simples, um arquivo CSV é um arquivo de texto simples onde cada linha contém uma série de valores separados por vírgulas. Essa estrutura direta torna os dados CSV fáceis de gerar, ler e processar em uma ampla gama de sistemas de software.

O formato CSV é leve e legível por humanos, sendo por isso uma escolha popular para exportar relatórios, transferir dados entre bancos de dados e integrar com ferramentas de análise. Cada linha em um arquivo CSV representa um único registro, e cada valor dentro dessa linha é separado por uma vírgula. A primeira linha do arquivo geralmente serve como cabeçalho, listando os nomes de cada coluna. Todas as linhas subsequentes contêm os dados reais, com cada valor correspondendo a uma coluna no cabeçalho.

Entender como os arquivos CSV são estruturados ajuda a tomar decisões melhores sobre a escolha de delimitadores, escape de caracteres e codificação -- todos os fatores que afetam se os sistemas a jusante conseguem interpretar sua saída de maneira confiável. O formato de arquivo CSV é definido pelo RFC 4180, que fornece orientação sobre como lidar com casos extremos como vírgulas incorporadas, caracteres de nova linha dentro de campos e valores de string entre aspas.

Como Instalar IronXL em Seu Projeto .NET?

Adicionar o IronXL a um novo projeto leva apenas alguns segundos através do NuGet, o gerenciador de pacotes da Microsoft for .NET. Abra o Visual Studio, depois acesse o Console do Gerenciador de Pacotes NuGet e execute o seguinte comando:

Install-Package IronXl.Excel

Alternativamente, clique com o botão direito no seu projeto no Solution Explorer, selecione "Gerenciar Pacotes NuGet", pesquise por "IronXL" na guia Procurar e clique em Instalar. O IronXL suporta .NET Framework 4.6.2+, .NET Core, .NET 5/6/7/8/10, e roda em qualquer plataforma sem dependências externas ou requisitos de interoperabilidade COM.

Uma vez instalado, adicione o namespace IronXL ao seu arquivo de código usando a instrução using:

using IronXL;

using IronXL;

Esse único namespace fornece acesso a todas as classes necessárias para criação de planilhas e operações de exportação CSV. Ao contrário das abordagens que dependem de StreamWriter ou StringBuilder para escrever arquivos CSV manualmente, o IronXL lida automaticamente com toda a complexidade da formatação correta do CSV -- incluindo a escapação de caracteres especiais, a preservação de tipos de dados e a avaliação de fórmulas antes da exportação.

A documentação do IronXL cobre toda a superfície da API, incluindo recursos avançados como estilo de célula, avaliação de fórmulas, proteção por senha e geração de gráficos. Para referência rápida, a biblioteca de exemplos IronXL fornece trechos de código prontos para execução que cobrem dezenas de cenários comuns de planilha.

Como Criar um Novo Arquivo CSV do Zero?

Criar um novo arquivo CSV programaticamente envolve três etapas: criar uma planilha, preenchê-la com dados e salvá-la no formato CSV. A API do IronXL espelha o modelo de objeto Excel familiar, facilitando para desenvolvedores escrever código que funcione com conceitos de planilha em um aplicativo de console ou qualquer tipo de projeto .NET.

Considere um cenário onde você precise exportar uma lista de registros de funcionários para CSV. Aqui está um exemplo completo usando declarações de nível superior:

using IronXL;

// Create a new workbook and worksheet
WorkBook workBook = WorkBook.Create();
WorkSheet sheet = workBook.CreateWorkSheet("Employees");

// Add header row with column names
sheet["A1"].Value = "EmployeeID";
sheet["B1"].Value = "Name";
sheet["C1"].Value = "Department";
sheet["D1"].Value = "Salary";

// Add employee data rows
sheet["A2"].Value = 1001;
sheet["B2"].Value = "Sarah Johnson";
sheet["C2"].Value = "Engineering";
sheet["D2"].Value = 85000;

sheet["A3"].Value = 1002;
sheet["B3"].Value = "Michael Chen";
sheet["C3"].Value = "Marketing";
sheet["D3"].Value = 72000;

sheet["A4"].Value = 1003;
sheet["B4"].Value = "Emily Rodriguez";
sheet["C4"].Value = "Finance";
sheet["D4"].Value = 91000;

// Save as CSV file
workBook.SaveAsCsv("employees.csv", ",");

using IronXL;

// Create a new workbook and worksheet
WorkBook workBook = WorkBook.Create();
WorkSheet sheet = workBook.CreateWorkSheet("Employees");

// Add header row with column names
sheet["A1"].Value = "EmployeeID";
sheet["B1"].Value = "Name";
sheet["C1"].Value = "Department";
sheet["D1"].Value = "Salary";

// Add employee data rows
sheet["A2"].Value = 1001;
sheet["B2"].Value = "Sarah Johnson";
sheet["C2"].Value = "Engineering";
sheet["D2"].Value = 85000;

sheet["A3"].Value = 1002;
sheet["B3"].Value = "Michael Chen";
sheet["C3"].Value = "Marketing";
sheet["D3"].Value = 72000;

sheet["A4"].Value = 1003;
sheet["B4"].Value = "Emily Rodriguez";
sheet["C4"].Value = "Finance";
sheet["D4"].Value = 91000;

// Save as CSV file
workBook.SaveAsCsv("employees.csv", ",");

O método WorkBook.Create() inicializa uma nova planilha inteiramente na memória, não exigindo arquivos temporários ou entrada/saída de disco até a operação de salvamento final. O método CreateWorkSheet() adiciona uma planilha nomeada ao workbook -- esse nome se torna relevante ao exportar workbooks com várias planilhas para CSV.

using IronXL;

// Define the Student class with public string properties
public class Student
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
}

// Create sample data
var students = new List<Student>
{
    new Student { FirstName = "John", LastName = "Smith", Email = "john@example.com" },
    new Student { FirstName = "Jane", LastName = "Doe", Email = "jane@example.com" }
};

WorkBook workBook = WorkBook.Create();
WorkSheet sheet = workBook.DefaultWorkSheet;

// Add header row
sheet["A1"].Value = "FirstName";
sheet["B1"].Value = "LastName";
sheet["C1"].Value = "Email";

// Use foreach to iterate through the list and write each item
int row = 2;
foreach (var item in students)
{
    sheet[$"A{row}"].Value = item.FirstName;
    sheet[$"B{row}"].Value = item.LastName;
    sheet[$"C{row}"].Value = item.Email;
    row++;
}

workBook.SaveAsCsv("students.csv", ",");

using IronXL;

// Define the Student class with public string properties
public class Student
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
}

// Create sample data
var students = new List<Student>
{
    new Student { FirstName = "John", LastName = "Smith", Email = "john@example.com" },
    new Student { FirstName = "Jane", LastName = "Doe", Email = "jane@example.com" }
};

WorkBook workBook = WorkBook.Create();
WorkSheet sheet = workBook.DefaultWorkSheet;

// Add header row
sheet["A1"].Value = "FirstName";
sheet["B1"].Value = "LastName";
sheet["C1"].Value = "Email";

// Use foreach to iterate through the list and write each item
int row = 2;
foreach (var item in students)
{
    sheet[$"A{row}"].Value = item.FirstName;
    sheet[$"B{row}"].Value = item.LastName;
    sheet[$"C{row}"].Value = item.Email;
    row++;
}

workBook.SaveAsCsv("students.csv", ",");

Como Converter um Arquivo Excel Existente para CSV?

Converter planilhas Excel para o formato CSV é uma exigência comum ao integrar com sistemas legados, preparar dados para importações de banco de dados ou gerar saída legível por máquina a partir de relatórios criados por humanos. O IronXL lida com essa conversão com código mínimo, preservando a precisão dos dados.

using IronXL;

// Load an existing Excel file
WorkBook workBook = WorkBook.Load("Monthly_Report_20251012.xlsx");

// Convert and save as CSV format
workBook.SaveAsCsv("Monthly_Report_20251012.csv");

using IronXL;

// Load an existing Excel file
WorkBook workBook = WorkBook.Load("Monthly_Report_20251012.xlsx");

// Convert and save as CSV format
workBook.SaveAsCsv("Monthly_Report_20251012.csv");

O método Load() abre arquivos Excel em vários formatos, incluindo XLSX, XLS, XLSM e até mesmo CSV ou TSV existentes. Essa flexibilidade significa que você pode construir pipelines de exportação padronizados que aceitam arquivos de entrada independentemente de seu formato original. Veja a lista completa de formatos Excel suportados na documentação do IronXL.

using IronXL;

// Load a multi-sheet workbook (e.g., annual sales by region)
WorkBook workBook = WorkBook.Load("annual_sales.xlsx");

// Export all sheets to CSV -- creates separate files for each sheet
workBook.SaveAsCsv("sales_export.csv");
// Output: sales_export.North.csv, sales_export.South.csv, sales_export.East.csv, etc.

// Or export a specific worksheet
WorkSheet northRegion = workBook.GetWorkSheet("North");
northRegion.SaveAsCsv("north_region_sales.csv");

using IronXL;

// Load a multi-sheet workbook (e.g., annual sales by region)
WorkBook workBook = WorkBook.Load("annual_sales.xlsx");

// Export all sheets to CSV -- creates separate files for each sheet
workBook.SaveAsCsv("sales_export.csv");
// Output: sales_export.North.csv, sales_export.South.csv, sales_export.East.csv, etc.

// Or export a specific worksheet
WorkSheet northRegion = workBook.GetWorkSheet("North");
northRegion.SaveAsCsv("north_region_sales.csv");

Como Exportar um DataTable para CSV?

Aplicações empresariais frequentemente trabalham com objetos DataTable populados a partir de consultas de banco de dados, respostas de API ou processamento de dados em memória. O IronXL faz a ponte entre essas estruturas de dados .NET e exportações de arquivos, fornecendo um caminho confiável da memória do aplicativo para arquivos CSV compartilháveis. Este método é mais confiável do que escrever arquivos CSV manualmente com um StreamWriter porque o IronXL lida com a escapação de caracteres, gestão de delimitadores, e codificação automaticamente.

using IronXL;
using System.Data;

// Create and populate a DataTable with columns
DataTable products = new DataTable();
products.Columns.Add("SKU", typeof(string));
products.Columns.Add("ProductName", typeof(string));
products.Columns.Add("Price", typeof(decimal));
products.Columns.Add("InStock", typeof(int));

// Add rows of data
products.Rows.Add("SKU-001", "Wireless Mouse", 29.99m, 150);
products.Rows.Add("SKU-002", "Mechanical Keyboard", 89.99m, 75);
products.Rows.Add("SKU-003", "USB-C Hub", 45.99m, 200);

// Create workbook and transfer DataTable contents
WorkBook workBook = WorkBook.Create();
WorkSheet sheet = workBook.DefaultWorkSheet;

// Add header row from column names
for (int col = 0; col < products.Columns.Count; col++)
{
    sheet.SetCellValue(0, col, products.Columns[col].ColumnName);
}

// Add data rows using nested loops
for (int row = 0; row < products.Rows.Count; row++)
{
    for (int col = 0; col < products.Columns.Count; col++)
    {
        sheet.SetCellValue(row + 1, col, products.Rows[row][col].ToString());
    }
}

// Export to CSV
workBook.SaveAsCsv("product_inventory.csv", ",");

using IronXL;
using System.Data;

// Create and populate a DataTable with columns
DataTable products = new DataTable();
products.Columns.Add("SKU", typeof(string));
products.Columns.Add("ProductName", typeof(string));
products.Columns.Add("Price", typeof(decimal));
products.Columns.Add("InStock", typeof(int));

// Add rows of data
products.Rows.Add("SKU-001", "Wireless Mouse", 29.99m, 150);
products.Rows.Add("SKU-002", "Mechanical Keyboard", 89.99m, 75);
products.Rows.Add("SKU-003", "USB-C Hub", 45.99m, 200);

// Create workbook and transfer DataTable contents
WorkBook workBook = WorkBook.Create();
WorkSheet sheet = workBook.DefaultWorkSheet;

// Add header row from column names
for (int col = 0; col < products.Columns.Count; col++)
{
    sheet.SetCellValue(0, col, products.Columns[col].ColumnName);
}

// Add data rows using nested loops
for (int row = 0; row < products.Rows.Count; row++)
{
    for (int col = 0; col < products.Columns.Count; col++)
    {
        sheet.SetCellValue(row + 1, col, products.Rows[row][col].ToString());
    }
}

// Export to CSV
workBook.SaveAsCsv("product_inventory.csv", ",");

Este padrão itera através da estrutura DataTable, transferindo primeiro os cabeçalhos das colunas e depois populando cada linha de dados sistematicamente. A propriedade DefaultWorkSheet fornece acesso rápido à primeira planilha em um workbook recém-criado, eliminando a necessidade de criação explícita de planilhas em cenários simples.

Como lidar com delimitadores personalizados em arquivos CSV?

Sistemas diferentes e padrões regionais exigem caracteres de delimitador variados. Enquanto a vírgula é o separador padrão em muitos países, os pontos e vírgulas são muitas vezes preferidos nas regiões europeias onde as vírgulas servem como separadores decimais em valores numéricos. Arquivos separados por tabulação (TSV) são populares quando os dados de origem contêm vírgulas dentro dos valores dos campos. O método SaveAsCsv() do IronXL acomoda todos esses cenários sem exigir código adicional para lidar com cada linha de saída.

using IronXL;

WorkBook workBook = WorkBook.Load("data.xlsx");

// Standard comma delimiter (default format)
workBook.SaveAsCsv("output_comma.csv", ",");

// Semicolon delimiter (common in European systems)
workBook.SaveAsCsv("output_semicolon.csv", ";");

// Tab delimiter (TSV format)
workBook.SaveAsCsv("output_tab.tsv", "\t");

// Pipe delimiter (used in some data interchange formats)
workBook.SaveAsCsv("output_pipe.csv", "|");

using IronXL;

WorkBook workBook = WorkBook.Load("data.xlsx");

// Standard comma delimiter (default format)
workBook.SaveAsCsv("output_comma.csv", ",");

// Semicolon delimiter (common in European systems)
workBook.SaveAsCsv("output_semicolon.csv", ";");

// Tab delimiter (TSV format)
workBook.SaveAsCsv("output_tab.tsv", "\t");

// Pipe delimiter (used in some data interchange formats)
workBook.SaveAsCsv("output_pipe.csv", "|");

O segundo parâmetro de SaveAsCsv() aceita qualquer string como delimitador, proporcionando flexibilidade completa para integração com diversos sistemas e requisitos regionais. Ao gerar arquivos para distribuição internacional, considere as expectativas de configurações regionais do sistema-alvo -- sistemas financeiros europeus geralmente esperam separação por ponto e vírgula, enquanto sistemas norte-americanos tipicamente usam vírgulas como padrão. O padrão RFC 4180 para CSV descreve como os valores contendo delimitadores devem ser colocados entre aspas para evitar erros de análise.

Quais são as melhores práticas para geração de arquivos CSV em C#?

Ao trabalhar com arquivos CSV em C#, seguir práticas estabelecidas garante que seus dados permaneçam precisos, legíveis e compatíveis com outros sistemas. A tabela a seguir resume as considerações mais importantes:

Além do básico, considere codificar explicitamente quando direcionar audiências internacionais. UTF-8 com BOM é frequentemente necessário para arquivos CSV abertos no Microsoft Excel para exibir caracteres não ASCII corretamente. Para exportações de alto volume envolvendo milhões de linhas, considere dividir os dados em vários arquivos em vez de escrever um único CSV grande -- isso mantém os tamanhos de arquivo gerenciáveis e reduz a pressão de memória durante tanto a geração quanto o consumo.

Para equipes construindo pipelines de dados, a documentação de async e streaming do IronXL cobre padrões para lidar com conjuntos de dados grandes sem carregar planilhas inteiras na memória. A biblioteca de exemplos do IronXL inclui padrões adicionais para processamento em lote, trabalhos de exportação agendados e integração com estruturas ORM populares como Entity Framework.

Ao trabalhar com as ferramentas de processamento de CSV do ecossistema .NET, entender onde o IronXL se ajusta em relação a abordagens de nível mais baixo ajuda a escolher a ferramenta certa para cada cenário. Para geração pura de CSV sem qualquer envolvimento do Excel, StreamWriter com lógica de citação manual pode ser suficiente. Para qualquer coisa envolvendo compatibilidade com formato Excel, avaliação de fórmulas ou formatação rica, o IronXL fornece uma base mais confiável.

Como ler um arquivo CSV existente com o IronXL?

Ler dados CSV de volta em seu aplicativo segue o mesmo padrão de carregar qualquer outro formato de planilha. O método Load() do IronXL reconhece arquivos CSV e os analisa no modelo padrão de workbook/planilha, dando acesso a células individuais e intervalos usando a mesma API utilizada para arquivos Excel.

using IronXL;

// Load an existing CSV file
WorkBook workBook = WorkBook.Load("employees.csv");
WorkSheet sheet = workBook.DefaultWorkSheet;

// Access specific cells by reference
string firstHeader = sheet["A1"].StringValue;

// Iterate through all rows
foreach (var row in sheet.Rows)
{
    foreach (var cell in row)
    {
        Console.Write(cell.StringValue + "\t");
    }
    Console.WriteLine();
}

// Access a range of cells
var nameColumn = sheet["B2:B100"];
foreach (var cell in nameColumn)
{
    Console.WriteLine(cell.StringValue);
}

using IronXL;

// Load an existing CSV file
WorkBook workBook = WorkBook.Load("employees.csv");
WorkSheet sheet = workBook.DefaultWorkSheet;

// Access specific cells by reference
string firstHeader = sheet["A1"].StringValue;

// Iterate through all rows
foreach (var row in sheet.Rows)
{
    foreach (var cell in row)
    {
        Console.Write(cell.StringValue + "\t");
    }
    Console.WriteLine();
}

// Access a range of cells
var nameColumn = sheet["B2:B100"];
foreach (var cell in nameColumn)
{
    Console.WriteLine(cell.StringValue);
}

Essa consistência entre as operações de leitura e escrita significa que sua equipe só precisa aprender uma única API para todas as tarefas relacionadas a planilhas. O mesmo método WorkBook.Load() que abre arquivos CSV também lida com os formatos XLSX, XLS e XLSM -- útil ao construir pipelines que aceitam entrada em vários formatos. Saiba mais sobre ler arquivos CSV com o IronXL na documentação.

Quais são os seus próximos passos?

Este guia abordou os padrões principais para criação e gestão de arquivos CSV usando o IronXL em C#:

• WorkBook.Create() para inicializar novas planilhas na memória
• WorkBook.Load() para abrir arquivos Excel e CSV existentes em qualquer formato suportado
• SaveAsCsv() para exportar dados com delimitadores personalizáveis
• Exportação de planilhas individuais usando GetWorkSheet() para conversões direcionadas
• Padrões de iteração DataTable para workflows de banco de dados para CSV
• Exportação de lista de objetos usando loops foreach
• Lendo dados CSV de volta em seu aplicativo com acesso de faixa completa

Para colocar essas técnicas em prática, inicie uma avaliação gratuita do IronXL para explorar a gama completa de capacidades de planilha sem limite de tempo para testes. Quando estiver pronto para a implantação em produção, revise as opções de licenciamento do IronXL para encontrar o plano certo para o tamanho da sua equipe e requisitos de uso.

Para exemplos adicionais que cobrem cenários avançados como formatação de células, criação de fórmulas, geração de gráficos e proteção por senha, explore a documentação do IronXL e a biblioteca completa de exemplos de código. A série de tutoriais do IronXL cobre cenários de integração mais complexos, incluindo exportações de DataTable, conversões de formato e escrita em arquivos CSV.