Each object becomes one row.
dotnet add package \ RecursiveAI.OneDocument.Spreadsheets
Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
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);
Wrote orders.xlsxThe worksheet has columns Id and Placed and one data row.
Unzip the example, 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.
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:
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:
<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:
[SpreadsheetRow(Sheet = "Orders")] public partial record Order( int Id, [property: SpreadsheetColumn("Order date")] DateOnly Placed);
Related recipes
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.