IRONSOFTWAREHOME
USANDO O IRONXL

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

Curtis Chau
Curtis Chau
Updated: 21 de abril de 2026

Arquivos CSV -- valores separados por vírgulas armazenados em formato de texto simples -- permanecem como um dos formatos mais universais para troca de dados entre aplicativos, bancos de dados e sistemas de relatórios. Seja exportando uma lista de usuários, gerando relatórios financeiros ou preparando dados para importação em plataformas de análise, a capacidade de criar e ler arquivos CSV programaticamente usando C# é essencial para o desenvolvimento moderno em .NET. Os desenvolvedores muitas vezes começam a geração de CSV usando uma abordagem simples var line com StringBuilder ou StreamWriter, mas esses métodos manuais rapidamente se tornam propensos a erros à medida que a complexidade dos dados aumenta.

Alguns desenvolvedores recorrem a bibliotecas de ajuda CSV para operações básicas de leitura/escrita, mas essas ferramentas ainda exigem mapeamento manual e manipulação a nível de linha, comparado a abordagens de primeiro uso de planilhas como IronXL. Este guia demonstra como escrever dados em arquivos CSV, converter planilhas Excel existentes para formato CSV e exportar objetos para valores separados por vírgulas usando IronXL -- uma poderosa biblioteca .NET que simplifica operações de planilhas sem exigir a instalação do Microsoft Excel. O IronXL funciona em ambientes Windows, macOS, Linux e conteinerizados como Docker e Azure, tornando-o ideal para aplicativos nativos de nuvem e arquiteturas de microsserviços.

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:

PM > Install-Package IronXL.Excel

C# Salvar em CSV Usando IronXL: Imagem 1 - Instalação

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 declaração using:

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 com toda a complexidade da formatação adequada de CSV automaticamente — incluindo escape de caracteres especiais, preservação de tipos de dados e 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.

Quais Plataformas o IronXL Suporta?

O IronXL roda em qualquer plataforma onde .NET é suportado. Isso inclui ambientes de desktop e servidor Windows, máquinas de desenvolvimento macOS e servidores Linux, incluindo contêineres Docker. Para equipes que constroem aplicativos nativos da nuvem no Azure ou AWS, o IronXL funciona sem necessidade de configuração adicional. A biblioteca não requer interoperabilidade COM, nenhuma instalação do Microsoft Office e nenhuma dependência de sistema externo – tornando-a fácil de implantar e atualizar através de fluxos de trabalho padrão de gerenciamento de pacotes.

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

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

Saída

C# Salvar em CSV Usando IronXL: Imagem 2 - Saída CSV

Referências de células como sheet["A1"] fornecem acesso direto a células específicas onde os valores podem ser atribuídos. O IronXL aceita vários tipos de dados incluindo strings, inteiros, decimais, datas e valores booleanos, lidando automaticamente com o formato apropriado para cada tipo. Para cenários de entrada de dados mais complexos, explore o guia de operações de intervalo do IronXL para técnicas de atribuição de células em massa.

O método SaveAsCsv() exporta o conteúdo da planilha para um arquivo. O primeiro parâmetro especifica o nome do arquivo de saída e o caminho, e o segundo parâmetro define o caractere delimitador. O IronXL lida automaticamente com a formatação adequada, incluindo a proteção de caracteres especiais que poderiam quebrar a análise de CSV e manter a integridade dos dados durante o processo de exportação.

Como Exportar uma Lista de Objetos para CSV?

Ao trabalhar com objetos fortemente tipados, você pode usar um loop foreach para iterar por uma coleção e escrever cada item na planilha. Aqui está um exemplo usando uma classe Student com propriedades de string públicas:

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

Este padrão demonstra como exportar objetos de lista para dados CSV iterando por cada item e mapeando suas propriedades para colunas específicas. O loop foreach processa cada aluno na coleção, e a interpolação de strings constrói as referências das células dinamicamente. Para cenários que envolvem mapeamento de propriedades baseado em reflexão ou tipos anônimos, você pode adaptar essa abordagem iterando sobre objetos PropertyInfo a partir dos metadados do tipo.

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

O método Load() abre arquivos Excel em vários formatos, incluindo XLSX, XLS, XLSM, e até mesmo arquivos 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.

Entrada

C# Salvar em CSV Usando IronXL: Imagem 3 - Entrada de Amostra do Excel

Saída

C# Salvar em CSV Usando IronXL: Imagem 4 - Saída de Excel para CSV

