NkkinXlsx 0.1.0

NkkinXlsx

NkkinXlsx is a dependency-free .xlsx library targeting .NET 10. It reads and writes spreadsheet packages directly with the .NET ZIP and XML APIs. Native legacy binary .xls creation is not supported.

Install

dotnet add package NkkinXlsx --version 0.1.0

Quick start

using NkkinXlsx;

var workbook = new Workbook();
var sheet = workbook.AddWorksheet("Sales");
sheet.SetValue("A1", "Region");
sheet.SetValue("B1", "Revenue");
sheet.SetValue("A2", "North");
sheet.SetValue("B2", 1250.50);
sheet.SetFormula("B3", "SUM(B2:B2)", cachedValue: 1250.50);

sheet["A1"].Style = new CellStyle(Bold: true, FillColor: "D9EAF7");
sheet.SetAutoFilter("A1:B2");
sheet.AddTable("SalesTable", "A1:B2");
sheet.AddBarChart("Revenue by region", "A2:A2", "B2:B2", "D2");
sheet.AddPivotTable("RevenueByRegion", "A1:B2", "F1",
    ["Region"], new PivotValueField("Revenue", Aggregation: PivotAggregation.Sum));
workbook.Save("sales.xlsx");

var reopened = Workbook.Open("sales.xlsx");
Console.WriteLine(reopened.GetWorksheet("Sales")["B2"].Value);

sheet.SaveCsv("sales.csv");

Save(Stream) and Open(Stream) are also available for XLSX. Worksheet.SaveCsv(Stream) writes CSV and leaves the stream open. CSV defaults to comma-separated UTF-8 with a BOM (for Excel compatibility), invariant numeric values, ISO 8601 dates, and a used-cell range; pass a range or CsvOptions to customize the export.

Current capabilities

• Create, read, and edit cell values and formulas, including cached formula values.
• Export a worksheet to CSV, including quoted commas/quotes/newlines, custom delimiters, and range selection. Formula cells export their cached values; formulas aren't calculated.
• Basic font, fill, alignment, and number-format styles.
• Worksheet auto-filters and table creation.
• Column bar charts and embedded PNG, JPEG, GIF, or BMP images on newly created sheets.
• Native worksheet pivot-table definitions and cached source records, with row fields and Sum, Count, Average, Min, or Max aggregations.
• Worksheet protection using Excel's legacy password hash.
• No NuGet runtime dependencies.

The reader currently imports worksheet names, cell values, formulas, simple styles, and worksheet auto-filter ranges. It does not preserve or import existing tables, charts, images, protection settings, macros, pivot tables, external links, or other unsupported package parts when a workbook is opened and saved. Use it for supported-content workbooks only; do not use it to round-trip complex files that must retain unsupported features.

The same worksheet data can be exported as XLSX or CSV. PDF remains intentionally outside this package so applications can use their existing PDF library without adding a PDF dependency here. Pivot tables are generated from a source range on the same worksheet and placed at a non-overlapping destination. They carry a refreshable cache; formulas are stored as formula text and are not calculated. Pivot output rendering/refresh is left to spreadsheet applications. Worksheet protection is not file encryption and does not provide strong access control. Conditional formatting, sorting, merged cells, and full Excel feature compatibility are not implemented yet.

CSV text that starts with a formula marker (=, +, -, or @, including after leading whitespace) is prefixed with an apostrophe by default to reduce spreadsheet formula-injection risk. Set EscapeFormulaLikeText = false only when the exported content is trusted and the original text must be kept verbatim.

Performance

The writer streams worksheet XML directly to the ZIP package rather than building a second full worksheet XML tree in memory. It deduplicates ordinary text through the XLSX shared-string table and uses balanced ZIP compression for XML. There are no third-party dependencies.

Comparative benchmark (Windows x64)

Measured on .NET 10.0.13, Windows 11 x64, Intel Core i3-8100 @ 3.60 GHz, with 30,000 data rows × 8 columns. Data contains repeated labels, unique text, integers, decimals, dates, and booleans. Each writer was populated before timing, warmed with one save, then saved seven times to memory; the table reports median save time and process-wide allocated bytes during save. Generated workbooks were independently opened and checked for dimensions and representative values.

For this workload, NkkinXlsx's default-style XML optimization reduced its output from 1,413,575 bytes to 1,358,443 bytes (3.9% smaller) compared with the earlier run, while the measured save time changed from 408 ms to 401 ms (within normal run-to-run variance). EPPlus produced a 1.2% larger file in this run. MiniExcel had the fastest save time on Windows, but its output was about 98% larger and it allocated more during save. NkkinXlsx saved about 46% faster than EPPlus, with about 69% fewer save-time allocations. It was about 4.3× faster than ClosedXML and used about 83% fewer save-time allocations, with similarly sized output.

Real Android device benchmark

The same typed 8-column dataset was also exported on a connected OPPO CPH2599 (Android 16, .NET 10 Release build, trimming/AOT disabled for the comparison). This device run used 10,000 rows, one warm-up, then three timed saves; values below are medians. The APK wrote the files on-device and checked NkkinXlsx save/reopen plus CSV output.

On this device and workload, the optimized NkkinXlsx file is about 3.8% smaller than EPPlus's. MiniExcel was about 4 ms faster than NkkinXlsx, while its file was about 48% larger and save-time allocations were about 3.7× higher. NkkinXlsx was about 47% faster than EPPlus and allocated about 70% less during save. These results are device-specific.

Main DLL sizes in both benchmark tables are the primary library assemblies from the resolved NuGet packages; they are not total application size. Package footprint is based on compressed NuGet .nupkg archives; dependency closure sums the resolved packages for the benchmark's .NET 10 target. It is not a measurement of a trimmed application APK. EPPlus was run with its noncommercial personal license mode for this local benchmark only; this does not grant commercial-use rights.

These are serialization-focused comparisons, not complete application benchmarks: workbook/data-object construction is excluded, there is no styling beyond the common date number format, and formulas/tables/charts are excluded. Timings vary by machine, runtime, and data; a different API/input representation can affect allocation results. This is not a claim that NkkinXlsx is faster for every workload or feature set.

The reproducible desktop harness uses the versions above, warms up each writer, reports the median of seven saves, outputs one sample workbook per library, and prints package sizes:

dotnet run --project .\NkkinXlsx.Benchmarks\NkkinXlsx.Benchmarks.csproj --configuration Release -- --rows 30000 --iterations 7

EPPlus benchmarks use a noncommercial personal license mode. Respect EPPlus licensing terms and use a commercial license where required.

Build and smoke test

dotnet build .\NkkinXlsx.slnx
dotnet run --project .\NkkinXlsx.SmokeTests\NkkinXlsx.SmokeTests.csproj

Android device smoke test

The optional Android harness is kept outside the core solution so library builds do not require the Android workload. With Android SDK tools on PATH and a USB-debugging-enabled device connected, run:

dotnet build .\NkkinXlsx.DeviceSmokeTest\NkkinXlsx.DeviceSmokeTest.csproj --configuration Release
adb install -r .\NkkinXlsx.DeviceSmokeTest\bin\Release\net10.0-android\com.nkkin.xlsx.devicesmoketest-Signed.apk
adb logcat -c
adb shell monkey -p com.nkkin.xlsx.devicesmoketest -c android.intent.category.LAUNCHER 1
Start-Sleep -Seconds 10
adb logcat -d -s NkkinXlsxDeviceTest

The harness writes and reopens a 10,000-row XLSX, exports CSV, checks representative values and output rows, and logs a device-specific PASS/FAIL report. Generated test files are stored in the harness app's private data directory.