README.md

XLibur.Report worked examples

Ten examples, each writing both the template it authored and the report generated from it. Open the pair side by side: a template language reads much better as a before and after than as a listing, and the template is where the interesting part of every one of these lives.

dotnet run --project XLibur.Report.Examples                        # all of them
dotnet run --project XLibur.Report.Examples -- AnnualSalesReport   # one of them
dotnet run --project XLibur.Report.Examples -- --list
dotnet run --project XLibur.Report.Examples -- --out c:\temp\reports

Files land in bin/<config>/<tfm>/Reports unless --out says otherwise, named <Example>-1-template.xlsx and <Example>-2-report.xlsx.

Example	What it shows
MinimalReport	The three things there are to learn: an expression in a cell, a defined name over the rows to repeat, and the options row. Start here.
AnnualSalesReport	The flagship. A bound title band, a per-row formula, grouping by region with subtotals and an outline, a sort inside each group, an autofilter, conditional colouring, a grand total.
ExcelFunctions	SUM, IF, ROUND, MAX, CEILING — Excel's own functions inside {{ }}, returning typed results.
ConditionalRows	<<If>> dropping a row when written in a repeated row, and a whole range when written in an options row.
HorizontalReport	<<Horizontal>>: one column per item instead of one row.
CustomTag	Two tags of your own, one acting before any row exists and one after — and why a tag has two moments.
ErrorHandling	A bad expression costs its own cell and nothing else. Also what turns out not to be an error: an unbound name reads as blank.
Chart	A chart series drawn over one template row plotting every generated row, with no tag and nothing to remember.
Pivot	The two ways to a pivot over generated data — drawn in the template, or generated by it with <<Pivot>>.
EverythingAtOnce	Every feature the file format can break, in one workbook, with a printed checklist for opening it in Excel.

Reading the output

Each example prints what its generated workbook says when read back, so the console is a self-check before Excel is opened at all — how many rows came out of one, how many conditional-formatting rules survived, where a chart's series ended up.

ErrorHandling is the one example that ends with errors, on purpose.

EverythingAtOnce, and why it is not for reading

A handful of things about a generated workbook no test in the suite can check: whether Excel opens the file without offering to repair it, and whether what it then draws is what was meant. The OpenXML schema validator — which every example here runs on save — says the parts are well-formed, which is necessary and nowhere near sufficient. So EverythingAtOnce builds one workbook covering everything that has historically broken, and prints a checklist to work down. Run it after touching the write path.

These are tested

XLibur.Report.Tests/ExampleSmokeTests.cs runs every example and asserts it generates without complaint and writes its pair. Documentation that is never executed is documentation that is eventually wrong.