SpreadCheetah is a high-performance .NET library for generating spreadsheet (Microsoft Excel XLSX) files.
Features
Performance (see benchmarks below)
Low memory allocation (see benchmarks below)
Async APIs
No dependency to Microsoft Excel
Targeting .NET Standard 2.0 for .NET Framework and earlier versions of .NET Core
Targeting .NET 6 and newer for more optimizations
Trimmable and native AOT compatible
SpreadCheetah is designed to create spreadsheet files in a forward-only manner.
That means worksheets from left to right, rows from top to bottom, and row cells from left to right.
This allows for creating spreadsheet files in a streaming manner, while also keeping a low memory footprint.
Most basic spreadsheet functionality is supported, such as cells with different data types, basic styling, and formulas. More advanced functionality will be added in future releases. See the list of currently supported spreadsheet functionality in the wiki.
SpreadCheetah is available as a package on nuget.org. The NuGet package targets .NET Standard 2.0 as well as newer versions of .NET. The .NET Standard 2.0 version is intended for backwards compatibility (.NET Framework and earlier versions of .NET Core). More optimizations are enabled when targeting newer versions of .NET.
Basic usage
using (var spreadsheet = await Spreadsheet.CreateNewAsync(stream))
{
// A spreadsheet must contain at least one worksheet.
await spreadsheet.StartWorksheetAsync("Sheet 1");
// Cells are inserted row by row.
var row = new List<Cell>
{
new Cell("Answer to the ultimate question:"),
new Cell(42)
};
// Rows are inserted from top to bottom.
await spreadsheet.AddRowAsync(row);
// Remember to call Finish before disposing.
// This is important to properly finalize the XLSX file.
await spreadsheet.FinishAsync();
}
Source Generators is a feature in the C# compiler. SpreadCheetah includes a source generator that makes it easier to create rows from objects. It is used in a similar way to the System.Text.Json source generator:
namespace MyNamespace;
// A plain old C# class which we want to add as a row in a worksheet.
// The source generator will pick the properties with public getters.
// The order of the properties will decide the order of the cells.
public class MyObject
{
public string Question { get; set; }
public int Answer { get; set; }
}
The source generator will be instructed to generate code by defining a partial class like this:
using SpreadCheetah.SourceGeneration;
namespace MyNamespace;
[WorksheetRow(typeof(MyObject))]
public partial class MyObjectRowContext : WorksheetRowContext;
During build, the type will be analyzed and an implementation of the context class will be created. We can then create a row from an object by calling AddAsRowAsync with the object and the context type as parameters:
await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream);
await spreadsheet.StartWorksheetAsync("Sheet 1");
var myObj = new MyObject
{
Question = "How many Rings of Power were there?",
Answer = 20
};
await spreadsheet.AddAsRowAsync(myObj, MyObjectRowContext.Default.MyObject);
await spreadsheet.FinishAsync();
Here is a peek at part of the code that was generated for this example. As you can see, the generated code also takes advantage of using a pooled array to avoid memory allocations:
The source generator can generate rows from classes, records, and structs. It can be used in all supported .NET versions, including .NET Framework, however the C# version must be 8.0 or greater.
More features of the source generator can be seen in the wiki.
Benchmarks
The benchmark results here have been collected using BenchmarkDotNet with the following system configuration:
Disclaimer: The libraries have different feature sets compared to each other.
SpreadCheetah can only create spreadsheets, while the other libraries used in this comparison
can also open spreadsheets. SpreadCheetah is also a newer library and has been designed from
the ground up to utilize many of the newer performance related features in .NET. The other
libraries have longer history and need to take backwards compatibility into account.
Keep this in mind when evaluating the results.
The code executed in the benchmark creates a worksheet of 20 000 rows and 10 columns filled
with string values. Some of these libraries have multiple ways of achieving the same result,
but to make this a fair comparison the idea is to use the most efficient approach for each library.
The code is available in the Benchmark project.
