FreeDataExports 1.1.14

FreeDataExports

⚠️ Note: FreeDataExports is being replaced by FreeDataExportsv2 and will no longer be maintained. New projects should use FreeDataExportsv2, which offers a cleaner API, richer formatting, charts, images, Excel tables, and identical XLSX/ODS output from the same code.

A lightweight .NET library for exporting data to .xlsx, .ods, and .csv files — no Excel or LibreOffice installation required. Available on NuGet.

Table of Contents

1. Supported Formats & Platforms
2. Initialization
3. Excel Export (XLSX 2019)
4. LibreOffice Export (ODS 1.3)
5. CSV Export
6. Column Widths
7. Tab Colors
8. Format Code Overrides
9. Error Handling
10. Saving / Getting Bytes
11. Formatting Reference
12. Data Types Reference

Supported Formats & Platforms

File formats

.NET platform support

• .NET 6 through .NET 10
• .NET Standard 2.0
• .NET Core 2.x – 3.1
• .NET Framework 4.6.1 – 4.8
• Mono 5.4, 6.4
• Xamarin.iOS 10.14, 12.16
• Xamarin.Android 8.0, 10.0
• Universal Windows Platform 10.0.16299
• Unity 2018.1

See the full compatibility matrix at dotnet.microsoft.com/platform/dotnet-standard.

Initialization

FreeDataExports exposes a shared IDataWorkbook interface so you can write format-agnostic code and switch between XLSX and ODS with a single line change.

using FreeDataExports;

// Shared interface — lets you write the same code for either format
IDataWorkbook workbook = new DataExport().CreateXLSX2019();
IDataWorkbook workbook = new DataExport().CreateODSv1_3();

Note: Tab color strings and column-width units differ between XLSX and ODS. See Tab Colors and Column Widths for details.

Excel Export (XLSX 2019)

using FreeDataExports;

// Create a new XLSX workbook
var workbook = new DataExport().CreateXLSX2019();

// Optional metadata
workbook.CreatedBy = "Jane Doe";
workbook.FontSize  = 11;

// Add worksheets
var orders    = workbook.AddWorksheet("Orders");
var inventory = workbook.AddWorksheet("Inventory");

// Header row
orders.AddRow()
    .AddCell("OrderId",    DataType.String)
    .AddCell("Item",       DataType.String)
    .AddCell("Units",      DataType.String)
    .AddCell("Price",      DataType.String)
    .AddCell("OrderDate",  DataType.String)
    .AddCell("SalesAssoc", DataType.String)
    .AddCell("Delivered",  DataType.String);

// Data rows
foreach (var o in Orders)
{
    orders.AddRow()
        .AddCell(o.OrderId,         DataType.Number)
        .AddCell(o.Item,            DataType.String)
        .AddCell(o.Units,           DataType.Number)
        .AddCell(o.Price,           DataType.Currency)
        .AddCell(o.OrderDate,       DataType.LongDate)
        .AddCell(o.SalesAssociate,  DataType.String)
        .AddCell(o.Delivered,       DataType.Boolean);
}

// Inventory sheet
inventory.AddRow()
    .AddCell("ItemId", DataType.String)
    .AddCell("Item",   DataType.String)
    .AddCell("Number", DataType.String)
    .AddCell("Price",  DataType.String);

foreach (var i in Inventory)
{
    inventory.AddRow()
        .AddCell(i.ItemId,  DataType.Number)
        .AddCell(i.Item,    DataType.String)
        .AddCell(i.Number,  DataType.Number)
        .AddCell(i.Price,   DataType.Currency);
}

// Optional — tab colors (RGB hex, no #)
orders.TabColor    = "0000FF00"; // green
inventory.TabColor = "000000FF"; // blue

// Optional — column widths (character units)
orders.ColumnWidths("10", "10", "5", "10", "28.5", "15", "10");
inventory.ColumnWidths("10", "10", "10", "10");

// Optional — format overrides and error worksheet
workbook.Format(DataType.DateTime24, @"m/d/yy\ h:mm;@");
workbook.AddErrorsWorksheet();

// Save
await workbook.SaveAsync("Orders.xlsx");

LibreOffice Export (ODS 1.3)

The ODS API mirrors the XLSX API — the main differences are the tab color format and column width units. See Tab Colors and Column Widths.

using FreeDataExports;

// Create a new ODS workbook
var workbook = new DataExport().CreateODSv1_3();

// Optional metadata
workbook.CreatedBy = "Jane Doe";
workbook.FontSize  = 11;

// Add worksheets
var orders    = workbook.AddWorksheet("Orders");
var inventory = workbook.AddWorksheet("Inventory");

// Header row
orders.AddRow()
    .AddCell("OrderId",    DataType.String)
    .AddCell("Item",       DataType.String)
    .AddCell("Units",      DataType.String)
    .AddCell("Price",      DataType.String)
    .AddCell("OrderDate",  DataType.String)
    .AddCell("SalesAssoc", DataType.String)
    .AddCell("Delivered",  DataType.String);

