Toon.DotNet.Excel 1.7.1

Toon.DotNet.Excel

Excel integration for ToonDotNet — convert Excel workbooks and worksheets to and from TOON format.

Features

Encoding — Excel → TOON

• Encode a single worksheet to a TOON root array, using the first row as column headers
• Encode a full workbook to a TOON root object, one key per sheet name
• Encode directly from a file path — open an .xlsx and get back a TOON string in one call
• Save as .toon — read an Excel file and write the result straight to a .toon file

Decoding — TOON → Excel

• Decode a TOON string into a new XLWorkbook — root array becomes Sheet1, root object becomes one sheet per key
• Load a .toon file directly into a new XLWorkbook
• Save as .xlsx — decode a TOON string and write the result straight to an Excel file
• Convert .toon to .xlsx — file-to-file conversion in one call

Extension methods

• IXLWorksheet.ToToon() — encode a worksheet inline
• IXLWorkbook.ToToon() — encode all sheets inline
• string.ToExcelWorkbook() — decode a TOON string inline

Cell type handling

• Numbers, booleans, text and blank/null cells are round-tripped faithfully
• DateTime values are encoded as ISO 8601 strings and parsed back on decode
• TimeSpan values are preserved as formatted strings

Sheet management

• Multi-sheet workbooks are fully supported
• Sheet names are automatically sanitised (forbidden Excel characters removed, truncated to 31 characters)
• Duplicate sheet names after sanitisation receive a numeric suffix, e.g. Sales (2)

Other

• All encode/decode calls accept the standard EncodeOptions and DecodeOptions from Toon.DotNet
• 56 unit tests, 100% passing, 78% code coverage

Installation

dotnet add package ToonDotNet.Excel

Compatibility

• .NET 10.0
• .NET 9.0
• .NET 8.0

How it works

Each worksheet is treated as tabular data: the first row provides column headers and every subsequent row becomes a TOON data row.

Decoding reverses the mapping: a root TOON object creates one sheet per key; a root array creates a single sheet named Sheet1.

Quick start

Encode a worksheet to TOON

using ClosedXML.Excel;
using ToonDotNet.Excel;

using var workbook = new XLWorkbook("report.xlsx");

// Single sheet → root array
string toon = workbook.Worksheet("Sales").ToToon();
// [3]{id,product,amount}:
//   1,Widget,9.99
//   2,Gadget,19.99
//   3,Doohickey,4.99

Encode a full workbook to TOON

// All sheets → root object keyed by sheet name
string toon = workbook.ToToon();
// Sales[3]{id,product,amount}:
//   1,Widget,9.99
//   ...
// Customers[2]{id,name}:
//   1,Alice
//   2,Bob

Decode TOON back to an Excel workbook

using var decoded = toon.ToExcelWorkbook();
decoded.SaveAs("output.xlsx");

Convert an Excel file directly to a TOON file

ToonExcel.SaveAsToon("report.xlsx", "report.toon");

Convert a TOON file directly to an Excel file

ToonExcel.ConvertToonToExcel("report.toon", "report.xlsx");

API overview

ToonExcel static class

Encoding (Excel → TOON)

Decoding (TOON → Excel)

Note: Decode and LoadToonFile return a new XLWorkbook instance. The caller is responsible for disposing it.

Extension methods

// IXLWorksheet
string toon = worksheet.ToToon(options);

// IXLWorkbook
string toon = workbook.ToToon(options);

// string
using XLWorkbook wb = toonString.ToExcelWorkbook(options);

Options

Options are passed directly from ToonDotNet and work identically here.

EncodeOptions

DecodeOptions

var opts = new EncodeOptions { Delimiter = '|', Indent = 4 };
string toon = workbook.ToToon(opts);

Cell type handling

Dependencies

• Toon.DotNet — core TOON encoding and decoding
• ClosedXML — Excel file reading and writing

License

MIT