repository·master·Indexed 41 days ago
https://github.com/rabanti-github/nanoxlsxA lightweight, dependency-free .NET library for creating and reading Microsoft Excel (.xlsx) files. It features a modular architecture consisting of NanoXLSX.Core for base logic, NanoXLSX.Reader for parsing workbooks, NanoXLSX.Writer for creating files, and optional modules for formatting and compatibility. Compatible with .NET Standard 2.0 and .NET 4.5 or newer.
NanoXLSX v3 uses a modular architecture. While the NanoXLSX meta-package is recommended for most users as it includes everything, you can pick specific modules:
NanoXLSX is modular. While the meta package installs everything, you can choose specific modules based on your needs:
NanoXLSX.Core is the foundational component of the NanoXLSX library. It provides the core logic required to manipulate workbooks, worksheets, cells, and styles in the XLSX format.
Important: This package is a logic-only library; it does not handle the actual reading or writing of files to disk. To perform file I/O, you must use additional plugin packages that depend on NanoXLSX.Core.
The ImportOptions class has been renamed to ReaderOptions. When migrating to v3.0.0, update your code to use the new class name and note the following changes to constants and methods:
| Old ImportOptions Constant | New ReaderOptions Constant |
|---|---|
DEFAULT_TIMESPAN_FORMAT | DefaultTimeSpanFormat |
DEFAULT_DATETIME_FORMAT | DefaultDateTimeFormat |
| Old method name | New method name |
|---|---|
EnforceValidColumnDimensions | EnforceStrictValidation |
EnforceValidRowDimensions | EnforceStrictValidation |
ImportOptions.GlobalType.AllSingleToDecimal has been removed.ReaderOptions.GlobalType.AllNumbersToDecimal if the same behavior is required.If your code directly uses internal reader classes, you must update the namespace. All internal reader classes have moved from NanoXLSX.LowLevel to NanoXLSX.Internal.Readers.
Warning: The architecture of these internal classes was redesigned from scratch in v3.0.0. If you have custom modifications to these classes, they will likely need to be redone.
Recommended approach: Instead of modifying internal classes, use the introduced plugin architecture to implement custom readers that can replace or append to existing readers during the read process.
NanoXLSX v3.0.0 introduced breaking changes to improve usability, consistency, and modularization. The most significant change is the modularization of the library into three distinct packages:
NanoXLSX.Core: Contains core classes such as Workbook, Worksheet, Cell, and Style.NanoXLSX.Reader: Contains all reading functionalities.NanoXLSX.Writer: Contains all writing functionalities.When migrating, you must update your project references to include the specific package required for your task (reading or writing) instead of relying on a single monolithic package. Additionally, you may need to update namespaces (e.g., adding using NanoXLSX.Extensions; for reader extension methods) and adapt to renamed constants that now follow standard C# naming conventions.
// Example of updated namespace usage for reader extensions
using NanoXLSX.Extensions;The recommended way to install NanoXLSX is using NuGet. You can install the meta-package NanoXLSX, which bundles all modules (Core, Reader, Writer, Formatting, and Compatibility), or install specific modules individually for advanced scenarios (e.g., NanoXLSX.Core + NanoXLSX.Writer for write-only applications).
Use the Package Manager or .NET CLI to install the full bundle.
# By Package Manager (PM)
Install-Package NanoXLSX
# By .NET CLI
dotnet add package NanoXLSXThe Fill class was overhauled to support flexible color definitions (ARGB, indexed, theme, or system colors).
Fill.BackgroundColor and Fill.ForegroundColor are now the Color class instead of string.IndexedColor property was removed. Use the Color class with IndexedColor.Value enum or integer indices.FillType.patternColor $\rightarrow$ FillType.PatternColor).Fill.ValidateColr(string, bool, bool) moved to NanoXLSX.Utils.Validators.ValidateColr(string, bool, bool).Fill fill = new Fill();
fill.ForegroundColor = Color.CreateIndexed(IndexedColor.Value.Yellow);
// ARGB
Fill fill2 = new Fill();
fill2.BackgroundColor = Color.CreateRgb("FF00FF00");
// Theme color with tint
Fill fill3 = new Fill();
fill3.ForegroundColor = Color.CreateTheme(Theme.ColorSchemeElement.Accent1, 0.5f);
// Implicit conversions
Fill fill4 = "FF00FF00"; // Implicit SrgbColor
Fill fill5 = IndexedColor.Value.Red2; // Implicit IndexedColor
Fill fill6 = 64; // Implicit IndexedColor via index numberThe NanoXLSX meta package is the recommended way to install the library as it automatically includes the necessary dependencies for a full feature set. Installing this package provides access to core workbook operations, reading, writing, and cell formatting.
# Use NuGet to install the meta package
dotnet add package NanoXLSXIn version 3.0.0, the Workbook class underwent modularization.
Workbook.Load(...) and Workbook.LoadAsync(...) have been removed. Use the Reader module instead.Workbook.AddStyle(Style) and Workbook.AddStyleComponent(Style, AbstractStyle) are removed. Apply styles directly to cells or ranges.Workbook.RemoveStyle(...) methods are removed. Use cell.RemoveStyle() instead.Workbook.GetMruColors() now returns IReadOnlyList<Color> instead of string. The new Color class (namespace NanoXLSX.Colors) supports RGB, ARGB, system, theme, or indexed colors.// Old way (removed):
// workbook.AddStyle(myStyle);
// New way:
workbook.CurrentWorksheet.Cells["A1"].CellStyle.CurrentFont.Bold = true;
// OR
workbook.CurrentWorksheet.Cells["A1"].CellStyle.Append(fontStyle);