Criando um arquivo Excel utilizando EPPlus. (C#/.NET)

Neste post, embarcaremos numa jornada prática demonstrando o poder do EPPlus, um pacote incrível para manipulação de arquivos Excel diretamente do C# sem depender das licenças do Microsoft Office. Vamos entender como adicionar esse recurso aos nossos projetos, criar e modificar arquivos Excel, além de acessar e estilizar células de forma simples. Prepare-se para desvendar essa ferramenta que pode otimizar e abrir novas possibilidades nos seus projetos de desenvolvimento.

Gerar relatórios em Excel é uma coisa relativamente comum e o problema de muitas abordagens é: Ter que usar interop como abordagem para o processo, ou seja, a maquina que vai gerar o relatório (mesmo que seja um servidor) precisa ter o Microsoft Office instalado e isso significa pagar por licenças. Neste post mostro como utilizar o pacote EPPlus, que consegue gerar e manipular arquivos Excel sem a necessidade de utilizar interop.

Vantagens de utilizar o EPPlus:

1. Não requer instalação do Microsoft Office;
2. API simples;
3. Formato compatível com Open Office XML;

Pre-requisitos

Este pacote não vem instalado/habilitado por padrão nos seus projetos. Sendo assim, podemos utilizar o NuGet para adicioná-lo.

Install-Package EPPlus

Se você não quiser utilizar o console do NuGet, pode utilizar a interface dele e instalar o pacote.

Uma vez que o pacote estiver instalado, basta fazer a importação:

using OfficeOpenXml;

Estrutura do arquivo Excel

O arquivo Excel é considerado um pacote (package) que possui um Workbook e dentro dele existem as planilhas.

Então a estrutura é:

• ExcelPackage (Pacote Excel, o seu arquivo)
  • ExcelWorkbook (O elemento que guarda todas as planilhas do seu arquivo)
    • ExcelWorksheet: A planilha em si. Existe uma instancia desta classe para cada planilha que existe no seu arquivo.

Criando um novo arquivo

Para criar um arquivo, primeiro temos que criar um pacote:

var package = new ExcelPackage();

ou 

ExcelPackage package = new ExcelPackage();

Ok. Agora você já possui um pacote e um Workbook (ele é criado automaticamente) .

Para facilitar, podemos separar o Workbook em uma variável. Desta forma, vamos escrever menos:

var workbook = package.Workbook;

ou

ExcelWorkbook workbook = package.Workbook;

Abrindo um arquivo Excel

As vezes você vai precisar abrir um arquivo. Vamos supor que você quer abrir o arquivo c:\temp\planilha.xlsx…

var package = new ExcelPackage(new FileInfo("c:\\temp\\planilha.xlsx"));

No código acima, passamos uma instancia da classe System.IO.FileInfo no construtor do ExcelPackage e utilizará esta informação para abrir o arquivo.

Adicionando uma planilha (sheet)

Para adicionar uma planilha:

var sheet = workbook.Worksheets.Add("SheetName");

ou 

ExcelWorksheet sheet = workbook.Worksheets.Add("SheetName");

No código acima, adicionamos uma planilha com o nome “SheetName”. Você pode adicionar quantas planilhas quiser.

Recuperando uma planilha

Vamos imaginar que você adicionou varias planilhas ao seu arquivo ou está lendo um arquivo que possui diversas planilhas. Como acessar uma sheet específica?

Na classe Workbook existe uma propriedade chamada Worksheets. Ela é uma espécie de lista de Worksheets que te permite acessar os objetos pelo índice ou pelo nome da planilha.

var sheet = workbook.Worksheets["SheetName"];

O código acima recupera o objeto referente a planilha com nome SheetName.

var sheet = workbook.Worksheets[1];

O código acima recupera a segunda planilha do Workbook.

O próximo passo é acessar as células da planilha…

Acessando células da planilha

As células são acessadas através da propriedade Cells. Elas podem ser acessadas de diversas formas.

A primeira forma é passando a referência de linha (row) e coluna (col). No código abaixo estou escrevendo a string “oi!” na célula A1 (primeira coluna da primeira linha).

var row = 1;
var col = 1;

sheet.Cells[row, col].Value = "oi!";

Importante: A referencia de linha e coluna para o EPPlus é base 1, ou seja, a primeira linha é a número 1 (em contraste com base zero, que é a forma como acessamos posições nos vetores do C#).

Outra forma de escrever “oi!” na primeira célula da primeira linha do Excel é utilizando a forma abaixo, que é passando a referência da célula que desejamos escrever. Note que utilizamos a mesma propriedade (Cells), mas desta vez passamos uma string ao invés de dois inteiros.

sheet.Cells["A1"].Value = "oi!";

Você não precisa selecionar apenas uma célula por vez! Você pode selecionar um grupo (range) de células. Abaixo eu seleciono as primeiras colunas da primeira linha e coloco elas em negrito.

sheet.Cells["A1:E1"].Style.Font.Bold = true;

Nos exemplos acima, selecionamos e alteramos as células de uma vez, mas você pode armazenar a referência para uma célula ou um range de células.

var celA3 = sheet.Cells["A3"];
var rangeA1E1 = sheet.Cells["A1:E1"];

No código acima, salvei a referência para a célula A3 e para o range que começa na A1 e vai até a E1.

Outra nota importante: Se você quiser apagar o conteúdo de uma célula, não basta mudar o valor dela para uma string vazia. O Excel considera isso como uma célula preenchida. Se você quiser apagar o conteúdo, deve definir a propriedade Value da célula para null.

Salvando o arquivo

O que falta agora é salvar o arquivo.

Da forma que fizemos neste exemplo, podemos salva-lo informando o nome do arquivo:

package.SaveAs(new FileInfo(@"sampleEpplus.xlsx"));

Como o pacote (package) é o objeto que representa o arquivo em si, é nele que está a função que salva o arquivo.

Para informar o nome do arquivo você deve passar uma instancia da classe System.IO.FileInfo. O pacote EPPlus vai pegar o nome do arquivo desta instancia e utiliza-lo.

Se você preferir, pode passar a instancia da classe FileInfo no momento da criação do pacote. Assim você pode chamar a função Save sem passar qualquer argumentos. (Ou a função SaveAs, passando outra instancia da classe FileInfo para criar uma cópia do arquivo)

var blankPackage = new ExcelPackage(new FileInfo(@"blankSample.xlsx"));
blankPackage.Workbook.Worksheets.Add("blankSheet");
blankPackage.Save(); //Salva arquivo blankSample.xlsx
blankPackage.SaveAs(new FileInfo(@"blankSampleCopy.xlsx")); //Salva copia com nome blankSampleCopy.xlsx

Este post já está bem grande, mas vale mais uma observação: Para conseguir salvar, o arquivo deve conter, no mínimo, uma planilha!

Com este conhecimento, você já é capaz de criar um arquivo (ou editar) um arquivo Excel. No próximo post vou mostrar como mudar a formatação das células, fazendo com que as datas e números sejam exibidos corretamente.

Criei um arquivo com este exemplo no meu Github.

Espero ter ajudado!