Ícone de mensagem
Ir para o conteúdo do rodapé
  1. IronXL
  2. Blog IronXL
  3. Usando o IronXL
  4. Exportar DataGridView para Excel em C# com cabeçalhos de coluna
USANDO O IRONXL

Exportar DataGridView para Excel em C# com cabeçalhos de coluna

Jordi Bardia
Jordi Bardia
Atualizado:

Como você exporta um DataGridView para Excel com cabeçalhos de coluna em C#?

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.

O Que Você Precisa Antes de Começar

Antes de escrever qualquer código, certifique-se de que os seguintes elementos estejam no lugar:

  • Visual Studio 2022 ou posterior (qualquer edição)
  • SDK .NET 10 instalado
  • Um projeto de Aplicação Windows Forms direcionado for .NET 10
  • Acesso ao NuGet para instalar o IronXL

Os exemplos abaixo usam declarações de nível superior e a estrutura moderna de projeto .NET 10 ao longo.

Como Você Instala a Biblioteca em um Projeto .NET?

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.

Install-Package IronXL
Install-Package IronXL
SHELL 
dotnet add package IronXL
dotnet add package IronXL
SHELL

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;
using IronXL;
using System;
using System.Data;
using System.Windows.Forms;
$vbLabelText   $csharpLabel

Esses imports dão acesso à funcionalidade Excel do IronXL, operações DataTable e controles Windows Forms necessários para o processo de exportação.

Como configurar um DataGridView com dados de exemplo?

Comece criando uma Aplicação Windows Forms no Visual Studio. Adicione um DataGridView chamado dataGridView1 e um Botão 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;
    }
}
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;
    }
}
$vbLabelText   $csharpLabel

Os 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 maneira idêntica com o código de exportação mostrado mais adiante. 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 para todos os cenários de vinculação sem modificação.

Se o seu DataGridView for populado 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() sobre eles mantém as colunas numéricas como numéricas na saída do Excel, o que é importante para qualquer relatório subsequente ou uso de tabela dinâmica.

Isso cria um DataGridView populado com todos os dados:

C# Export DataGridView para Excel com Cabeçalhos de Coluna Usando IronXL: Imagem 1 - Dados de exemplo em um DataGridView

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.

Como exportar o DataGridView para Excel mantendo os cabeçalhos de coluna?

O método de exportação lê os cabeçalhos das colunas 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 esse 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 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);
    }
}
$vbLabelText   $csharpLabel

Analisando as Etapas da Exportação

Cada etapa do método serve a um propósito específico:

  • WorkBook.Create: Inicializa um novo arquivo Excel na memória usando o formato XLSX. Nenhum arquivo é escrito no disco até que SaveAs seja chamado.
  • CreateWorkSheet: Adiciona uma folha nomeada para conter os dados exportados. O nome "Exported Data" aparece como o rótulo da guia no Excel.
  • Loop de cabeçalho da coluna: Lê dataGridView1.Columns[col].HeaderText para cada coluna e escreve no índice da linha 0. Este é o passo chave que preserva os cabeçalhos.
  • Loops de linha de dados: Loops aninhados iteram cada linha e coluna, usando row + 1 como o índice da linha do Excel para que os dados sempre comecem abaixo da linha do cabeçalho.
  • Verificação de null: Impede exceções quando uma célula não contém valor, o que é comum em dados reais.
  • SaveFileDialog: Permite que os usuários escolham o nome e o destino do arquivo em tempo de execução em vez de codificar um caminho.

O arquivo exportado se parece com este:

C# Export DataGridView para Excel com Cabeçalhos de Coluna Usando IronXL: Imagem 2 - Arquivo Excel de saída com os dados de exemplo exportados

Como lidar com casos extremos comuns durante a exportação?

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.

Células Vazias

A verificação de nulo (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.

Tipos de Dados Mistos

O IronXL lida automaticamente com diferentes formatos de dados. Quando você passa um número como uma 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 (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);
$vbLabelText   $csharpLabel

Essa abordagem mantém as colunas numéricas como numéricas no Excel para que fórmulas e classificações funcionem corretamente posteriormente.

Caracteres Especiais em Cabeçalhos

Os 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.

Conjuntos de Dados Grandes

Para grades contendo dezenas de milhares de linhas, considere mover a lógica de exportação para um thread em segundo plano para manter a interface do usuário responsiva. Envolva a chamada WorkBook.Create e a lógica de loop em uma chamada Task.Run e atualize a interface do usuário com o callback de conclusão. 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.

Como se comparam as principais abordagens de exportação?

Antes de se comprometer com uma biblioteca, é útil entender as compensações entre os métodos mais comuns.

Comparação de métodos de exportação de DataGridView para Excel em C#
Método Escritório necessário Cabeçalhos de Coluna Desempenho Seguro para Servidor
Interoperabilidade com o Microsoft Office Sim Manual Lento Não
OpenXml SDK 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. OpenXml SDK é poderoso, mas de baixo nível - escrever uma linha de cabeçalho requer construir estruturas XML manualmente. Tanto o IronXL quanto o XML fechado fornecem APIs de nível superior, mas o modelo WorkBook e WorkSheet do IronXL mapeia-se de forma próxima à maneira como os desenvolvedores já pensam sobre planilhas.

Como Exportar para CSV em vez de XLSX?

O mesmo padrão de exportação se aplica quando você precisa de um arquivo CSV em vez de uma planilha do 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);
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);
$vbLabelText   $csharpLabel

