# SharpCell

> A free (MIT) Excel formula engine for .NET 8 and later: it reads .xlsx files, recalculates them, saves the results back and evaluates formulas, including dynamic arrays, LET/LAMBDA and tables with structured references. Results are checked against workbooks calculated by Microsoft Excel.

Packages: `SharpCell` (the engine, no dependencies) and `SharpCell.Xlsx` (reads .xlsx and saves values back). Namespaces: `SharpCell`, `SharpCell.Xlsx`. Call `Workbook.Recalculate()` after changing cells; values do not update on assignment. Excel errors are values, not exceptions. A `Workbook` is not thread-safe.

## Docs

- [Overview](https://ifmelate.github.io/SharpCell/index.md): What SharpCell is, its packages and a first example.
- [Getting started](https://ifmelate.github.io/SharpCell/getting-started.md): Install, read an .xlsx file, recalculate, read values; walks through the console sample.
- [Formulas and values](https://ifmelate.github.io/SharpCell/guides/formulas.md): Formula syntax, references, CellValue kinds, dynamic arrays, names and LAMBDA, parse errors.
- [Cells, ranges and dates](https://ifmelate.github.io/SharpCell/guides/cells.md): Going through non-empty cells, UsedRange, reading and writing blocks of values, dates as DateTime, typing into cells as in Excel, defined names.
- [Recalculation](https://ifmelate.github.io/SharpCell/guides/recalculation.md): When values update, changed cells, precedents and dependents, cancellation, diagnostics, threads, cloning templates, culture and dates.
- [Custom functions](https://ifmelate.github.io/SharpCell/guides/custom-functions.md): Functions written in C# that formulas call by name: arguments, scalar parameters, volatile functions, failures.
- [Reading .xlsx files](https://ifmelate.github.io/SharpCell/guides/xlsx.md): What the reader loads and skips, saved results, streams, unsupported formats.
- [Saving .xlsx files](https://ifmelate.github.io/SharpCell/guides/saving.md): Writing recalculated values back into the file a workbook was read from: what is written, what is refused, KeepUncalculated.
- [Tables and hidden rows](https://ifmelate.github.io/SharpCell/guides/tables.md): Structured references such as Sales[Units], tables from .xlsx files and code, hidden rows and filters in SUBTOTAL and AGGREGATE.
- [Functions](https://ifmelate.github.io/SharpCell/guides/functions.md): Function status, criteria syntax for COUNTIF and friends, dates as numbers, regular expressions.
- [What SharpCell does not do](https://ifmelate.github.io/SharpCell/guides/limits.md): Every known gap in one list.
- [Roadmap](https://ifmelate.github.io/SharpCell/roadmap.md): What was released, what is being built now and what comes later.
- [For AI coding agents](https://ifmelate.github.io/SharpCell/agents.md): llms.txt, llms-full.txt and rules to paste into an agent's instructions.

## API reference

- [CalculationDiagnostic](https://ifmelate.github.io/SharpCell/api/SharpCell.CalculationDiagnostic.md): Something calculation noticed that is not visible in cell values alone.
- [Cell](https://ifmelate.github.io/SharpCell/api/SharpCell.Cell.md): A handle to one cell position.
- [CellBorder](https://ifmelate.github.io/SharpCell/api/SharpCell.CellBorder.md): One edge of a cell's border.
- [CellBorderStyle](https://ifmelate.github.io/SharpCell/api/SharpCell.CellBorderStyle.md): The lines Excel draws borders with.
- [CellColor](https://ifmelate.github.io/SharpCell/api/SharpCell.CellColor.md): A colour as Excel shows it, in sRGB.
- [CellFont](https://ifmelate.github.io/SharpCell/api/SharpCell.CellFont.md): The font of a cell's text.
- [CellHorizontalAlignment](https://ifmelate.github.io/SharpCell/api/SharpCell.CellHorizontalAlignment.md): Where a cell's text sits across the cell.
- [CellRange](https://ifmelate.github.io/SharpCell/api/SharpCell.CellRange.md): A rectangle of cells on one sheet, such as `A1:C10`.
- [CellStyle](https://ifmelate.github.io/SharpCell/api/SharpCell.CellStyle.md): How a cell looks in Excel: font, fill, borders, alignment and protection (locked, formula hidden).
- [CellUnderline](https://ifmelate.github.io/SharpCell/api/SharpCell.CellUnderline.md): How a font underlines text.
- [CellValue](https://ifmelate.github.io/SharpCell/api/SharpCell.CellValue.md): A value produced by a cell or a formula.
- [CellValueKind](https://ifmelate.github.io/SharpCell/api/SharpCell.CellValueKind.md): The kind of value a CellValue holds.
- [CellVerticalAlignment](https://ifmelate.github.io/SharpCell/api/SharpCell.CellVerticalAlignment.md): Where a cell's text sits from top to bottom of the cell.
- [ConditionalFormat](https://ifmelate.github.io/SharpCell/api/SharpCell.ConditionalFormat.md): A conditional format: which cells of its ranges it formats, and how.
- [ConditionalFormatType](https://ifmelate.github.io/SharpCell/api/SharpCell.ConditionalFormatType.md): What a conditional format looks at, as Excel's New Formatting Rule dialog offers it.
- [ConditionalOperator](https://ifmelate.github.io/SharpCell/api/SharpCell.ConditionalOperator.md): How a ConditionalFormatType.CellValue rule compares the cell's value with its formulas.
- [ConditionalStyle](https://ifmelate.github.io/SharpCell/api/SharpCell.ConditionalStyle.md): What a conditional format changes about a cell's look, as Excel's Format Cells for a rule sets it: the font's style and colour, the fill, the borders and the number format.
- [DataValidation](https://ifmelate.github.io/SharpCell/api/SharpCell.DataValidation.md): A data validation rule: what the cells of a range accept and the messages Excel shows for them.
- [DateSystem](https://ifmelate.github.io/SharpCell/api/SharpCell.DateSystem.md): The workbook's date system: which day serial number 0 or 1 stands for.
- [DefinedName](https://ifmelate.github.io/SharpCell/api/SharpCell.DefinedName.md): A defined name as Workbook.DefinedNames lists it.
- [DeleteShift](https://ifmelate.github.io/SharpCell/api/SharpCell.DeleteShift.md): Which cells take the place of deleted cells, as in Excel's Delete dialog.
- [DiagnosticKind](https://ifmelate.github.io/SharpCell/api/SharpCell.DiagnosticKind.md): What a CalculationDiagnostic reports.
- [ErrorKind](https://ifmelate.github.io/SharpCell/api/SharpCell.ErrorKind.md): Excel error values.
- [ErrorKinds](https://ifmelate.github.io/SharpCell/api/SharpCell.ErrorKinds.md): Conversion between ErrorKind and its literal text (`#DIV/0!`).
- [FormulaParseException](https://ifmelate.github.io/SharpCell/api/SharpCell.FormulaParseException.md): Thrown when formula text cannot be parsed.
- [FunctionArguments](https://ifmelate.github.io/SharpCell/api/SharpCell.FunctionArguments.md): The arguments of one call of a function added through Workbook.Functions.
- [FunctionCollection](https://ifmelate.github.io/SharpCell/api/SharpCell.FunctionCollection.md): The functions a workbook's formulas can call besides Excel's: add one with FunctionCollection.Add, and formulas calling it by name (ignoring case) use it from the next calculation on.
- [FunctionOptions](https://ifmelate.github.io/SharpCell/api/SharpCell.FunctionOptions.md): How a function added through Workbook.Functions takes its arguments.
- [Hyperlink](https://ifmelate.github.io/SharpCell/api/SharpCell.Hyperlink.md): A hyperlink on a cell: a web or e-mail address, a file, or a place in the workbook.
- [InsertShift](https://ifmelate.github.io/SharpCell/api/SharpCell.InsertShift.md): Where the cells beside inserted cells go, as in Excel's Insert dialog.
- [IterationSettings](https://ifmelate.github.io/SharpCell/api/SharpCell.IterationSettings.md): Iterative calculation, Excel's "Enable iterative calculation": circular references are calculated over and over until they settle, instead of giving 0.
- [LambdaValue](https://ifmelate.github.io/SharpCell/api/SharpCell.LambdaValue.md): A function value produced by `LAMBDA`.
- [Note](https://ifmelate.github.io/SharpCell/api/SharpCell.Note.md): A note on a cell: Excel's Insert Note (called a comment before Excel 365), shown in a box beside the cell, by default only while the pointer rests on it.
- [PageMargins](https://ifmelate.github.io/SharpCell/api/SharpCell.PageMargins.md): The margins of a printed sheet in inches, as in Excel's Page Setup > Margins: the space around the cells, and how far the header and footer are from the top and bottom edges.
- [PageOrientation](https://ifmelate.github.io/SharpCell/api/SharpCell.PageOrientation.md): How a sheet is turned on the printed page, as in Excel's Page Layout > Orientation.
- [RecalculationResult](https://ifmelate.github.io/SharpCell/api/SharpCell.RecalculationResult.md): What one Workbook.Recalculate did.
- [SheetProtection](https://ifmelate.github.io/SharpCell/api/SharpCell.SheetProtection.md): What users may still do on a protected sheet, as Excel's Protect Sheet dialog lists it: by default they may select cells and nothing else.
- [Table](https://ifmelate.github.io/SharpCell/api/SharpCell.Table.md): An Excel table: a named range with column names, an optional header row and an optional totals row.
- [TimePeriod](https://ifmelate.github.io/SharpCell/api/SharpCell.TimePeriod.md): The periods of Excel's A Date Occurring rule, counted from today.
- [ValidationErrorStyle](https://ifmelate.github.io/SharpCell/api/SharpCell.ValidationErrorStyle.md): What Excel does when a value breaks a rule.
- [ValidationOperator](https://ifmelate.github.io/SharpCell/api/SharpCell.ValidationOperator.md): How a value is compared with a rule's formulas; lists and custom rules do not compare.
- [ValidationType](https://ifmelate.github.io/SharpCell/api/SharpCell.ValidationType.md): What a data validation rule lets a cell hold, as Excel's Data Validation dialog names it under Allow.
- [Workbook](https://ifmelate.github.io/SharpCell/api/SharpCell.Workbook.md): A workbook: sheets, defined names and calculation settings.
- [Worksheet](https://ifmelate.github.io/SharpCell/api/SharpCell.Worksheet.md): A sheet of a Workbook.
- [XlsxReader](https://ifmelate.github.io/SharpCell/api/SharpCell.Xlsx.XlsxReader.md): Reads .xlsx workbooks: sheets, values, formulas with the results Excel cached, defined names, tables, hidden rows, whether a sheet is filtered, the date system, number formats, cell styles, column widths, row heights, merged cells, frozen panes and gridlines, from .xlsx and macro-enabled .xlsm files.
- [XlsxWriteException](https://ifmelate.github.io/SharpCell/api/SharpCell.Xlsx.XlsxWriteException.md): A workbook was not saved because SharpCell could not calculate some of its formulas; see XlsxWriteOptions.KeepUncalculated.
- [XlsxWriteOptions](https://ifmelate.github.io/SharpCell/api/SharpCell.Xlsx.XlsxWriteOptions.md): Options for XlsxWriter.
- [XlsxWriter](https://ifmelate.github.io/SharpCell/api/SharpCell.Xlsx.XlsxWriter.md): Saves a workbook as an .xlsx file: values, formulas, styles, number formats, sizes, merged cells, panes, sheets, defined names and tables.

## Optional

- [Compatibility report](https://ifmelate.github.io/SharpCell/compatibility.md): Every function's status and how many Excel-calculated cells it matches.
- [Compatibility data](https://ifmelate.github.io/SharpCell/compatibility.json): The same report as JSON, for tools.
- [Full documentation](https://ifmelate.github.io/SharpCell/llms-full.txt): All guides and the API reference in one file.