Uma das características marcantes do IronXL durante a conversão é a avaliação automática de fórmulas. Ao salvar em CSV, o IronXL calcula todas as fórmulas presentes na planilha e exporta os valores resultantes em vez do texto da fórmula. Por exemplo, uma célula contendo =SUM(A1:A10) seria exportada como o total calculado, garantindo que o arquivo CSV contenha dados acionáveis que sistemas downstream possam usar imediatamente.

Como Funciona a Exportação de Múltiplas Planilhas?

Ao trabalhar com workbooks Excel contendo várias planilhas, o IronXL cria arquivos CSV separados para cada planilha automaticamente. Esta capacidade é particularmente valiosa para relatórios financeiros, dados de vendas regionais, ou qualquer cenário onde cada departamento ou categoria ocupe sua própria planilha dentro de um único workbook mestre.

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

A convenção de nomenclatura acrescenta o nome de cada planilha ao nome base do arquivo, tornando simples identificar a origem de cada arquivo exportado ao processar ou arquivar. Para exportações direcionadas onde apenas planilhas específicas são necessárias, recupere a planilha desejada usando GetWorkSheet() e chame SaveAsCsv() diretamente nesse objeto de planilha.

Saiba mais sobre conversão entre formatos Excel na documentação do IronXL.

Como Exportar um DataTable para CSV?

Aplicativos empresariais frequentemente trabalham com objetos DataTable preenchidos a partir de consultas de banco de dados, respostas de API ou processamento de dados na 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 manualmente arquivos CSV com um StreamWriter porque o IronXL lida automaticamente com o escape de caracteres, gerenciamento de delimitadores e codificação.

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 de coluna 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.

Saída

C# Salvar em CSV Usando IronXL: Imagem 5 - Saída de DataTable para CSV

O IronXL preserva os tipos de dados durante o processo de transferência, garantindo que valores numéricos mantenham sua precisão e datas conservem sua formatação. Esta abordagem escala bem para DataTables de qualquer tamanho, seja contendo dezenas de linhas de uma consulta de pesquisa simples ou milhares de registros de exportações de dados volumosos. Para manipulação adicional de planilhas antes da exportação, explore opções de formatação de células e operações de intervalo.

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 requerer código adicional para manipular 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", "|");

O segundo parâmetro de SaveAsCsv() aceita qualquer string como delimitador, proporcionando total flexibilidade 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:

Melhores Práticas de Geração de Arquivos CSV em C#
PráticaPor que isso importaAbordagem do IronXL
Delimitadores consistentesEvita erros de análise em sistemas subsequentesPasse o delimitador como segundo parâmetro para SaveAsCsv()
Cotação de valores especiaisPreserva a integridade do campo quando vírgulas aparecem nos dadosTratado automaticamente pelo IronXL
Formatos de data consistentesEvita ambiguidade entre locais e sistemasDefina o formato da célula antes de salvar para controlar a saída
Evite novas linhas nos valoresEvita corrupção da estrutura das linhasIronXL escapa novas linhas incorporadas durante a exportação
Trate exceçõesAssegura que os fluxos de arquivo fechem corretamenteIronXL descarta recursos internamente
Valide antes de salvarDetecta problemas de dados antes que eles alcancem os consumidoresUse operações em intervalos para validar valores das células pré-exportação

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-lhe acesso a células e intervalos individuais usando a mesma API usada 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);
}

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 múltiplos formatos. Saiba mais sobre leitura de arquivos CSV com 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 existentes de Excel e CSV 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 fluxos de trabalho 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.

Curtis Chau
Redator Técnico

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.

...
Leia mais

Artigos relacionados

Key in blue circle

Obtenha sua chave de avaliação gratuita de 30 dias instantaneamente.

Your trial license will be sent to your email address

Sem limitações. 100% desbloqueado. Sem cartão de crédito.

bullet_checkedNão é necessário cartão de crédito nem criação de conta.Sem limitações. 100% desbloqueado. Sem cartão de crédito.
  • Logo Aetna
  • Logo NASA
  • Logo GE
  • Logo Porsche
  • Logo USDA
  • Logo Qatar
Join Millions of Engineers who’ve tried IronPDF
Agende sua demonstração ao vivo gratuita.
Booking Badge

Aprovado por milhões de engenheiros em todo o mundo.

Logotipos dos clientes da Iron Software
Agende sua consulta sem compromisso.
Preencha o formulário abaixo ou envie um e-mail para sales@ironsoftware.com
Os seus dados serão sempre mantidos em sigilo.
Aprovado por milhões de engenheiros em todo o mundo.
Logotipos dos clientes da Iron Software
Obtenha sua chave de avaliação gratuita de 30 dias instantaneamente.
Não é necessário cartão de crédito nem criação de conta.