---
title: "Export a list of objects to Excel in C#"
url: https://recursiveai.org/onedocument/cookbook/export-objects-to-excel/
description: "Export a list of C# records to Excel with OneDocument. Generate XLSX column headers from members and write date values as dates, not text."
version: "1.0.0"
---

# Export a list of objects to Excel in C#

**OneDocument** is a free, open-source Word, Excel and PowerPoint document library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneDocument.Spreadsheets) · [GitHub](https://github.com/recursive-ai-oss/onedocument-csharp) · [Docs](https://recursiveai.org/onedocument/docs/) · [Download example (.zip)](https://recursiveai.org/onedocument/cookbook/export-objects-to-excel/export-objects-to-excel.zip)

Each object becomes one row.

```shell
dotnet add package \
    RecursiveAI.OneDocument.Spreadsheets
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
using RecursiveAI.OneDocument.Spreadsheets;
using RecursiveAI.OneDocument
    .Spreadsheets.Binding;
Spreadsheet.Write<Order>("orders.xlsx",
    [new(101, new DateOnly(2026, 11, 19))]);
Console.WriteLine("Wrote orders.xlsx");

[SpreadsheetRow]
public partial record Order(
    int Id, DateOnly Placed);
```

```text
Wrote orders.xlsx
```

The worksheet has columns `Id` and `Placed` and one data row.

Unzip [the example](https://recursiveai.org/onedocument/cookbook/export-objects-to-excel/export-objects-to-excel.zip), then `dotnet run`.

## The full program

The download writes two orders to a worksheet named `Orders`. It reopens the file to print the header cells and the dates read back into `Order` records.

```csharp
using RecursiveAI.OneDocument
    .Spreadsheets;
using RecursiveAI.OneDocument
    .Spreadsheets.Binding;

var orders = new List<Order>
{
    new(101, new DateOnly(2026, 11, 19)),
    new(102, new DateOnly(2026, 11, 20)),
};
Spreadsheet.Write("orders.xlsx", orders);

var headers = Spreadsheet.ReadRows("orders.xlsx", "Orders").First();
Console.WriteLine($"Columns: {string.Join(", ", headers)}");
foreach (var order in Spreadsheet.Read<Order>("orders.xlsx"))
    Console.WriteLine(FormattableString.Invariant($"{order.Id}: {order.Placed:yyyy-MM-dd}"));

[SpreadsheetRow(Sheet = "Orders")]
public partial record Order(int Id, DateOnly Placed);
```

`dotnet run` prints:

```text
Columns: Id, Placed
101: 2026-11-19
102: 2026-11-20
```

`[SpreadsheetRow]` tells the package’s source generator to build the row mapping at compile time. If you omit the attribute, the type won’t meet `Spreadsheet.Write`’s type constraint; if you omit `partial`, the generator can’t complete the type. The project needs this package reference; there’s no separate generator package to install:

```xml
<PackageReference
    Include="RecursiveAI.OneDocument.Spreadsheets"
    Version="1.0.0" />
```

## Variations

**Give a column a reader-facing name.** Replace the record declaration in the full program with this one. The C# property stays `Placed`, but the header becomes `Order date`:

```csharp
[SpreadsheetRow(Sheet = "Orders")]
public partial record Order(
    int Id,
    [property: SpreadsheetColumn("Order date")]
    DateOnly Placed);
```

## Related recipes

- [Read Excel into a list of objects in C#](https://recursiveai.org/onedocument/cookbook/read-excel-rows-as-objects/)
- [Create an Excel XLSX file in C#](https://recursiveai.org/onedocument/cookbook/create-excel-file/)

---

## The short answer

Mark a `partial` record with `[SpreadsheetRow]` and pass its list to `Spreadsheet.Write("orders.xlsx", orders)`. OneDocument writes the column headers and cells for you. Use this when you already have objects to export. If you need to put different values in specific cells, use worksheet authoring instead of treating the whole sheet as a list of records.

## How do I export a list to Excel?

Start with a type that describes one row, not the entire worksheet. The record in this example has an integer and a date, so the workbook gets two columns. By default, OneDocument takes public instance fields and properties in declaration order, and uses their names as headers. Pass `Sheet` to the attribute when the workbook should have a named tab instead of the default `Sheet1`.

The row mapping is generated when the project builds. It doesn’t discover new columns from the contents of individual objects while the program is running. If your data includes a nested object, project the values you need onto flat record members before exporting. For example, keep an order’s date as `DateOnly`, not as a display string. OneDocument writes that value to XLSX as an Excel date serial (the number Excel uses to represent a date) with `yyyy-mm-dd` formatting. Excel can then sort it as a date. Use `DateTime` if the time of day matters; a workbook cell does not preserve the original time zone or offset.

Use `[SpreadsheetColumn]` when the header is meant for the spreadsheet’s reader rather than the program’s author. The variation above lets `Order date` appear in the workbook while C# still uses `Placed`. For delivery to another system that expects no header, set `HasHeader = false` on `[SpreadsheetRow]`. If you leave the header on, the first row is bold and frozen, and the writer allows up to 1,048,575 data rows beneath it; exceeding that raises `OfficeLimitException`.