A 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.

Como Estilizar a Linha de Cabeçalho no Arquivo Exportado?

Os dados exportados são mais legíveis quando a linha de cabeçalho é visualmente distinta. O IronXL fornece opções de estilização de células que permitem aplicar texto em negrito, cor de fundo e tamanho de fonte após escrever os valores do 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 (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";
}
$vbLabelText   $csharpLabel

Uma 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.

Como posso começar com um teste gratuito?

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";
IronXl.License.LicenseKey = "YOUR-LICENSE-KEY-HERE";
$vbLabelText   $csharpLabel

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 exportar DataTables diretamente para Excel, ler arquivos Excel em DataGridViews e criar gráficos a partir de dados exportados.

Escolhendo a Estratégia de Exportação Certa para Seu Caso de Uso

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 com a linha de cabeçalho automaticamente. 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.

Perguntas frequentes

Como posso exportar dados do DataGridView para o Excel em C#?

Utilize a biblioteca IronXL para criar uma planilha do Excel, itere pelas colunas do DataGridView para escrever os cabeçalhos na linha 0 e, em seguida, itere pelas linhas de dados e escreva os valores das células a partir da linha 1. Salve a planilha com a opção Salvar como.

Qual a vantagem de usar o IronXL para exportar dados?

IronXL fornece uma API de alto nível para operações com o Excel que não requer a instalação do Microsoft Office. Ela lida com cabeçalhos, tipos de dados e formatos de arquivo sem manipulação manual de XML.

É possível preservar os cabeçalhos das colunas ao exportar do DataGridView para o Excel?

Sim. Leia a propriedade HeaderText de cada coluna do DataGridView e escreva-a na linha 0 da planilha IronXL antes de escrever quaisquer linhas de dados.

Preciso de um período de teste para começar a usar o IronXL para exportar para o Excel?

Está disponível uma versão de avaliação gratuita que dá acesso a todos os recursos. Instale o pacote NuGet , gere uma chave de avaliação e defina IronXL antes de fazer qualquer chamada à biblioteca.

O IronXL consegue lidar com grandes conjuntos de dados DataGridView ao exportar para o Excel?

Sim. Para grades muito grandes, execute a exportação em uma thread em segundo plano usando Task.Run para manter a interface do usuário responsiva enquanto o IronXL grava os dados.

Quais são os passos para exportar um DataGridView para o Excel usando o IronXL?

Instale o IronXL, crie uma WorkBook e uma WorkSheet, percorra as colunas do DataGridView para escrever os cabeçalhos na linha 0, percorra as linhas para escrever os dados a partir da linha 1 e, em seguida, chame o método SaveAs para gravar o arquivo.

Por que escolher o IronXL em vez de outras bibliotecas para exportar para o Excel?

O IronXL não requer instalação do Office, funciona em servidores e fornece uma API WorkBook/WorkSheet limpa que se adapta naturalmente à forma como os desenvolvedores pensam sobre planilhas — com documentação robusta e suporte ativo.

Existe suporte disponível para solucionar problemas com o IronXL?

Sim. A IronXL fornece documentação detalhada da API, exemplos de código e suporte técnico direto para clientes licenciados.

Posso personalizar o processo de exportação para Excel com o IronXL?

Sim. Depois de inserir os dados, você pode aplicar fontes em negrito, cores de fundo, bordas e formatos de número a qualquer intervalo de células usando a API de Estilos do IronXL.

O IronXL suporta a exportação de dados para outros formatos além do Excel?

Sim. O IronXL suporta os formatos XLSX, XLS, CSV e TSV. A troca de formatos requer apenas a alteração do valor da enumeração ExcelFileFormat passado para WorkBook.Create.

Jordi Bardia
Jordi Bardia
  Converse agora mesmo com a equipe de engenharia.
Engenheiro de Software
Jordi é extremamente proficiente em Python, C# e C++, e quando não está utilizando suas habilidades na Iron Software, dedica-se à programação de jogos. Compartilhando as responsabilidades por testes, desenvolvimento e pesquisa de produtos, Jordi agrega imenso valor à melhoria contínua dos produtos. Essa experiência diversificada o mantém ...
Leia mais

Artigos relacionados

Teste grátis por 30 dias → Produto completo. Sem limites. Sem cartão. Comece seu teste gratuito

Iron Support Team

We're online 24 hours, 5 days a week.
Chat
Email
Call Me