Exportar dados de um controle DataGridView do Windows Forms para formato Excel é um requisito comum, mas os desenvolvedores frequentemente enfrentam um obstáculo frustrante: o arquivo exportado está sem cabeçalhos de coluna. Quando você precisa exportar DataGridView para Excel com cabeçalhos de coluna, a solução deve preservar de forma confiável todos os seus dados e formatação. Abordagens tradicionais usando Interoperabilidade com o Microsoft Office podem ser lentas, frágeis e requerem que o MS Excel esteja instalado em cada máquina que executa o código.
IronXL resolve esse problema de forma limpa. É uma biblioteca Excel for .NET que lê, cria e escreve arquivos Excel sem qualquer dependência de Office. Este tutorial guia você através de uma solução completa de exportação -- uma que lida com cabeçalhos de coluna, tipos de dados, células nulas, e salvamento de arquivos amigável ao usuário com apenas algumas linhas de código.
Ao final, você terá um manipulador de botão Windows Forms funcionando que exporta um DataGridView para um arquivo XLSX com todos os cabeçalhos de coluna intactos.
Antes de escrever qualquer código, certifique-se de que os seguintes elementos estejam no lugar:
Os exemplos abaixo usam declarações de nível superior e a estrutura moderna de projeto do .NET 10 em todo.
Abra o Console do Gerenciador de Pacotes NuGet no Visual Studio e execute qualquer um dos seguintes comandos. O pacote está listado na NuGet Gallery e tem como alvo o .NET Standard 2.0 e superior, portanto, funciona com qualquer projeto .NET moderno.
Após a instalação, adicione os namespaces necessários no topo do seu arquivo de formulário:
using IronXL;
using System;
using System.Data;
using System.Windows.Forms;Imports IronXL
Imports System
Imports System.Data
Imports System.Windows.FormsEsses imports dão acesso à funcionalidade Excel do IronXL, operações DataTable e controles Windows Forms necessários para o processo de exportação.
Comece criando uma Aplicação Windows Forms no Visual Studio. Adicione um DataGridView chamado dataGridView1 e um Button chamado btnExport ao formulário principal através do designer. Em seguida, preencha a grade ao carregar o formulário:
using System;
using System.Data;
using System.Windows.Forms;
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
}
private void Form1_Load(object sender, EventArgs e)
{
DataTable dt = new DataTable();
// Define columns -- these names become Excel headers
dt.Columns.Add("Product ID", typeof(int));
dt.Columns.Add("Product Name", typeof(string));
dt.Columns.Add("Price", typeof(decimal));
dt.Columns.Add("Stock Quantity", typeof(int));
// Add sample rows
dt.Rows.Add(1001, "Laptop", 999.99m, 15);
dt.Rows.Add(1002, "Mouse", 29.99m, 50);
dt.Rows.Add(1003, "Keyboard", 79.99m, 30);
dt.Rows.Add(1004, "Monitor", 299.99m, 12);
dt.Rows.Add(1005, "Headphones", 89.99m, 25);
// Bind data to the grid
dataGridView1.DataSource = dt;
}
}Imports System
Imports System.Data
Imports System.Windows.Forms
Public Partial Class Form1
Inherits Form
Public Sub New()
InitializeComponent()
End Sub
Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
Dim dt As New DataTable()
' Define columns -- these names become Excel headers
dt.Columns.Add("Product ID", GetType(Integer))
dt.Columns.Add("Product Name", GetType(String))
dt.Columns.Add("Price", GetType(Decimal))
dt.Columns.Add("Stock Quantity", GetType(Integer))
' Add sample rows
dt.Rows.Add(1001, "Laptop", 999.99D, 15)
dt.Rows.Add(1002, "Mouse", 29.99D, 50)
dt.Rows.Add(1003, "Keyboard", 79.99D, 30)
dt.Rows.Add(1004, "Monitor", 299.99D, 12)
dt.Rows.Add(1005, "Headphones", 89.99D, 25)
' Bind data to the grid
dataGridView1.DataSource = dt
End Sub
End ClassOs nomes das colunas definidos em chamadas dt.Columns.Add(...) se tornarão a linha de cabeçalho no arquivo Excel exportado. Você pode substituir qualquer fonte de dados aqui -- um resultado de consulta de banco de dados, uma importação CSV ou uma resposta de API armazenada como um DataTable funcionam de forma idêntica com o código de exportação mostrado mais tarde. A abordagem DataTable é particularmente conveniente porque o DataGridView expõe uma propriedade DataSource que aceita qualquer IList ou IBindingList, o que significa que o mesmo código de exportação se generaliza em todos os cenários de vinculação sem modificação.
Se o seu DataGridView é preenchido a partir de um banco de dados usando um SqlDataAdapter, o DataTable já contém colunas tipadas. Passar esses valores tipados para SetCellValue em vez de chamar ToString() neles mantém colunas numéricas como numéricas na saída do Excel, o que é importante para qualquer relatório ou uso de tabela dinâmica posterior.
Isso cria um DataGridView populado com todos os dados:
Para cenários de ligação de dados mais avançados, a documentação da Microsoft sobre vinculação de dados do DataGridView fornece exemplos adicionais.
O método de exportação lê cabeçalhos de coluna da propriedade HeaderText de cada coluna do DataGridView e os escreve na linha 0 da planilha. As linhas de dados seguem da linha 1 em diante. Conecte este método ao evento de clique btnExport:
private void btnExport_Click(object sender, EventArgs e)
{
try
{
// Create a new Excel workbook in XLSX format
WorkBook workbook = WorkBook.Create(ExcelFileFormat.XLSX);
WorkSheet worksheet = workbook.CreateWorkSheet("Exported Data");
// Write column headers to row 0
for (int col = 0; col < dataGridView1.Columns.Count; col++)
{
worksheet.SetCellValue(0, col, dataGridView1.Columns[col].HeaderText);
}
// Write data rows starting at row 1
for (int row = 0; row < dataGridView1.Rows.Count; row++)
{
// Skip the placeholder new-row at the bottom of the grid
if (dataGridView1.AllowUserToAddRows && row == dataGridView1.Rows.Count - 1)
continue;
for (int col = 0; col < dataGridView1.Columns.Count; col++)
{
var cellValue = dataGridView1.Rows[row].Cells[col].Value;
if (cellValue != null)
{
worksheet.SetCellValue(row + 1, col, cellValue.ToString());
}
}
}
// Prompt the user to choose a save location
using SaveFileDialog saveFileDialog = new SaveFileDialog
{
Filter = "Excel Files|*.xlsx",
FileName = "DataGridView_Export.xlsx"
};
if (saveFileDialog.ShowDialog() == DialogResult.OK)
{
workbook.SaveAs(saveFileDialog.FileName);
MessageBox.Show("Export completed successfully!", "Success",
MessageBoxButtons.OK, MessageBoxIcon.Information);
}
}
catch (Exception ex)
{
MessageBox.Show($"Export failed: {ex.Message}", "Error",
MessageBoxButtons.OK, MessageBoxIcon.Error);
}
}Private Sub btnExport_Click(sender As Object, e As EventArgs)
Try
' Create a new Excel workbook in XLSX format
Dim workbook As WorkBook = WorkBook.Create(ExcelFileFormat.XLSX)
Dim worksheet As WorkSheet = workbook.CreateWorkSheet("Exported Data")
' Write column headers to row 0
For col As Integer = 0 To dataGridView1.Columns.Count - 1
worksheet.SetCellValue(0, col, dataGridView1.Columns(col).HeaderText)
Next
' Write data rows starting at row 1
For row As Integer = 0 To dataGridView1.Rows.Count - 1
' Skip the placeholder new-row at the bottom of the grid
If dataGridView1.AllowUserToAddRows AndAlso row = dataGridView1.Rows.Count - 1 Then
Continue For
End If
For col As Integer = 0 To dataGridView1.Columns.Count - 1
Dim cellValue = dataGridView1.Rows(row).Cells(col).Value
If cellValue IsNot Nothing Then
worksheet.SetCellValue(row + 1, col, cellValue.ToString())
End If
Next
Next
' Prompt the user to choose a save location
Using saveFileDialog As New SaveFileDialog With {
.Filter = "Excel Files|*.xlsx",
.FileName = "DataGridView_Export.xlsx"
}
If saveFileDialog.ShowDialog() = DialogResult.OK Then
workbook.SaveAs(saveFileDialog.FileName)
MessageBox.Show("Export completed successfully!", "Success",
MessageBoxButtons.OK, MessageBoxIcon.Information)
End If
End Using
Catch ex As Exception
MessageBox.Show($"Export failed: {ex.Message}", "Error",
MessageBoxButtons.OK, MessageBoxIcon.Error)
End Try
End SubCada etapa do método serve a um propósito específico:
SaveAs seja chamado.dataGridView1.Columns[col].HeaderText para cada coluna e o escreve no índice de linha 0. Este é o passo chave que preserva os cabeçalhos.row + 1 como o índice de linha do Excel, de modo que os dados sempre começam abaixo da linha de cabeçalho.O arquivo exportado se parece com este:
Dados do mundo real raramente parecem tão limpos quanto um conjunto de dados de exemplo. Aqui estão os cenários que você provavelmente encontrará e como resolvê-los.
A verificação de nulidade (if (cellValue != null)) no loop de dados trata células vazias sem lançar uma exceção. Células vazias permanecem em branco na saída do Excel, preservando a estrutura da grade.
O IronXL lida automaticamente com diferentes formatos de dados. Quando você passa um número como string via ToString(), o Excel ainda pode reconhecê-lo como numérico dependendo do valor. Para controle preciso de tipo, cast o valor da célula para o tipo correto antes de escrever:
if (cellValue is int intVal)
worksheet.SetCellValue(row + 1, col, intVal);
else if (cellValue is decimal decVal)
worksheet.SetCellValue(row + 1, col, (double)decVal);
else
worksheet.SetCellValue(row + 1, col, cellValue?.ToString() ?? string.Empty);If TypeOf cellValue Is Integer Then
Dim intVal As Integer = CType(cellValue, Integer)
worksheet.SetCellValue(row + 1, col, intVal)
ElseIf TypeOf cellValue Is Decimal Then
Dim decVal As Decimal = CType(cellValue, Decimal)
worksheet.SetCellValue(row + 1, col, CDbl(decVal))
Else
worksheet.SetCellValue(row + 1, col, If(cellValue?.ToString(), String.Empty))
End IfEssa abordagem mantém as colunas numéricas como numéricas no Excel para que fórmulas e classificações funcionem corretamente posteriormente.
Cabeçalhos de coluna com caracteres especiais como &, <, > e letras acentuadas são exportados corretamente. O IronXL lida automaticamente com a codificação e não requer nenhuma fuga por parte do usuário.
Para grades contendo dezenas de milhares de linhas, considere mover a lógica de exportação para um thread em segundo plano para manter o UI responsivo. Envolva o WorkBook.Create e a lógica de loop em uma chamada Task.Run e atualize o UI do callback concluído. A documentação da Microsoft sobre programação assíncrona com Task explica o padrão em detalhes.
Para cenários adicionais, como estilização de células, preservação de fórmulas e proteção por senha, a documentação IronXL cobre cada um em detalhes.
Antes de se comprometer com uma biblioteca, é útil entender as compensações entre os métodos mais comuns.
| Método | Escritório necessário | Cabeçalhos de Coluna | Desempenho | Seguro para Servidor |
|---|---|---|---|---|
| Interoperabilidade com o Microsoft Office | Sim | Manual | Lento | Não |
| SDK OpenXml | Não | Manual | Rápido | Sim |
| XML fechado | Não | Manual | Bom | Sim |
| IronXL | Não | Automático | Rápido | Sim |
Soluções baseadas em Interop exigem que o Excel esteja instalado no servidor, o que é uma preocupação de licenciamento e uma complexidade de implantação. SDK OpenXml é poderoso, mas de baixo nível - escrever uma linha de cabeçalho requer construir estruturas XML manualmente. IronXL e XML fechado fornecem APIs de nível mais alto, mas o modelo WorkBook e WorkSheet do IronXL mapeia de perto para a maneira como os desenvolvedores já pensam sobre planilhas.
O mesmo padrão de exportação se aplica quando você precisa de um arquivo CSV em vez de um livro de trabalho Excel. Mude o formato e a extensão do arquivo:
WorkBook csvWorkbook = WorkBook.Create(ExcelFileFormat.CSV);
WorkSheet csvSheet = csvWorkbook.CreateWorkSheet("Data");
// Headers and data loops remain identical
using SaveFileDialog dialog = new SaveFileDialog
{
Filter = "CSV Files|*.csv",
FileName = "DataGridView_Export.csv"
};
if (dialog.ShowDialog() == DialogResult.OK)
csvWorkbook.SaveAs(dialog.FileName);Imports System.Windows.Forms
Dim csvWorkbook As WorkBook = WorkBook.Create(ExcelFileFormat.CSV)
Dim csvSheet As WorkSheet = csvWorkbook.CreateWorkSheet("Data")
' Headers and data loops remain identical
Using dialog As New SaveFileDialog With {
.Filter = "CSV Files|*.csv",
.FileName = "DataGridView_Export.csv"
}
If dialog.ShowDialog() = DialogResult.OK Then
csvWorkbook.SaveAs(dialog.FileName)
End If
End UsingA exportação CSV é útil quando o sistema consumidor não suporta XLSX ou quando o tamanho do arquivo é uma preocupação para conjuntos de dados muito grandes.
Os dados exportados são mais legíveis quando a linha de cabeçalho é visualmente distinta. O IronXL fornece opções de estilo de célula que permitem aplicar texto em negrito, cor de fundo e tamanho de fonte após escrever os valores de cabeçalho:
// Write headers and apply bold styling
for (int col = 0; col < dataGridView1.Columns.Count; col++)
{
string cellAddress = worksheet.GetCellAddress(0, col);
worksheet[cellAddress].Value = dataGridView1.Columns[col].HeaderText;
worksheet[cellAddress].Style.Font.Bold = true;
worksheet[cellAddress].Style.SetBackgroundColor("#4472C4");
worksheet[cellAddress].Style.Font.FontColor = "#FFFFFF";
}' Write headers and apply bold styling
For col As Integer = 0 To dataGridView1.Columns.Count - 1
Dim cellAddress As String = worksheet.GetCellAddress(0, col)
worksheet(cellAddress).Value = dataGridView1.Columns(col).HeaderText
worksheet(cellAddress).Style.Font.Bold = True
worksheet(cellAddress).Style.SetBackgroundColor("#4472C4")
worksheet(cellAddress).Style.Font.FontColor = "#FFFFFF"
Next colUma linha de cabeçalho estilizado torna o arquivo exportado imediatamente utilizável para relatórios sem exigir que o destinatário aplique a formatação manualmente. Para uma lista completa de propriedades de estilo, consulte a referência de estilização de células do IronXL.
IronXL fornece um teste gratuito que permite testar todos os recursos, incluindo os fluxos de trabalho de exportação mostrados neste artigo. Instale o pacote com qualquer um dos comandos NuGet mostrados acima, gere uma chave de teste na página de licenciamento do IronXL e defina-a em sua aplicação antes da primeira chamada à biblioteca:
IronXL.License.LicenseKey = "YOUR-LICENSE-KEY-HERE";Imports IronXL
IronXL.License.LicenseKey = "YOUR-LICENSE-KEY-HERE"O teste produz arquivos Excel totalmente funcionais e não restringe quais recursos estão disponíveis. Para implantação em produção, opções de licenciamento cobrem desenvolvedores individuais, equipes e redistribuição livre de royalties.
Para cenários de exportação relacionados, explore como o IronXL lida com exportação de DataTables diretamente para Excel, leitura de arquivos Excel em DataGridViews, e criação de gráficos a partir dos dados exportados.
O método de exportação célula por célula, mostrado ao longo deste tutorial, atende à maioria das aplicações Windows Forms. Se o seu DataGridView estiver vinculado a um DataTable, você também pode passar o DataTable diretamente para o conversor de DataTable para planilha do IronXL, que lida automaticamente com a linha de cabeçalho. Escolha a abordagem direta de DataTable quando o layout da sua coluna for fixo e você quiser o caminho de código mais curto possível. Escolha a abordagem manual célula por célula quando precisar de lógica condicional por célula - por exemplo, destacar células cujo valor esteja fora de um intervalo aceitável ou mapear tipos anuláveis explicitamente antes de escrever.
Para cenários do lado do servidor, como controladores ASP.NET Core que geram relatórios Excel para download, a mesma API do IronXL se aplica. A única diferença é o alvo de salvamento: em vez de SaveAs(filePath), chame workbook.ToByteArray() e escreva os bytes na resposta HTTP com um tipo de conteúdo de application/vnd.openxmlformats-officedocument.spreadsheetml.sheet. Os cabeçalhos de coluna são transferidos identicamente, independentemente de a saída ir para um arquivo ou um fluxo.
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.
IronXL faz parte do IRON SUITE.
10 produtos de API .NET para seus documentos de escritório
A API do Excel que você precisa, sem as complicações do Office Interop.
