Introduction

The adoption of XML as the native file format for Excel 2007 has opened up a whole host of new possibilities. Now for the first time we can create native Excel files on the server using standard tools. No longer is there a need to pollute your beautiful server room with a headless PC running Excel and an old VB6 app that uses OLE Automation to create reports. Such things can be consigned to the trash heap of IT history.

However, the new Office Open XML standard is so new there are precious few good code samples. This article aims to correct the situation by providing a flexible set of open source class libraries that you can use to create Excel spreadsheets on the server.

Why create Excel spreadsheets on the server?

Excel has long been recognized as the de facto standard when it comes to presenting management reports. The unique combination of great calculation engine, excellent charting facilities and the possibility to perform "what if" analysis, make it the "must have" business intelligence tool.

So when we came to replace our aging management reporting infrastructure, we set one key requirement: the new system must be Web-based and provide a "download in Excel" option. For our business intelligence project we built the data warehouse using SQL Server 2005 populated from our PeopleSoft and Novient implementations using SQL Server 2005 Integration Services (SSIS). The OLAP cube was built on SQL Server 2005 Analysis Services (SSAS). SQL Server 2005 Reporting Services (SSRS) provides the Web-based access to management reports and the all important "download in Excel" option. So why do we need to create Excel on the server?

The problem with SQL Server 2005 Reporting Services is that it the Excel spreadsheets it generates are "dumb". They contain no formula - just the raw data. So the recipient cannot perform a "what if" analysis by changing a few values and expecting the spreadsheet to recalculate.

We considered a number of ways to overcome this issue, but by far the most attractive is to create the Excel spreadsheet on the server, straight from the OLAP cube data. So we created a web-part for SharePoint Server 2007 so the user could enter their criteria and view the report on-line via Excel Services. Of course users can download the file for off-line viewing in Excel 2007 or even Excel 2003 file format. This SharePoint web-part and its associated web service that does the file format conversion will be the topic of another article.

The Open Source ExcelPackage Assembly

The ExcelPackage assembly is a set of classes and wrappers around the .NET 3.0 System.IO.Packaging API and the new SpreadsheetML file format. It extracts away the complexity of dealing with the individual XML components that make up the new Excel 2007 file format. The classes are published as an assembly called ExcelPackage which you can install in the GAC and use as the basis of your own applications. In the sprit of open source projects, if you wish to help extend the functionality offered by the ExcelPackage assembly then join the team over at the ExcelPackage Open XML project.

Creating an Excel spreadsheet from scratch

Sample 1 shows how to create a new Excel spreadsheet containing some basic data and calculations. So let's see how this is achieved.

This creates a new instance of the all important ExcelPackage class which gives you access to the Excel workbook and worksheets. If mynewfile.xlsx already exists, then ExcelPackage will open the existing file. Otherwise mynewfile.xlsx will be created from scratch.

Let’s start by adding a new worksheet called “Tinned Goods” and adding some basic data and a simple calculation:

If all this seems a bit too easy - well yes it is! The ExcelPackage assembly does all the hard work of creating the XML elements that are needed to represent an Excel worksheet, the Excel rows, the Excel cells etc. All you need to do is connect in the data! The ExcelWorksheet class has all the properties and methods needed to create and manipulate worksheets. A number of supporting classes (such as ExcelCell, ExcelRow, ExcelColumn, ExcelHeaderFooter etc.) provide properties and methods of each worksheet component. They also provide helper functions that make it easy to manipulate Excel data. For example, the ExcelCell.GetCellAddress(iRow, iColumn) method turns your row and column integers into Excel-style cell addresses.

Ok, so in our sample some of the data is too wide for the column, so let's change the column size:

worksheet.Column(1).Width = 15;

Next, add some headers and footers to the spreadsheet. Note how we use the PageNumber and NumberOfPages constants to insert codes into the footer text. This causes Excel to insert the page number and the number of pages in the document footer. worksheet.HeaderFooter.oddHeader.CenteredText = "Tinned Goods Sales";

// add the page number to the footer plus the total number of pages
worksheet.HeaderFooter.oddFooter.RightAlignedText =
string.Format("Page {0} of {1}", ExcelHeaderFooter.PageNumber,
ExcelHeaderFooter.NumberOfPages);

OK, so let's write some real hard code. Let's insert a line into the worksheet so we can add some more data. This will screw up our formula as it will be referencing the wrong set of rows (i.e. the new row will not be included in the total).

worksheet.InsertRow(3);

Well hell no, the formula is correct. The InsertRow method not only updates all the row and cell references in the underlying XML, but also updates all the formulas in the spreadsheet! Ok, we now have our report, but we want to ensure our corporate search engine can find the file later. So let's add some standard and custom document properties.

Below is a screenshot of the final output showing the header and the document properties.