// Data rows
foreach (var o in Orders)
{
    orders.AddRow()
        .AddCell(o.OrderId,         DataType.Number)
        .AddCell(o.Item,            DataType.String)
        .AddCell(o.Units,           DataType.Number)
        .AddCell(o.Price,           DataType.Currency)
        .AddCell(o.OrderDate,       DataType.LongDate)
        .AddCell(o.SalesAssociate,  DataType.String)
        .AddCell(o.Delivered,       DataType.Boolean);
}

// Inventory sheet
inventory.AddRow()
    .AddCell("ItemId", DataType.String)
    .AddCell("Item",   DataType.String)
    .AddCell("Number", DataType.String)
    .AddCell("Price",  DataType.String);

foreach (var i in Inventory)
{
    inventory.AddRow()
        .AddCell(i.ItemId,  DataType.Number)
        .AddCell(i.Item,    DataType.String)
        .AddCell(i.Number,  DataType.Number)
        .AddCell(i.Price,   DataType.Currency);
}

// Optional — tab colors (CSS hex, with #)
orders.TabColor    = "#00FF00"; // green
inventory.TabColor = "#0000FF"; // blue

// Optional — column widths (inches or centimeters — specify the unit)
orders.ColumnWidths(".8in", "1in", ".5in", "1in", "1.5in", "1in", "1in");
inventory.ColumnWidths(".8in", "1in", ".8in", "1in");

// Optional — format overrides and error worksheet
workbook.Format(DataType.Currency, "symbol=$,language=en,country=US,decimals=2");
workbook.AddErrorsWorksheet();

// Save
await workbook.SaveAsync("Orders.ods");

CSV Export

using FreeDataExports;

var csv = new DataExport().CreateCsv();

// Header
csv.AddRow("OrderId", "Item", "Units", "Price", "OrderDate", "SalesAssoc", "Delivered");

// Data
foreach (var o in Orders)
{
    csv.AddRow(o.OrderId, o.Item, o.Units, o.Price,
               o.OrderDate, o.SalesAssociate, o.Delivered);
}

await csv.SaveAsync("Orders.csv");

AddRow returns this so calls can be chained:

csv.AddRow("A", "B", "C")
   .AddRow(1,   2,   3);

CsvFile methods

Column Widths

Set column widths after adding all rows. Returns the worksheet for chaining.

// XLSX — character-width units (same as Excel's column width)
orders.ColumnWidths("10", "10", "5", "10", "28.5", "15", "10");

// ODS — physical units (inches or centimeters, include the unit suffix)
orders.ColumnWidths(".8in", "1in", ".5in", "1in", "1.5in", "1in", "1in");
orders.ColumnWidths("2cm", "2.5cm", "1.5cm", "2cm");

XLSX vs ODS: XLSX column widths are specified in Excel character units. ODS column widths require a physical measurement with a unit suffix (in or cm). These values are not interchangeable — specify the appropriate format for the workbook type you are creating.

Tab Colors

Tab color format differs between XLSX and ODS:

// XLSX
orders.TabColor = "0000FF00"; // green
orders.TabColor = "000000FF"; // blue

// ODS
orders.TabColor = "#00FF00";  // green
orders.TabColor = "#0000FF";  // blue

Format Code Overrides

Override the default format code for any DataType before writing data:

// XLSX — standard Excel format strings
workbook.Format(DataType.DateTime24, @"m/d/yy\ h:mm;@");
workbook.Format(DataType.Currency,   @"""$""#,##0.00");

// ODS — key=value descriptor strings
workbook.Format(DataType.Currency, "symbol=$,language=en,country=US,decimals=2");
workbook.Format(DataType.Decimal,  "decimals=8");

Overrides apply to all worksheets in the workbook.

Error Handling

Every AddCell call is wrapped in a try/catch. When a type conversion fails:

• The offending cell is left empty.
• The error is recorded internally.

Options

// Auto-create a red "Errors" worksheet on save — only added when errors actually occur
workbook.AddErrorsWorksheet();

// Or retrieve errors as a string at any time
string report = workbook.GetErrors();
if (!string.IsNullOrEmpty(report))
    Console.WriteLine(report);

Saving / Getting Bytes

All three workbook types (XLSX, ODS, CSV) share the same save API:

// Synchronous — file path
workbook.Save(path);

// Asynchronous — file path
await workbook.SaveAsync(path);

// In-memory byte array (e.g. for an HTTP response body)
byte[] bytes = workbook.GetBytes();

// Asynchronous byte array
byte[] bytes = await workbook.GetBytesAsync();

Formatting Reference

XLSX format strings

These are Excel number-format codes stored in the .xlsx package. Many contain escape characters and are written as C# verbatim or literal strings.

ODS format descriptors

ODS files use key=value descriptor strings rather than Excel format codes.

Data Types Reference

License

This project is licensed under the MIT License. See the LICENSE file for details.