Reading data from an Excel spreadsheet

Sample 2 shows how to read data from an existing Excel spreadsheet. We will use the spreadsheet generated by Sample 1 as the source document. To output the contents of column 2 to the console, this is all we need:

Starting with a template

Sample 3 shows how to create a new Excel spreadsheet based on an existing file and populate it with data from a database. This is a much better approach as you can quickly create a spreadsheet with the right formula and the correct corporate 'look and feel' using Excel 2007. You can then have the calculations in your template validated by the business before starting to write any code. This whole approach saves a lot of coding time!

Before running the code sample, open the template and take a look at its content. You will see it already has the desired layout and all the formula and formatting required for the title and total lines. However, it only has room for three "data rows" (i.e. rows 5, 6 & 7). You will see how we cope with this later.

So let's start by creating a new Excel spreadsheet based on a template.

Next open a connection to the database and run the query. This example uses data from the AdventureWorks sample database, so you will need this installed if you want to run the sample.

while (sqlReader.Read())
{
int col = 1;
// we have our total formula on row 7, so push them down so we can insert
// more data
if (row > startRow) worksheet.InsertRow(row);
// our query has the columns in the right order, so simply
// iterate through the columns
for (int i = 0; i < sqlReader.FieldCount; i++)
{
// use the email address as a hyperlink for column 1
if (sqlReader.GetName(i) == "EmailAddress")
{
// insert the email address as a hyperlink for the name
string hyperlink = "mailto:" + sqlReader.GetValue(i).ToString();
worksheet.Cell(row, 1).Hyperlink = new Uri(hyperlink, UriKind.Absolute);
}
else
{
// do not bother filling cell with blank data
// (also useful if we have a formula in a cell)
if (sqlReader.GetValue(i) != null)
worksheet.Cell(row, col).Value = sqlReader.GetValue(i).ToString();
col++;
}
}
row++;
}

So now we have filled our worksheet with the entire dataset. Note how we use the email address as a hyperlink. Using hyperlinks is useful when you want to link one report up with another.

The purist among you will notice that all the data is written into the cell as a string. However, the Cell(row, col).Value = "xxx"property assignment code checks if the value is a number or a string and sets the cell's data type accordingly.

As mentioned earlier, the template only has room for three data rows. We cope with this by simply inserting rows into the template - thereby pushing the "Total" row down the sheet. The InsertRow method automatically updates the formula in the "Total" row so that they take into account the extra rows.

As we have inserted a whole set of rows into the spreadsheet, they will not have the correct style. We correct this by simply iterating through the new rows and copying the style from the first row to all the other rows.

The Power of Named Styles

Anyone familiar with styling HTML with CSS will understand the power and flexibility of using named styles rather than updating the style of every individual element. With named styles, the look and feel of the whole spreadsheet can be altered by changing one style definition. This capability was introduced in Excel 2003, but Excel 2007 goes one step further and makes it a dream to create a template using named styles.

We apply two built-in named styles to highlight the top achieving and the worst performing sales reps.

// style the first row as they are the top achiever
worksheet.Cell(startRow, 6).Style = "Good";
// style the last row as they are the worst performer
worksheet.Cell(row, 6).Style = "Bad";

The biggest problem with named styles in Excel 2007 is that if they are not used in your template, then Excel strips out the definition when the file is saved. This is a real headache. There are two ways to cope with this (1) add extra rows that have styles applied and delete them later (which is the technique used in this sample) or (2) load your own style.xml file which contains all the definitions you want to use.

Shared formula

Excel 2007 has a neat feature which saves a lot of coding when it comes to applying the same formula to a range of cells. A formula in one cell can be marked as "shared" and all cells referenced by the shared formula obtain their own version of the formula. So if cell E5 has the formula D5*12, then cell E6 would have the formula D6*12etc. etc. To set up a shared formula simply call the CreateSharedFormula method. In the following example, the formula in cell E5 is marked as "shared" and all the other cells in the range E5:E21 are assigned their own variation of the formula.

Ensuring your formula are recalculated on File-Open

One problem we came across with Excel 2007 is that it does not automatically re-calculate the spreadsheet when it is re-opened - even when the Calculate option set to automatic! This is because the existing cells in the template have both a formula and a value in the cell. So Excel just assumes the value is correct and does not attempt to re-compute the formula. Of course, we have just added twenty rows of data and updated the formula references in the XML - but Excel has no why of knowing this, so assumes the values must be right!

The only way to force the recalculation is to ensure the cell has no value - just a formula. So the RemoveValue() method becomes very useful for all formula in the worksheet. Hence:

worksheet.Cell(22, 5).RemoveValue();

Because of this phenomenon, we changed the ExcelCell.Formula property assignment code so that it removes the cell's value when you assign the cell a formula.

The final output of Sample 3 code should look something like this - much more professional than anything that can be achieved starting from scratch.

Integrity issues

As soon as you start deleting rows or even worksheets from the package, you have potential for integrity issues. Your formulas will reference cells (or worksheets) that no longer exist. The ExcelPackage assembly does a good job of tidying up after you - but cannot cope with complex situations. You will soon know if you have an integrity problem - Excel will complain bitterly when opening the newly created file.

A classic problem is the calcChain.xml file. This tells Excel in what order the calculations should be processed. So if you delete a row that is referenced by the calcChain, Excel will complain. However, if you simply remove the calcChain.xml from the package, Excel re-creates it when the file is opened - and does not complain! So this is an easy fix. The ExcelPackage assembly does exactly that - deletes the calcChain.xml file from the template so that Excel simply re-creates it when the file is opened.

The ExcelPackage assembly also provides you with direct access to each of the XML documents that make up the package. So you can write your own code to manipulate the XML directly. However, if you choose to do this, be careful to ensure the XML conforms to the new Office Open XML standard. Otherwise, Excel will simply strip out your all hard work as "badly formed".

Debugging your application

If you want to understand exactly what is been written into each of the component XML files by the ExcelPackage assembly, then simply add the following line of code:

xlPackage.DebugMode = true;

This will cause the assembly to output the raw XML files in the same location as the output file. You will see a sub-folder called 'xl' and another callled 'docProps'.

Summary

This article has demonstrated just how easy it is to create Excel-based reports on the server using the open source ExcelPackage assembly. We hope you will be able to join us in extending the functionality of the assembly over at the ExcelPackage Open XML project. There is plenty still to do; charting, conditional formatting, inserting comments, to name just a few!

Good luck with your project!

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

I did not see an option for attaching a schema (or XML Mapping if you prefer) to the Workbook. My understanding of the new Office 2007 suite is limited so I am not sure if this is a problem or not. How do I determine that an XML element (lets say 'ClientID') should be mapped to a specific cell (lets say 'E2') and what happens if the Schema on the template changes?

Hi,
I have developed excel exports based on the excelpackage (originally found it on the codeplex site actually) however are now trying to find a way to speed´it up.

The requirement is to write thousands of rows to a excel file in a timely manner.
My application is taking hours to do this with the excel package. I timed it to only write 166 rows per minute. One row includes writing 4 values, and copying the cellstyle for the 8 cells around them in the same row. If I want to write 60 thousand rows this will take a long time.

Is there any way to write a whole section of rows faster? (I have pretty fast hardware so thats not the problem, and the SQL statements are very fast)

OK, i have found a way to increase speed to 516 rows per minute (from 166) however it is still too slow. I just wrote the insert statement so that it always inserts after the row, before it was inserting above the row to write and the more rows the slower the insert statement is, as it seems to calculate the move of all other rows down a step for each insert.

The problem still exists though as i need to speed it up several times.

ExcelPackage uses the XML DOM and the PackagingAPI to create the Excel 2007 files. The big advantage of the DOM is that you can update any part of the XML file in any order. The disadvantage is that the DOM is resource hungry and can be slow.

Certainly understanding what ExcelPackage is doing behind the scenes helps avoid the resource hungry steps. For example, if you are applying the same style to a new cell, then use the StyleID rather than the StyleName as the latter has to do a complex lookup to change the StyleName into an ID.

If you are writing out so many lines, you probably should be using XmlWriter directly. However, ExcelPackage does not support this mode of operation - and I doubt that it ever should/could as you need to write out the XML in the correct order. This may be find for your 60k rows, but most other apps require a bit more flexibility!

I have to ask, why create a 60k spreadsheet in the first place? I cannot see why a business person would ever find such a thing useful. Please, do tell.

Can anyone give me a hand? I have downloaded the samples, not changed anything but the 3rd sample does not working. I am using MS ExcelViewer 2003 with Compatibility Pack. First two samples are ok, but I can not open sample3.xlsx file. Only dialog box appears with info that:
"The converter failed to save the file".

Bummer.
I need to use it in Windows client applications, that will call the Excel calculation on a server, but there will be a lot of servers, os it would be way to expencive to buy MOSS, unless I run the Excel calculation as a central services to the other servers to use, but I don't think it would be a good idea to make all of the servers relay on that the central server with Excel calculation is available at all time.

But just for the fun of it. Do you have some numbers on what kind of calculation load a central server would be able to perform?

Certainly the ExcelPackage assembly can be installed anywhere on the server, so no need to install in the GAC. So long as the assembly is referenced correctly or in the relevant web app bin folder, then all will work.

However, .NET 3.0 redistributable package must be installed on the server as the WindowsBase.dll assembly contains the all important System.IO.PackagingAPI.